Catálogos de preços versionados para gateways de API de IA: Impeça a variação de preços devido à quebra de cotações e estorno

O faturamento da API AI falha quando o gateway trata os preços do provedor como uma tabela de pesquisa estática. A parte difícil não é multiplicar os tokens por uma taxa. A parte difícil é saber qual taxa era válida no momento da solicitação, qual SKU correspondia ao intervalo de uso real, se o preço foi aprovado e por que a cotação do cliente difere da fatura do fornecedor.

Um gateway que oferece suporte a vários modelos, contas, regiões, modos de cache, trabalhos em lote, ferramentas hospedadas e implantações provisionadas precisa de um plano de controle de preços. Esse plano de controle deve ingerir cartões de preços do fornecedor, versão de cada taxa aprovada, mapear o uso do fornecedor em SKUs faturáveis, testar cotações antes da implementação e reconciliar linhas contábeis liquidadas com faturas.

O problema do leitor: a variação de preços quebra mais do que as páginas de preços

Os preços do provedor podem variar entre dimensões que as equipes de aplicação raramente veem diretamente: versão do modelo, tokens de entrada, tokens de entrada em cache, tokens de saída, tokens de raciocínio, gravações em cache, ferramentas hospedadas, descontos em lote, tipo de implantação, região, moeda e planos de capacidade comprometida. Se essas dimensões forem niveladas em um campo de “custo por token”, o gateway acabará por fazer cotações incorretas, reservar orçamentos em excesso, faturar menos aos inquilinos ou alocar gastos para o centro de custo errado.

A falha geralmente aparece em um dos cinco lugares:

• Cotações de simulação: uma solicitação é aceita porque o gateway faz uma estimativa em relação a uma taxa antiga ou incompleta.
• Reservas de orçamento: o saldo do locatário é reservado usando um catálogo, mas liquidado usando outro.
• Ledgers de uso: tokens armazenados em cache, tokens de raciocínio, chamadas de ferramentas ou unidades de lote são armazenados como totais genéricos e não podem ser reavaliados corretamente.
• Exportações de estornos: o setor financeiro recebe os totais do inquilino sem as dimensões da fatura do fornecedor necessárias para explicar a variação.
• APIs de parceiros: produtos downstream expõem preços sem saber se esses preços são atuais, estimados, obsoletos ou bloqueados.

Fatos a serem preservados no design de preços

Fato: a documentação do provedor público geralmente separa os preços por modelo e categoria de token. Os tokens de entrada, entrada em cache e saída podem ter taxas diferentes. Alguns relatórios de uso expõem contagens de entradas em cache ou de tokens de raciocínio, o que significa que um gateway deve preservar as subcategorias de uso em vez de armazenar apenas o total de tokens.

Fato: os preços nem sempre são puramente tokens de pagamento conforme o uso. Alguns provedores vendem capacidade comprometida, rendimento provisionado ou unidades de token vinculadas a capacidade de modelo específico. Nesses modos, o custo pode ser baseado em tempo, unidades de capacidade ou proporções de entrada/saída específicas do modelo, em vez de uma simples fatura de token por solicitação.

Fato: ferramentas hospedadas e recursos de recuperação podem criar eventos faturáveis adicionais fora da inferência normal do modelo. Fundamentos de pesquisa, pesquisa de arquivos, contexto de URL, execução de código, gravações de cache e etapas intermediárias de agente podem exigir mapeamento de SKU separado.

Recomendação: trate esses fatos como requisitos de esquema, não como exceções. Se um evento de uso contiver uma dimensão faturável que o catálogo não consegue mapear, o gateway deverá colocar a transação em retenção de faturamento em vez de silenciosamente precificá-la como zero.

Crie um catálogo de preços versionado

Um catálogo de preços deve ser uma tabela ou serviço de primeira classe, e não constantes incorporadas em adaptadores de provedores. O catálogo existe para responder a uma pergunta: para este evento de utilização, neste momento, neste contexto de conta de inquilino e fornecedor, qual taxa aprovada deve ser usada?

Campos principais do catálogo

Uma linha prática do catálogo deve incluir pelo menos estes campos:

