Pular para o conteúdo
Engenharia com agentes de IA: governança e custo em reais.

IA em produção · 16 de novembro de 2026

Custo por consulta: como medir e explicar a conta de tokens

Por Medha

Cenário (sintético)

A fatura mensal da API de IA generativa veio bem acima do estimado. Na reunião, a primeira pergunta foi óbvia: "por que subiu tanto?". Ninguém conseguiu responder. O time sabia o valor total da fatura, mas não sabia quanto cada funcionalidade do produto consumia, quanto cada tipo de consulta custava, nem se o aumento vinha de mais uso ou de consultas individualmente mais caras.

Sem esse detalhamento, a única alavanca disponível era cortar uso no escuro — reduzir para todo mundo, sem saber onde estava a origem real do custo. Esse é o sintoma de um problema anterior: custo por consulta não estava sendo medido, só o total da fatura no fim do mês.

Medir no momento da geração, não estimar depois

A resposta de uma API de modelo de linguagem normalmente já vem acompanhada da contagem de tokens de entrada e de saída daquela chamada específica. Esse número deve ser capturado e registrado no momento da chamada — não estimado depois por aproximação de caracteres, que é impreciso e esconde variação real entre modelos e idiomas.

from dataclasses import dataclass
from datetime import datetime

@dataclass
class PrecoModelo:
    """Preço por 1 milhão de tokens, em dólar. Preencha com o valor
    vigente na página oficial de preços do provedor no momento do
    cálculo — os preços de modelo mudam com frequência e não devem
    ser fixados como constante no código sem revisão periódica."""
    preco_entrada_por_milhao: float
    preco_saida_por_milhao: float

@dataclass
class RegistroConsulta:
    endpoint: str
    modelo: str
    tokens_entrada: int
    tokens_saida: int
    custo_brl: float
    criado_em: datetime

def calcular_custo(tokens_entrada: int, tokens_saida: int, preco: PrecoModelo, cotacao_usd_brl: float) -> float:
    """Calcula o custo em reais de uma consulta a partir da contagem de
    tokens de entrada e saída devolvida pela própria API na chamada."""
    custo_usd = (
        tokens_entrada / 1_000_000 * preco.preco_entrada_por_milhao
        + tokens_saida / 1_000_000 * preco.preco_saida_por_milhao
    )
    return custo_usd * cotacao_usd_brl

O ponto central aqui não é o valor do preço em si (que varia por provedor e por modelo, e deve sempre vir da fonte oficial no momento do cálculo, nunca de um número fixado no código), é o hábito de registrar tokens de entrada, tokens de saída, modelo usado e o endpoint ou funcionalidade de origem para cada consulta individual — o dado bruto que permite qualquer análise posterior.

Explicar a fatura exige quebrar por dimensão, não só somar

Com o registro por consulta em mãos, a pergunta "por que subiu?" passa a ter resposta possível. O primeiro corte útil é por endpoint ou funcionalidade — porque nem toda funcionalidade tem o mesmo padrão de uso, nem o mesmo tamanho de contexto necessário:

def custo_por_endpoint(registros: list[RegistroConsulta]) -> dict[str, float]:
    """Soma o custo total por endpoint/funcionalidade — o primeiro
    passo para saber onde a conta está concentrada, em vez de olhar
    só o total geral da fatura."""
    totais: dict[str, float] = {}
    for r in registros:
        totais[r.endpoint] = totais.get(r.endpoint, 0.0) + r.custo_brl
    return totais

def custo_medio_por_consulta(registros: list[RegistroConsulta]) -> dict[str, float]:
    """Calcula o custo médio por consulta em cada endpoint — separa o
    efeito de 'mais uso' (mais consultas, custo médio igual) do efeito
    de 'consulta mais cara' (menos consultas, custo médio maior)."""
    somas: dict[str, float] = {}
    contagens: dict[str, int] = {}
    for r in registros:
        somas[r.endpoint] = somas.get(r.endpoint, 0.0) + r.custo_brl
        contagens[r.endpoint] = contagens.get(r.endpoint, 0) + 1
    return {ep: somas[ep] / contagens[ep] for ep in somas}

Com essas duas quebras, uma alta na fatura tem duas explicações possíveis e distinguíveis: mais volume de consultas em um endpoint específico (o custo médio por consulta se mantém, o total sobe porque o uso subiu) ou consultas individualmente mais caras (o custo médio por consulta sobe, o que costuma indicar contexto maior, prompt mais longo ou mudança de modelo). Cada uma pede uma ação diferente — a primeira pode ser um sinal positivo de adoção, a segunda costuma ser um problema técnico a investigar, tema da próxima peça desta série.

Critério prático de aceite para custo por consulta

  1. Toda consulta ao modelo registra tokens de entrada, tokens de saída, modelo usado e endpoint/funcionalidade de origem, no momento da chamada?
  2. O custo é calculado a partir da tabela de preço oficial vigente do provedor, revisada periodicamente, e não de um valor fixado uma vez no código?
  3. É possível quebrar o custo total por endpoint/funcionalidade, não só ver o total da fatura?
  4. É possível separar, em uma alta de custo, o efeito de "mais volume" do efeito de "consulta mais cara"?

Sem essas quatro respostas, a única resposta possível para "por que a conta subiu" continua sendo "não sei".

Próximo passo

A peça seguinte detalha o segundo caso do critério 4 acima: onde o custo por consulta individualmente vaza — contexto excessivo, chamada repetida e ausência de cache — e o que fazer em cada caso.

Para aplicar este critério e os outros da série, fique de olho no Checklist de RAG em Produção, gratuito — ainda em preparação: deixe seu e-mail na lista de espera para recebê-lo assim que ele sair.

Checklist de RAG em Produção

Os critérios da série IA em produção reunidos num checklist para levar um RAG da prova de conceito à produção.

Só enviamos o material e avisos sobre ele. Privacidade