Streaming de API de IA: SSE, primeira saída e timeouts
Crie streaming confiável com os eventos corretos de Chat e Responses, parsing de SSE, métrica de primeira saída efetiva, timeouts por fase e diagnóstico do 499.

O streaming de API de IA envia a saída de forma incremental enquanto o modelo gera a resposta, em vez de esperar pelo corpo completo. Ele pode melhorar a sensação de rapidez, mas não reduz automaticamente a latência do modelo e acrescenta um contrato de protocolo que o cliente precisa interpretar corretamente.
A primeira regra é usar o parser adequado ao endpoint. O Chat Completions usa chunks de completion transmitidos em stream, enquanto o Responses usa eventos de resposta tipados. Um cliente pode receber HTTP 200 e ainda assim não exibir nada se esperar o formato de evento errado.
Comece com uma solicitação sem buffer
Para um modelo de Chat Completions, curl -N desativa o buffer de saída do curl:
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
}'
Para um modelo compatível com Responses:
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": "Explique SSE em três pontos.",
"stream": true
}'
Use um ID de modelo exato de Modelos e preços. Teste antes a mesma solicitação com o streaming desativado; isso separa a validação da solicitação da interpretação do stream.
Trate o stream de eventos como um protocolo
Server-Sent Events são registros delimitados, e não fragmentos arbitrários de JSON. Um cliente de produção precisa:
- manter o corpo da resposta sem buffer na biblioteca HTTP, no proxy e na camada de interface;
- acumular leituras parciais da rede até que um evento completo esteja disponível;
- interpretar o tipo de evento usado pelo endpoint selecionado;
- tratar deltas de texto, eventos de raciocínio ou de ferramentas, eventos de conclusão e eventos de erro;
- não presumir que toda resposta útil contém texto visível;
- preservar o cancelamento e as informações finais de uso;
- fechar o stream depois de um evento final, em vez de esperar indefinidamente.
Sempre que possível, use um SDK com suporte nativo ao protocolo escolhido. Um parser próprio deve ser testado com frames fragmentados, vários eventos em uma única leitura, saída apenas com ferramentas e um evento final limpo.
Meça mais do que o tempo até o primeiro token
O “tempo até o primeiro token” costuma ser vago demais para o tráfego de agentes. Separe estas medições:
| Medição | O que significa |
|---|---|
| Conexão e autenticação | Tempo para alcançar o gateway e validar a chave |
| Cabeçalhos de resposta do provedor | Tempo até a rota selecionada iniciar uma resposta |
| Primeira saída efetiva | Primeiro evento útil de texto, raciocínio ou ferramenta |
| Primeiro texto visível | Primeiro texto que o usuário realmente consegue ver |
| Vazão de saída | Velocidade de geração visível depois que a saída começa |
| Tempo total de resposta | Tempo até a conclusão, a falha ou o cancelamento |
Uma chamada de ferramenta pode produzir saída efetiva antes de qualquer texto visível. Por isso, a primeira saída efetiva é a métrica operacional mais segura, enquanto o primeiro texto visível é útil para a experiência do usuário.
Os registros de uso do Modelflare mantêm evidências de tempo por solicitação para que essas fases possam ser comparadas com modelo, grupo, status, tokens e custo.
Defina timeouts por fase
Um único timeout global curto gera falhas ambíguas. Um cliente de streaming deve considerar vários limites de tempo:
- Timeout de conexão: falha ao estabelecer a conexão HTTP.
- Timeout de cabeçalhos ou da primeira saída: nenhuma resposta ou evento efetivo depois que a solicitação foi aceita.
- Timeout de inatividade: o stream começou, mas nenhum evento novo chegou por um período inesperadamente longo.
- Prazo geral: a operação completa ultrapassou o limite de negócio da carga de trabalho.
Solicitações com muito raciocínio ou baseadas em ferramentas podem, legitimamente, esperar mais antes do texto visível do que uma resposta curta de chat. Defina os limites com base no comportamento observado da carga de trabalho e cancele de forma intencional quando o usuário não precisar mais do resultado.
Entenda o cancelamento e os registros 499
Se o cliente, o proxy reverso, a aba do navegador ou o prazo de quem fez a chamada fechar a conexão com o cliente, o gateway pode registrar a solicitação como cancelada pelo cliente. Um rótulo 499 em um registro de solicitação é evidência de que a conexão com o cliente terminou antes da conclusão; isso, por si só, não prova que o modelo ou o canal selecionado falhou.
Ao investigar um cancelamento, compare:
- o prazo do cliente e o sinal de abort;
- o buffer e os timeouts de inatividade do proxy;
- o tempo até a primeira saída efetiva;
- se algum evento chegou ao cliente;
- o modelo e o grupo selecionados;
- o ID da solicitação e o horário do cancelamento.
Diagnostique um stream que não retorna texto visível
Siga esta ordem:
- Repita a solicitação com "stream": false.
- Confirme que o modelo oferece suporte ao endpoint selecionado.
- Capture os eventos brutos antes que a interface os transforme.
- Verifique se a resposta contém uma chamada de ferramenta ou um evento de raciocínio em vez de texto.
- Verifique se algum intermediário está acumulando o corpo em buffer.
- Confirme que o parser trata o evento final do endpoint.
- Revise nos registros de uso o status, a primeira saída, o tempo total e o cancelamento.
Se a solicitação sem streaming funcionar e os eventos brutos do stream chegarem, a falha geralmente está na interpretação ou na renderização do cliente, e não na autenticação ou no acesso ao modelo. Se nenhum evento bruto chegar, continue com o Guia de erros de API de IA.
Checklist de streaming para produção
- Use explicitamente o parser de Chat Completions ou de Responses.
- Desative o buffer no cliente HTTP e em todas as camadas de proxy sob seu controle.
- Teste os eventos de texto, raciocínio, apenas ferramentas e erro usados pela aplicação.
- Diferencie a primeira saída efetiva do primeiro texto visível.
- Use timeouts adequados a cada fase e um sinal de abort intencional.
- Trate novas tentativas como novas solicitações, a menos que a operação tenha um design de idempotência seguro.
- Preserve o ID da solicitação, o status, o modelo selecionado, o grupo e os tempos para o diagnóstico.
- Compare a escolha de endpoint em Responses API ou Chat Completions.
Perguntas frequentes
O streaming faz o modelo gerar mais rápido?
Não necessariamente. O streaming expõe a saída mais cedo; a velocidade de geração e o tempo até o primeiro evento continuam dependendo do modelo, da rota, do contexto, do raciocínio e das ferramentas.
Por que o curl funciona e a aplicação não mostra nada?
A aplicação ou um intermediário pode estar acumulando o corpo em buffer, ou o parser pode esperar chunks do Chat Completions enquanto recebe eventos do Responses. Capture os frames brutos na fronteira da aplicação antes de mudar o modelo ou a rota.
O cliente deve tentar novamente depois que um stream se desconecta?
Somente quando repetir a operação for seguro. Um stream desconectado pode já ter gerado trabalho no provedor ou atividade de ferramentas. Use novas tentativas limitadas e idempotência no nível da aplicação quando efeitos colaterais duplicados forem um problema.