max_tokens è il budget di output per una singola risposta. Ti protegge dalle risposte che non finiscono più ma, se è troppo basso, tronca le risposte o non restituisce niente.
Come funziona
Il modello genera un token alla volta. Quando il conteggio raggiunge max_tokens, la generazione si ferma, anche a metà frase. La risposta indica poi perché si è chiusa:
finish_reason |
Significato |
|---|---|
stop |
Il modello ha finito da solo |
length |
È stato raggiunto il limite di max_tokens |
tool_calls |
Il modello chiede di chiamare uno strumento |
Il parametro ha diversi nomi. L’API Chat Completions di OpenAI ora segna max_tokens come deprecato a favore di max_completion_tokens, un limite superiore che comprende sia l’output visibile sia i token di ragionamento. La Responses API di OpenAI usa max_output_tokens. La Messages API di Anthropic usa max_tokens. Molti provider compatibili con OpenAI accettano max_tokens.
Prompt e output condividono un’unica finestra di contesto. Se la finestra è di 32.768 token e il prompt ne occupa 30.000, possono tornare al massimo 2.768 token, qualunque cosa dica max_tokens.
Perché è importante
- Controllo dei costi. Con una chiave a token,
max_tokensè il massimo che una singola risposta può costare in output. - Risposte vuote. Sui modelli di ragionamento il pensiero esce dallo stesso budget. Un limite di 100 può finire tutto in token di ragionamento, così la risposta visibile è vuota e
finish_reasonèlength. - JSON rotto. Una risposta troncata lascia l’output strutturato incompleto e impossibile da parsare. Controlla
finish_reasonprima del parsing.
Su BroadNet Inference
DeepSeek V4.1 Flash, GLM 5.3 e Qwen3.8 27B ragionano prima di rispondere, e la documentazione di BroadNet dice che il ragionamento conta in max_tokens. Concedi 1.000 token o più, lascialo non impostato oppure abbassa reasoning_effort:
response = client.chat.completions.create(
model="broadnet/glm-5.3",
max_tokens=2000,
messages=[{"role": "user", "content": "Summarize this contract clause."}],
)
if response.choices[0].finish_reason == "length":
print("Cut off: raise max_tokens or lower reasoning_effort")
Le dimensioni del contesto cambiano da modello a modello: 1.048.576 token per DeepSeek V4.1 Flash e GLM 5.3, 262.144 per Qwen3.8 27B e 32.768 per BroadNet Gemma 4 VL 26B. Vedi le pagine dei modelli e perché i modelli di ragionamento restituiscono risposte vuote.
Errori comuni
- Copiare durante una migrazione un limite basso pensato per un modello senza ragionamento. Vedi la checklist di migrazione.
- Trattare
lengthcome un successo. Registralo nei log e ritenta con più margine.