Streaming de API de IA: SSE e timeouts
Aprenda eventos de Chat Completions e Responses, parsing SSE, primeira saída efetiva, timeouts por fase e diagnóstico de 499.
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
- Repita com "stream": false.
- Confirme que o modelo suporta o endpoint.
- Capture eventos brutos antes da UI.
- Procure ferramenta ou raciocínio sem texto.
- Exclua buffering intermédio.
- Verifique o evento terminal no parser.
- 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.