max_tokens é o orçamento de saída de uma resposta. Ele protege você de respostas que não acabam nunca, mas, se ficar baixo demais, corta as respostas ou não devolve nada.
Como funciona
O modelo gera um token de cada vez. Quando a contagem chega a max_tokens, a geração para, mesmo no meio de uma frase. A resposta então informa por que terminou:
finish_reason |
Significado |
|---|---|
stop |
O modelo terminou sozinho |
length |
O limite de max_tokens foi atingido |
tool_calls |
O modelo está pedindo para chamar uma ferramenta |
O parâmetro tem vários nomes. A API Chat Completions da OpenAI agora marca max_tokens como obsoleto em favor de max_completion_tokens, um limite superior que inclui tanto a saída visível quanto os tokens de raciocínio. A Responses API da OpenAI usa max_output_tokens. A Messages API da Anthropic usa max_tokens. Muitos provedores compatíveis com a OpenAI aceitam max_tokens.
O prompt e a saída dividem a mesma janela de contexto. Se a janela tem 32.768 tokens e o prompt tem 30.000, no máximo 2.768 tokens podem voltar, não importa o que diga max_tokens.
Por que isso importa
- Controle de custo. Em uma chave cobrada por token,
max_tokensé o máximo que uma única resposta pode custar em saída. - Respostas vazias. Em modelos de raciocínio, o pensamento sai do mesmo orçamento. Um limite de 100 pode ser gasto inteiro em tokens de raciocínio, e aí a resposta visível vem vazia e
finish_reasonélength. - JSON quebrado. Uma resposta cortada deixa a saída estruturada incompleta e impossível de interpretar. Confira
finish_reasonantes de fazer o parse.
Na BroadNet Inference
DeepSeek V4.1 Flash, GLM 5.3 e Qwen3.8 27B raciocinam antes de responder, e a documentação da BroadNet diz que o raciocínio conta para max_tokens. Reserve 1.000 tokens ou mais, deixe o parâmetro sem definir ou reduza 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")
O tamanho do contexto muda conforme o modelo: 1.048.576 tokens para DeepSeek V4.1 Flash e GLM 5.3, 262.144 para Qwen3.8 27B e 32.768 para BroadNet Gemma 4 VL 26B. Veja as páginas dos modelos e por que modelos de raciocínio devolvem respostas vazias.
Erros comuns
- Copiar, numa migração, um limite pequeno usado com um modelo sem raciocínio. Veja o checklist de migração.
- Tratar
lengthcomo sucesso. Registre esse caso no log e tente de novo com mais folga.