Contagem e orçamentação de tokens
Nesta página
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
tiktokenpara 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