Como instrumentar uma aplicação de IA para investigar falhas, latência e consumo

1. Comece pelas perguntas operacionais, não pelos campos

A observabilidade de uma aplicação de IA consiste em conseguir reconstruir o seu comportamento a partir de sinais relacionados: que pedido chegou, que etapas foram executadas, o que falhou e quanto tempo demorou cada parte. Numa aplicação que já chama um modelo através de uma API, instrumentar não significa copiar cada entrada e resposta para um registo. Significa recolher contexto suficiente para responder de forma repetível a perguntas operacionais, com um âmbito e uma política de dados definidos.

Antes de escolher uma biblioteca ou criar um painel, escreva as perguntas a que a equipa precisa de responder durante um incidente. Por exemplo: que versão da aplicação e do prompt processou este pedido? O modelo foi chamado uma vez ou houve tentativas adicionais? Que ferramenta foi executada e quanto tempo demorou? A demora ocorreu na aplicação, na rede, no modelo ou numa ferramenta? Que utilização foi comunicada pela API? Estas perguntas delimitam o desenho; os campos que não ajudam a respondê-las não devem ser incluídos por hábito.

Convém distinguir a observabilidade da avaliação do conteúdo. Este guia centra-se no percurso técnico e operacional de um pedido: falhas, latência, tentativas adicionais e consumo comunicado. Não propõe um método para decidir se uma resposta é verdadeira, escolher um fornecedor ou desenhar um fluxo conversacional. Essa fronteira mantém os registos reduzidos e evita apresentar um sinal técnico como prova de qualidade.

2. Desenhe o ciclo e defina como correlacionar os eventos

Um pedido que parece uma única chamada na interface pode incluir várias operações: validação da entrada, construção do prompt, chamada ao modelo, processamento da resposta e, eventualmente, uma chamada a uma ferramenta. Se houver novas tentativas, cada uma deve ficar visível como uma operação distinta. O registo deve permitir reunir estes eventos sem depender de identificadores que a API externa não garanta.

Gere um identificador próprio para o pedido quando este entra na aplicação e propague-o pelos componentes que controla. Acrescente identificadores secundários ou números de etapa para distinguir chamadas ao modelo e às ferramentas. Se o fornecedor devolver um identificador de pedido, guarde-o como campo adicional para facilitar uma consulta ou um pedido de apoio posterior, mas não o use como única ligação: pode não estar disponível em todos os erros ou percursos de execução.

Defina também os limites temporais de cada medição. A duração total começa quando a aplicação aceita o pedido e termina quando entrega a resposta ou regista a falha final. A duração de uma chamada ao modelo começa quando essa chamada é iniciada e termina quando chega uma resposta ou um erro. Uma chamada a uma ferramenta tem os seus próprios tempos de início e fim. Registar milissegundos sem especificar esses limites produz valores que não podem ser comparados com segurança.

3. Defina um esquema mínimo e registe aquilo que a API realmente fornece

Um esquema mínimo deve separar os dados gerados pela aplicação dos campos recebidos do fornecedor. Entre os campos próprios podem estar o identificador do pedido, a etapa, o número da tentativa, o estado, as marcas temporais e as versões do código e do prompt. O modelo solicitado, a configuração e o identificador devolvido pelo fornecedor podem ajudar a reconstruir a execução, mas a origem de cada dado deve ser identificada.

A utilização comunicada por uma API não é universal. Pode variar consoante o endpoint, o modelo, a modalidade, a versão ou o tipo de resposta; também pode faltar em erros ou respostas parciais. A documentação disponível para este guia não especifica um fornecedor concreto nem permite afirmar que existe uma lista universal de campos. Por isso, implemente um adaptador para cada API e consulte a respetiva documentação primária atual para confirmar nomes, unidades e condições. Guarde o resultado como «utilização comunicada pela API», incluindo a indicação dos campos presentes, e não preencha valores em falta com zeros sem distinguir essa situação.

Separe também o tempo medido pela aplicação de qualquer duração comunicada pelo fornecedor. O primeiro mede o percurso no seu sistema; o segundo, se existir, obedece à definição do fornecedor. Mantenha as unidades explícitas — por exemplo, milissegundos para durações — e defina se as marcas temporais são guardadas em UTC. Uma convenção consistente permite comparar pedidos e detetar alterações sem misturar relógios ou intervalos diferentes.

4. Instrumente eventos estruturados de ponta a ponta

Os registos estruturados são mais fáceis de filtrar e agrupar do que mensagens em prosa. Defina nomes estáveis para eventos, estados e campos; evite que cada componente use uma etiqueta diferente para o mesmo conceito. Não é necessário adotar uma plataforma específica de observabilidade para começar: pode emitir eventos JSON na aplicação e exportá-los para a plataforma já utilizada pela equipa.

Um padrão útil consiste em emitir um evento de início e outro de conclusão por etapa, ou um único evento de conclusão que inclua início, fim e resultado quando a etapa for curta e não necessitar de atualizações em tempo real. Para operações longas, o evento de conclusão deve manter a ligação ao pedido original. Se utilizar rastreios distribuídos, propague o contexto pelos serviços e filas que controla; verifique se o identificador não se perde ao passar de uma tarefa síncrona para outra assíncrona.

O exemplo seguinte é pseudocódigo esquemático, não uma integração executável com uma API: os nomes dos campos da resposta e dos erros dependem do SDK e do fornecedor. Na implementação real, adapte a extração de utilização e erros à documentação atual e garanta que o bloco de exceção não regista automaticamente corpos que possam conter dados sensíveis.

