Dévoiler a caixa preta: Observabilidade prática para aplicações LLM – Um estudo de caso

A ascensão das aplicações LLM e o imperativo da observabilidade

Os grandes modelos de linguagem (LLM) transformaram o desenvolvimento de aplicações, permitindo funcionalidades antes confinadas à ficção científica. De chatbots inteligentes e geradores de conteúdo a assistentes de código sofisticados e ferramentas de análise de dados, os LLM impulsionam uma nova geração de softwares. No entanto, esse poder vem acompanhado de um conjunto de desafios únicos. Ao contrário das aplicações determinísticas tradicionais, os LLM são intrinsecamente probabilísticos, exibindo frequentemente comportamentos não lineares, preconceitos sutis e “alucinações” ocasionais. Depurar e otimizar essas aplicações pode ser semelhante a olhar dentro de uma caixa-preta.

É aqui que a observabilidade se torna não apenas uma melhor prática, mas uma necessidade absoluta. A observabilidade para aplicações LLM vai além das métricas de sistema tradicionais (CPU, memória, rede). Ela examina os aspectos qualitativos do desempenho do modelo, as nuances da engenharia de consultas, a eficácia dos pipelines de geração aumentada por recuperação (RAG) e a experiência do usuário como um todo. Sem uma observabilidade sólida, os desenvolvedores ficam adivinhando por que uma consulta não produz o resultado desejado, por que uma consulta RAG falha em recuperar documentos relevantes ou por que o desempenho de uma aplicação se deteriorou.

Estudo de caso: “DocuChat” – Uma aplicação LLM de base de conhecimento interna

Consideremos um estudo de caso prático: “DocuChat”, uma aplicação empresarial interna projetada para permitir que os funcionários consultem enormes bases de conhecimento internas (por exemplo, documentos de políticas, manuais técnicos, diretrizes de RH) usando linguagem natural. DocuChat utiliza uma arquitetura RAG sofisticada, combinando um LLM com um banco de dados vetorial armazenando embeddings de documentos internos. Os funcionários podem fazer perguntas como: “Qual é a política sobre despesas de trabalho remoto?” ou “Como configurar a autenticação única para o novo sistema de RH?”

Arquitetura base do DocuChat:

• Frontend: Uma interface web simples para entrada do usuário e exibição das respostas.
• Backend API: Gerencia sessões de usuário, orquestra interações.
• Pipeline RAG:
  • Pré-processamento de consultas: Limpa e potencialmente reescreve as consultas dos usuários.
  • Banco de dados vetorial (por exemplo, Pinecone, Weaviate): Armazena os embeddings dos documentos.
  • Módulo de recuperação: Interroga o banco de dados vetorial para encontrar pedaços de documentos relevantes com base na consulta do usuário processada.
  • Construtor de contexto: Junta os pedaços recuperados em um contexto coerente para o LLM.
• Integração do LLM (por exemplo, OpenAI GPT-4, Llama 2): Recebe a consulta do usuário e o contexto recuperado para gerar uma resposta.
• Pós-processamento da saída: Formata a resposta do LLM para exibição.

Os desafios da observabilidade no DocuChat

No início, o DocuChat foi lançado com um registro básico. Quando problemas surgiram, depurar foi um verdadeiro pesadelo:

• “A resposta está incorreta”: Foi uma consulta ruim? Documentos recuperados não relevantes? Uma alucinação?
• “Está lento”: Onde está o gargalo? Pesquisa no banco de dados vetorial? Tempo de inferência do LLM?
• “Não está usando os documentos corretos”: Por que o módulo de recuperação falhou? Embeddings inadequadas? Má formulação da consulta?
• “O modelo parece tendencioso”: Quais entradas levam a saídas tendenciosas?

Implementando uma observabilidade prática para o DocuChat

Para enfrentar esses desafios, a equipe do DocuChat implementou uma estratégia de observabilidade abrangente focada em quatro pilares principais: Registro, Rastreamento, Métricas e Feedback dos usuários.

1. Registro aprimorado: insights granulares em cada etapa

Além do simples registro de consultas/respostas, o registro do DocuChat foi enriquecido para capturar informações críticas em cada etapa do pipeline RAG.

Exemplos de registros enriquecidos:

• Registro de consultas de usuários:

  {
   "timestamp": "2023-10-27T10:00:01Z",
   "session_id": "sess_abc123",
   "user_id": "user_456",
   "original_query": "Qual é a política sobre despesas de trabalho remoto?",
   "request_id": "req_def789"
  }

• Registro de pré-processamento de consultas:

  {
   "timestamp": "2023-10-27T10:00:01Z",
   "request_id": "req_def789",
   "stage": "query_preprocessing",
   "processed_query": "política sobre despesas de trabalho remoto",
   "rewritten": false,
   "latency_ms": 15
  }

