Il parametro reasoning_effort
In questa pagina
Lezione riscritta il 2 novembre 2026. La versione precedente affermava che
reasoning_effortaccettava solo due valori ed esisteva solo su Mistral Small. In realtà, i valori accettati dipendono dal modello e Mistral Large 4 ne offre tre. Fonte: Reasoning (documentazione Mistral).
Impostare la profondità del pensiero
Il ragionamento regolabile si basa su un principio semplice: decidi tu, richiesta per richiesta, quanto il modello debba riflettere prima di rispondere. La leva si chiama reasoning_effort. La passi nella chiamata API allo stesso livello del modello e dei messaggi, senza bisogno di altre configurazioni.
Valori accettati, modello per modello
Questo è l’errore più comune: i valori accettati dipendono dal modello.
| Modello | Valori documentati | Raccomandazione ufficiale |
|---|---|---|
Mistral Small 4 (mistral-small-2603) | high, none | — |
Mistral Medium 3.5 (mistral-medium-3-5) | high, none | high per flussi di lavoro agentici e codice |
Mistral Large 4 (mistral-large-4-0) | low, medium, high | Inizia con high, poi passa a medium o low se token o latenza sono prioritari |
Su Small 4 e Medium 3.5, high genera un frammento di ragionamento completo prima della risposta, al costo di un consumo maggiore di token; none riduce il ragionamento al minimo e lo omette dalla risposta. Su Large 4, la scala ha tre livelli: low per compiti semplici, medium per bilanciare qualità, token e latenza, e high per compiti complessi. Large 4 non accetta none: la documentazione specifica che il livello precedentemente chiamato none nella sua versione preview ora si chiama low.
Un’ultima sfumatura: il tipo ReasoningEffort negli SDK elenca anche minimal, xhigh e max perché l’enumerazione copre tutti i modelli della piattaforma (max è usato, ad esempio, dal modello di terze parti zai-glm-5-3). Il fatto che un valore appaia nell’enumerazione non significa che il tuo modello lo accetti.
Implementazione in Python
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Mistral Small 4, ragionamento profondo
response_high = client.chat.complete(
model="mistral-small-2603",
messages=[{"role": "user", "content": "Solve x^3 - 6x^2 + 11x - 6 = 0 and verify each root."}],
reasoning_effort="high",
)
# Mistral Small 4, risposta diretta
response_none = client.chat.complete(
model="mistral-small-2603",
messages=[{"role": "user", "content": "What is the capital of Portugal?"}],
reasoning_effort="none",
)
# Mistral Large 4, livello intermedio
response_medium = client.chat.complete(
model="mistral-large-4-0",
messages=[{"role": "user", "content": "Compare two caching strategies for a high-traffic API."}],
reasoning_effort="medium",
)
La struttura della risposta cambia in base all’impostazione. Con high, message.content è una lista che inizia con un frammento di ragionamento; con none, è una semplice stringa. Il tuo codice deve quindi gestire entrambe le forme, come mostra la prossima lezione.
In TypeScript, il parametro segue la convenzione di denominazione JavaScript e si scrive reasoningEffort:
import { Mistral } from '@mistralai/mistralai';
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });
const response = await client.chat.complete({
model: 'mistral-small-2603',
messages: [{ role: 'user', content: 'Solve x^3 - 6x^2 + 11x - 6 = 0.' }],
reasoningEffort: 'high',
});
Scegliere il livello in base al compito
Riserva il ragionamento profondo per problemi matematici a più passaggi, debug di codice complesso, analisi comparative, pianificazione, enigmi logici e valutazione dei rischi. Questi condividono una caratteristica comune: sono possibili molteplici percorsi e scegliere quello sbagliato ha un costo elevato.
Disattivalo (o scendi al livello più basso) per domande fattuali semplici, traduzioni, parafrasi, estrazione diretta di informazioni e conversazioni quotidiane. Qui il modello non ha nulla da arbitrare: recupera o trasforma, e una fase di ragionamento aggiungerebbe solo latenza.
Misurare il costo
Il ragionamento consuma token di output. L’esempio nella documentazione ufficiale dà un’idea della scala: un indovinello sull’età inviato a Mistral Small 4 con high consuma 77 token di input e 1.114 token di output. Alla tariffa elencata per Small 4 di 0,15 $ per milione di token di input e 0,60 $ per milione di token di output, la richiesta costa circa 0,0007 $. È trascurabile per singola unità, ma su un milione di richieste simili, il solo ragionamento rappresenta diverse centinaia di dollari, senza alcun guadagno se metà delle domande non ne avesse bisogno.
Il campo usage in ogni risposta ti dà la misura esatta: traccia completion_tokens per tipo di richiesta prima di generalizzare un’impostazione.
Instradamento per complessità
Una soluzione semplice consiste nello scegliere il livello in base alla domanda, utilizzando una tabella per modello per assicurarti di non inviare mai un valore rifiutato:
LEVELS = {
"mistral-small-2603": {"simple": "none", "complex": "high"},
"mistral-large-4-0": {"simple": "low", "complex": "high"},
}
COMPLEX_WORDS = ("calculate", "prove", "compare", "analyze", "optimize", "debug", "why")
def query(client, question, model="mistral-small-2603", level=None):
"""Sceglie reasoning_effort in base alla domanda, o applica un livello forzato."""
if level is None:
is_complex = any(word in question.lower() for word in COMPLEX_WORDS)
level = LEVELS[model]["complex" if is_complex else "simple"]
return client.chat.complete(
model=model,
messages=[{"role": "user", "content": question}],
reasoning_effort=level,
)
Le euristiche basate su parole chiave restano grossolane; bastano però a riservare il ragionamento alle richieste che ne beneficiano, e l’argomento level ti permette di forzare un’impostazione. La Lezione 12 propone un’architettura di instradamento più completa.
Limiti da conoscere
Il ragionamento aumenta la probabilità di una risposta corretta, ma non la garantisce: verifica i risultati critici (Lezione 9). Aumenta anche la latenza, fattore cruciale in un’interfaccia conversazionale. Infine, il valore passato deve corrispondere al modello chiamato: prevedi una tabella come quella sopra piuttosto che spargere stringhe nel tuo codice.
Punti chiave
reasoning_effortcontrolla il ragionamento richiesta per richiesta, senza altre configurazioni- Small 4 e Medium 3.5 accettano
highenone; Large 4 accettalow,mediumehigh, ma nonnone - Le enumerazioni degli SDK contengono valori che non tutti i modelli accettano
- Con
high,contentè una lista di frammenti; connone, una stringa - Misura il costo con
usage.completion_tokense instrada in base alla complessità