5. Minimize os dados sensíveis antes de guardar ou exportar

A observabilidade não exige guardar prompts completos, respostas integrais ou argumentos de ferramentas em todos os pedidos. Estes conteúdos podem incluir dados pessoais, segredos, informação comercial ou material desnecessário para responder a perguntas operacionais. Comece por metadados e sinais derivados: identificadores opacos, versões, comprimentos, categorias de erro, estados e tempos.

Decida, campo a campo, que ação se aplica: excluir, redigir, transformar ou guardar com acesso restrito e retenção limitada. Para estabelecer uma ligação a uma entidade empresarial, pode bastar uma chave pseudonimizada ou uma referência interna que só um sistema autorizado consiga resolver. Um hash não garante anonimato se o valor original for previsível ou puder ser comparado com uma lista; não o trate automaticamente como solução de privacidade.

Teste a redação antes de ativar o registo em produção. Use exemplos sintéticos com casos típicos e variantes, como um endereço de correio eletrónico numa entrada, um token num cabeçalho ou um dado confidencial numa resposta de ferramenta. Verifique tanto o evento que sai da aplicação como o que chega ao repositório: uma regra aplicada apenas no painel ou depois da exportação deixa os dados expostos durante o percurso.

6. Construa painéis e alertas para investigar, não para acumular gráficos

Um painel útil responde a uma pergunta e deixa claro que ação pode seguir-se. Comece com três vistas: estado dos pedidos, distribuição da latência e utilização comunicada. Para o estado, mostre pedidos concluídos, falhados e sem resultado final, separados por categoria de erro. Para a latência, mostre a duração total e por etapa, incluindo percentis além das médias, porque uma média pode ocultar uma cauda de pedidos lentos. Para a utilização, mostre apenas os campos disponíveis e separe os dados por modelo, versão ou tipo de pedido quando essa segmentação ajudar a detetar alterações.

Os alertas devem representar uma condição que alguém possa investigar ou corrigir. Uma taxa de erros acima do comportamento habitual durante um intervalo definido pode justificar um alerta; uma falha isolada pode ficar no registo sem acordar a equipa. Os limiares dependem do volume e das expectativas do serviço, pelo que não convém fixar um valor universal sem dados. Inclua a janela de observação, o responsável e uma ligação à consulta ou ao procedimento de resposta.

Não apresente uma estimativa de custos baseada na utilização comunicada como se fosse um montante faturado. Para uma estimativa interna, multiplique as unidades disponíveis pelos preços e regras aplicáveis à conta e à configuração específicas, e identifique o resultado como estimativa. Os valores reais podem depender de condições que não se deduzem apenas do evento de resposta; confirme qualquer reconciliação com a documentação atual e os dados oficiais de faturação do fornecedor em causa.

7. Investigue um pedido falhado de forma reproduzível

Quando chega uma ocorrência, comece por identificar o ID do pedido e confirmar que corresponde ao ambiente e ao período corretos. Reúna os eventos por ordem temporal e por etapa. Antes de interpretar o resultado, verifique se o rastreio está completo: há eventos de início e de conclusão? Faltam segmentos de ferramentas? O registo assinala um erro terminal ou apenas uma tentativa falhada? Uma execução incompleta pode parecer uma falha do modelo quando, na realidade, as evidências simplesmente não foram guardadas.

Em seguida, reconstrua as versões e a sequência: código da aplicação, versão do prompt, modelo solicitado e qualquer modelo efetivamente utilizado que tenha sido possível observar, número de tentativas, ferramentas e estados. Compare a duração total com a soma das etapas, tendo em conta o trabalho local, as filas e os tempos que não estejam instrumentados. Se a soma não coincidir, registe-o como lacuna de telemetria, não como prova de uma causa.

Por fim, separe os factos das hipóteses. Um timeout do fornecedor pode estar registado como resultado de uma tentativa; isso, por si só, não demonstra por que ocorreu. Uma ferramenta lenta pode explicar parte do tempo medido, mas não necessariamente o comportamento final. Registe o que se sabe, o que falta e que verificação permitiria distinguir as hipóteses. Esta disciplina evita atribuir causas que o registo não comprova.

8. Verifique a instrumentação e amplie-a por etapas

A instrumentação também precisa de testes: a aplicação pode funcionar enquanto perde IDs, omite o evento de conclusão ou regista dados que deviam ter sido redigidos. Execute testes controlados para sucesso, erro, timeout, nova tentativa e chamada a ferramenta. Em cada caso, verifique a sequência completa, desde o evento de entrada até ao resultado final, bem como as permissões e a redação antes da exportação.

Comece por um percurso de produção limitado e confirme que as consultas respondem a perguntas reais. Verifique o volume gerado pelos registos e se a equipa consegue encontrar um pedido sem procurar manualmente em vários sistemas. Ajuste a seleção de eventos e a retenção antes de ampliar o âmbito. O objetivo não é maximizar a quantidade de telemetria, mas manter evidências suficientes e consultáveis para operar o sistema.

As convenções de telemetria e os campos de utilização das APIs podem evoluir. Versione o esquema interno e valide os adaptadores quando mudar o SDK, a API ou a configuração. Se o fornecedor alterar uma resposta, a camada de normalização deve poder adaptar-se sem que todos os painéis e consultas dependam dos nomes externos. Uma prática geral de observabilidade pode orientar a organização de sinais e rastreios; não substitui a documentação técnica primária para confirmar campos ou faturação de um fornecedor específico.

Continue a explorar

Correções e transparência

Se encontrar informação incorreta ou desatualizada, envie-nos a página e a fonte que devemos rever.