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

CampoTipoObrigatórioDescrição
modelstringSimId do modelo, de GET /llm/models, no formato provedor/modelo.
messagesarraySimA conversa, como na OpenAI. role: system, developer, user, assistant ou tool.
max_tokensintegerSimObrigatório (ou max_completion_tokens). Até o teto da conta e o max_output_tokens de cada modelo da chamada.
streambooleanNãoCom true, a resposta é text/event-stream.
stream_options.include_usagebooleanNãoCom 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.

Relacionadas

Ver tudo que dá para fazer em LLM

Veja o Connect aplicado ao seu produto.

Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.