Implementare lo streaming in Python
In questa pagina
Dal prototipo alla produzione
La lezione precedente ha trattato i concetti dello streaming SSE. La parte più difficile resta da fare: trasformare un loop dimostrativo in un client capace di reggere il carico, sopravvivere agli errori di rete e alimentare un’interfaccia web. Questa lezione segue la traiettoria reale di un progetto: prima lo scheletro, poi la gestione degli errori, quindi l’asincronia, l’esposizione HTTP e infine la misurazione.
Il pattern di base
Tutto inizia con questo scheletro di dieci righe, che adatterai per ogni progetto. Fa due cose contemporaneamente: visualizza i token man mano che arrivano e li accumula per il ritorno della funzione.
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))
def stream_chat(messages: list, model: str = "mistral-large-latest") -> str:
"""Invia una richiesta streaming e visualizza i token in tempo reale."""
stream = client.chat.stream(
model=model,
messages=messages
)
full_text = ""
for chunk in stream:
content = chunk.data.choices[0].delta.content
if content:
full_text += content
print(content, end="", flush=True)
print() # Nuova riga
return full_text
Questa versione funziona per uno script locale. Presenta però un difetto fatale in produzione: stampa sul terminale, quindi non può fare altro che lavoro da terminale.
Gestione completa degli errori
Errori di rete, timeout e limiti di frequenza non sono ipotesi: sono certezze a scala di traffico reale. Il client sottostante risolve entrambi i problemi. Ritenta automaticamente gli errori 429 con un backoff esponenziale e non stampa più nulla: emette eventi tipizzati tramite yield, lasciando al chiamante la decisione su cosa farne: visualizzarli, inviarli a un WebSocket o scriverli in un database.
from mistralai.client import Mistral
from mistralai.client.errors import SDKError
import os
import time
client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))
def stream_with_retry(
messages: list,
model: str = "mistral-large-latest",
max_retries: int = 3,
max_tokens: int = 2000
) -> dict:
"""Streaming con ritento automatico e metriche."""
for attempt in range(max_retries):
try:
stream = client.chat.stream(
model=model,
messages=messages,
max_tokens=max_tokens
)
full_text = ""
finish_reason = None
chunk_count = 0
for chunk in stream:
delta = chunk.data.choices[0].delta
if delta.content:
full_text += delta.content
chunk_count += 1
yield {"type": "token", "content": delta.content}
if chunk.data.choices[0].finish_reason:
finish_reason = chunk.data.choices[0].finish_reason
yield {
"type": "done",
"full_text": full_text,
"finish_reason": finish_reason,
"chunks": chunk_count
}
return
except SDKError as e:
if e.status_code == 429 and attempt < max_retries - 1:
wait_time = 2 ** attempt # Backoff esponenziale
yield {"type": "retry", "wait": wait_time, "attempt": attempt + 1}
time.sleep(wait_time)
else:
yield {"type": "error", "message": str(e), "status": e.status_code}
return
except Exception as e:
yield {"type": "error", "message": str(e), "status": None}
return
Il backoff esponenziale 2 ** attempt attende 1 secondo, poi 2, poi 4. Questa progressione non è decorativa: se tutti i tuoi client ritentassero con lo stesso ritmo fisso, colpirebbero le API in burst sincronizzati, prolungando proprio la saturazione da cui stanno soffrendo. Nota inoltre che solo l’errore 429 attiva un ritento: ritentare un 401 dovuto a una chiave non valida ritarderebbe solo la diagnosi.
Lato chiamante, il consumo diventa una semplice lettura di eventi:
messages = [
{"role": "system", "content": "You are a technical assistant."},
{"role": "user", "content": "Explain design patterns in Python."}
]
for event in stream_with_retry(messages):
if event["type"] == "token":
print(event["content"], end="", flush=True)
elif event["type"] == "retry":
print(f"\n[Ritento {event['attempt']}, attesa di {event['wait']}s...]")
elif event["type"] == "done":
print(f"\n\n--- Completato ({event['chunks']} chunk, {event['finish_reason']})")
elif event["type"] == "error":
print(f"\n[Errore: {event['message']}]")
Streaming asincrono con asyncio
Il client sincronico blocca il suo thread per l’intera generazione. Su un server web che deve gestire cinquanta conversazioni simultanee, ciò significa immobilizzare cinquanta thread solo per attendere. Il client asincrono rimuove questo vincolo:
from mistralai.client import Mistral
import asyncio
import os
client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))
async def async_stream_chat(messages: list) -> str:
"""Streaming asincrono per applicazioni concorrenti."""
stream = await client.chat.stream_async(
model="mistral-large-latest",
messages=messages
)
full_text = ""
async for chunk in stream:
content = chunk.data.choices[0].delta.content
if content:
full_text += content
print(content, end="", flush=True)
print()
return full_text
# Esecuzione
async def main():
messages = [{"role": "user", "content": "Hello, introduce yourself."}]
result = await async_stream_chat(messages)
print(f"\nTotale: {len(result)} caratteri")
asyncio.run(main())
La logica è identica alla versione sincrona; cambiano solo stream_async, l’await sulla chiamata e l’async for sul loop.
Integrazione con FastAPI
Successivamente, devi far uscire questo stream dal tuo processo Python per portarlo nel browser. FastAPI gestisce questo aspetto con StreamingResponse, a patto di riformattare ogni frammento nel formato SSE visto nella lezione precedente:
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
from mistralai.client import Mistral
import os
import json
app = FastAPI()
client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))
async def generate_stream(prompt: str):
"""Generatore SSE per FastAPI."""
stream = await client.chat.stream_async(
model="mistral-large-latest",
messages=[{"role": "user", "content": prompt}]
)
async for chunk in stream:
content = chunk.data.choices[0].delta.content
if content:
data = json.dumps({"content": content})
yield f"data: {data}\n\n"
yield "data: [DONE]\n\n"
@app.get("/chat/stream")
async def chat_stream(prompt: str):
return StreamingResponse(
generate_stream(prompt),
media_type="text/event-stream"
)
Due dettagli determinano il corretto funzionamento di questo endpoint. Il doppio newline \n\n che termina ogni yield è ciò che separa gli eventi nel protocollo SSE: senza di esso, il browser attende indefinitamente un evento che considera incompleto. E media_type="text/event-stream" è ciò che permette al client JavaScript di consumare la risposta con un EventSource piuttosto che con un normale fetch.
Misurazione delle prestazioni
Una volta attivato lo stream, vorrai sapere come si comporta. Due metriche sono sufficienti per guidare l’ottimizzazione:
import time
start = time.perf_counter()
first_token_time = None
token_count = 0
stream = client.chat.stream(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Write a paragraph about Paris."}]
)
for chunk in stream:
if chunk.data.choices[0].delta.content:
if first_token_time is None:
first_token_time = time.perf_counter() - start
token_count += 1
total_time = time.perf_counter() - start
print(f"Time to First Token (TTFT): {first_token_time:.3f}s")
print(f"Token generati: {token_count}")
print(f"Tempo totale: {total_time:.3f}s")
print(f"Token/secondo: {token_count / total_time:.1f}")
Il TTFT (Time to First Token) — il tempo tra l’invio della richiesta e la visualizzazione del primo carattere — è la metrica più importante per l’esperienza utente. Ha la priorità sul tempo totale: una generazione di quindici secondi la cui prima parola appare in tre decimi di secondo sembrerà veloce, mentre una generazione di cinque secondi fornita in un unico blocco sembrerà lenta. Misuralo sui tuoi prompt reali, messaggio di sistema incluso: un messaggio di sistema lungo due pagine allunga il TTFT prima ancora che il primo token venga generato.
Punti chiave
- Usa un pattern generatore (
yield) per propagare i token in streaming - Implementa un backoff esponenziale per gli errori 429 (limite di frequenza)
- Preferisci
stream_asyncper le applicazioni web concorrenti - Misura il TTFT e i token/secondo per ottimizzare le prestazioni
- Con FastAPI,
StreamingResponse+text/event-streampropaga gli SSE al browser