Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Il parametro reasoning_effort

Lezione 2 di 12 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Impostare la profondità del pensiero
  2. Valori accettati, modello per modello
  3. Implementazione in Python
  4. Scegliere il livello in base al compito
  5. Misurare il costo
  6. Instradamento per complessità
  7. Limiti da conoscere
  8. Punti chiave

Lezione riscritta il 2 novembre 2026. La versione precedente affermava che reasoning_effort accettava 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.

ModelloValori documentatiRaccomandazione ufficiale
Mistral Small 4 (mistral-small-2603)high, none—
Mistral Medium 3.5 (mistral-medium-3-5)high, nonehigh per flussi di lavoro agentici e codice
Mistral Large 4 (mistral-large-4-0)low, medium, highInizia 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_effort controlla il ragionamento richiesta per richiesta, senza altre configurazioni
  • Small 4 e Medium 3.5 accettano high e none; Large 4 accetta low, medium e high, ma non none
  • Le enumerazioni degli SDK contengono valori che non tutti i modelli accettano
  • Con high, content è una lista di frammenti; con none, una stringa
  • Misura il costo con usage.completion_tokens e instrada in base alla complessità