• Registro do módulo de recuperação (crucial para RAG):

  {
   "timestamp": "2023-10-27T10:00:02Z",
   "request_id": "req_def789",
   "stage": "retrieval",
   "search_query": "política sobre despesas de trabalho remoto",
   "retrieved_chunks": [
   {
   "chunk_id": "doc_123_chunk_a",
   "document_title": "Política de Trabalho Remoto v2.1",
   "score": 0.92,
   "content_snippet": "...Os funcionários são elegíveis para reembolso de despesas relacionadas ao trabalho remoto..."
   },
   {
   "chunk_id": "doc_456_chunk_b",
   "document_title": "Diretrizes de Reembolso de Despesas",
   "score": 0.88,
   "content_snippet": "...Todas as despesas de trabalho remoto devem ser pré-aprovadas..."
   }
   ],
   "num_chunks_retrieved": 2,
   "latency_ms": 150,
   "vector_db_query_params": {"k": 5, "metric": "cosine"}
  }

• Registro de inferência do LLM:

  {
   "timestamp": "2023-10-27T10:00:03Z",
   "request_id": "req_def789",
   "stage": "llm_inference",
   "model_name": "gpt-4",
   "input_tokens": 512,
   "output_tokens": 120,
   "prompt_template_version": "v3.1",
   "llm_api_cost": 0.005,
   "latency_ms": 1200,
   "full_prompt_hash": "abcdef123" // Hash do prompt real enviado ao LLM
  }

• Registro de resposta final:

  {
   "timestamp": "2023-10-27T10:00:04Z",
   "request_id": "req_def789",
   "final_response": "De acordo com a Política de Trabalho Remoto v2.1 e as Diretrizes de Reembolso de Despesas, os funcionários são elegíveis para reembolso de despesas relacionadas ao trabalho remoto que foram pré-aprovadas.",
   "response_quality_score": null, // A ser preenchido pelo feedback
   "overall_latency_ms": 1400
  }

Esses registros, armazenados em um sistema de registro centralizado (por exemplo, Elasticsearch, Splunk), permitem uma pesquisa, filtragem e identificação de padrões poderosas. Por exemplo, pesquisar ““score” : < 0.7” nos registros de recuperação pode sinalizar problemas potenciais com a relevância dos documentos.

2. Rastreamento distribuído: Rastreando o percurso da consulta

Enquanto os registros fornecem instantâneas, o rastreamento conecta essas instantâneas em uma narrativa completa de uma única consulta. Usando OpenTelemetry, o DocuChat instrumentou seus serviços para gerar rastros que cobrem todo o pipeline RAG.

Etapas de rastreamento chave para o DocuChat:

• handle_user_request (Etapa raiz)
• query_preprocessing
• vector_db_lookup
• build_llm_context
• llm_api_call
• response_post_processing

Uma ferramenta de visualização de rastreamento (por exemplo, Jaeger, Datadog APM) imediatamente destacou os gargalos de latência. Se llm_api_call mostrava sistematicamente uma latência alta, isso indicava um problema com o fornecedor do LLM ou com a rede. Se vector_db_lookup estava lento, a indexação do banco de dados vetorial ou os parâmetros de consulta precisavam ser otimizados. O rastreamento também ajudou a visualizar a sequência exata de eventos, facilitando a identificação de onde uma consulta poderia estar mal formulada ou onde o contexto foi perdido.

3. Métricas: Quantificando o desempenho e a saúde

As métricas fornecem visões agregadas e numéricas do comportamento do sistema ao longo do tempo. O DocuChat coletou uma ampla gama de métricas usando o Prometheus e as exibiu em painéis Grafana.

Métricas essenciais para o DocuChat:

• Volume de consultas: Total de consultas por minuto.
• Latência:
  • Latência de consulta de ponta a ponta (p50, p90, p99).
  • Latência por componente (por exemplo, `vector_db_lookup_latency_ms`, `llm_inference_latency_ms`).
• Taxa de erro:
  • Taxa de erro global da API.
  • Erros específicos (por exemplo, `llm_api_rate_limit_errors`, `vector_db_connection_errors`).
• Métricas específicas para LLM:
  • `llm_input_token_count_total`: Soma dos tokens de entrada utilizados.
  • `llm_output_token_count_total`: Soma dos tokens de saída gerados.
  • `llm_api_cost_total`: Custo cumulativo das chamadas à API LLM.
  • `model_usage_by_version`: Monitora qual versão do LLM está sendo utilizada.
• Métricas específicas para RAG:
  • `retrieved_chunks_count_avg`: Número médio de partes recuperadas por solicitação.
  • `retriever_max_score_avg`: Pontuação média de relevância máxima das partes recuperadas.
  • `context_length_avg`: Comprimento médio do contexto enviado ao LLM.

A supervisão dessas métricas revelou tendências. Um aumento repentino em `llm_api_cost_total` pode indicar um problema de eficiência na construção das solicitações (por exemplo, o envio de contextos muito grandes). Uma queda em `retriever_max_score_avg` pode sinalizar um problema com a indexação de novos documentos ou a qualidade dos embeddings, ou uma mudança nos padrões de solicitação dos usuários.

4. Feedback dos usuários: A camada qualitativa

