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

Contagem e orçamentação de tokens

Aula 12 de 20 Atualizada a 28 de julho de 2026 Avancado
Nesta página
  1. Compreender os tokens
  2. Contar com o tiktoken
  3. Orçamentar antes de chamar
  4. Estimar custos antes de gastar
  5. Pontos-chave

Compreender os tokens

Os tokens são a unidade fundamental de medição para os LLMs. Cada chamada à API é faturada em tokens, e cada modelo rejeita pedidos que excedam a sua janela de contexto. Dominar a contagem de tokens permite-lhe fazer três coisas que a aproximação não consegue: prever custos antes de os incorrer, otimizar os seus prompts com base em números concretos em vez de intuição e respeitar os limites de contexto sem descobrir um transbordamento apenas quando a API lança um erro.

Contar com o tiktoken

A biblioteca tiktoken aplica exatamente a mesma tokenização que o modelo. Instancia um codificador para o modelo alvo e, em seguida, conta o comprimento da sequência codificada.

import tiktoken

# Codificador para modelos GPT
encoder = tiktoken.encoding_for_model("gpt-5.6-terra")

def count_tokens(text: str) -> int:
    """Conta o número de tokens num texto."""
    return len(encoder.encode(text))

# Exemplos
print(count_tokens("Hello"))           # ~1-2 tokens
print(count_tokens("Hello world"))     # ~3-4 tokens
print(count_tokens("Development"))     # ~2-3 tokens (acentos custam mais)

O terceiro exemplo merece uma pausa. “Development” custa mais do que o seu comprimento de caracteres sugeriria porque os caracteres acentuados tokenizam de forma menos eficiente. Na prática, um corpus em português consome mais tokens do que um equivalente em inglês: se estimou o seu orçamento usando prompts em inglês e depois implementou em português, a sua fatura real excederá a sua previsão.

Uma chamada à API transporta mais do que texto bruto: cada mensagem inclui um papel (role), por vezes um nome, e a API adiciona tokens estruturais. A função seguinte incorpora esta sobrecarga para fornecer um total realista.

def count_conversation_tokens(messages: list[dict]) -> int:
    """Conta tokens numa conversa (mensagens + sobrecarga)."""
    total = 0
    for message in messages:
        total += 4  # Sobrecarga por mensagem (papel, etc.)
        total += count_tokens(message["content"])
        if message.get("name"):
            total += count_tokens(message["name"])
    total += 2  # Tokens de fim
    return total

conversation = [
    {"role": "system", "content": "You are a technical assistant."},
    {"role": "user", "content": "Explain microservices."},
    {"role": "assistant", "content": "Microservices are an architecture..."},
]

print(f"Total tokens: {count_conversation_tokens(conversation)}")

Numa conversa de três mensagens, a sobrecarga é negligenciável. Num histórico de duzentas mensagens curtas — típico num chat de suporte — soma quase mil tokens que não contabilizou.

Orçamentar antes de chamar

A janela de contexto não é um orçamento de entrada: é um orçamento partilhado entre o que envia e o que o modelo gera. Se encher a janela até à borda com o seu prompt, a resposta será truncada. A estrutura BudgetTokens torna esta alocação explícita, reservando antecipadamente uma parte para a saída.

from dataclasses import dataclass

@dataclass
class BudgetTokens:
    """Gere o orçamento de tokens para uma chamada."""
    context_limit: int       # Janela do modelo
    system_tokens: int = 0   # Prompt do sistema
    history_tokens: int = 0  # Histórico da conversa
    user_tokens: int = 0     # Mensagem atual
    output_reserve: int = 2000 # Reservado para a resposta

    @property
    def available_tokens(self) -> int:
        used = (
            self.system_tokens
            + self.history_tokens
            + self.user_tokens
        )
        return self.context_limit - used - self.output_reserve

    @property
    def is_over(self) -> bool:
        return self.available_tokens < 0

    def report(self) -> str:
        return (
            f"Contexto: {self.context_limit} | "
            f"Sistema: {self.system_tokens} | "
            f"Histórico: {self.history_tokens} | "
            f"Utilizador: {self.user_tokens} | "
            f"Reserva de saída: {self.output_reserve} | "
            f"Disponível: {self.available_tokens}"
        )

# Exemplo com uma janela de contexto de 128K tokens
budget = BudgetTokens(
    context_limit=128_000,
    system_tokens=count_tokens(system_prompt),
    history_tokens=count_conversation_tokens(history),
    user_tokens=count_tokens(user_message),
)

