BroadRouter
Começar

Streaming de LLM explicado: chunks SSE, deltas, usage e cancelamento

Pela equipe da BroadNet Inference · 4 min de leitura · Publicado em · Atualizado em

Uma API de LLM transmite uma chat completion como Server-Sent Events: cada linha data traz um chunk JSON cujo choices[0].delta contém o próximo pedaço de texto. Concatene os deltas, pare em data: [DONE] e defina include_usage em stream_options para receber as contagens de tokens em um chunk final com a lista choices vazia. Para cancelar, feche a conexão.

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

  1. 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.
  2. Sem checar o [DONE]. Uma conexão que caiu parece uma resposta curta. Trate a falta de [DONE] como resposta incompleta e registre o X-Request-ID, como descreve o guia de erros.
  3. 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.
  4. 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.
  5. 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.

Perguntas frequentes

Qual é a diferença entre SSE e WebSockets para streaming de LLM?

SSE é unidirecional, do servidor para o cliente, sobre uma resposta HTTP normal. É tudo de que uma chat completion precisa, por isso as APIs compatíveis com a OpenAI usam SSE. WebSockets são bidirecionais e exigem upgrade de protocolo; são usados para voz em tempo real, não para chat completions.

Por que o usage vem null nos meus chunks de streaming?

O usage só é enviado quando você pede. Adicione stream_options com include_usage definido como true. Aí todos os chunks, menos o último, têm usage null, e o último traz os totais com a lista choices vazia.

Sou cobrado se cancelar um stream?

Depende do provedor, e muitos não documentam. Suponha que os tokens gerados antes de o servidor perceber a conexão fechada são cobrados. Registre o X-Request-ID e compare com os seus registros de uso.

Como sei se um stream terminou normalmente?

Você recebeu data: [DONE] e o último chunk de conteúdo tinha um finish_reason como stop. Um finish_reason length significa que max_tokens cortou a resposta. Sem [DONE], a conexão caiu.

O streaming deixa o modelo mais rápido?

Não. O tempo total de geração é o mesmo. O streaming reduz o tempo até o usuário ver as primeiras palavras, e é isso que faz uma interface de chat parecer rápida.

Ler em MarkdownPerguntar ao ChatGPTPerguntar ao ClaudePerguntar ao Perplexity