Observabilidade LLM em um gateway de API multimodelo: Traces, Token Ledgers, Tenant Analytics e Safe Prompt Logging

Mantenha duas ideias separadas: a telemetria explica o que aconteceu, enquanto o razão de uso registra o que deve ser cobrado, reconciliado e relatado. Eles fazem referência entre si com IDs de solicitação e IDs de rastreamento, mas não precisam residir no mesmo sistema de armazenamento.

Crie um token e um livro-razão de custos, não apenas contadores

Os contadores de token são úteis para gráficos, mas não são suficientes para faturamento ou investigação de incidentes. Um livro-razão deve representar transições de estado. Crie uma linha quando o gateway aceitar uma solicitação e atualize-a conforme a solicitação avança.

Estados úteis do razão

• aceito: verificações de autenticação e política aprovadas.
• encaminhada: a solicitação foi enviada a um provedor.
• streaming: o provedor começou a devolver tokens.
• concluído: a resposta foi concluída com sucesso.
• user_aborted: o cliente foi desconectado antes da conclusão.
• nova tentativa: foi feita uma tentativa adicional do provedor.
• fallback_used: um modelo ou provedor diferente foi selecionado após falha ou correspondência de política.
• falhou: a solicitação terminou sem uma resposta utilizável.
• reconciliado: os dados de uso ou custo do fornecedor foram comparados e aplicados.

Esse modelo de estado ajuda a detectar erros comuns de faturamento e análise: respostas transmitidas em que o cliente se desconectou, novas tentativas que foram cobradas pelo provedor, mas ocultadas do usuário, caminhos alternativos que contaram o modelo errado e diferenças de contabilidade de cache entre provedores.

Use as convenções OpenTelemetry GenAI e estenda com cuidado

As convenções semânticas do OpenTelemetry GenAI fornecem um vocabulário portátil para operações de modelo. Use essas convenções para atributos comuns, como nome da operação, provedor, modelo, parâmetros de solicitação, motivos de término da resposta, uso de token e status de erro quando aplicáveis.

No entanto, as convenções neutras em termos de provedor não abrangerão todas as dimensões de negócios em um gateway. Adicione atributos de propriedade do gateway ou colunas contábeis para:

• ID do locatário, ID da equipe, ID do cliente revendedor e ID do aplicativo;
• ID da chave da API do gateway e escopo da chave;
• plano de faturamento, limite de gastos e política orçamentária;
• alias do modelo e versão da política de roteamento;
• ID do modelo de prompt e versão do prompt;
• nome do fluxo de trabalho e etapa do fluxo de trabalho;
• custo estimado, custo final faturado e status de reconciliação.

A compensação é a cardinalidade. Esses campos são valiosos para investigação, mas podem tornar as métricas caras e barulhentas se usadas como rótulos de métricas em todos os lugares. Uma regra prática é: agregados de baixa cardinalidade vão para métricas; identificadores de alta cardinalidade vão para traces, logs e ledgers.

Projetar prompt seguro e registro de saída

O registro completo facilita a depuração, mas aumenta a privacidade, a conformidade, o armazenamento e a exposição a riscos internos. O padrão mais seguro é a observabilidade que prioriza os metadados.

Padrão: somente metadados

Para a maior parte do tráfego de produção, armazene:

• ID e versão do modelo de prompt;
• hashes de prompts e saídas normalizados;
• contagens de tokens de entrada, saída, cache e contexto;
• nome do esquema de resposta e resultado da validação;
• rótulos de segurança e decisões políticas;
• resumos de erros e classes de erros do provedor;
• recuperação de metadados, não de documentos brutos.

Opt-in: captura de conteúdo controlada

Se você precisar de conteúdo bruto ou editado para depuração profunda, exija uma política explícita. Bons controles incluem listas de permissões de ambiente, consentimento do locatário, amostragem, comprimento máximo da carga útil, redação automática, janelas de retenção curtas, criptografia, acesso baseado em função, registros de auditoria e um caminho de aprovação rápida para incidentes confidenciais.

Não trate a redação como perfeita. Reduz o risco; isso não o elimina. Para cargas de trabalho regulamentadas ou de alta sensibilidade, considere armazenar apenas hashes e reproduzir problemas em um equipamento sintético com dados de teste aprovados.

Adicionar observabilidade RAG como uma camada separada

A geração por recuperação aumentada pode alterar tanto a qualidade quanto o custo. Registrar apenas a chamada de modelo final oculta a causa raiz quando o recuperador retorna muitos pedaços, documentos obsoletos ou contexto irrelevante.

Para cada etapa de recuperação, capture:

• índice ou nome da coleção;
• estratégia de recuperação e modelo de incorporação;
• IDs de documentos ou IDs com hash;
• contagem de blocos e total de tokens de contexto;
• latência de recuperação;
• Distribuição da pontuação máxima, se disponível;
• cobertura de citações;
• se o contexto recuperado foi usado na resposta final.

Isso permite distinguir “o modelo piorou” de “o recuperador começou a enviar contexto excessivo ou de baixa qualidade”. Também ajuda a identificar fluxos de trabalho em que os tokens de contexto dominam o custo total.

Conciliar o uso do gateway com a cobrança do provedor

As estimativas do gateway estão disponíveis imediatamente. Os dados de faturamento do provedor geralmente são mais lentos, mas mais confiáveis. Use ambos.

Um trabalho de reconciliação diário deve comparar as linhas do razão do gateway com APIs de uso do provedor, APIs de custo, exportações de painel ou exportações de faturas. Agrupe deltas por provedor, modelo, projeto e janela de tempo. Acompanhe as diferenças separadamente para tokens de entrada, tokens de saída, tokens armazenados em cache, contagens de solicitações e custos.