if budget.is_over:
    print("Orçamento excedido — compactação necessária")

O método report faz mais do que ajudar na depuração. Registe-o numa amostra de pedidos de produção e verá imediatamente qual o componente que está a consumir o seu contexto. Na maioria das aplicações, a surpresa vem do histórico, raramente do prompt do sistema que todos monitorizam.

De seguida, precisa de agir quando o orçamento é excedido. A função prepare_context aplica a regra mais simples e robusta: manter as mensagens mais recentes e descartar as mais antigas assim que o orçamento se esgota. A iteração corre em sentido inverso, inserindo no início para restaurar a ordem cronológica.

def prepare_context(
    system_prompt: str,
    history: list[dict],
    message: str,
    model_limit: int = 128_000,
    output_reserve: int = 4_000,
) -> list[dict]:
    """Prepara o contexto respeitando o orçamento de tokens."""

    system_tokens = count_tokens(system_prompt)
    message_tokens = count_tokens(message)
    history_budget = (
        model_limit - system_tokens - message_tokens - output_reserve
    )

    # Manter as mensagens mais recentes dentro do orçamento
    kept_messages = []
    used_tokens = 0

    for msg in reversed(history):
        msg_tokens = count_tokens(msg["content"]) + 4
        if used_tokens + msg_tokens > history_budget:
            break
        kept_messages.insert(0, msg)
        used_tokens += msg_tokens

    return (
        [{"role": "system", "content": system_prompt}]
        + kept_messages
        + [{"role": "user", "content": message}]
    )

Este truncamento é brutal: tudo o que fica fora do orçamento é perdido. Quando o contexto antigo é realmente importante — um ficheiro de cliente acompanhado ao longo de várias semanas — substitua a eliminação pura pela estratégia de compactação abordada na lição anterior.

Estimar custos antes de gastar

Os erros de faturação mais dispendiosos provêm do processamento em lote: executa uma passagem por 10.000 documentos e descobre o valor no dia seguinte. Estimar primeiro, em alguns milissegundos de computação local, evita este cenário.

def estimate_cost(
    input_tokens: int,
    estimated_output_tokens: int,
    model: str = "gpt-5.6-terra",
) -> dict:
    """Estima o custo de uma chamada antes de a executar."""
    # Tarifas por milhão de tokens (julho de 2026 — verifique os preços oficiais)
    rates = {
        "gpt-5.6-luna": {"input": 0.20, "output": 1.20},
        "gpt-5.6-terra": {"input": 2.00, "output": 12.00},
        "gpt-5.6-sol": {"input": 5.00, "output": 30.00},
    }

    rate = rates.get(model, rates["gpt-5.6-terra"])
    input_cost = (input_tokens / 1_000_000) * rate["input"]
    output_cost = (estimated_output_tokens / 1_000_000) * rate["output"]

    return {
        "model": model,
        "input_tokens": input_tokens,
        "estimated_output_tokens": estimated_output_tokens,
        "input_cost": f"${input_cost:.6f}",
        "output_cost": f"${output_cost:.6f}",
        "total_cost": f"${input_cost + output_cost:.6f}",
    }

# Antes de enviar um prompt grande
estimation = estimate_cost(
    input_tokens=50_000,
    estimated_output_tokens=2_000,
    model="gpt-5.6-sol",
)
print(estimation)

A tabela de tarifas está codificada neste exemplo, com a data num comentário. Trate-a como dados de configuração a verificar regularmente face à grelha de preços oficial: uma estimativa calculada com preços desatualizados é mais perigosa do que nenhuma estimativa, porque inspira uma falsa confiança.

Por fim, conheça os limites de cada modelo para planear o seu orçamento. As janelas de contexto variam de modelo para modelo dentro da família GPT-5.6 — consulte a página oficial de modelos da OpenAI para os valores atuais e configure o context_limit a partir das suas definições, em vez de o codificar diretamente no código de chamada.

Pontos-chave

  • Utilize o tiktoken para contar tokens antes de cada chamada, tendo em conta a sobrecarga por mensagem
  • O português consome mais tokens do que o inglês para conteúdo equivalente: ajuste as suas estimativas
  • Reserve sempre um orçamento para tokens de saída dentro da janela de contexto
  • Gere o contexto automaticamente descartando as mensagens mais antigas
  • Estime os custos antes de enviar pedidos dispendiosos, utilizando tarifas verificadas