Ir para o conteúdo principal
Português— Escolher um idioma
Menu

max_completion_tokens e orçamento de tokens

Aula 10 de 12 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. O que o limite realmente restringe
  2. Orientar o raciocínio: esforço, não o limite
  3. Dimensionar o limite de saída
  4. Detetar truncagem
  5. Não confundir com o limite de contexto
  6. Pontos-chave

Lição reescrita a 3 de novembro de 2026 com base na referência da API da xAI (Chat Completions e Responses), no guia Reasoning e nas melhores práticas da xAI: max_completion_tokens e max_output_tokens limitam apenas a resposta visível — os tokens de raciocínio e os tokens de chamada de função não contam para este limite — e o valor padrão é 128.000. A versão anterior afirmava o oposto e dimensionava o limite com base no raciocínio; definia também um esforço para grok-4.20-0309-reasoning, que não o aceita. Fontes: Chat Completions · Responses · Reasoning.

O que o limite realmente restringe

Num modelo de raciocínio, pode pensar que o limite de saída partilha o seu orçamento entre o pensamento e a resposta. Não é esse o caso na xAI. A referência da API é explícita: max_completion_tokens (Chat Completions) e max_output_tokens (Responses API) aplicam-se apenas aos tokens de saída visíveis; os tokens de raciocínio e os tokens de chamada de função não são contabilizados.

max_completion_tokens → apenas resposta visível
tokens de raciocínio → fora do limite, definidos pelo esforço

Sem um valor definido, este limite assume por padrão 128.000 tokens. Quanto ao antigo max_tokens, está obsoleto em favor de max_completion_tokens.

Orientar o raciocínio: esforço, não o limite

Uma vez que o limite não afeta o raciocínio, é o esforço que regula a quantidade. Em grok-4.7, grok-4.6 e grok-4.5, o parâmetro é reasoning_effort no Chat Completions e reasoning.effort na Responses API; o valor padrão é high, aceita low e medium, e xhigh a partir do Grok 4.6. O raciocínio não pode ser desativado.

grok-4.20-0309-reasoning não aceita este parâmetro: raciocina sempre, e a sua variante grok-4.20-0309-non-reasoning responde sem raciocínio. Finalmente, em grok-4.20-multi-agent, o esforço não define a profundidade do raciocínio, mas sim o número de agentes mobilizados (4 ou 16).

response = client.chat.completions.create(
    model="grok-4.7",
    reasoning_effort="low",  # tarefa simples: pouco raciocínio
    messages=[{"role": "user", "content": "Classify this ticket: billing, access, or bug?"}],
)
print(response.usage.completion_tokens_details.reasoning_tokens)

O número de tokens de raciocínio aparece no uso da resposta: usage.completion_tokens_details.reasoning_tokens no Chat Completions, usage.output_tokens_details.reasoning_tokens na Responses API. Estes tokens fazem parte dos tokens faturados: portanto, é o esforço, e não o limite de saída, que pesa nesta rubrica.

Dimensionar o limite de saída

O limite serve apenas para restringir o comprimento da própria resposta. As melhores práticas da xAI dão uma regra simples: defina-o acima da resposta mais longa que espera, ou deixe o seu valor padrão de 128.000 tokens. Um limite demasiado apertado corta a resposta visível, independentemente do esforço de raciocínio.

Resposta esperadaLimite de saída razoável
Um rótulo, um númeroalgumas dezenas de tokens
Um parágrafo500 a 1.000 tokens
Um relatório estruturadovários milhares de tokens
Sem ideia precisao valor padrão

Detetar truncagem

Quando a resposta visível atinge o limite, o Chat Completions devolve "length" em finish_reason em vez de "stop", e a Responses API devolve um estado incomplete. Pode detetar esta situação e tentar novamente com um limite mais elevado:

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":
    # A resposta visível foi cortada: tentar novamente com um limite mais elevado
    response = client.chat.completions.create(
        model="grok-4.7",
        messages=[{"role": "user", "content": question}],
        max_completion_tokens=8000,
    )

Não confundir com o limite de contexto

O limite de saída é independente da janela de contexto do modelo — 500.000 tokens para grok-4.7, 1 milhão para grok-4.20-0309-reasoning — que limita toda a conversa. E um pedido de raciocínio profundo pode levar vários minutos: a xAI recomenda permitir pelo menos 900 segundos por pedido e preferir o streaming.

Pontos-chave

  • max_completion_tokens e max_output_tokens limitam apenas a resposta visível: o raciocínio não conta para este limite
  • Sem um valor, o limite de saída assume por padrão 128.000 tokens; max_tokens está obsoleto
  • A quantidade de raciocínio é definida pelo esforço (reasoning_effort ou reasoning.effort) no grok-4.5 ao 4.7; grok-4.20-0309-reasoning não possui isto
  • Os tokens de raciocínio aparecem no uso e fazem parte da faturação
  • Uma resposta cortada é detetada por finish_reason: "length" ou pelo estado incomplete