BroadRouter

Como definir max_tokens em modelos de raciocínio: um método

Pela equipe da BroadNet Inference · 6 min de leitura · Publicado em

Em um modelo de raciocínio, max_tokens limita o raciocínio e a resposta juntos, então um limite apertado pode encerrar a resposta antes de qualquer texto visível. Meça o total de tokens de completion por tipo de tarefa, defina max_tokens em cerca do percentil 95 mais 20%, mantenha prompt mais max_tokens dentro da janela de contexto e repita respostas cortadas com orçamento dobrado, até um teto fixo.

Um modelo de raciocínio pensa antes de responder, e na maioria das APIs compatíveis com a OpenAI as duas coisas saem de um único orçamento: max_tokens. Configure como faria em um modelo sem raciocínio, algumas centenas de tokens para uma resposta curta, e algumas respostas voltam vazias com finish_reason: "length". A correção rápida está em por que um modelo de raciocínio devolve uma resposta vazia. Este post é o método por trás de um orçamento confiável: medir, dimensionar por percentis, respeitar a janela de contexto e tratar as respostas que ainda forem cortadas.

Para saber quanto custa o raciocínio e como reduzir, veja tokens de raciocínio: por que você paga mais saída do que vê.

Por que o orçamento acaba antes da resposta?

O modelo gera em ordem: primeiro o raciocínio, depois a resposta visível. Cada token dos dois conta em max_tokens. A documentação da BroadNet diz isso sobre o DeepSeek V4.1 Flash, o GLM 5.3 e o Qwen3.8 27B: “the reasoning counts toward max_tokens” (tradução: o raciocínio conta em max_tokens), e com um limite pequeno “the answer comes back empty” (tradução: a resposta volta vazia). A referência de Chat Completions da OpenAI define max_completion_tokens do mesmo jeito, como um limite superior “including visible output tokens and reasoning tokens” (tradução: incluindo tokens de saída visíveis e tokens de raciocínio).

Então a pergunta certa não é “qual o tamanho da minha resposta?”. É “qual o tamanho do raciocínio mais a resposta, nesta tarefa, com este effort?”. E isso varia mais do que se imagina. O guia da OpenAI diz que os modelos dela podem gerar “anywhere from a few hundred to tens of thousands of reasoning tokens” (tradução: de algumas centenas a dezenas de milhares de tokens de raciocínio), dependendo do problema.

Um max_tokens maior custa mais?

Não. Esse é o motivo mais comum de orçamentos apertados demais. max_tokens é um teto. Você paga pelos tokens efetivamente gerados. Uma resposta que precisa de 1.800 tokens custa o mesmo com teto de 4.000 ou de 40.000.

O que um teto apertado custa:

Teto em relação à necessidade O que você paga O que você recebe
Teto acima da necessidade Os tokens gerados A resposta
Teto abaixo da necessidade O teto inteiro, todo em raciocínio Nada aproveitável, mais uma retentativa

Um exemplo. Suponha que um quarto das suas chamadas precise de mais de 1.000 tokens. Com max_tokens=1000, cada uma dessas chamadas cobra 1.000 tokens de saída de raciocínio, não devolve nada e é repetida. Isso dá, em média, 250 tokens de saída desperdiçados por chamada, considerando todas as chamadas, antes das próprias retentativas, mais a latência de uma segunda requisição. Com o teto em 4.000, nada se perde. No Qwen3.8 27B, a saída custa $2.17 por 1M de tokens, então o desperdício pesa em volume.

O risco real de um teto alto é uma resposta descontrolada: um modelo que entra em loop ou pensa demais e gera muito mais do que o necessário. Um teto fixo limita isso. Escolha o teto com base em dados, como abaixo.

Como medir o que uma tarefa precisa?

Rode prompts reais de um tipo de tarefa com um teto generoso e registre os tokens de completion e a parcela de raciocínio. Quando o modelo informa, usage.completion_tokens_details.reasoning_tokens traz a parte do raciocínio; a documentação da BroadNet lista esse campo.

import os
from openai import OpenAI

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])
MODEL = "broadnet/qwen3.8-27b"

def measure(prompts, ceiling=16_000, **kw):
    """Run real prompts with a generous ceiling and return per-call token counts."""
    rows = []
    for p in prompts:
        r = client.chat.completions.create(model=MODEL, max_tokens=ceiling,
                                           messages=[{"role": "user", "content": p}], **kw)
        u, d = r.usage, r.usage.completion_tokens_details
        reasoning = (d.reasoning_tokens or 0) if d else 0
        rows.append({"reasoning": reasoning, "answer": u.completion_tokens - reasoning,
                     "finish": r.choices[0].finish_reason})
    return rows

