Custo de IA por cliente, usuário e modelo

O custo em dinheiro vem da fatura ou da API de custo do provedor ou do gateway. Eventos de analytics dizem quem, em qual projeto e com qual ferramenta, mas não servem como valor: numa base real, o analytics mandava todos os tokens como novos, sem descontar o cache de prompt, e inflava o custo várias vezes. Use o analytics só para atribuir, e concilie as duas fontes por dia.

Antes de confiar num dia, confira se a soma do custo por usuário reconstitui o custo do modelo no dia (por exemplo, 99% ou mais, com uma tolerância absoluta para modelos de custo irrisório) e se os usuários coletados cobrem o total informado pela API. Dia que não fecha dispara alarme e é recoletado.

APIs de relatório costumam agrupar por modelo ou por usuário, não pelos dois. Consulte o custo por modelo no dia, como referência, e, para cada modelo, o custo por usuário. Grave com merge pela chave data, produto, modelo e usuário, para recoletar um dia sem duplicar.

Custo sem usuário na origem (infraestrutura, chamadas em lote, cobranças fixas do provedor) é rateado por um peso de uso declarado: requisições, tokens ou eventos. A soma rateada é igual ao custo original. O que não tem uso rastreável no dia vai para um balde de custo sem atribuição, visível, nunca espalhado em silêncio.

O mesmo usuário aparece com e-mail, id de login e id do app. Leve tudo a um id canônico e some os fragmentos. Nomes de modelo mudam com versões e datas: normalize num modelo canônico com o provedor ao lado. Marque usuários de desenvolvimento e confira, a cada carga, o mapa de chave de API para produto: chave e rótulo trocados não dão erro.

O uso da própria equipe (testes, agentes internos, desenvolvimento) é despesa da empresa, não custo do produto. Separe numa linha própria e tire do custo por cliente e da margem do plano.

O provedor fecha o dia em UTC, que cobre pedaços de dois dias de São Paulo. No diário, declare qual dia está usando; no mensal, a diferença é pequena. Nunca misture colunas de dia UTC e de dia local na mesma soma.

A maior parte do custo de API é cobrada em dólar. Guarde o valor e a moeda de origem, converta com a taxa do dia da competência numa camada só e nunca some valores de moedas diferentes. Exposição cambial = soma do valor de origem em USD.

Some o custo dos usuários do cliente no mês e compare com o MRR e com os créditos comprados. Mostre a distribuição de custo por usuário em percentis (p50, p75, p90, p99): a média esconde os heavy users. Um limite simples de alerta funciona, como usuário com mais de US$ 20 num dia.

Eventos de uso enviados pelo produto podem chegar duas vezes. Deduplique por um hash do conteúdo do evento antes de somar tokens, e guarde as retentativas da chamada como métrica própria: retentativa consome token e não entrega resposta.