Vai al contenuto principale
Italiano— Scegli una lingua
Menu

max_completion_tokens e budget di token

Lezione 10 di 12 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Cosa limita effettivamente il cap
  2. Guidare il ragionamento: effort, non il cap
  3. Dimensionare il cap dell’output
  4. Rilevare il troncamento
  5. Non confonderlo con il limite di contesto
  6. Punti chiave

Lezione riscritta il 3 novembre 2026 sulla base del riferimento API xAI (Chat Completions e Responses), della guida Reasoning e delle best practice di xAI: max_completion_tokens e max_output_tokens limitano solo la risposta visibile—i token di ragionamento e quelli delle chiamate di funzione non contano verso questo limite—e il valore predefinito è 128.000. La versione precedente affermava il contrario e dimensionava il limite in base al ragionamento; impostava inoltre un effort su grok-4.20-0309-reasoning, che non lo accetta. Fonti: Chat Completions · Responses · Reasoning.

Cosa limita effettivamente il cap

Per un modello di ragionamento, potresti pensare che il cap dell’output condivida il suo budget tra pensiero e risposta. Non è affatto così su xAI. Il riferimento API è esplicito: max_completion_tokens (Chat Completions) e max_output_tokens (Responses API) si applicano solo ai token di output visibili; i token di ragionamento e quelli delle chiamate di funzione non vengono conteggiati.

max_completion_tokens → solo risposta visibile
token di ragionamento → fuori dal cap, impostati dall'effort

Senza un valore specifico, questo cap assume come predefinito 128.000 token. Quanto al vecchio max_tokens, è deprecato a favore di max_completion_tokens.

Guidare il ragionamento: effort, non il cap

Poiché il cap non tocca il ragionamento, è l’effort a regolarne la quantità. Su grok-4.7, grok-4.6 e grok-4.5, il parametro è reasoning_effort in Chat Completions e reasoning.effort nella Responses API; il valore predefinito è high, accetta low e medium, e xhigh a partire da Grok 4.6. Il ragionamento non può essere disabilitato.

grok-4.20-0309-reasoning non accetta questo parametro: ragiona sempre, mentre la sua variante grok-4.20-0309-non-reasoning risponde senza ragionamento. Su grok-4.20-multi-agent, infine, l’effort non imposta la profondità del ragionamento ma il numero di agenti mobilitati (4 o 16).

response = client.chat.completions.create(
    model="grok-4.7",
    reasoning_effort="low",  # compito semplice: poco ragionamento
    messages=[{"role": "user", "content": "Classifica questo ticket: fatturazione, accesso o bug?"}],
)
print(response.usage.completion_tokens_details.reasoning_tokens)

Il numero di token di ragionamento appare nell’uso della risposta: usage.completion_tokens_details.reasoning_tokens in Chat Completions, usage.output_tokens_details.reasoning_tokens nella Responses API. Fanno parte dei token fatturati: quindi è l’effort, non il cap dell’output, a pesare su questa voce di costo.

Dimensionare il cap dell’output

Il cap serve solo a delimitare la lunghezza della risposta stessa. Le best practice di xAI forniscono una regola semplice: impostalo al di sopra della risposta più lunga che ti aspetti, oppure lascia il suo valore predefinito di 128.000 token. Un cap troppo stretto tronca la risposta visibile, indipendentemente dall’effort di ragionamento.

Risposta attesaCap dell’output ragionevole
Un’etichetta, un numeroalcune decine di token
Un paragrafoda 500 a 1.000 token
Un report strutturatodiverse migliaia di token
Nessuna idea precisail valore predefinito

Rilevare il troncamento

Quando la risposta visibile raggiunge il cap, Chat Completions restituisce "length" in finish_reason invece di "stop", mentre la Responses API restituisce uno stato incomplete. Puoi rilevare questa situazione e riprovare con un cap più alto:

response = client.chat.completions.create(
    model="grok-4.7",
    messages=[{"role": "user", "content": question}],
    max_completion_tokens=2000,
)

if response.choices[0].finish_reason == "length":
    # La risposta visibile è stata troncata: riprova con un cap più alto
    response = client.chat.completions.create(
        model="grok-4.7",
        messages=[{"role": "user", "content": question}],
        max_completion_tokens=8000,
    )

Non confonderlo con il limite di contesto

Il cap dell’output è indipendente dalla finestra di contesto del modello—500.000 token per grok-4.7, 1 milione per grok-4.20-0309-reasoning—che delimita l’intera conversazione. Inoltre, una richiesta di ragionamento profondo può richiedere diversi minuti: xAI raccomanda di concedere almeno 900 secondi per richiesta e di preferire lo streaming.

Punti chiave

  • max_completion_tokens e max_output_tokens limitano solo la risposta visibile: il ragionamento non conta verso questo limite
  • Senza un valore, il cap dell’output predefinisce a 128.000 token; max_tokens è deprecato
  • La quantità di ragionamento è impostata dall’effort (reasoning_effort o reasoning.effort) su grok-4.5 fino a 4.7; grok-4.20-0309-reasoning non lo possiede
  • I token di ragionamento appaiono nell’uso e fanno parte della fatturazione
  • Una risposta troncata si rileva tramite finish_reason: "length" o lo stato incomplete