Streaming SSE
In questa pagina
Risposte in tempo reale con Server-Sent Events
Per impostazione predefinita, l’API Chat Completions attende che il modello abbia terminato di generare l’intera risposta prima di inviartela. Per una domanda breve, nessuno nota il ritardo. Per un rapporto di mille parole, invece, significa diversi secondi di schermo vuoto, lasciando l’utente a chiedersi se l’applicazione si sia bloccata. Lo streaming risolve questo problema inviando i token man mano che vengono generati, creando il familiare effetto macchina da scrivere visibile nelle interfacce conversazionali.
Il protocollo utilizzato è Server-Sent Events (SSE), uno standard HTTP che consente al server di inviare dati al client in modo continuo su una connessione persistente. Non c’è nulla di esotico qui: niente WebSocket da installare, nessuna dipendenza extra.
Streaming vs non-streaming
In modalità non-streaming, che è quella predefinita, il client invia la richiesta e attende la risposta completa:
Client ──── request ────► Server
(wait 3-10s)
Client ◄── complete response ── Server
Il vantaggio è la semplicità: la risposta è atomica, un singolo oggetto JSON facile da elaborare, validare e archiviare. Lo svantaggio è altrettanto chiaro: la latenza percepita è elevata perché l’utente non vede nulla durante l’intero processo di generazione.
In modalità streaming, il server invia i token uno per uno, o in piccoli gruppi:
Client ──── request ────► Server
Client ◄── chunk 1 ─────── Server (after ~200ms)
Client ◄── chunk 2 ─────── Server (after ~250ms)
Client ◄── chunk 3 ─────── Server (after ~300ms)
...
Client ◄── [DONE] ──────── Server
La latenza percepita crolla drasticamente: il primo carattere appare entro poche centinaia di millisecondi, migliorando significativamente l’esperienza utente. In cambio, devi ricostruire il messaggio lato client e gestire uno stato che non arriva più come un blocco unico.
Il protocollo SSE nel dettaglio
Ecco come appare effettivamente il flusso HTTP che ricevi:
data: {"id":"cmpl-abc","choices":[{"delta":{"content":"Hello"}}],"usage":null}
data: {"id":"cmpl-abc","choices":[{"delta":{"content":" "}}],"usage":null}
data: {"id":"cmpl-abc","choices":[{"delta":{"content":"!"}}],"usage":null}
data: [DONE]
Ogni riga inizia con data: seguito da un oggetto JSON, e le righe vuote fungono da separatori tra gli eventi. Nota il dettaglio che intrappola tutti alla prima implementazione: il frammento di testo si trova nel campo delta, non in message come nella modalità classica. Il flusso termina con un evento data: [DONE], che segnala esplicitamente la fine. Senza di esso, non saresti in grado di distinguere una generazione terminata da una connessione interrotta.
Abilitare lo streaming in Python
Con l’SDK Mistral, abiliti lo streaming chiamando chat.stream() invece di chat.complete():
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))
stream = client.chat.stream(
model="mistral-large-latest",
messages=[
{"role": "user", "content": "Explain how an electric motor works."}
]
)
for chunk in stream:
content = chunk.data.choices[0].delta.content
if content:
print(content, end="", flush=True)
print() # Final newline
L’argomento flush=True merita una spiegazione, poiché dimenticarlo è la causa classica di uno streaming che “non funziona”. Senza di esso, Python mantiene i caratteri nel buffer e li visualizza a blocchi. Questo annulla visivamente tutti i benefici dello streaming, anche se i chunk stanno arrivando correttamente.
Struttura di un chunk
Un chunk in streaming non si legge come una risposta completa e i percorsi di accesso differiscono:
# Non-streaming: response.choices[0].message.content
# Streaming: chunk.data.choices[0].delta.content
# Il primo chunk contiene spesso il ruolo
# chunk.data.choices[0].delta.role == "assistant"
# I chunk successivi contengono frammenti di testo
# chunk.data.choices[0].delta.content == "Hello"
# L'ultimo chunk contiene finish_reason
# chunk.data.choices[0].finish_reason == "stop"
Il primo chunk solitamente trasporta il ruolo senza testo, quelli successivi trasportano i frammenti e l’ultimo fornisce il finish_reason. Ecco perché il controllo if content: nel codice precedente non è una precauzione inutile: concatenare un valore None farebbe fallire il loop alla prima iterazione.
Ricostruire la risposta completa
Visualizzare i frammenti non basta quando hai bisogno di conservare la risposta, ad esempio per aggiungerla alla cronologia della conversazione, registrarla o archiviarla in un database. Devi quindi accumulare il testo parallelamente alla sua visualizzazione:
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))
stream = client.chat.stream(
model="mistral-large-latest",
messages=[{"role": "user", "content": "List 5 programming languages."}]
)
full_response = ""
finish_reason = None
for chunk in stream:
delta = chunk.data.choices[0].delta
if delta.content:
full_response += delta.content
print(delta.content, end="", flush=True)
if chunk.data.choices[0].finish_reason:
finish_reason = chunk.data.choices[0].finish_reason
print(f"\n\nFinish reason: {finish_reason}")
print(f"Complete response ({len(full_response)} characters)")
La variabile finish_reason viene catturata nello stesso loop per la stessa ragione della modalità classica: una risposta troncata da max_tokens appare sullo schermo esattamente come una risposta completa, e solo questo campo ti dirà la differenza.
Quando usare lo streaming
Lo streaming non è sempre migliore. È indicato ogni volta che un umano sta guardando lo schermo, ma superfluo o addirittura dannoso quando una macchina elabora l’output.
| Caso d’uso | Raccomandazione |
|---|---|
| Chatbot interattivo | Streaming (migliore UX) |
| Elaborazione batch | Non-streaming (più semplice) |
| API backend per frontend | Streaming (SSE al browser) |
| Pipeline dati | Non-streaming (elaborazione atomica) |
| Estrazione strutturata | Non-streaming (parsing JSON più affidabile) |
L’ultimo caso è il più istruttivo. Se ti aspetti un JSON, lo streaming non aggiunge nulla: non puoi analizzare un oggetto incompleto e dovrai comunque attendere l’ultimo frammento. Tanto vale mantenere la chiamata atomica e il codice semplice.
Punti chiave
- Lo streaming riduce la latenza percepita inviando i token man mano che vengono generati
- Il protocollo SSE è uno standard HTTP semplice e robusto
- In modalità streaming, usa
delta.contentinvece dimessage.content - Accumula i frammenti lato client per ricostruire la risposta completa
- Preferisci lo streaming per le interfacce utente e il non-streaming per l’elaborazione automatizzata