Sforzo di ragionamento: Basso, Medio e Alto
In questa pagina
Aggiornato il 3 novembre 2026 in base al riferimento API di xAI:
max_completion_tokenslimita solo la risposta visibile; i token di ragionamento non contano verso questo limite e lo sforzo ne controlla la quantità. Fonte: Chat Completions. Addendum del 3 novembre: La lezione collegava precedentemente lo sforzo all’API (Chat Completions o Responses) e lo applicava agrok-4.20-0309-reasoning, che non lo supporta; secondo la pagina Reasoning di xAI, dipende dal modello (grok-4.7,grok-4.6,grok-4.5,grok-4.20-multi-agent). L’esempio riportava ancheusage.completion_tokens, assente nelle risposte dell’API Responses (output_tokens,output_tokens_details.reasoning_tokens). Fonte: Reasoning.
Controllo della profondità di ragionamento
Lo sforzo di ragionamento ti permette di calibrare quanto il modello “pensi” prima di rispondere. È una leva diretta per bilanciare qualità, velocità e consumo di token.
È il modello a determinare la disponibilità, non l’API. Secondo la documentazione di xAI:
| Modello | Sforzo | Valori |
|---|---|---|
grok-4.7, grok-4.6 | Profondità di ragionamento | low, medium, high (default), xhigh |
grok-4.5 | Profondità di ragionamento | low, medium, high (default); xhigh viene trattato come high |
grok-4.20-multi-agent | Numero di agenti mobilitati (4 o 16), non profondità | low, medium, high, xhigh |
grok-4.20-0309-reasoning | Non configurabile: il modello ragiona sempre | — |
Su questi modelli il ragionamento non può essere disattivato: senza configurazione, lo sforzo è impostato di default su high. Cambia solo il nome del parametro a seconda dell’API: reasoning_effort al livello superiore in Chat Completions, reasoning.effort all’interno di un oggetto reasoning con l’API Responses.
{
"model": "grok-4.7",
"input": "Solve the system of equations: 3x + 2y = 12, x - y = 1",
"reasoning": {
"effort": "medium"
}
}
Livelli di sforzo
La documentazione descrive ogni livello e il suo utilizzo appropriato:
low: Utilizza un certo grado di ragionamento rimanendo veloce. Per usi agentici sensibili alla latenza e chiamate semplici a strumenti.medium: Maggiore riflessione, per applicazioni meno sensibili alla latenza. Per analisi dati complesse e ragionamento su contesti lunghi.high(default): Molti più token di ragionamento. Per problemi molto difficili, matematica complessa, logica multi-step.xhigh: Profondità massima, con la relativa latenza. Per i problemi più ardui, quando la qualità conta più del tempo di risposta.
Le best practice di xAI aggiungono una regola semplice: imposta esplicitamente lo sforzo su ogni richiesta e registralo insieme a ogni risultato, così le tue misurazioni restano comparabili.
I modelli di ragionamento rifiutano inoltre tre parametri: presence_penalty, frequency_penalty e stop faranno fallire la richiesta.
Impatto sui token
Il livello di sforzo ha un impatto diretto sul consumo di token di ragionamento:
low: Pochi token di ragionamento, risposta veloce, costo bassomedium: Consumo moderato, buon compromessohighexhigh: Molti token di ragionamento, risposta più lenta, costo elevato
Questi token di ragionamento sono fatturati come token di output (vedi Lezione 8). Il limite di output (max_completion_tokens in Chat Completions, max_output_tokens nell’API Responses) limita solo la risposta visibile: il ragionamento non conta verso tale limite, quindi è lo sforzo a controllarne la quantità.
Scegliere il livello giusto
| Compito | Sforzo consigliato |
|---|---|
| Classificazione del testo | low |
| Riassunto con analisi | medium |
| Estrazione strutturata di entità | low |
| Risoluzione di equazioni | high |
| Analisi di bug nel codice | high |
| Riformulazione di testo | low |
| Confronto di opzioni con pro/contro | medium |
| Dimostrazione matematica | high |
Esempio pratico: stessa domanda, tre sforzi
for effort in ["low", "medium", "high"]:
response = client.responses.create(
model="grok-4.7",
input="Explain why 0.1 + 0.2 != 0.3 in computing.",
reasoning={"effort": effort},
)
usage = response.usage
print(f"Effort {effort}: {usage.output_tokens} output tokens, "
f"including {usage.output_tokens_details.reasoning_tokens} reasoning tokens")
Il divario tra i livelli dipende dalla domanda: misuralo sui tuoi casi specifici invece di affidarti a un rapporto generico e registra lo sforzo insieme a ogni risultato.
Punti chiave
- Lo sforzo dipende dal modello:
low,medium,high(default) exhighsugrok-4.7egrok-4.6, senzaxhighsugrok-4.5;grok-4.20-0309-reasoningnon lo supporta reasoning_effortin Chat Completions,reasoning.effortnell’API Responses; il ragionamento non può essere disattivato- Il livello di sforzo incide direttamente sul numero di token di ragionamento e quindi sul costo
- Senza configurazione, lo sforzo è impostato di default su
high: impostalo esplicitamente su ogni richiesta, come raccomanda xAI - Adatta lo sforzo alla complessità reale del compito per ottimizzare i costi