Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Risposte in streaming in Python

Lezione 6 di 14 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Il problema risolto dallo streaming
  2. Utilizzo di chat.stream()
  3. Cosa contiene un chunk
  4. Visualizzare e salvare simultaneamente
  5. La variante asincrona
  6. Quando usare lo streaming e quando evitarlo
  7. Punti chiave

Il problema risolto dallo streaming

Con chat.complete(), attendi che il modello generi l’intera risposta prima di ricevere anche un solo carattere. Per una risposta breve, questo ritardo passa inosservato. Ma per un’analisi dettagliata, uno snippet di codice lungo o un ragionamento su più paragrafi, l’utente fissa uno schermo vuoto per diversi secondi. In un’interfaccia di chat, anche pochi secondi di silenzio possono far sembrare l’applicazione bloccata.

Lo streaming cambia questa percezione: la risposta arriva in modo incrementale, pezzo per pezzo, e viene visualizzata progressivamente proprio come nelle interfacce di chat che conosci. Il tempo totale di generazione non diminuisce di un millisecondo, ma la prima parola appare quasi immediatamente. È quel ritardo iniziale che l’utente percepisce realmente.

Utilizzo di chat.stream()

L’SDK Mistral V2 espone il metodo chat.stream(), che restituisce un iteratore di chunk invece di un singolo oggetto:

import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

stream = client.chat.stream(
    model="mistral-small-latest",
    messages=[
        {
            "role": "user",
            "content": "Describe the steps to deploy a Flask application on a Linux server."
        }
    ]
)

for chunk in stream:
    content = chunk.data.choices[0].delta.content
    if content:
        print(content, end="", flush=True)

# Final newline
print()

Due dettagli fanno tutta la differenza in questo ciclo. Il controllo if content è essenziale perché alcuni chunk arrivano senza testo e, altrimenti, stamperemmo None. Inoltre, flush=True forza Python a scrivere immediatamente sull’output invece di attendere che il buffer si riempia. Senza di esso, tutto il testo apparirebbe in un unico blocco alla fine, annullando completamente il vantaggio che stai cercando.

Aspettochat.complete()chat.stream()
RitornoOggetto completoIteratore di chunk
Latenza percepitaAlta (attesa totale)Bassa (primo token veloce)
Accesso al testoresponse.choices[0].message.contentchunk.data.choices[0].delta.content
Utilizzo dei tokenDisponibile nella rispostaDisponibile nell’ultimo chunk

Cosa contiene un chunk

Ogni chunk trasporta un delta, ovvero un frammento della risposta in costruzione. Ispezionandolo, accedi sia al testo che ai metadati di fine stream:

for chunk in stream:
    delta = chunk.data.choices[0].delta

    # Contenuto testuale (può essere None per alcuni chunk)
    text = delta.content

    # Motivo di arresto (None tranne che per l'ultimo chunk)
    end = chunk.data.choices[0].finish_reason

    if text:
        print(text, end="", flush=True)

    if end:
        print(f"\n[Stream end: {end}]")

Il flusso segue sempre la stessa coreografia: il primo chunk solitamente contiene il ruolo assistant, i chunk intermedi forniscono il testo in piccoli pezzi e l’ultimo fornisce il finish_reason. Verificando questo chunk finale, determini se la risposta è terminata normalmente o è stata interrotta da max_tokens.

Visualizzare e salvare simultaneamente

Lo streaming ha uno svantaggio: il testo scorre via, ma non lo trattieni da nessuna parte. Eppure, un’applicazione reale spesso necessita di archiviare la risposta in un database per la cronologia delle conversazioni. La soluzione consiste nell’accumulare i frammenti mentre li visualizzi:

import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

stream = client.chat.stream(
    model="mistral-small-latest",
    messages=[
        {"role": "user", "content": "List five Python web frameworks."}
    ]
)

full_response = []

for chunk in stream:
    content = chunk.data.choices[0].delta.content
    if content:
        full_response.append(content)
        print(content, end="", flush=True)

print()

# La risposta completa ricostruita
final_text = "".join(full_response)
print(f"\nTotal length: {len(final_text)} characters")

Nota l’uso di una lista seguita da un "".join() finale invece della concatenazione di stringhe a ogni iterazione del ciclo. Per una risposta lunga, quest’ultimo approccio copia tutto il testo accumulato per ogni frammento ricevuto, risultando inefficiente.

La variante asincrona

In un server web (FastAPI, aiohttp), la versione sincrona blocca il thread durante l’intera generazione, congelando altre richieste in corso. L’SDK fornisce quindi chat.stream_async():

import asyncio
import os
from mistralai.client import Mistral

async def generate_response():
    client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

    stream = await client.chat.stream_async(
        model="mistral-small-latest",
        messages=[
            {"role": "user", "content": "Explain the concept of a coroutine in Python."}
        ]
    )

    async for chunk in stream:
        content = chunk.data.choices[0].delta.content
        if content:
            print(content, end="", flush=True)

    print()

asyncio.run(generate_response())

La struttura è identica alla versione sincrona, a parte le parole chiave await e async for. Non appena il tuo codice viene eseguito in un server web, questa è la variante che devi utilizzare.

Quando usare lo streaming e quando evitarlo

In un’interfaccia di chat, lo streaming è sempre obbligatorio: è in gioco il comfort di lettura. Sul lato delle API backend, vale la pena abilitarlo purché il tuo frontend possa consumare gli eventi Server-Sent. Per qualsiasi risposta più lunga di poche frasi, il guadagno in termini di latenza percepita giustifica la complessità aggiuntiva. Al contrario, in uno script batch che elabora migliaia di documenti e scrive i risultati su file, nessuno sta guardando lo schermo: chat.complete() rimane più semplice e perfettamente adeguato.

Punti chiave

  • chat.stream() restituisce un iteratore di chunk per la visualizzazione progressiva
  • Il contenuto si trova in chunk.data.choices[0].delta.content
  • Usa flush=True nelle tue chiamate print() per la visualizzazione in tempo reale
  • Ricostruisci la risposta completa accumulando i chunk se necessario
  • La versione asincrona chat.stream_async() è consigliata per le applicazioni web