Streaming de contabilidade de token em um AI API Gateway: uso final, cancelamentos e respostas parciais

Se o chamador downstream omitir, o gateway poderá decidir se deve injetá-lo em rotas onde isso for compatível. Documente esse comportamento porque alguns clientes esperam compatibilidade exata de fios e alguns modelos ou upstreams podem não suportar o uso final da mesma maneira.

Recomendação: não liquide os custos do inquilino desde os primeiros períodos. Mantenha a linha do razão aberta até que o evento de uso final seja capturado, a resposta do provedor termine sem uso ou o fluxo insira um erro ou caminho de cancelamento.

Transmissão antrópica

O uso cumulativo do Antrópico requer uma regra diferente. Se um gateway vir três eventos message_delta com contagens de tokens de saída de 10, 25 e 40, a contagem de saída será 40, não 75.

let lastUsage = null;
para aguardar (evento const de anthropicStream) {
  if (event.type === "message_delta" && event.usage) {
    if (latestUsage && event.usage.output_tokens < lastUsage.output_tokens) {
      emit("cumulative_usage_regressed", requestId);
    }
    últimoUso = evento.uso;
  }
  forwardToClient(evento);
}
liquidarFromLatestCumulativeUsage(latestUsage);

Recomendação: registre o valor de uso cumulativo mais recente e emita um evento de observabilidade se ele regredir. Uma regressão pode indicar erros no analisador, eventos duplicados, alterações de provedor ou fluxos mistos.

Streaming estilo Gemini e Vertex

O Gemini oferece suporte a blocos de streaming para reduzir a latência percebida. Nos SDKs estilo Vertex, o streaming pode expor um fluxo assíncrono e um objeto de resposta agregado. Um gateway deve preservar esse caminho agregado quando disponível.

const streamingResult = aguarda model.generateContentStream(request);
para aguardar (parte const de streamingResult.stream) {
  encaminharPedaço(pedaço);
  contagemDeliveredBytesOrText(pedaço);
}
const agregado = aguarda streamingResult.response;
liquidarFromAggregatedUsage(agregado);

Recomendação: evite criar toda a contabilidade a partir de partes visíveis se o SDK fornecer um registro de resposta completo. Pedaços são para latência. O objeto final geralmente é melhor para faturamento e análise.

Trate de desconexões de clientes como eventos contábeis de primeira classe

As desconexões de clientes são onde muitos gateways perdem dinheiro ou sobrecarregam os clientes. Uma guia do navegador é fechada, uma rede móvel cai ou um aplicativo cancela uma solicitação. O gateway percebe que o soquete downstream está fechado, mas o provedor upstream ainda pode estar gerando.

O gateway deve fazer uma escolha política explícita:

• Cancelar o upstream imediatamente: reduz o desperdício de geração e o custo do provedor, mas pode interromper os fluxos de trabalho em que o back-end ainda precisa do resultado após a desconexão da IU.
• Continuar o upstream em segundo plano: pode preservar o trabalho dos consumidores do lado do servidor, mas o usuário pode não ver todos os tokens gerados e cobrados.
• Comportamento dependente da rota: cancele para bate-papo interativo, continue para fluxos de trabalho semelhantes aos de trabalho e torne a configuração visível para os locatários.

Um padrão prático para streaming interativo é cancelar o upstream quando o cliente downstream se desconecta e, em seguida, marcar a linha do razão como client_aborted. Se o uso final chegar durante o cancelamento, faça o acordo a partir desse uso oficial. Caso contrário, marque a linha como estimated ou pending_reconciliation em vez de fingir que é exata.

downstream.on("close", async () => {
  if (!providerCompleted) {
    ledger.markClientAborted(requestId);
    aguarde upstream.abort().catch(() => {
      ledger.emit("upstream_cancel_failed", requestId);
    });
  }
});

Recomendação: exponha rótulos de faturamento transparentes, como final, provider_reconciled, estimado, dispensado ou reconciliação_pendente. Isso é mais defensável do que mostrar todas as chamadas transmitidas como imediatamente exatas.

Aplicação de cota durante uma transmissão

O faturamento preciso geralmente depende do uso final do provedor, mas a aplicação de cotas nem sempre pode esperar até o fim. Um locatário com um orçamento rígido não deve ter permissão para transmitir indefinidamente porque o uso exato não está disponível no meio do voo.

Use dois mecanismos juntos:

1. Reserva pré-voo: reserve um valor máximo estimado com base no modelo, no máximo de tokens solicitados, na política do locatário e no saldo atual.
2. Verificações de pressão de streaming: estime a saída entregue durante o fluxo e pare se a solicitação cruzar um limite de segurança configurado.

Este é um mecanismo de controle, não a conta final. Os provedores podem contar tokens armazenados em cache, tokens de raciocínio, tokens multimodais ou tokens ocultos de maneira diferente do estimador de um gateway.

Compensação: estimativas em tempo real ajudam a impor orçamentos, mas podem divergir dos tokens cobrados pelo fornecedor. A liquidação final deve usar o uso oficial do provedor, quando disponível, e a reconciliação deve ajustar as estimativas posteriormente.

Eventos de observabilidade que detectam bugs contábeis

As falhas de faturamento de streaming são mais fáceis de depurar quando o gateway emite eventos direcionados em vez de apenas logs de solicitação genéricos. Adicione eventos como:

