BroadRouter

Streaming de chat completions e conexões que caem

Atualizado em

Defina stream como true em /v1/chat/completions e leia os Server-Sent Events até o marcador literal data: [DONE]. Adicione stream_options include_usage para receber as contagens de tokens no último chunk. Se a conexão terminar antes de [DONE], trate a resposta como incompleta e registre o X-Request-ID.

O streaming permite que um agente ou uma interface de chat mostre a resposta enquanto ela é gerada. A BroadNet Inference usa o formato padrão de streaming de chat completions, então o SDK Python da OpenAI e o SDK Node da OpenAI fazem a interpretação por você.

Com curl

curl -N -D stream-headers.txt https://inference.broadnet.ai/v1/chat/completions \
  -H "Authorization: Bearer $BROADNET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"broadnet/gemma-4-26b-a4b","stream":true,"stream_options":{"include_usage":true},"messages":[{"role":"user","content":"Count from one to three."}]}'

-N desliga o buffer do curl, e -D salva os cabeçalhos, incluindo X-Request-ID.

Como é o stream?

A resposta é um stream de Server-Sent Events. Pelo padrão HTML do WHATWG, cada evento é uma ou mais linhas data: seguidas de uma linha em branco, e uma linha que começa com dois-pontos é um comentário que você pode ignorar. Cada linha data: contém um chunk JSON, e o texto chega em choices[0].delta.content.

As regras

  1. Leia os eventos até a linha literal data: [DONE] e depois feche o leitor.
  2. Com stream_options: {"include_usage": true}, um chunk extra chega logo antes de [DONE]. Ele traz o usage da requisição inteira e uma lista choices vazia, então confira choices antes de acessar um índice.
  3. Quando o modelo os informa, esse usage inclui completion_tokens_details.reasoning_tokens (DeepSeek V4.1 Flash, GLM 5.3 e Qwen3.8 27B raciocinam primeiro) e prompt_tokens_details.cached_tokens. Tokens em cache são cobrados pelo preço menor de entrada em cache.

Com o SDK Python

No código, o comentário final indica que None significa que o stream terminou antes do chunk com o usage.

import os
from openai import OpenAI

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])

stream = client.chat.completions.create(
    model="broadnet/gemma-4-26b-a4b",
    messages=[{"role": "user", "content": "Count from one to three."}],
    stream=True,
    stream_options={"include_usage": True},
)
usage = None
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
    if chunk.usage:
        usage = chunk.usage
print()
print(usage)  # None means the stream ended before the usage chunk

O SDK lê até [DONE] por você. O guia do SDK Node da OpenAI mostra o mesmo loop em JavaScript.

Quando o stream termina antes

Se a conexão fechar antes de [DONE], a resposta está incompleta. A orientação da BroadNet:

  • registre o X-Request-ID;
  • decida se a sua aplicação pode fazer com segurança uma nova requisição. Uma nova tentativa é uma nova inferência e, no pagamento por uso, é cobrada de novo.

Para agentes em um plano ilimitado, as novas tentativas não custam nada a mais, mas ainda ocupam a sessão enquanto rodam.

A documentação da BroadNet diz que ainda é necessária uma verificação de liberação por modelo antes de confiar no streaming em produção, então teste no modelo que você vai colocar em produção.

Solução de problemas

  • Tudo aparece só no final. O curl precisa de -N. Atrás do seu próprio proxy, desligue o buffer de resposta para text/event-stream.
  • IndexError ou undefined no último chunk. O chunk de usage tem uma lista choices vazia. Confira chunk.choices antes de ler [0].
  • Nenhum usage. Você não enviou stream_options, ou o stream caiu antes do chunk final.
  • O stream para com finish_reason length e pouco texto. Um modelo de raciocínio gastou max_tokens raciocinando. Veja por que modelos de raciocínio retornam respostas vazias.
  • 429 ao fazer streaming em paralelo. Cada stream aberto conta como uma requisição em andamento; uma chave de pagamento por uso permite 4. Veja códigos de erro e novas tentativas na BroadNet.

Perguntas frequentes

Como obter o uso de tokens ao fazer streaming de chat completions?

Envie stream_options com include_usage definido como true. Um chunk extra chega logo antes de data: [DONE], com usage preenchido e um array choices vazio. Se o stream cair antes, esse chunk nunca chega.

Por que o curl imprime a resposta do streaming toda de uma vez?

O curl usa buffer na saída por padrão. Adicione a opção -N (sem buffer) para que cada Server-Sent Event apareça assim que chegar.

Um stream repetido é cobrado duas vezes?

No pagamento por uso, sim. Uma nova tentativa é uma nova requisição de inferência. Em um plano ilimitado de DeepSeek V4.1 Flash não há medidor de tokens, mas a nova tentativa ainda ocupa a sessão enquanto roda.

Streaming custa mais do que uma requisição normal?

Não. O streaming muda a forma como a resposta é entregue, não como ela é cobrada. No pagamento por uso, você paga os mesmos preços por token de entrada e de saída de uma requisição sem streaming.

Ler em MarkdownPerguntar ao ChatGPTPerguntar ao ClaudePerguntar ao Perplexity