Mostrare in streaming la risposta di un LLM nel browser con Server-Sent Events (FastAPI + fetch)
La risposta del modello parola per parola: un endpoint FastAPI che inoltra Ollama come SSE, codice browser che la legge con fetch e POST, e un pulsante Stop vero.

Un modello linguistico scrive la risposta un pezzo alla volta. Se la pagina web aspetta la risposta completa, l'utente fissa un'icona di caricamento per dieci o venti secondi. Con lo streaming, le prime parole compaiono appena il modello le produce e l'utente può fermare subito una risposta sbagliata. Questa guida costruisce tutto il percorso: un server del modello, un piccolo backend Python e il codice browser che mostra il testo mentre arriva, con un pulsante Stop che ferma davvero il modello.
Lo stack: FastAPI 0.162.0 con il supporto nativo ai Server-Sent Events, httpx 0.28.1 per chiamare il modello e JavaScript semplice nel browser. Il modello gira in locale con Ollama, quindi puoi provare tutto senza chiave API. Versioni verificate su PyPI il 30 ottobre 2026.
Perché Server-Sent Events
Server-Sent Events (SSE) è un formato di testo semplice dentro una normale risposta HTTP con Content-Type: text/event-stream. Il server scrive piccoli blocchi di righe campo: valore, ogni blocco termina con una riga vuota e la connessione resta aperta:
event: token
data: {"text": "Light "}
event: token
data: {"text": "is "}
event: done
data: {"prompt_tokens": 12, "output_tokens": 9}
Il formato è definito nello standard HTML, sezione 9.2. Va in una sola direzione, dal server al browser, ed è proprio quello che serve per una risposta in streaming. È HTTP normale e lo usano anche le API dei modelli in cloud: la Messages API di Anthropic, per esempio, fa streaming con SSE. Anche i WebSocket funzionerebbero, ma aggiungono un secondo protocollo allo stack per un lavoro che non ne ha bisogno.
Perché non EventSource
I browser hanno un client SSE integrato, EventSource. Il suo costruttore accetta solo un URL e un'opzione, withCredentials (vedi il dizionario EventSourceInit nello standard). Questo significa che:
- invia sempre una richiesta GET, quindi il prompt dovrebbe stare nell'URL, dove finisce nei log del server e nella cronologia del browser, e i prompt lunghi superano i limiti di lunghezza degli URL;
- non puoi aggiungere intestazioni come
Authorization; - si riconnette da solo quando la connessione cade, e per una risposta di chat questo vuol dire generare di nuovo la stessa risposta, e pagarla di nuovo.
Per la chat usiamo quindi fetch() con un corpo POST e leggiamo noi lo stream della risposta. Servono una cinquantina di righe di codice.
Il backend: FastAPI inoltra Ollama come SSE
L'endpoint di chat di Ollama, POST /api/chat, fa streaming per impostazione predefinita. Non usa SSE: invia un oggetto JSON per riga, ognuno con un pezzo di message.content, e un oggetto finale con "done": true e i conteggi dei token (prompt_eval_count, eval_count). Il nostro backend legge quelle righe e le rimanda come eventi SSE con tre nomi: token, done ed error.
Dalla versione 0.135.0 FastAPI ha il supporto nativo a SSE: imposti response_class=EventSourceResponse e fai yield degli eventi dall'endpoint.
import json
import os
from collections.abc import AsyncIterable
import httpx
from fastapi import FastAPI
from fastapi.sse import EventSourceResponse, ServerSentEvent
from pydantic import BaseModel
OLLAMA_URL = os.environ.get("OLLAMA_URL", "http://localhost:11434")
MODEL = os.environ.get("OLLAMA_MODEL", "llama3.2")
app = FastAPI()
http = httpx.AsyncClient(timeout=httpx.Timeout(10.0, read=120.0))
class Prompt(BaseModel):
text: str
@app.post("/api/chat/stream", response_class=EventSourceResponse)
async def chat_stream(prompt: Prompt) -> AsyncIterable[ServerSentEvent]:
body = {"model": MODEL, "messages": [{"role": "user", "content": prompt.text}], "stream": True}
try:
async with http.stream("POST", f"{OLLAMA_URL}/api/chat", json=body) as upstream:
if upstream.status_code != 200:
detail = (await upstream.aread()).decode(errors="replace")[:300]
yield ServerSentEvent(data={"status": upstream.status_code, "detail": detail}, event="error")
return
async for line in upstream.aiter_lines(): # Ollama streams one JSON object per line
if not line:
continue
chunk = json.loads(line)
if chunk.get("done"):
yield ServerSentEvent(data={"prompt_tokens": chunk.get("prompt_eval_count"),
"output_tokens": chunk.get("eval_count")}, event="done")
return
text = chunk.get("message", {}).get("content", "")
if text:
yield ServerSentEvent(data={"text": text}, event="token")
except httpx.HTTPError as exc:
yield ServerSentEvent(data={"detail": type(exc).__name__}, event="error")
Alcuni punti da notare:
- Gli errori viaggiano dentro lo stream. Quando il primo byte della risposta SSE è partito, lo stato HTTP è già 200 e non può più cambiare. Un modello inesistente (Ollama risponde 404) o una connessione persa devono diventare un evento
errorche il browser capisce. - Il campo
dataè JSON. FastAPI codificadatain JSON, quindi un token che contiene un a capo o le virgolette arriva intatto. Se ti serve inviare testo così com'è,ServerSentEventha ancheraw_data. - Il timeout di lettura è lungo, quello di connessione è breve. Un modello può impiegare molti secondi prima del primo token, soprattutto quando deve essere caricato in memoria. Il fallimento della connessione, invece, deve arrivare presto.
- FastAPI si occupa delle parti noiose. Secondo la documentazione imposta
Cache-Control: no-cache, inviaX-Accel-Buffering: noperché Nginx non trattenga lo stream e invia un commento di keep-alive ogni 15 secondi quando non c'è altro da mandare. Lo standard HTML raccomanda quel keep-alive perché alcuni proxy chiudono le connessioni inattive.
Lo stesso schema funziona con l'API di un modello in cloud: sostituisci la chiamata a Ollama con la chiamata in streaming del tuo fornitore e tieni i tre nomi di evento. La chiave API resta sul server: il browser parla solo con il tuo backend.
Il browser: leggere SSE da fetch
fetch() fornisce il corpo della risposta come uno stream di byte. TextDecoderStream lo trasforma in testo, e il resto è l'algoritmo di parsing dello standard HTML, "Interpreting an event stream": dividere in righe (CRLF, LF o CR), ignorare le righe che iniziano con i due punti, raccogliere le righe data e consegnare l'evento alla riga vuota.
export async function* readSSE(response) {
const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
let buffer = '';
let type = '', data = [], id = null;
try {
while (true) {
const { value, done } = await reader.read();
if (done) return; // an event without its final blank line is discarded, as the spec says
buffer += value;
// Split on CRLF, LF or CR; a CR at the very end may be the first half of a CRLF, so keep it.
const lines = buffer.split(/\r\n|\r(?!$)|\n/);
buffer = lines.pop();
for (const line of lines) {
if (line === '') { // blank line: dispatch the event
if (data.length) yield { event: type || 'message', data: data.join('\n'), id };
type = ''; data = [];
continue;
}
if (line.startsWith(':')) continue; // comment, e.g. keep-alive pings
const i = line.indexOf(':');
const field = i === -1 ? line : line.slice(0, i);
let val = i === -1 ? '' : line.slice(i + 1);
if (val.startsWith(' ')) val = val.slice(1);
if (field === 'data') data.push(val);
else if (field === 'event') type = val;
else if (field === 'id' && !val.includes('\0')) id = val;
}
}
} finally {
reader.releaseLock();
}
}
Il dettaglio che sfugge a molti parser scritti a mano: i pezzi che arrivano dalla rete non rispettano i confini degli eventi. Un pezzo può finire a metà riga, oppure tra il \r e il \n di un fine riga. Per questo il codice tiene l'ultima riga incompleta in buffer e non divide su un \r che si trova proprio alla fine. TextDecoderStream risolve lo stesso problema un livello più in basso, per i caratteri UTF-8 di più byte spezzati tra due pezzi.
Poi una piccola funzione invia il prompt e trasforma gli eventi in callback:
export async function streamChat(url, prompt, { onToken, signal } = {}) {
const res = await fetch(url, {
method: 'POST',
headers: { 'content-type': 'application/json', accept: 'text/event-stream' },
body: JSON.stringify({ text: prompt }),
signal,
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
for await (const ev of readSSE(res)) {
const payload = JSON.parse(ev.data);
if (ev.event === 'token') onToken?.(payload.text);
else if (ev.event === 'error') throw new Error(`model error: ${JSON.stringify(payload)}`);
else if (ev.event === 'done') return payload; // token counts reported by the model server
}
throw new Error('stream ended before the "done" event');
}
Tratta come errore uno stream che finisce senza done. Proxy, bilanciatori di carico e riavvii del server possono tagliare una risposta a metà, e senza quel controllo una risposta troncata sembra completa.
Mostrare il testo e il pulsante Stop
Nella pagina, aggiungi ogni pezzo come testo, non come HTML:
const controller = new AbortController();
stop.addEventListener('click', () => controller.abort());
const usage = await streamChat('/api/chat/stream', promptText, {
onToken: (t) => out.append(t), // text node: never innerHTML with model output
signal: controller.signal,
});
element.append(stringa) crea un nodo di testo, quindi se il modello scrive <img src=x onerror=...> vedi quei caratteri invece di eseguirli. Se mostri Markdown, passa prima l'output in un sanitizer. L'output di un modello è un input non fidato, come qualunque cosa scritta da un utente.
Quando l'utente preme Stop, controller.abort() annulla la fetch. Il browser chiude la connessione, Uvicorn si accorge della disconnessione, il generatore dell'endpoint viene annullato e il blocco async with chiude la connessione verso Ollama. Un modello locale smette di calcolare; con un'API a pagamento smetti di pagare token che nessuno leggerà. Il nostro test verifica tutta la catena: dopo l'annullamento, il finto server del modello vede il client andarsene prima della fine della risposta.
Provarlo senza un modello
La cartella dell'esempio contiene fake_ollama.py, 65 righe con la sola libreria standard di Python che imitano l'endpoint in streaming di Ollama. ./test_stream.sh lo avvia insieme a due copie del backend ed esegue lo stesso sse-client.js usato dalla pagina, questa volta in Node.js. Controlla quattro cose:
- il parser gestisce eventi divisi tra più pezzi, un CRLF spezzato tra due pezzi, i commenti e
datasu più righe; - la risposta completa arriva in ordine, seguita dai conteggi dei token;
- un modello sconosciuto (404 da Ollama) arriva al browser come evento
error; - annullare dopo il primo token chiude la connessione verso il server del modello.
stream-sse OK { prompt_tokens: 12, output_tokens: 9 } { completed: 1, client_closed: 1 }
Lo stesso test gira in GitHub Actions a ogni modifica. Per provarlo con un modello vero: ollama pull llama3.2, poi uvicorn server:app --port 8000, e apri http://localhost:8000/.
Cosa rompe lo streaming in produzione
Il codice sopra funziona sul tuo portatile. In produzione capita spesso che qualcosa tra il browser e il server raccolga tutta la risposta prima di inoltrarla, e la risposta compare tutta insieme alla fine. Controlla in quest'ordine:
- Reverse proxy. Nginx mette in buffer le risposte inoltrate, a meno che non gli si dica altrimenti. La sua documentazione di
proxy_bufferingdice che l'intestazione di rispostaX-Accel-Buffering: nodisattiva il buffer, e FastAPI la invia; altri proxy e CDN hanno le proprie impostazioni di buffer e di timeout. - Compressione. Uno strato di compressione può aspettare abbastanza byte prima di inviare un blocco compresso. Se i token arrivano a raffiche, disattiva la compressione per le risposte
text/event-streame riprova. - Timeout di inattività. I bilanciatori di carico chiudono le connessioni che restano in silenzio troppo a lungo. Il commento di keep-alive ogni 15 secondi aiuta, ma un modello che ragiona a lungo prima del primo token può comunque incontrare un timeout breve.
- Limite di connessioni con HTTP/1.1. MDN segnala che senza HTTP/2 i browser permettono solo sei connessioni aperte per dominio, condivise tra tutte le schede. Un utente con diverse schede di chat aperte può bloccare le proprie richieste. Servi l'applicazione in HTTP/2 o chiudi gli stream quando finiscono.
- CORS. Se la pagina e l'API stanno su origini diverse, la POST con corpo JSON provoca una richiesta preliminare (preflight) a cui l'API deve rispondere. Il nostro tester di richieste HTTP invia una richiesta dal tuo browser e spiega gli errori CORS in parole semplici. Per i codici di stato che puoi incontrare lungo la strada, vedi il riferimento dei codici di stato HTTP.
Limiti di questo approccio
- Nessuna ripresa automatica. Se la connessione cade a metà, la risposta è persa e l'utente deve chiedere di nuovo. La documentazione di FastAPI mostra come riprendere con gli ID degli eventi e l'intestazione
Last-Event-ID, ma per l'output di un modello funziona solo se il server conserva il testo generato. - Connessioni lunghe. Ogni risposta tiene aperte due connessioni per tutta la sua durata (dal browser al backend, dal backend al modello). Dimensiona limiti di connessione, numero di worker e timeout dei proxy sul numero di risposte in streaming contemporanee, non sulle richieste al secondo.
- I limiti di frequenza valgono comunque. Una chiamata in streaming può fallire con 429 prima del primo token come qualsiasi altra chiamata; la nostra guida su HTTP 429 e Retry-After mostra come ripeterla.
L'esempio completo e testato di questo articolo è nel nostro repository pubblico: adamant-solutions/ai-dev-examples/stream-sse