Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Implementare lo streaming in Python

Lezione 6 di 16 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Dal prototipo alla produzione
  2. Il pattern di base
  3. Gestione completa degli errori
  4. Streaming asincrono con asyncio
  5. Integrazione con FastAPI
  6. Misurazione delle prestazioni
  7. Punti chiave

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_async per le applicazioni web concorrenti
  • Misura il TTFT e i token/secondo per ottimizzare le prestazioni
  • Con FastAPI, StreamingResponse + text/event-stream propaga gli SSE al browser