BroadRouter

Streaming delle chat completions e connessioni interrotte

Aggiornato

Imposta stream a true su /v1/chat/completions e leggi i Server-Sent Events fino al marcatore letterale data: [DONE]. Aggiungi stream_options include_usage per ricevere i conteggi dei token nell’ultimo chunk. Se la connessione si chiude prima di [DONE], considera la risposta incompleta e registra l’X-Request-ID.

Lo streaming permette a un agente o a un’interfaccia di chat di mostrare la risposta mentre viene generata. BroadNet Inference usa il formato di streaming standard delle chat completions, quindi l’SDK Python di OpenAI e l’SDK Node di OpenAI se ne occupano al posto tuo.

Con curl

curl -N -D stream-headers.txt 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 from one to three."}]}'

-N disattiva il buffering di curl, e -D salva gli header, compreso X-Request-ID.

Com’è fatto lo stream?

La risposta è uno stream di Server-Sent Events. Secondo lo standard HTML del WHATWG, ogni evento è composto da una o più righe data: seguite da una riga vuota, e una riga che inizia con i due punti è un commento che puoi ignorare. Ogni riga data: contiene un chunk JSON, e il testo arriva in choices[0].delta.content.

Le regole

  1. Leggi gli eventi fino alla riga letterale data: [DONE], poi chiudi il reader.
  2. Con stream_options: {"include_usage": true}, subito prima di [DONE] arriva un chunk in più. Contiene usage per l’intera richiesta e una lista choices vuota, quindi controlla choices prima di accedere a un indice.
  3. Quando il modello li riporta, quell’usage comprende completion_tokens_details.reasoning_tokens (DeepSeek V4.1 Flash, GLM 5.3 e Qwen3.8 27B ragionano prima di rispondere) e prompt_tokens_details.cached_tokens. I token in cache sono fatturati al prezzo ridotto dell’input in cache.

Con l’SDK Python

Nel codice, il commento finale indica che None significa che lo stream si è chiuso prima del chunk con l’usage.

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/gemma-4-26b-a4b",
    messages=[{"role": "user", "content": "Count from one to three."}],
    stream=True,
    stream_options={"include_usage": True},
)
usage = None
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
    if chunk.usage:
        usage = chunk.usage
print()
print(usage)  # None means the stream ended before the usage chunk

L’SDK legge fino a [DONE] al posto tuo. La guida all’SDK Node di OpenAI mostra lo stesso ciclo in JavaScript.

Quando lo stream si chiude prima

Se la connessione si chiude prima di [DONE], la risposta è incompleta. Le indicazioni di BroadNet:

  • registra l’X-Request-ID;
  • decidi se la tua applicazione può fare in sicurezza una nuova richiesta. Un retry è una nuova inferenza e, a consumo, viene fatturato di nuovo.

Per gli agenti con un piano illimitato, i retry non costano nulla in più, ma occupano comunque la sessione mentre sono in corso.

La documentazione di BroadNet dice che serve ancora una verifica di rilascio modello per modello prima di fare affidamento sullo streaming in produzione, quindi provalo sul modello che porterai in produzione.

Risoluzione dei problemi

  • Viene stampato tutto alla fine. curl ha bisogno di -N. Dietro un tuo proxy, disattiva il buffering delle risposte per text/event-stream.
  • IndexError o undefined sull’ultimo chunk. Il chunk con l’usage ha una lista choices vuota. Controlla chunk.choices prima di leggere [0].
  • Nessun usage. Non hai inviato stream_options, oppure lo stream si è interrotto prima del chunk finale.
  • Lo stream si ferma con finish_reason length e poco testo. Un modello di ragionamento ha speso max_tokens nel ragionamento. Vedi perché i modelli di ragionamento restituiscono risposte vuote.
  • 429 con stream in parallelo. Ogni stream aperto conta come richiesta in corso; una chiave a consumo ne consente 4. Vedi codici di errore e retry di BroadNet.

Domande frequenti

Come ottengo l’uso dei token in streaming con le chat completions?

Invia stream_options con include_usage impostato a true. Subito prima di data: [DONE] arriva un chunk in più, con usage compilato e un array choices vuoto. Se lo stream si interrompe prima, quel chunk non arriva mai.

Perché curl stampa tutta la risposta in streaming in una volta?

Per impostazione predefinita curl mette l’output in buffer. Aggiungi l’opzione -N (nessun buffering) così ogni Server-Sent Event viene stampato appena arriva.

Uno stream ritentato viene fatturato due volte?

A consumo, sì. Un retry è una nuova richiesta di inferenza. Con un piano illimitato DeepSeek V4.1 Flash non c’è un contatore di token, ma il retry occupa comunque la sessione mentre è in corso.

Lo streaming costa più di una richiesta normale?

No. Lo streaming cambia il modo in cui la risposta viene consegnata, non come viene fatturata. A consumo paghi gli stessi prezzi per token di input e di output di una richiesta senza streaming.

Leggi in MarkdownChiedi a ChatGPTChiedi a ClaudeChiedi a Perplexity