• catalog_version_id: versão imutável usada para cotação, reserva, liquidação e reconciliação.
• provedor: o provedor upstream ou adaptador de provedor interno.
• provider_account_scope: global, organização, projeto, espaço de trabalho, locatário BYOK, conta de revendedor ou contrato empresarial.
• model_id_or_alias: o ID do modelo visível ao provedor ou o alias do modelo interno que está sendo precificado.
• pricing_sku: o SKU canônico usado pelo gateway para liquidação.
• provider_meter_id: medidor de fatura upstream opcional, quando disponível.
• billing_unit: token de entrada, token de entrada em cache, token de saída, token de raciocínio, gravação em cache, consulta de pesquisa, token de imagem, segundo de áudio, unidade de lote, hora PTU ou outra unidade explícita.
• region_scope: global, região, zona de residência, mercado ou classe de residência de dados.
• deployment_type: sem servidor, em lote, provisionado, dedicado, ajustado ou sandbox interno.
• service_tier: padrão, prioridade, lote, rápido, provisionado ou outro nível de gateway.
• moeda: a moeda da taxa antes da marcação, impostos, créditos ou conversão.
• taxa: taxa decimal exata, nunca ponto flutuante binário.
• minimum_unit: a menor unidade faturável.
• regra de arredondamento: por solicitação, por linha de fatura, por período de inquilino ou definido pelo provedor.
• source_url: documentação, tabela de preços, referência de contrato ou tíquete de aprovação interna.
• observed_at: quando o preço foi detectado ou importado.
• efetivo_de e efetivo_para: a janela de validade.
• approval_state: rascunho, revisado, aprovado, obsoleto, bloqueado ou substituído.

O detalhe importante da implementação é que uma versão do catálogo é imutável quando usada pelo tráfego. As correções devem criar uma nova versão ou uma entrada de ajuste, e não alterar a versão histórica à qual as linhas do razão existentes fazem referência.

Separar aliases de modelo de SKUs de preços

Alases internos como chat-default, support-fast ou reasoning-premium são conveniências operacionais. Eles não devem substituir o ID do modelo visível ao provedor ou o SKU de preço no razão.

Um evento de uso deve armazenar todas as três identidades:

• requested_model_alias: o que o aplicativo solicitou.
• upstream_model_id: como o gateway realmente chamou.
• pricing_sku: o que o mecanismo de faturamento usou para liquidação.

Isso evita que promoções de alias reescrevam o histórico. Se chat-default apontar para um modelo em agosto e um modelo mais recente em setembro, o uso de agosto deverá permanecer vinculado ao modelo upstream de agosto e à versão do catálogo de agosto.

Citação de uma versão de catálogo imutável

As citações só são úteis se puderem ser explicadas posteriormente. O gateway deve selecionar uma versão do catálogo antes do envio, usá-la para a cotação pré-voo, persisti-la na reserva do orçamento e levá-la até a liquidação final.

Um ciclo de vida de solicitação mínimo é assim:

1. Normalize a solicitação nas dimensões faturáveis esperadas: modelo, nível de serviço, região, estimativa de token, elegibilidade de cache, ferramentas, modo em lote e tipo de implantação.
2. Selecione a versão ativa do catálogo aprovada para o escopo da conta do locatário e do provedor.
3. Resolva os SKUs esperados para cada dimensão faturável possível.
4. Calcule uma estimativa de pré-voo e reserve o orçamento do inquilino.
5. Envie a solicitação upstream somente se todos os mapeamentos de SKU necessários existirem.
6. Capture metadados de uso final da resposta do provedor, incluindo subcategorias.
7. Liquidar o uso real usando a mesma versão do catálogo, a menos que seja necessário um fluxo de trabalho de correção explícito.
8. Registre qualquer variação entre os valores reservados e liquidados.

Recomendação: cite e reserve com suposições conservadoras e, em seguida, resolva a partir do uso pós-resposta. O preço exato de pré-despacho é difícil para streaming, novas tentativas, ferramentas hospedadas, agentes de longa execução e comportamento de acertos de cache. O objetivo não é uma previsão perfeita. O objetivo é exposição controlada e liquidação explicável.

Falha ao fechar para dimensões faturáveis desconhecidas

