Thinking chunks: leggere il ragionamento del modello
In questa pagina
Lezione riscritta il 2 novembre 2026 sulla base della sezione Handling thinking chunks della documentazione Mistral. La versione precedente leggeva il ragionamento da un campo
textnel chunk di pensiero: tale campo non esiste; il ragionamento è una lista di chunk di testo.
Due forme di risposta
Con reasoning_effort="high", il campo message.content di una risposta non è più una stringa, ma una lista di chunk. Con reasoning_effort="none", torna a essere una semplice stringa, senza alcuna traccia del ragionamento. Un codice robusto gestisce sempre entrambe le forme: questa è la regola d’oro di questa lezione.
Anatomia di un thinking chunk
Nella lista compaiono due tipi di chunk:
ThinkChunk(type: "thinking") contiene la traccia del ragionamento. Il suo campothinkingè a sua volta una lista di frammentiTextChunk;TextChunk(type: "text") contiene la risposta finale, nel suo campotext.
Ecco la struttura di una risposta di Mistral Small 4, tratta dall’esempio ufficiale (testi abbreviati):
{
"model": "mistral-small-2603",
"usage": {"prompt_tokens": 77, "completion_tokens": 1114, "total_tokens": 1191},
"choices": [{
"finish_reason": "stop",
"message": {
"role": "assistant",
"content": [
{"type": "thinking", "thinking": [
{"type": "text", "text": "Okay, let's try to figure out John's age..."}
]},
{"type": "text", "text": "Let's denote the ages of the sisters as follows..."}
]
}
}]
}
Il modello oggetti dell’SDK Python segue esattamente questa struttura: ThinkChunk.thinking contiene i chunk del ragionamento, e ogni TextChunk espone il proprio contenuto tramite .text.
Analisi della risposta in Python
Il codice ufficiale distingue i chunk con isinstance, dopo aver escluso il caso della stringa semplice:
from mistralai.client.models import TextChunk, ThinkChunk
content = chat_response.choices[0].message.content
if isinstance(content, str): # reasoning_effort="none"
print(content)
else:
for chunk in content:
if isinstance(chunk, ThinkChunk):
print("--- reasoning ---")
for inner in chunk.thinking:
if isinstance(inner, TextChunk):
print(inner.text)
print("--- end of reasoning ---")
elif isinstance(chunk, TextChunk):
print(chunk.text)
In un’applicazione, vorrai una funzione che restituisca ragionamento e risposta separatamente. La chiameremo separate e la riutilizzeremo più avanti nel corso:
from mistralai.client.models import TextChunk, ThinkChunk
def separate(content):
"""Restituisce (ragionamento, risposta) per un contenuto che può essere una stringa o una lista di chunk."""
if isinstance(content, str):
return "", content
reasoning, answer = [], []
for chunk in content or []:
if isinstance(chunk, ThinkChunk):
reasoning.extend(i.text for i in chunk.thinking if isinstance(i, TextChunk))
elif isinstance(chunk, TextChunk):
answer.append(chunk.text)
return "".join(reasoning), "".join(answer)
reasoning, answer = separate(chat_response.choices[0].message.content)
Visualizzazione del ragionamento nell’interfaccia
Separare le due parti ti permette di decidere cosa mostrare all’utente. Tre approcci comuni:
- Nascondere il ragionamento e mostrare solo la risposta, per un assistente rivolto al grande pubblico;
- Comprimere il ragionamento in un blocco che l’utente può aprire se lo desidera, per uno strumento esperto;
- Mostrare tutto il ragionamento, per un tutor educativo dove il processo conta quanto il risultato.
def render_html(content, show_reasoning=False):
reasoning, answer = separate(content)
html = f"<div class='answer'>{answer}</div>"
if show_reasoning and reasoning:
html = (
"<details><summary>View model reasoning</summary>"
f"<pre>{reasoning}</pre></details>" + html
)
return html
In un progetto reale, effettua l’escape del testo prima di inserirlo nell’HTML (ad esempio con html.escape): sia il ragionamento che la risposta sono testo generato, non markup attendibile.
Streaming in tre fasi
Nello streaming, delta.content cambia forma man mano che la risposta si sviluppa:
- Fase di ragionamento:
delta.contentè una lista contenente unThinkChunk; - Transizione: una singola lista contenente sia il
ThinkChunkdi chiusura che il primoTextChunk; - Fase di risposta:
delta.contentè una stringa semplice.
Il seguente codice, adattato dall’esempio ufficiale, visualizza entrambe le fasi tracciando un flag di stato:
import os
from mistralai.client import Mistral
from mistralai.client.models import TextChunk, ThinkChunk
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
in_reasoning = False
for event in client.chat.stream(
model="mistral-large-4-0",
messages=[{"role": "user", "content": "What is 17 × 23?"}],
reasoning_effort="high",
):
delta = event.data.choices[0].delta.content
if not delta:
continue
if isinstance(delta, str): # answer phase
if in_reasoning:
print("\n--- end of reasoning ---")
in_reasoning = False
print(delta, end="", flush=True)
continue
for chunk in delta: # reasoning phase and transition
if isinstance(chunk, ThinkChunk):
if not in_reasoning:
print("--- reasoning ---")
in_reasoning = True
for inner in chunk.thinking:
if isinstance(inner, TextChunk):
print(inner.text, end="", flush=True)
elif isinstance(chunk, TextChunk):
if in_reasoning:
print("\n--- end of reasoning ---")
in_reasoning = False
print(chunk.text, end="", flush=True)
Lo streaming cambia l’esperienza: invece di attendere che un lungo processo di ragionamento termini davanti a uno schermo bloccato, l’utente vede il modello al lavoro, o almeno un indicatore di attività se scegli di nascondere il ragionamento.
Punti chiave
contentè una stringa connone, una lista di chunk conhigh: gestisci sempre entrambi i casiThinkChunk.thinkingè una lista diTextChunk; la risposta finale risiede in unTextChunkdi primo livello- Una funzione
separateche restituisce (ragionamento, risposta) semplifica il resto del tuo codice - Nello streaming: lista di ragionamento, transizione mista, poi stringhe di risposta
- Effettua l’escape sia del ragionamento che della risposta prima di visualizzarli