BroadRouter

max_tokens

Atualizado em

max_tokens é um parâmetro de APIs de LLM que define o máximo de tokens que um modelo pode gerar em uma resposta. Quando a geração atinge o limite, ela para e a resposta é marcada como cortada, por exemplo com finish_reason igual a "length".

Também chamado de: limite de tokens de saída, tamanho máximo da saída, máximo de tokens, max_completion_tokens, max_output_tokens, output token limit, maximum output length

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_reason antes 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 length como sucesso. Registre esse caso no log e tente de novo com mais folga.

Perguntas frequentes

max_tokens é a mesma coisa que a janela de contexto?

Não. A janela de contexto é o total que o modelo consegue processar, prompt mais saída. max_tokens limita só a saída, e prompt mais max_tokens ainda precisam caber na janela.

Devo sempre definir max_tokens?

Defina quando precisar de um teto rígido de custo ou de tamanho. Em modelos de raciocínio, deixe bastante folga, ou não defina se o padrão do provedor já for grande o suficiente.

Qual a diferença entre max_tokens e max_completion_tokens?

A OpenAI tornou max_tokens obsoleto no Chat Completions em favor de max_completion_tokens, que inclui explicitamente os tokens de raciocínio. Muitos provedores compatíveis com a OpenAI ainda aceitam max_tokens.

Ler em MarkdownPerguntar ao ChatGPTPerguntar ao ClaudePerguntar ao Perplexity