BroadRouter
Inizia

Server-sent events (SSE)

Aggiornato

I server-sent events (SSE) sono uno standard web con cui un server invia a un client un flusso di eventi testuali su un’unica risposta HTTP di lunga durata, con content type text/event-stream. Ogni evento è composto da una o più righe di campo, come data:, ed è chiuso da una riga vuota.

Detto anche: SSE, server-sent events, eventi inviati dal server, streaming SSE, text/event-stream, event stream, EventSource

SSE è l’impaginazione in testo semplice che sta sotto quasi ogni risposta LLM in streaming. Conoscere il formato aiuta quando non hai un SDK o quando uno stream si comporta in modo strano.

Come funziona

Il formato è definito dallo standard HTML del WHATWG. La risposta ha tipo MIME text/event-stream ed è sempre in UTF-8. Il body è fatto di righe campo: valore:

: keep-alive comment, ignored by clients

event: update
id: 42
data: first line
data: second line

data: {"choices":[{"delta":{"content":"Hi"}}]}

data: [DONE]

Le regole di parsing che contano:

  • Una riga vuota invia l’evento. Finché non arriva, il client tiene tutto in buffer.
  • Più righe data: si uniscono con un a capo in un unico messaggio.
  • Una riga che inizia con i due punti è un commento. I server li inviano per tenere aperte le connessioni inattive.
  • Uno spazio dopo i due punti viene rimosso. Le righe possono terminare con CRLF, LF o CR.
  • event, id e retry impostano il tipo di evento, l’ID dell’ultimo evento e il ritardo di riconnessione in millisecondi.

Le letture dalla rete non coincidono con gli eventi. Una lettura può contenere mezzo evento o tre eventi, quindi un parser deve accumulare i byte e dividere sulle righe vuote, non sulle letture.

Riconnessione, proxy e [DONE]

Lo standard prevede un meccanismo di recupero per i browser: dopo un’interruzione, EventSource si riconnette e invia un header Last-Event-ID, e un server può fermare i tentativi con HTTP 204. La specifica avverte anche che i “legacy proxy servers” (proxy server legacy) possono chiudere le connessioni HTTP dopo un breve timeout, e suggerisce una riga di commento “every 15 seconds or so” (ogni 15 secondi circa).

Le API LLM usano meno di tutto questo. Lo stream di Chat Completions di OpenAI invia solo righe data: e termina con data: [DONE], una convenzione dell’API, non di SSE. Non c’è un ID evento da cui ripartire, quindi uno stream interrotto non si può continuare; un nuovo tentativo è una nuova richiesta. Il quadro generale dello streaming e il vantaggio sul time to first token sono trattati in quella pagina.

Su BroadNet Inference

La documentazione di BroadNet dice di impostare stream=true e di “read Server-Sent Events until the literal data: [DONE] marker” (traduzione: leggere i Server-Sent Events fino al marcatore letterale data: [DONE]). Se la connessione si chiude prima, considera la risposta incompleta, registra l’header X-Request-ID e decidi se una nuova richiesta di inferenza è sicura. Con stream_options: {"include_usage": true}, l’usage arriva nell’ultimo chunk. L’esempio curl della documentazione usa -N perché curl non faccia buffering. Uno stream occupa anche uno slot di concorrenza finché non finisce: 4 con una chiave a consumo, uno con una chiave oraria. La documentazione chiede di verificare lo streaming modello per modello prima della produzione. Il codice per ogni SDK è nella guida allo streaming, e il contenuto dei chunk è spiegato in Lo streaming LLM spiegato.

Domande frequenti

Posso usare l’API EventSource del browser con un’API LLM?

Di solito non direttamente. Il costruttore EventSource della specifica accetta solo un URL e un flag withCredentials, quindi non può inviare un body POST né un header Authorization. Usa fetch e fai tu il parsing dello stream, oppure un SDK.

Cosa significa "data: [DONE]"?

Non fa parte dello standard SSE. Le API in stile OpenAI inviano la riga letterale "data: [DONE]" come ultimo evento per dire che la risposta è completa.

Perché il mio stream arriva tutto in una volta?

Qualcosa tra il server e il tuo codice sta mettendo in buffer la risposta, per esempio un reverse proxy, un framework o curl senza -N. Disattiva il buffering per quella rotta.

Leggi in MarkdownChiedi a ChatGPTChiedi a ClaudeChiedi a Perplexity