Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Thinking chunks: leggere il ragionamento del modello

Lezione 3 di 12 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Due forme di risposta
  2. Anatomia di un thinking chunk
  3. Analisi della risposta in Python
  4. Visualizzazione del ragionamento nell’interfaccia
  5. Streaming in tre fasi
  6. Punti chiave

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 text nel 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 campo thinking è a sua volta una lista di frammenti TextChunk;
  • TextChunk (type: "text") contiene la risposta finale, nel suo campo text.

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:

  1. Fase di ragionamento: delta.content è una lista contenente un ThinkChunk;
  2. Transizione: una singola lista contenente sia il ThinkChunk di chiusura che il primo TextChunk;
  3. 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 con none, una lista di chunk con high: gestisci sempre entrambi i casi
  • ThinkChunk.thinking è una lista di TextChunk; la risposta finale risiede in un TextChunk di primo livello
  • Una funzione separate che 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