Diferenças comuns de reconciliação

• Desconexões de streaming: o gateway pode ver um cliente abortado enquanto o provedor ainda cobra os tokens gerados.
• Repetições: múltiplas tentativas podem ser cobradas mesmo que apenas uma resposta final seja retornada.
• Cache de prompt: os provedores podem expor a contabilidade do token armazenado em cache de maneira diferente.
• Arredondamento: pequenas diferenças por solicitação podem se tornar visíveis em escala.
• Descontos em lote ou níveis: as faturas do fornecedor podem aplicar preços que a estimativa em tempo real ainda não conhecia.
• Alterações no provedor: o preço do modelo, o comportamento da tokenização ou as exportações de faturamento podem mudar com o tempo.

Quando a reconciliação encontrar um delta, evite substituir silenciosamente seu razão. Armazene a estimativa original, o valor reconciliado pelo provedor, a fonte de reconciliação e o código de motivo, se conhecido.

Painéis que respondem a questões operacionais

Inicie painéis a partir dos problemas do leitor, não de métricas personalizadas. Visualizações úteis incluem:

• custo por locatário, equipe, aplicativo e fluxo de trabalho;
• custo por tarefa bem-sucedida, não apenas custo por solicitação;
• Latência p50, p95 e p99 por provedor, modelo e alias de modelo;
• taxa de fallback e taxa de novas tentativas por rota;
• taxa de tempo limite e tendências de classe de erro do provedor;
• taxa de acertos de cache e estimativa de economia de tokens em cache;
• taxa de falha na validação de saída estruturada;
• principais versões de prompt por erro de queima de orçamento;
• Compartilhamento de token de contexto RAG por fluxo de trabalho;
• blocos de guarda-corpo e acertos do classificador de injeção imediata.

Para alertas, combine sinais técnicos e comerciais. Um aumento repentino nos gastos dos locatários pode ser mais urgente do que um pequeno aumento na latência global. Um salto na taxa de fallback após uma alteração no alias do modelo pode indicar um problema de compatibilidade. Respostas 401, 429 ou 5xx repetidas podem apontar para problemas importantes, esgotamento da cota ou instabilidade do provedor.

Fluxo mínimo de implementação para um proxy compatível com OpenAI

Para um proxy /chat/completions, o fluxo pode ser simples:

1. Receba a solicitação e atribua request_id e rastreie o contexto.
2. Autentique a chave do gateway e resolva o escopo do locatário, da equipe, do aplicativo e da política.
3. Crie o intervalo do gateway pai.
4. Crie uma linha do razão com estado aceito.
5. Resolva o alias do modelo para o modelo do provedor e a versão da política de roteamento.
6. Metadados de registro: operação, ID do modelo de prompt, nome do esquema, hash de prompt e política de captura de conteúdo.
7. Inicie o período de chamada do modelo usando atributos semânticos GenAI quando aplicável.
8. Encaminhe a solicitação para o provedor selecionado.
9. Para streaming, atualize o estado quando o primeiro bloco chegar e conte o uso com a precisão permitida pela resposta do provedor.
10. Após a conclusão, analise o uso do provedor, o motivo da conclusão, o status e a classe do erro.
11. Atualize o razão com tokens, custo estimado, detalhes de nova tentativa/substituição e estado final da solicitação.
12. Emitir métricas do razão e dos dados do intervalo.
13. Execute a reconciliação diária e armazene o custo confirmado pelo fornecedor separadamente da estimativa original.

Lista de verificação de implementação

• Defina IDs de solicitação canônica e IDs de rastreamento.
• Adote atributos OpenTelemetry GenAI para modelo de telemetria comum.
• Crie um registro de uso de gateway com transições de estado de solicitação.
• Normalize as dimensões de provedor, modelo, alias de modelo, locatário, aplicativo e fluxo de trabalho.
• Mantenha dados de investigação de alta cardinalidade fora dos rótulos de métricas.
• Desativar o prompt bruto e a captura de saída por padrão.
• Adicione políticas explícitas para amostragem, redação, retenção e controle de acesso.
• Capture metadados de recuperação para fluxos de trabalho RAG.
• Crie painéis de controle de custo, latência, confiabilidade, validação e comportamento do locatário.
• Concilie as estimativas do gateway com o uso do provedor e as exportações de custos.
• Alerta sobre picos de gastos, regressões de latência, saltos de fallback, falhas de validação e eventos relevantes para a segurança.

Conclusão

Um gateway multimodelo é o lugar certo para implementar a observabilidade do LLM porque ele vê as solicitações antes que elas cheguem a qualquer provedor e pode anexar um contexto de negócios que os provedores não conhecem. O design mais forte não é “registrar tudo”. É um modelo em camadas: rastreamentos neutros em termos de provedor para execução, um token durável e registro de custos para faturamento, análise de locatários para governança, metadados RAG para qualidade de recuperação e registro de prompt com privacidade em primeiro lugar para depuração segura.

Comece com metadados, transições de estado e reconciliação. Adicione a captura de conteúdo somente quando a política, a retenção e os controles de acesso estiverem prontos. Essa sequência fornece aos desenvolvedores a evidência de que precisam para depurar latência, qualidade e gastos sem transformar a observabilidade em um novo risco de exposição de dados.

Leitura relacionada

• comportamento de repetição e fallback no roteamento da API LLM
• padrões de cache imediato e controle de custos em lote
• gerenciamento de chaves de API da equipe e limites de gastos