Senza streaming, il client aspetta che l’intera risposta sia pronta. Con lo streaming, il testo compare mentre il modello lo scrive.
Come funziona
Lo streaming usa i server-sent event (SSE). Il server risponde con content type text/event-stream e tiene aperta la connessione. MDN descrive il formato: righe field: value, con messaggi “separated by a pair of newline characters” (traduzione: separati da una coppia di caratteri di a capo).
Nel formato Chat Completions, ogni evento porta un chunk con un piccolo delta:
data: {"choices":[{"index":0,"delta":{"content":"Hel"}}]}
data: {"choices":[{"index":0,"delta":{"content":"lo"}}]}
data: {"choices":[],"usage":{"prompt_tokens":12,"completion_tokens":2}}
data: [DONE]
Il client unisce i delta. La riga letterale data: [DONE] segna la fine. Il chunk con l’usage compare solo se la richiesta lo ha chiesto con stream_options: {"include_usage": true}.
Perché è importante
- Velocità percepita. Gli utenti vedono le prime parole dopo il time to first token, non dopo l’intera risposta. Da lì il testo scorre ai token al secondo del modello.
- Output lunghi. Lo streaming tiene attiva la connessione, il che aiuta con i proxy che chiudono le richieste inattive.
- Azione anticipata. Agenti e interfacce possono iniziare a fare il parsing o il rendering prima della fine.
Ci sono anche dei costi. OpenAI osserva che lo streaming rende più difficile la moderazione, perché “partial completions may be more difficult to evaluate” (traduzione: le risposte parziali possono essere più difficili da valutare). Uno stream può anche interrompersi a metà, e una risposta in streaming occupa uno slot di concorrenza finché non termina.
Su BroadNet Inference
BroadNet usa il formato standard di streaming di chat completions su https://inference.broadnet.ai/v1/chat/completions, quindi gli SDK Python e Node lo interpretano al posto tuo. Con curl, aggiungi -N per disattivare il buffering:
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 three."}]}'
I modelli di ragionamento possono riportare reasoning_tokens e cached_tokens nel chunk finale con l’usage. Se la connessione si chiude prima di [DONE], considera la risposta incompleta, registra l’header X-Request-ID e valuta se una nuova richiesta è sicura. La documentazione di BroadNet consiglia di verificare lo streaming sul modello che metti in produzione prima di affidartici. I dettagli sono nella guida allo streaming e in errori e retry.
Errori comuni
- Considerare una connessione chiusa come una risposta completa. Solo
[DONE]significa che è finita. - Mettere un proxy con buffering davanti al client. La risposta arriva allora tutta in una volta.