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

Utilização de tokens e reasoning_tokens

Aula 9 de 12 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Compreenda a faturação de tokens
  2. O objeto usage padrão
  3. reasoning_tokens: específico de modelos de raciocínio
  4. Estratégias de otimização de custos
  5. Pontos-chave

Atualizado a 3 de novembro de 2026. Com base na referência da API Chat Completions da xAI: max_tokens está obsoleto em favor de max_completion_tokens, que limita apenas a resposta visível. Fonte: Chat Completions.

Compreenda a faturação de tokens

Cada pedido à API Chat Completions é faturado com base no número de tokens consumidos. O objeto usage na resposta fornece uma contagem exata, essencial para monitorizar custos, otimizar prompts e dimensionar os seus orçamentos de API.

O objeto usage padrão

Eis a estrutura do objeto usage devolvido com cada resposta:

{
  "usage": {
    "prompt_tokens": 127,
    "completion_tokens": 342,
    "total_tokens": 469
  }
}

Os três contadores básicos

  • prompt_tokens: número de tokens no seu pedido (mensagem de sistema + histórico + nova mensagem). Este é o lado de «entrada» da faturação.
  • completion_tokens: número de tokens gerados pelo modelo na sua resposta. Este é o lado de «saída».
  • total_tokens: soma dos dois anteriores. Este é o total faturado para este pedido.

Impacto do histórico nos custos

Como o endpoint é stateless (sem estado), o histórico é enviado com cada pedido. Isto significa que prompt_tokens aumenta a cada troca:

Troca 1 : prompt_tokens = 50   (sistema + 1 mensagem de utilizador)
Troca 2 : prompt_tokens = 150  (sistema + 2 utilizador + 1 assistente)
Troca 3 : prompt_tokens = 300  (sistema + 3 utilizador + 2 assistente)
Troca 10: prompt_tokens = 1500 (sistema + 10 utilizador + 9 assistente)

Em conversas longas, o custo do histórico pode rapidamente exceder o custo da própria resposta.

reasoning_tokens: específico de modelos de raciocínio

Os modelos Grok com capacidades de raciocínio (como grok-4.20-0309-reasoning) adicionam um campo extra ao objeto usage:

{
  "usage": {
    "prompt_tokens": 127,
    "completion_tokens": 892,
    "total_tokens": 1019,
    "completion_tokens_details": {
      "reasoning_tokens": 550
    }
  }
}

O que são reasoning_tokens?

reasoning_tokens representam os tokens utilizados pelo modelo para o seu raciocínio interno — o «pensamento» que ocorre antes de produzir a resposta final. Estes tokens são gerados, mas não são visíveis no campo content da resposta.

No exemplo acima:

  • O modelo gerou 892 tokens no total (completion_tokens)
  • Incluindo 550 tokens de raciocínio interno (reasoning_tokens)
  • Restando 342 tokens de resposta visível (892 - 550)

Porque é que isto importa

Os tokens de raciocínio são faturados como tokens de conclusão normais. Para um modelo de raciocínio, a resposta visível pode representar apenas uma fração do custo total:

usage = response.usage

visible_tokens = usage.completion_tokens - usage.completion_tokens_details.reasoning_tokens
reasoning_tokens = usage.completion_tokens_details.reasoning_tokens

print(f"Visible tokens: {visible_tokens}")
print(f"Reasoning tokens: {reasoning_tokens}")
print(f"Reasoning ratio: {reasoning_tokens / usage.completion_tokens * 100:.0f}%")

Não é incomum que os tokens de raciocínio representem 50 a 80% dos tokens de conclusão em perguntas complexas.

Estratégias de otimização de custos

Reduzir prompt_tokens

  • Resuma o histórico: em vez de enviar toda a conversa, resuma as trocas mais antigas
  • Limite a mensagem de sistema: um prompt de sistema de 500 tokens raramente é necessário — aponte para 100–200 tokens
  • Filtre mensagens: envie apenas as trocas relevantes para a pergunta atual

Controlar completion_tokens

  • Use max_completion_tokens (max_tokens está obsoleto): limita a resposta visível, não o raciocínio
  • Especifique o formato: «Responda em 3 frases» custa menos do que «Explique em detalhe»
  • Escolha o modelo certo: um modelo sem raciocínio é menos dispendioso se a tarefa não exigir pensamento complexo

Monitorizar custos em produção

import json

def log_usage(response, requete_id: str):
    usage = response.usage
    log = {
        "id": requete_id,
        "prompt": usage.prompt_tokens,
        "completion": usage.completion_tokens,
        "total": usage.total_tokens,
    }
    if hasattr(usage, "completion_tokens_details") and usage.completion_tokens_details:
        log["reasoning"] = usage.completion_tokens_details.reasoning_tokens

    print(json.dumps(log))

Pontos-chave

  • O objeto usage contém prompt_tokens, completion_tokens e total_tokens
  • prompt_tokens aumenta a cada troca devido ao histórico enviado
  • Modelos de raciocínio adicionam reasoning_tokens em completion_tokens_details
  • Tokens de raciocínio são faturados à taxa de saída, mas são invisíveis na resposta — a sua quota-parte do custo depende da tarefa e do esforço, por isso meça-a
  • Otimize resumindo o histórico, ajustando o esforço de raciocínio, limitando max_completion_tokens e escolhendo o modelo adequado