Streaming de API de IA: SSE e timeouts

O streaming de uma API de IA envia eventos enquanto o modelo gera, sem esperar pelo corpo completo. Melhora a rapidez percebida, mas não reduz necessariamente a latência do modelo e obriga o cliente a interpretar o protocolo correto.

Chat Completions transmite fragmentos de conclusão; Responses usa eventos tipificados. O cliente pode receber HTTP 200 e não mostrar nada se esperar o formato errado.

Comece sem buffering

curl -N -sS https://modelflare.dev/v1/responses \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_RESPONSES_MODEL","input":"Explain SSE.","stream":true}'

Teste primeiro o mesmo pedido sem streaming para separar validação de parsing. Use um ID de Modelos e preços.

Trate SSE como protocolo

Server-Sent Events são registos delimitados, não fragmentos arbitrários de JSON. O cliente deve impedir buffering em HTTP, proxy e UI; juntar leituras parciais; reconhecer eventos de texto, raciocínio, ferramenta, conclusão e erro; preservar cancelamento e utilização final; e fechar após o evento terminal.

Meça fases diferentes

Medida	Significado
Ligação e autenticação	Chegar ao gateway e validar a chave
Headers upstream	A rota escolhida começa a responder
Primeira saída efetiva	Primeiro texto, raciocínio ou ferramenta útil
Primeiro texto visível	Primeiro conteúdo visto pelo utilizador
Tempo total	Conclusão, falha ou cancelamento

Uma ferramenta pode gerar saída efetiva antes de texto. Para operação, meça a primeira saída efetiva; para experiência, também o primeiro texto visível.

Timeouts por fase

Separe timeout de ligação, headers ou primeira saída, inatividade do stream e deadline total. Pedidos de raciocínio ou ferramentas podem demorar mais até ao texto. Defina limites com cargas reais, não com um único timeout curto.

Se cliente, browser ou proxy fechar cedo, a Modelflare pode registar 499. Isto prova cancelamento downstream, não falha do modelo ou canal. Compare abort, proxy, primeira saída, modelo, grupo e instante.

Quando não aparece texto

1. Repita com "stream": false.
2. Confirme que o modelo suporta o endpoint.
3. Capture eventos brutos antes da UI.
4. Procure ferramenta ou raciocínio sem texto.
5. Exclua buffering intermédio.
6. Verifique o evento terminal no parser.
7. Compare estado, tempos e cancelamento.

Se o pedido normal funciona e há eventos brutos, o problema costuma estar no parsing ou renderização. Sem eventos, consulte o guia de erros. Para escolher o formato, veja Responses API ou Chat Completions.

Compare os dois endpoints sem buffering

Além do exemplo de Responses, teste Chat Completions com o formato próprio:

curl -N -sS https://modelflare.dev/v1/chat/completions \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_CHAT_MODEL",
    "messages": [{"role": "user", "content": "Explique SSE em três pontos."}],
    "stream": true
  }'

O parser deve:

• manter biblioteca HTTP, proxy e interface sem buffering;
• juntar leituras parciais até completar um evento;
• interpretar o tipo de evento do endpoint selecionado;
• distinguir texto, raciocínio, ferramentas, conclusão e erros;
• aceitar respostas úteis sem texto visível;
• preservar cancelamento e utilização final;
• fechar após o evento terminal.

Lista de verificação para streaming em produção

• Associe explicitamente o parser a Chat Completions ou Responses.
• Teste texto, raciocínio, apenas ferramentas, erros e conclusão normal.
• Meça separadamente primeiro evento, primeira saída efetiva e primeiro texto visível.
• Defina limites de ligação, primeira saída, inatividade e operação completa.
• Use um sinal de cancelamento intencional.
• Trate cada repetição como novo pedido, salvo se existir idempotência segura.
• Preserve ID, estado, modelo, grupo e tempos para diagnóstico.
• Confirme que nenhum intermediário volta a armazenar o fluxo em buffer.

Perguntas frequentes

O streaming faz o modelo gerar mais depressa?

Não necessariamente. Mostra a saída mais cedo; a espera pelo primeiro evento e a velocidade posterior continuam dependentes do modelo, rota, contexto, raciocínio e ferramentas.

Porque funciona no curl mas não na aplicação?

A aplicação ou um intermediário pode fazer buffering, ou o parser pode esperar fragmentos de Chat Completions e receber eventos de Responses. Capture os eventos sem transformação antes de mudar de modelo.

Um stream interrompido deve ser repetido?

Só quando a operação puder ser repetida em segurança. Trabalho upstream ou uma ferramenta podem já ter sido executados; limite tentativas e exija idempotência para efeitos secundários.