def pct(values, q):
    values = sorted(values)
    return values[min(len(values) - 1, int(q * len(values)))]

def recommend(rows, margin=1.2):
    total = [r["reasoning"] + r["answer"] for r in rows]
    return {"p50": pct(total, 0.5), "p95": pct(total, 0.95), "max": max(total),
            "max_tokens": int(pct(total, 0.95) * margin),
            "cut_off": sum(r["finish"] == "length" for r in rows)}

# print(recommend(measure(my_prompts)))                       # default effort
# print(recommend(measure(my_prompts, reasoning_effort="low")))

Regras para chegar a um número confiável:

  1. Um tipo de tarefa por rodada. Classificação, extração, code review e planejamento têm distribuições muito diferentes. Um max_tokens global único ou desperdiça dinheiro com retentativas ou deixa passar respostas descontroladas.
  2. 50 ou mais prompts reais. O percentil 95 de dez amostras é só a maior delas.
  3. Rode para cada effort que você usa. reasoning_effort="low" muda a distribuição. A BroadNet documenta low; teste outros valores antes de depender deles.
  4. Se cut_off não for zero, aumente o teto e rode de novo. Uma amostra cortada esconde o tamanho real.
  5. Rode de novo quando o modelo ou o prompt mudar. Uma nova versão do modelo pode pensar mais ou menos.

Depois defina max_tokens por tarefa a partir de recommend(). O percentil 95 mais 20% deixa a maioria das chamadas bem abaixo do teto e manda só os raros casos longos para o caminho de retentativa descrito abaixo. A ferramenta gratuita de orçamento de tokens de raciocínio faz essa conta no navegador quando você já tem os seus números.

Como a janela de contexto limita o orçamento?

A janela de contexto contém o prompt e a resposta juntos. O feed de preços da BroadNet define context_length como “the most tokens one request can hold, prompt and answer together” (tradução: o máximo de tokens que uma requisição comporta, prompt e resposta juntos). Portanto:

max_tokens ≤ tamanho do contexto − tokens do prompt

Modelo Contexto Espaço para max_tokens com um prompt de 200.000 tokens
GLM 5.3 1.048.576 848.576
DeepSeek V4.1 Flash 1.048.576 848.576
Qwen3.8 27B 262.144 62.144

Isso importa em trabalhos com contexto longo. Um agente cujo histórico cresceu até 250.000 tokens no Qwen3.8 27B tem só cerca de 12.000 tokens livres para raciocínio e resposta. Tarefas de contexto longo também tendem a exigir mais raciocínio, então confira o espaço restante no momento da chamada, não uma vez só na inicialização. Janela de contexto e a calculadora de janela de contexto ajudam a fazer caber.

O que fazer quando uma resposta ainda é cortada?

Confira finish_reason em toda chamada. Se for length, a resposta está faltando ou incompleta, mesmo quando content tem algum texto. Não faça o parsing como se estivesse completa; um objeto JSON truncado é uma fonte comum de erros mais adiante (saída estruturada).

Repita com orçamento dobrado, dentro do espaço que o contexto permite, até um teto fixo:

import json, urllib.request

FEED = json.load(urllib.request.urlopen("https://inference.broadnet.ai/pricing.json"))
CONTEXT = {m["id"]: m.get("context_length") for m in FEED["models"]}

def ask(model, messages, budget=4_000, hard_cap=32_000, **kw):
    """Retry a cut-off reply with a doubled budget, never past the cap or the context window."""
    while True:
        r = client.chat.completions.create(model=model, messages=messages,
                                           max_tokens=budget, **kw)
        if r.choices[0].finish_reason != "length":
            return r
        room = CONTEXT[model] - r.usage.prompt_tokens        # context holds prompt + answer
        nxt = min(budget * 2, hard_cap, room)
        if nxt <= budget:
            raise RuntimeError(f"still cut off at max_tokens={budget}")
        print(f"cut off at {budget}, retrying with {nxt}")
        budget = nxt

Duas alternativas a dobrar, dependendo da tarefa:

  • Repita com reasoning_effort="low" e o mesmo orçamento. Em tarefas simples, o modelo muitas vezes pensa demais, e menos effort resolve sem aumentar o teto.
  • Divida a tarefa. Se uma resposta continua batendo em um teto alto, a requisição geralmente está pedindo coisa demais de uma vez.

Registre cada corte com o tipo de tarefa. Uma taxa subindo significa que o prompt, o modelo ou os dados de entrada mudaram, e o orçamento precisa ser medido de novo. Retentativas são novas inferências e são cobradas de novo, então limite as tentativas, como em agentes de longa duração: timeouts e retentativas.

O que muda com streaming?