O bug de preços mais perigoso é a falta de um SKU que se torna de uso gratuito. Um gateway deverá falhar ao fechar quando uma resposta do provedor incluir um intervalo de uso que não tenha mapeamento aprovado.

Exemplos que devem acionar uma retenção de faturamento:

• Uma resposta de modelo inclui cached_input_tokens, mas o catálogo possui apenas taxas genéricas de token de entrada e saída.
• Um modelo de raciocínio retorna reasoning_tokens, mas nenhum SKU de raciocínio está configurado.
• Uma ferramenta de pesquisa hospedada cobra por consulta, mas o gateway registra apenas tokens de modelo.
• Um trabalho em lote recebe um desconto, mas o catálogo o mapeia para o SKU padrão sem servidor.
• Uma implantação provisionada emite cobranças de capacidade por hora, mas o razão do locatário espera liquidação por token.
• Uma implantação regional usa um modificador de residência que não está presente no catálogo ativo.

Uma retenção de faturamento não deve perder o evento. Ele deve preservar o uso bruto do provedor, o uso normalizado, os identificadores de solicitação, os identificadores do locatário, o escopo da conta do provedor, a tentativa de versão do catálogo, os campos SKU ausentes e o motivo pelo qual a liquidação foi bloqueada. Depois que o catálogo for atualizado e aprovado, a fila de espera poderá ser reproduzida de forma determinística.

Use verificações de diferenças de tabela de preços antes da aprovação

As páginas de preços e APIs dos provedores nem sempre são estáveis ​​em termos de máquina, e os contratos podem substituir as taxas públicas. Ainda assim, as verificações automáticas de diferenças são úteis como alertas. Eles devem detectar alterações antes que as cotações visíveis ao cliente sejam afetadas.

Um pipeline de importação de preços deve comparar as tabelas de preços recém-observadas com o último catálogo e sinalização aprovados:

• modelos novos ou modelos aposentados;
• entrada alterada, entrada em cache, saída ou taxas de raciocínio;
• novas categorias de tokens ou medidores de ferramentas;
• multiplicadores de gravação de cache ou de acerto de cache alterados;
• novos modificadores regionais, de residência ou de mercado;
• regras de desconto em lote alteradas;
• alteração das regras de capacidade provisionada ou capacidade comprometida;
• mudanças de moeda;
• alterações de arredondamento ou unidade mínima;
• conflitos entre tabelas de preços públicas e taxas contratuais específicas da conta.

Recomendação: trate scrapes e importações como dados de rascunho. Exija aprovação humana para qualquer alteração que afete o tráfego faturado, preços visíveis para parceiros ou finanças de exportações. A experimentação interna pode usar um catálogo sandbox, mas deve ter limites de gastos explícitos e nunca deve ser confundido com faturamento aprovado do cliente.

Adicionar testes de cotação como CI de preços

As alterações de preços precisam de testes pelo mesmo motivo que as alterações de código: uma pequena edição pode afetar muitos formatos de solicitação. Os testes de cotação devem ser executados sempre que houver alterações nas linhas do catálogo, nos mapeamentos de SKU, nos adaptadores de provedor ou nas políticas de marcação.

Use formatos de solicitação sintéticos que cubram a superfície de preços:

• solicitação de texto padrão com tokens de entrada e saída;
• solicitação com tokens de entrada armazenados em cache;
• solicitação com muito raciocínio com uso de raciocínio separado;
• solicitação de uso de ferramenta com cobrança de pesquisa, arquivo ou execução de código;
• solicitação multimodal com unidades de imagem, áudio, vídeo ou mídia gerada;
• trabalho em lote com taxas de desconto e liquidação atrasada;
• implantação provisionada com capacidade horária e comportamento de transbordamento;
• solicitação regional ou com escopo de residência;
• locatário com taxas de contrato específicas do fornecedor;
• Locatário parceiro com política de acréscimo ou desconto.

Cada teste deve afirmar mais do que um total final. Ele deve declarar a versão do catálogo selecionada, a lista de SKU, as unidades de faturamento, as taxas, o comportamento de arredondamento, a moeda, o total estimado, o valor da reserva e as linhas de liquidação esperada.

Exemplo de teste de cotação