BroadRouter

max_tokens

Aggiornato

max_tokens è un parametro delle API LLM che fissa il numero massimo di token che un modello può generare in una risposta. Quando la generazione raggiunge il limite, si ferma e la risposta viene segnata come troncata, per esempio con finish_reason impostato a "length".

Detto anche: limite di token in output, lunghezza massima dell’output, token massimi, max_completion_tokens, max_output_tokens, output token limit, maximum output length

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_reason prima 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 length come un successo. Registralo nei log e ritenta con più margine.

Domande frequenti

max_tokens è la stessa cosa della finestra di contesto?

No. La finestra di contesto è il totale che il modello può gestire, prompt più output. max_tokens limita solo l’output, e prompt più max_tokens devono comunque stare nella finestra.

Devo impostare sempre max_tokens?

Impostalo quando ti serve un tetto rigido a costo o lunghezza. Sui modelli di ragionamento lascia molto margine, oppure non impostarlo se il valore predefinito del provider è abbastanza alto.

Che differenza c’è tra max_tokens e max_completion_tokens?

OpenAI ha deprecato max_tokens in Chat Completions a favore di max_completion_tokens, che include esplicitamente i token di ragionamento. Molti provider compatibili con OpenAI accettano ancora max_tokens.

Leggi in MarkdownChiedi a ChatGPTChiedi a ClaudeChiedi a Perplexity