Com stream=True, o raciocínio acontece antes do primeiro token visível, então um modelo de raciocínio pode parecer travado no começo. Em uma interface de chat, mostre um estado de “pensando” até o conteúdo chegar e dimensione os timeouts do cliente para o tempo de raciocínio, não só para a resposta.

Alguns servidores também transmitem o próprio texto do raciocínio, em um campo separado. O nome não é padronizado: a API da DeepSeek usa reasoning_content, e o vLLM renomeou o campo de reasoning_content para reasoning, avisando que código de cliente antigo poderia ler em silêncio um campo vazio (texto original: “could silently read an empty” field). A documentação da BroadNet não documenta um campo com o texto do raciocínio, então não construa funcionalidades em cima dele sem conferir a resposta bruta do seu modelo. Se for ler, leia de forma defensiva:

for chunk in stream:
    if chunk.choices:
        delta = chunk.choices[0].delta
        thinking = getattr(delta, "reasoning", None) or getattr(delta, "reasoning_content", None)
        # log or display `thinking` only if your provider actually sends it
        if delta.content:
            print(delta.content, end="")
    elif chunk.usage:                                  # last chunk, with include_usage
        print("\nreasoning tokens:", getattr(chunk.usage.completion_tokens_details, "reasoning_tokens", None))

O usage no último chunk exige stream_options={"include_usage": True}, que a BroadNet documenta. Mais sobre streams no guia de streaming e em SSE explicado.

Qual nome de parâmetro enviar?

API Parâmetro Inclui raciocínio
OpenAI Chat Completions max_completion_tokens (max_tokens obsoleto) Sim
OpenAI Responses max_output_tokens Sim
BroadNet Inference (Chat Completions) max_tokens, conforme a documentação Sim
Servidores vLLM max_tokens, mais thinking_token_budget opcional Sim

Ao levar código de um provedor para outro, envie o nome que o provedor documenta e confirme com uma chamada de teste que o limite tem efeito. Um limite ignorado em silêncio parece ok até chegar uma resposta descontrolada. O checklist de migração cobre os outros parâmetros que mudam.

Onde a BroadNet Inference se encaixa

Os três modelos de raciocínio da BroadNet informam os tokens de raciocínio em usage quando o modelo os fornece, então a medição acima funciona como está. O DeepSeek V4.1 Flash e o GLM 5.3 dão mais espaço, com 1.048.576 tokens de contexto. O Qwen3.8 27B tem 262.144. Se uma tarefa não precisa de raciocínio, o Gemma 4 VL 26B não aparece como modelo de raciocínio e evita a questão do orçamento. Em um plano de preço fixo do DeepSeek V4.1 Flash, os tokens de raciocínio não têm cobrança por token, mas respostas cortadas ainda custam tempo, então o mesmo método vale. A BroadNet não documenta um teto separado para o raciocínio; se você precisar de um, use um provedor ou servidor self-hosted que ofereça isso.

Perguntas frequentes

Por que meu modelo de raciocínio devolve uma resposta vazia?

O modelo gastou todo o orçamento de max_tokens no raciocínio oculto antes de escrever a resposta. Nesse caso, finish_reason é "length". Aumente max_tokens, reduza reasoning_effort, ou as duas coisas. Este post traz o link para um guia curto com a correção rápida.

Qual max_tokens devo usar em um modelo de raciocínio?

Meça primeiro. Rode 50 ou mais prompts reais com um teto generoso, pegue o percentil 95 de completion_tokens daquela tarefa e some cerca de 20%. A documentação da BroadNet indica 1.000 tokens ou mais como piso; a OpenAI sugere reservar 25.000 quando você começa com os modelos dela.

Um max_tokens maior custa mais?

Não por si só. Você paga pelos tokens que o modelo gera, não pelo teto. Um teto maior só custa mais quando a resposta seria cortada de outra forma, e aí a resposta cortada já teria custado uma retentativa.

max_completion_tokens é o mesmo que max_tokens?

Na OpenAI, max_completion_tokens substitui o max_tokens, que está obsoleto, e inclui explicitamente os tokens de raciocínio. Muitos provedores compatíveis com a OpenAI documentam max_tokens. A documentação da BroadNet usa max_tokens e diz que o raciocínio conta dentro dele.

Dá para limitar o raciocínio separado da resposta?

Só se o servidor suportar. O vLLM tem o parâmetro thinking_token_budget, e alguns provedores têm o seu próprio. A BroadNet documenta reasoning_effort em low, não um teto separado para o raciocínio, então dimensione os dois juntos.

Ler em MarkdownPerguntar ao ChatGPTPerguntar ao ClaudePerguntar ao Perplexity