Sem streaming, uma chat completion não devolve nada até a resposta inteira ficar pronta. Uma resposta de 600 tokens a cerca de 100 tokens por segundo significa vários segundos de silêncio. Com streaming, as primeiras palavras aparecem assim que o modelo as escreve. Este post mostra o que de fato trafega pela conexão, como fazer o parse, como tirar o usage de tokens de um stream e como pará-lo de forma limpa. Para as regras específicas da BroadNet de forma resumida, veja o guia de referência de streaming.
Como é um stream SSE na conexão?
Server-Sent Events é uma resposta HTTP comum com Content-Type: text/event-stream. O servidor mantém a conexão aberta e escreve eventos. Cada evento é uma ou mais linhas data: seguidas de uma linha em branco. As APIs compatíveis com a OpenAI colocam um chunk JSON em cada evento e terminam com um [DONE] literal:
data: {"id":"c1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}],"usage":null}
data: {"id":"c1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"One, "},"finish_reason":null}],"usage":null}
data: {"id":"c1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"two, three."},"finish_reason":"stop"}],"usage":null}
data: {"id":"c1","object":"chat.completion.chunk","choices":[],"usage":{"prompt_tokens":14,"completion_tokens":6,"total_tokens":20}}
data: [DONE]
O formato acima é ilustrativo e resumido. Chunks reais também trazem model e created, e modelos de raciocínio podem informar tokens de raciocínio no usage.
O que vem em um chunk?
| Campo | Onde | O que significa |
|---|---|---|
choices[0].delta.role |
Primeiro chunk | Normalmente assistant. Enviado uma vez. |
choices[0].delta.content |
A maioria dos chunks | O próximo pedaço de texto. Pode vir vazio. |
choices[0].delta.tool_calls |
Chamadas de ferramenta | Fragmentos do nome da função e dos argumentos JSON, para juntar por index. |
choices[0].finish_reason |
Último chunk de conteúdo | stop, length ou tool_calls. null até lá. |
usage |
Chunk final, se pedido | Totais da requisição inteira. null em todos os outros. |
A ideia central é delta, não snapshot. Cada chunk traz só o que é novo. Você monta a mensagem juntando os pedaços em ordem. Chamadas de ferramenta chegam do mesmo jeito: os argumentos vêm como fragmentos de string que não são JSON válido até o último chegar, então faça o parse só depois que finish_reason for tool_calls.
Como obter o usage de tokens de um stream?
Uma resposta sem streaming sempre inclui usage. Um stream não, a menos que você peça. Defina stream_options: {"include_usage": true} e o servidor envia um chunk extra antes do [DONE]. Esse chunk tem os totais e um array choices vazio. Na BroadNet Inference, o usage também pode incluir prompt_tokens_details.cached_tokens e completion_tokens_details.reasoning_tokens quando o modelo os informa, que é o que você precisa para o registro de custos.
O bug comum: código que lê chunk.choices[0] em todo chunk dá erro de índice no chunk de usage. Confira choices primeiro.
Python: stream, coletar usage, cancelar
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/deepseek-v4.1-flash", # DeepSeek V4.1 Flash, a reasoning model
messages=[{"role": "user", "content": "Explain SSE in three sentences."}],
stream=True,
stream_options={"include_usage": True},
max_tokens=2000, # reasoning counts toward this limit
)
def user_pressed_stop(): # replace with your own condition
return False
parts, usage, finish = [], None, None
try:
for chunk in stream:
if chunk.choices:
choice = chunk.choices[0]
if choice.delta.content:
parts.append(choice.delta.content)
print(choice.delta.content, end="", flush=True)
if choice.finish_reason:
finish = choice.finish_reason
if chunk.usage:
usage = chunk.usage
if user_pressed_stop(): # your own condition
break
finally:
stream.close() # closes the HTTP connection
text = "".join(parts)
Só o break para a leitura, mas o socket continua aberto até ser recolhido pelo garbage collector. Feche-o explicitamente para o servidor perceber a desconexão.
Node: stream com um AbortController
import OpenAI from "openai";
const client = new OpenAI({ baseURL: "https://inference.broadnet.ai/v1", apiKey: process.env.BROADNET_API_KEY });
const controller = new AbortController();
setTimeout(() => controller.abort(), 30_000); // hard stop after 30 s
const stream = await client.chat.completions.create(
{
model: "broadnet/deepseek-v4.1-flash",
messages: [{ role: "user", content: "Explain SSE in three sentences." }],
stream: true,
stream_options: { include_usage: true },
},
{ signal: controller.signal },
);
let text = "";
for await (const chunk of stream) {
const delta = chunk.choices[0]?.delta?.content;
if (delta) text += delta;
if (chunk.usage) console.log(chunk.usage);
}
O README do openai-node documenta a opção signal, e ela funciona enquanto o corpo ainda está sendo lido. Em um servidor web, ligue controller.abort() ao evento close da requisição do cliente, para que um usuário que sai da página também pare a geração. Mais configuração no guia do SDK para Node.
curl: ver os eventos brutos
curl -N 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 to five."}]}'
-N desliga o buffer de saída, então os eventos aparecem conforme chegam. Pressione Ctrl+C para cancelar; isso fecha a conexão. O gerador de requisições de API monta esta requisição, e as versões em Python e Node, para qualquer modelo e base URL.
Como cancelar um stream, e quanto custa?
Cancelar em SSE é só fechar a conexão. Não existe mensagem de “stop”. O que acontece depois depende do servidor: um servidor bem-comportado percebe o socket fechado e para de gerar. Os tokens produzidos antes desse momento foram trabalho real. A referência da API da BroadNet não documenta a cobrança de streams cancelados, então planeje como se os tokens gerados até a desconexão fossem cobrados no pagamento por uso, e confira os seus registros de uso. Em um plano de preço fixo, um stream cancelado não custa nada a mais, mas só libera a sessão quando o servidor para.
Cinco bugs de streaming para conferir
- Proxies com buffer. O Nginx e algumas CDNs fazem buffer das respostas, então o cliente recebe tudo de uma vez. Desative o buffer do proxy na rota de streaming.
- Sem checar o
[DONE]. Uma conexão que caiu parece uma resposta curta. Trate a falta de[DONE]como resposta incompleta e registre oX-Request-ID, como descreve o guia de erros. - Retry no meio do stream. Os SDKs não fazem retry depois que o corpo começa a chegar. Um retry é uma nova requisição e, no pagamento por uso, uma nova cobrança.
- Ignorar
finish_reason: length. Em modelos de raciocínio como o DeepSeek V4.1 Flash, o pensamento conta em max_tokens, então um limite pequeno pode parar o stream antes de qualquer texto visível. Quanto custam os tokens de raciocínio. - Dividir as linhas errado. Se você faz o parse de SSE na mão, acumule bytes até ver uma linha em branco. Uma leitura TCP pode terminar no meio de um chunk JSON.
Onde a BroadNet Inference se encaixa
A BroadNet Inference usa o formato padrão de streaming compatível com a OpenAI, então os SDKs de Python e Node fazem o parse sem mudanças. O usage no chunk final inclui tokens em cache e de raciocínio quando o modelo os informa. A documentação diz que o streaming ainda deve ser verificado por modelo antes do uso em produção, então rode o código acima no modelo exato que você vai usar. Se o que mais importa para você é a rapidez com que o primeiro token chega, leia em seguida TTFT vs throughput. Se você precisa de voz em tempo real via WebSockets, esta API não foi feita para isso; ela oferece chat completions e transcrição de arquivos.
