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
- 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.
- 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. - 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.
- 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. - 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.
