LLM
Streaming de respostas de LLM por SSE pela API
Com stream: true em POST /llm/chat/completions, o Connect responde em text/event-stream, uma linha data: por pedaço e data: [DONE] no fim, como na OpenAI. O stream do SDK da OpenAI funciona sem adaptação, com modelos da OpenAI, da Anthropic e da Meta.
A chamada
POST /api/llm/chat/completions
Authorization: Bearer <merchant token>
{
"model": "anthropic/claude-sonnet-5-5",
"max_tokens": 1024,
"stream": true,
"stream_options": {
"include_usage": true
},
"messages": [
{
"role": "system",
"content": "You summarize marketing data in English."
},
{
"role": "user",
"content": "Summarize the account's week."
}
]
}O que dá para fazer
- Mostrar a resposta ao usuário enquanto ela é gerada.
- Pedir o consumo no stream com stream_options: {"include_usage": true}.
- Usar o mesmo código de stream para os três provedores.
- Combinar stream com fallback (models) e tools nos modelos que suportam.
Regras e limites
- Com stream: true a resposta é text/event-stream: uma linha data: {chunk} por pedaço e data: [DONE] ao final.
- O chunk com usage só vem se você enviar stream_options: {"include_usage": true}.
- Sem stream, a resposta pode começar com espaços em branco enquanto o modelo gera; espaço antes do JSON continua sendo JSON válido e o SDK da OpenAI lê normalmente.
- Um erro depois que a resposta começou não muda o status 200: no stream ele chega como um evento data: {"error": {...}} e o stream termina sem data: [DONE]. Verifique error antes de ler choices.
- Timeouts: 30s até o primeiro token, 60s sem novo token e 300s no total (llm_timeout, 504).
Campos principais
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| model | string | Sim | Id do modelo, de GET /llm/models, no formato provedor/modelo. |
| messages | array | Sim | A conversa, como na OpenAI. role: system, developer, user, assistant ou tool. |
| max_tokens | integer | Sim | Obrigatório (ou max_completion_tokens). Até o teto da conta e o max_output_tokens de cada modelo da chamada. |
| stream | boolean | Não | Com true, a resposta é text/event-stream. |
| stream_options.include_usage | boolean | Não | Com true, o chunk final traz usage (tokens). |
Para quem
Chat dentro do seu SaaS
O assistente do seu produto escreve a resposta em tempo real, sem o usuário esperar a resposta inteira.
Interfaces de agente
Mostre o raciocínio ou o texto parcial de um agente enquanto ele trabalha.
Geração longa de relatórios
Exiba o resumo de um relatório conforme o texto é gerado, em vez de uma tela de carregamento.
Perguntas frequentes
Como ativo o streaming?
Envie stream: true no corpo de POST /llm/chat/completions. A resposta passa a ser text/event-stream, com data: [DONE] no fim.
Como recebo o consumo de tokens no stream?
Envie stream_options: {"include_usage": true}. O chunk com usage só vem se você pedir.
O que acontece se der erro no meio do stream?
O status 200 já saiu, então o erro chega como um evento data: {"error": {...}} e o stream acaba sem data: [DONE]. O SDK da OpenAI levanta o erro.
Veja o Connect aplicado ao seu produto.
Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.
