BroadRouter
Inizia

Streaming degli LLM spiegato: chunk SSE, delta, usage e annullamento

A cura del team di BroadNet Inference · 4 min di lettura · Pubblicato · Aggiornato

Un’API LLM invia una chat completion in streaming come Server-Sent Events: ogni riga data contiene un chunk JSON il cui choices[0].delta porta il pezzo successivo di testo. Concatena i delta, fermati a data: [DONE] e imposta include_usage in stream_options per ricevere i conteggi dei token in un chunk finale con una lista choices vuota. Per annullare, chiudi la connessione.

Senza streaming, una chat completion non restituisce nulla finché la risposta non è completa. Una risposta da 600 token a circa 100 token al secondo significa diversi secondi di silenzio. Con lo streaming, le prime parole compaiono appena il modello le scrive. Questo articolo spiega cosa viaggia davvero sulla connessione, come fare il parsing, come ottenere l’usage dei token da uno stream e come fermarlo in modo pulito. Per le regole specifiche di BroadNet in forma breve, vedi la guida di riferimento allo streaming.

Com’è fatto uno stream SSE sulla connessione?

I Server-Sent Events sono una semplice risposta HTTP con Content-Type: text/event-stream. Il server tiene aperta la connessione e scrive eventi. Ogni evento è una o più righe data: seguite da una riga vuota. Le API compatibili con OpenAI mettono un chunk JSON in ogni evento e chiudono con un [DONE] letterale:

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]

La forma qui sopra è un esempio semplificato. I chunk reali portano anche model e created, e i modelli di ragionamento possono riportare i token di ragionamento in usage.

Cosa c’è in un chunk?

Campo Dove Cosa significa
choices[0].delta.role Primo chunk Di solito assistant. Inviato una sola volta.
choices[0].delta.content Quasi tutti i chunk Il pezzo successivo di testo. Può essere vuoto.
choices[0].delta.tool_calls Chiamate ai tool Frammenti del nome della funzione e degli argomenti JSON, da unire per index.
choices[0].finish_reason Ultimo chunk di contenuto stop, length o tool_calls. null fino ad allora.
usage Chunk finale, se richiesto Totali dell’intera richiesta. null in tutti gli altri.

Il concetto chiave è delta, non istantanea. Ogni chunk contiene solo ciò che è nuovo. Ricostruisci il messaggio unendo i pezzi in ordine. Le chiamate ai tool arrivano in streaming allo stesso modo: gli argomenti arrivano come frammenti di stringa che non sono JSON valido finché non arriva l’ultimo, quindi fai il parsing solo dopo che finish_reason è tool_calls.

Come si ottiene l’usage dei token da uno stream?

Una risposta senza streaming include sempre usage. Uno stream no, a meno che tu non lo chieda. Imposta stream_options: {"include_usage": true} e il server invia un chunk in più prima di [DONE]. Quel chunk ha i totali e un array choices vuoto. Su BroadNet Inference l’usage può includere anche prompt_tokens_details.cached_tokens e completion_tokens_details.reasoning_tokens quando il modello li riporta, ed è ciò che ti serve per il logging dei costi.

Il bug tipico: il codice che legge chunk.choices[0] su ogni chunk solleva un errore di indice sul chunk di usage. Controlla prima choices.

Python: streaming, raccolta dell’usage, annullamento

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)

Il solo break smette di leggere, ma il socket resta aperto finché non viene raccolto dal garbage collector. Chiudilo esplicitamente così il server vede la disconnessione.

Node: streaming con un 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);
}

Il README di openai-node documenta l’opzione signal, che funziona anche mentre il body viene ancora letto. In un server web, collega controller.abort() all’evento close della richiesta del client, così anche un utente che lascia la pagina ferma la generazione. Più dettagli di configurazione nella guida all’SDK per Node.

curl: vedere gli eventi grezzi

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 disattiva il buffering dell’output così gli eventi vengono stampati appena arrivano. Premi Ctrl+C per annullare; questo chiude la connessione. Il generatore di richieste API crea questa richiesta, e le versioni Python e Node, per qualsiasi modello e base URL.