• final_usage_missing: transmissão encerrada sem uso autorizado.
• cumulative_usage_regressed: contagem cumulativa de tokens retrocedida.
• stream_ended_without_stop_event: nenhum marcador normal de parada do provedor foi observado.
• aborted_after_provider_completion: o provedor foi concluído, mas o cliente downstream fechou antes que o gateway terminasse o encaminhamento.
• settled_from_estimate: o razão do inquilino usou uma estimativa porque o uso final não estava disponível.
• reconciliation_adjusted_usage: o relatório do provedor alterou posteriormente a linha.

Fato: as convenções semânticas do OpenTelemetry GenAI recomendam o uso de informações de uso retornadas pelo provedor para respostas de streaming, quando disponíveis, e alertam contra métricas de uso de relatórios se as contagens de token não puderem ser obtidas de forma eficiente ou precisa.

Para análises de uso de IA, isso significa que os painéis devem oferecer suporte a níveis de confiança. Um gráfico que mistura valores finais, estimados e reconciliados sem rótulos pode parecer limpo, mas enganar as equipes financeiras e de suporte.

Testes de conformidade para contabilidade de streaming

Não confie em testes manuais com um prompt de bate-papo de caminho feliz. Cada adaptador provedor deve ter testes de conformidade para os casos que quebram os livros contábeis:

• Fluxo normal: o uso final chega, o evento de parada é observado, o razão é liquidado como final.
• Fluxo de chamada de ferramenta: os deltas de chamada de ferramenta são encaminhados, o uso é capturado, os metadados estruturados não corrompem a contagem de tokens.
• Parada de segurança ou recusa: o provedor para mais cedo, o uso ainda é liquidado corretamente.
• Desconexão forçada do cliente: downstream fecha após saída parcial; o upstream é cancelado ou continuado de acordo com a política.
• Upstream 5xx após saída parcial: o gateway registra a entrega parcial e não marca a solicitação como um sucesso limpo.
• Tempo limite do gateway antes do uso final: a linha torna-se estimada ou há reconciliação pendente.
• Evento final ausente: o adaptador emite final_usage_missing e evita rótulos de cobrança exatos.

Esses testes devem afirmar transições de estado, campos contábeis, eventos de observabilidade emitidos e comportamento downstream. A compatibilidade do fluxo byte por byte não é suficiente; os efeitos colaterais contábeis fazem parte do contrato.

Lista de verificação prática de implementação

• Crie a linha do razão de uso antes de enviar a solicitação upstream.
• Armazene identificadores de inquilino, chave, usuário, modelo, rota, provedor e solicitação no momento da solicitação.
• Ative relatórios de uso final do provedor onde houver suporte, como stream_options.include_usage compatível com OpenAI.
• Para provedores cumulativos, armazene o valor de uso mais recente em vez de somar eventos.
• Preserva objetos de resposta agregados quando os SDKs os fornecem.
• Rastreie os resultados entregues separadamente do uso faturado pelo provedor.
• Ao desconectar, cancele o upstream de acordo com a política de rota e marque client_aborted.
• Use status de faturamento transparentes: reconciliação final, estimada, pendente, reconciliada pelo provedor ou dispensada.
• Emitir eventos de observabilidade específicos da contabilidade.
• Reconcilie posteriormente com relatórios de uso ou custo do provedor, quando disponíveis, preservando a atribuição do locatário no momento da solicitação.

O que mostrar aos inquilinos

Os inquilinos não precisam de todos os eventos internos, mas precisam de rótulos honestos. Uma tabela de uso útil pode mostrar:

• Status: final, estimado ou reconciliado.
• Resultado da solicitação: concluída, cliente anulado, erro do provedor ou tempo limite do gateway.
• Saída entregue: texto aproximado ou bytes enviados ao cliente.
• Tokens faturados: uso normalizado pelo provedor usado para custo.
• Ajuste: qualquer delta de reconciliação posterior.

Este design reduz a ambiguidade do suporte. Se um usuário viu apenas parte de uma resposta, o painel poderá explicar se o provedor já havia concluído, se o gateway cancelou o upstream e se a cobrança é final ou estimada.

Recomendações versus previsões

Recomendações: trate as solicitações transmitidas como máquinas de estado, aguarde o uso final oficial antes da liquidação exata, separe a saída entregue do uso faturado e rotule honestamente as linhas estimadas. Os adaptadores do provedor devem codificar a semântica de uso específica do provedor, em vez de nivelar cada fluxo em um proxy de byte genérico.

Previsão: a contabilidade de streaming se tornará mais importante à medida que os modelos expõem mais trabalhos ocultos: tokens de raciocínio, descontos em tokens em cache, processamento multimodal, rastreamentos de uso de ferramentas e paradas de segurança. Os gateways que já separam o uso cobrado pelo provedor da saída visível ao cliente se adaptarão mais facilmente do que os gateways que contam apenas o texto transmitido.

Conclusão acionável

Se o seu gateway oferece suporte a streaming, audite um caminho hoje: force a desconexão de um cliente após os primeiros blocos e inspecione a linha do razão. Se aparecer “sucesso” com contagens de tokens de aparência exata, suas análises provavelmente estão mentindo.

A solução é não abandonar o streaming. Mantenha a experiência rápida do usuário, mas torne a conclusão do fluxo, o cancelamento, os erros do provedor, a falta de uso final e a reconciliação de estados contábeis explícitos. Isso dá às equipes de produto resultados responsivos, custos defensáveis às equipes financeiras e às equipes de suporte evidências suficientes para explicar respostas parciais sem adivinhação.

Leitura relacionada

• projetando o razão de faturamento por trás de cada chamada de modelo
• junção de rastreamentos, registros de tokens e análises de uso seguro
• construindo um contrato de compatibilidade de gateway compatível com OpenAI