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.
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.