Come si annulla uno stream, e quanto costa?

In SSE annullare significa semplicemente chiudere la connessione. Non esiste un messaggio di “stop”. Cosa succede dopo dipende dal server: uno che si comporta bene si accorge del socket chiuso e smette di generare. I token prodotti prima di quel momento sono stati lavoro reale. Il riferimento API di BroadNet non documenta la fatturazione degli stream annullati, quindi pianifica come se i token generati fino alla disconnessione venissero fatturati con il pagamento a consumo, e controlla i tuoi dati di consumo. Con un piano flat uno stream annullato non costa nulla in più, ma libera la sessione solo quando il server si ferma.

Cinque bug di streaming da controllare

  1. Proxy che fanno buffering. Nginx e alcune CDN mettono in buffer le risposte, quindi il client riceve tutto in una volta. Disattiva il buffering del proxy per la route di streaming.
  2. Nessun controllo su [DONE]. Una connessione caduta sembra una risposta corta. Considera incompleta una risposta senza [DONE] e registra l’X-Request-ID, come descrive la guida agli errori.
  3. Retry a metà stream. Gli SDK non fanno retry una volta che il body ha iniziato ad arrivare. Un retry è una nuova richiesta e, con il pagamento a consumo, una nuova fattura.
  4. Ignorare finish_reason: length. Sui modelli di ragionamento come DeepSeek V4.1 Flash il thinking conta in max_tokens, quindi un limite basso può fermare lo stream prima di qualsiasi testo visibile. Quanto costano i token di ragionamento.
  5. Dividere male le righe. Se fai il parsing SSE a mano, accumula i byte finché non vedi una riga vuota. Una lettura TCP può finire a metà di un chunk JSON.

Dove si inserisce BroadNet Inference

BroadNet Inference usa il formato di streaming standard compatibile con OpenAI, quindi gli SDK Python e Node lo leggono senza modifiche. L’usage nel chunk finale include i token in cache e di ragionamento quando il modello li riporta. La sua documentazione dice che lo streaming va comunque verificato modello per modello prima di andare in produzione, quindi esegui il codice qui sopra sul modello esatto che metti in produzione. Se ti interessa soprattutto quanto arriva in fretta il primo token, leggi poi TTFT e throughput. Se ti serve la voce in tempo reale via WebSocket, questa API non è fatta per quello: offre chat completions e trascrizione di file.

Domande frequenti

Che differenza c’è tra SSE e WebSocket per lo streaming degli LLM?

SSE è unidirezionale, dal server al client, su una normale risposta HTTP. È tutto ciò che serve a una chat completion, per questo le API compatibili con OpenAI usano SSE. I WebSocket sono bidirezionali e richiedono un upgrade del protocollo; si usano per la voce in tempo reale, non per le chat completion.

Perché usage è null nei miei chunk in streaming?

Usage viene inviato solo se lo chiedi. Aggiungi stream_options con include_usage impostato a true. A quel punto ogni chunk tranne l’ultimo ha usage null, e l’ultimo porta i totali con una lista choices vuota.

Pago se annullo uno stream?

Dipende dal provider, e molti non lo documentano. Dai per scontato che i token generati prima che il server si accorga della connessione chiusa vengano fatturati. Registra l’X-Request-ID e confrontalo con i tuoi dati di consumo.

Come capisco se uno stream è finito normalmente?

Hai ricevuto data: [DONE] e l’ultimo chunk di contenuto aveva un finish_reason come stop. Un finish_reason length significa che max_tokens ha tagliato la risposta. Nessun [DONE] significa che la connessione è caduta.

Lo streaming rende il modello più veloce?

No. Il tempo totale di generazione è lo stesso. Lo streaming riduce il tempo prima che l’utente veda le prime parole, ed è questo che rende reattiva un’interfaccia di chat.

Leggi in MarkdownChiedi a ChatGPTChiedi a ClaudeChiedi a Perplexity