Nenhuma quantidade de dados técnicos pode capturar plenamente a qualidade subjetiva da saída de um LLM. DocuChat integrou um mecanismo de feedback simples:

• Dedão para cima/baixo: Os usuários podiam avaliar a utilidade de uma resposta.
• Feedback opcional em texto livre: Para as respostas “dedão para baixo”, os usuários podiam explicar brevemente o porquê (por exemplo, “não relevante”, “incompleto”, “alucinação”).

Esse retorno foi correlacionado com o ID da solicitação original e armazenado com o registro da resposta final. Um painel mostrou uma tendência de feedbacks positivos/negativos. É crucial que os feedbacks negativos acionem um alerta para a equipe de desenvolvimento, permitindo que eles examinem o histórico completo da solicitação e os logs em busca de interações problemáticas específicas. Isso frequentemente revelava padrões:

• Vários feedbacks “não relevantes” apontavam problemas com o recuperador (por exemplo, a necessidade de aprimorar modelos de embedding ou ajustar parâmetros de pesquisa por vetor).
• Os feedbacks “incompletos” indicavam, às vezes, que a janela de contexto do LLM era muito pequena ou que o prompt não o solicitava para ser exaustivo.
• Os feedbacks “alucinação” eram os mais difíceis, mas permitiam iterações específicas de engenharia de prompt ou até ajustes de temperatura do modelo.

Exemplos práticos de observabilidade em ação

Cenário 1: Diagnosticar respostas “não relevantes”

Problema: Os usuários relatam que o DocuChat fornece respostas não relevantes para perguntas específicas sobre políticas de RH.

Fluxo de observabilidade:

1. Feedback: Vários feedbacks “dedão para baixo” para solicitações relacionadas a RH, com comentários como “não respondeu à minha pergunta sobre férias.”
2. Logs (Registro do Recuperador): Filtrar os logs para solicitações com feedback negativo. Observar que, para essas solicitações, `retriever_max_score_avg` é baixo (< 0.7), e a tabela `retrieved_chunks` contém documentos não relacionados a RH, ou apenas documentos de RH muito gerais.
3. Métricas (Métricas do Recuperador): Notar uma queda em `retriever_max_score_avg` para uma categoria de documentos específica (por exemplo, ‘RH’).
4. Rastreamento: Explorar uma solicitação específica com uma resposta não relevante. O rastreamento mostra que `vector_db_lookup` terminou rapidamente, mas os chunks recuperados estavam claramente fora de contexto. O LLM então tentou responder com base nesse contexto fraco.
5. Causa raiz & Ação: Os embeddings dos novos documentos de políticas de RH estavam mal gerados ou o índice da base de dados vetorial precisava ser reconstruído. O reindexamento dos documentos de RH com um modelo de embedding atualizado ou o ajuste dos parâmetros de pesquisa por vetor (por exemplo, utilizando um filtro mais específico) resolveu o problema.

Cenário 2: Identificar gargalos de desempenho

Problema: Os tempos de resposta do DocuChat são intermitentes e lentos, especialmente durante os horários de pico.

Fluxo de observabilidade:

1. Métricas (Painel de latência): O painel Grafana mostra que `end_to_end_request_latency_p99` dispara significativamente durante os horários de pico. Além disso, `llm_inference_latency_ms_p99` mostra picos semelhantes, enquanto `vector_db_lookup_latency_ms_p99` permanece relativamente estável.
2. Logs (Registro de Inferências LLM): Filtrar as solicitações lentas revela que `llm_api_rate_limit_errors` ocorrem com frequência.
3. Rastreamento: As trilhas para as solicitações lentas mostram claramente que a extensão `llm_api_call` leva um tempo anormalmente longo, muitas vezes com tentativas repetidas devido à limitação de taxa.
4. Causa raiz & Ação: O aplicativo estaria atingindo os limites de taxa do fornecedor LLM durante períodos de alta utilização. A equipe decide implementar uma lógica de retorno exponencial e re-tentar, além de explorar planos de API de nível superior ou considerar agrupar solicitações quando apropriado.

Conclusão: O futuro observável do LLM

Construir aplicações LLM sólidas requer ir além da caixa preta. Como mostra o exemplo do DocuChat, uma estratégia de observabilidade holística — combinando registro detalhado, rastreamento distribuído, métricas aprofundadas e retornos humanos inestimáveis — transforma a depuração de uma conjectura em um processo orientado por dados. Isso permite que os desenvolvedores entendam não apenas se uma aplicação LLM funciona, mas como ela funciona, por que pode falhar e onde melhorias podem ser feitas.

O campo da observabilidade dos LLMs está evoluindo rapidamente, com novas ferramentas e técnicas surgindo para tratar especificamente a engenharia de prompt, a detecção de alucinações e a identificação de viés. Ao adotar essas práticas, as empresas podem desbloquear todo o potencial das aplicações LLM, garantindo que sejam confiáveis, eficazes e que realmente trazem valor para os usuários.

🕒 Published: April 1, 2026