Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Sforzo di ragionamento: Basso, Medio e Alto

Lezione 4 di 12 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Controllo della profondità di ragionamento
  2. Livelli di sforzo
  3. Impatto sui token
  4. Scegliere il livello giusto
  5. Esempio pratico: stessa domanda, tre sforzi
  6. Punti chiave

Aggiornato il 3 novembre 2026 in base al riferimento API di xAI: max_completion_tokens limita 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 a grok-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 anche usage.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:

ModelloSforzoValori
grok-4.7, grok-4.6Profondità di ragionamentolow, medium, high (default), xhigh
grok-4.5Profondità di ragionamentolow, medium, high (default); xhigh viene trattato come high
grok-4.20-multi-agentNumero di agenti mobilitati (4 o 16), non profonditàlow, medium, high, xhigh
grok-4.20-0309-reasoningNon 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 basso
  • medium: Consumo moderato, buon compromesso
  • high e xhigh: 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

CompitoSforzo consigliato
Classificazione del testolow
Riassunto con analisimedium
Estrazione strutturata di entitàlow
Risoluzione di equazionihigh
Analisi di bug nel codicehigh
Riformulazione di testolow
Confronto di opzioni con pro/contromedium
Dimostrazione matematicahigh

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) e xhigh su grok-4.7 e grok-4.6, senza xhigh su grok-4.5; grok-4.20-0309-reasoning non lo supporta
  • reasoning_effort in Chat Completions, reasoning.effort nell’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