stream

O endpoint de stream da API Nama permite a obtenção de respostas à medida que são geradas, fornecendo dados em tempo real. Isso é especialmente útil para aplicações que necessitam de respostas rápidas e incrementais. O funcionamento do endpoint de stream é similar ao endpoint padrão, aceitando o mesmo payload, mas com diferenças importantes no retorno das informações.

Cabeçalho

Authorization(obrigatório): Sua chave de API Nama.ai no formato Bearer YOUR_API_KEY. (Substitua YOUR_API_KEY pela sua chave de API.)

Content-Type(obrigatório): Indicar o tipo de conteúdo enviado no corpo da requisição. Deve ser application/json.

👍

Dica:

Você pode optar por utilizar o Token da aba 'Consumir' e ele preencherá automaticamente as informações da conta e do projeto.

Estrutura do Payload

O payload do endpoint de stream é o mesmo utilizado no endpoint padrão, incluindo o parâmetro opcional history para manter o contexto da conversa. Para saber mais sobre o uso do parâmetro history, consulte a Documentação: .

{  
    "dataset": "nome_do_dataset",  
    "question": "sua_pergunta",  
    "generational_presset": "id_do_presset",  
    "history": [  
        {  
            "question": "pergunta_anterior",  
            "answer": "resposta_anterior"  
        },  
        {  
            "question": "outra_pergunta_anterior",  
            "answer": "outra_resposta_anterior"  
        }  
    ]  
}

Funcionamento do Retorno

O endpoint de stream retorna dados em tempo real assim que o generational.content vai sendo gerado. Os dados são devolvidos em formato de string e precisam ser tratados pelo cliente para converter para um objeto JSON.

Informações do primeiro retorno: Os dados como search.content, search.context, e outras informações relacionadas ao search são retornadas no primeiro retorno e continuam se repetindo em cada chunk.
Informações de conteúdo gerado: O campo generational.content é retornado em pedaços (chunks) e precisa ser acumulado pelo cliente até a conclusão da resposta.
Tratamento de múltiplos objetos: Em cada chunk, pode haver mais de um objeto na string retornada. Portanto, é necessário tratar essa situação no lado do cliente.

Exemplo de Chunk Retornado:

{  
    "result": {  
        "search": [  
            {  
                "content": {  
                    "name": "Quem foi Dom Pedro?",  
                    "source": "https://pt.wikipedia.org/wiki/Dom_Pedro_I_do_Brasil",  
                    "subject": "Example Subject",  
                    "created_at": "2024-06-14T18:44:28.206686-03:00",  
                    "updated_at": "2024-06-14T18:44:28.229670-03:00"  
                },  
                "score": 1,  
                "answer": "",  
                "context": "Dom Pedro I foi um dos grandes nomes da história do Brasil, conhecido por sua participação no processo de independência e por ser o primeiro imperador do país."  
            }  
        ],  
        "generational": {  
            "content": "Dom Pedro"  
        }  
    },  
    "identifier": "75a60429-3083-4e25-a974-141ad928405f"  
}

Considerações Importantes

Tratamento da String: O cliente precisa converter a string recebida em um objeto JSON e tratar adequadamente os dados.
Acumulação do generational.content: O campo generational.content precisa ser acumulado conforme novos chunks são recebidos até a conclusão da resposta.
Repetição de Dados Relacionados ao search: Dados como search.content e search.context serão repetidos em cada chunk até a conclusão da resposta.
Tratamento de Múltiplos Objetos: Em cada chunk retornado, pode haver mais de um objeto. Portanto, é necessário que o cliente implemente uma lógica para lidar com essa situação e processar corretamente cada objeto recebido.

• Diferença com o Endpoint Padrão

O endpoint de stream não retorna generational.total_tokens.
As respostas são enviadas em pedaços assim que são geradas, ao contrário do endpoint padrão que aguarda toda a resposta ser gerada para retornar.

• Benefícios e Considerações do Uso do Endpoint de Stream

O uso do endpoint de stream apresenta vantagens significativas para aplicações que lidam com conteúdos extensos e necessitam de respostas rápidas. No entanto, também há considerações importantes a serem levadas em conta para sua implementação.

• Vantagens:

Retorno Incremental de Dados: O endpoint de stream retorna os dados à medida que são gerados, proporcionando respostas parciais em tempo real. Isso permite ao usuário receber informações de forma gradual, à medida que são disponibilizadas.

• Comparativo com o Endpoint Padrão:

Ao contrário do endpoint padrão, que aguarda a conclusão total da resposta antes de devolvê-la ao usuário, o endpoint de stream oferece uma abordagem mais dinâmica, retornando dados parciais conforme são gerados. Essa abordagem é ideal para situações em que a velocidade de resposta e a interatividade são prioritárias. No entanto, é importante considerar os custos adicionais de implementação e processamento associados ao uso do endpoint de stream.

Considerações:

Implementação Adicional no Cliente: O cliente precisa tratar a string retornada, convertendo-a para JSON e acumulando os dados necessários. Isso adiciona complexidade à implementação, exigindo um maior esforço de desenvolvimento para manipular os dados recebidos de forma incremental.
Aumento de Processamento e Custo: Como os dados são retornados em pedaços (chunks), pode haver um aumento no processamento necessário para gerenciar e acumular as respostas. Além disso, dependendo da estratégia de implementação, pode haver um consumo maior de recursos computacionais e, consequentemente, um custo adicional.

A decisão de utilizar esse endpoint deve levar em conta tanto os benefícios operacionais quanto as implicações adicionais na implementação e nos custos de processamento.