LLM Evals em Produção: Como Medir e Testar Agentes de IA no CI/CD

Testar modelos de linguagem inspecionando três ou quatro prompts no chat manual não sustenta sistemas em produção. Quando um provedor atualiza pesos ou quando prompts mudam, agentes corporativos quebram de forma silenciosa e imprevisível.

A engenharia de software para agentes exige suítes determinísticas de avaliação contínua (LLM Evals) integradas diretamente ao pipeline de integração contínua (CI/CD).

Por que o teste manual de prompts falha em escala?

O teste manual de prompts falha porque modelos de linguagem são sistemas probabilísticos que sofrem regressões não determinísticas em cenários de cauda longa.

Ajustar uma instrução de sistema para resolver um caso específico frequentemente quebra outros dez fluxos de negócio. Sem uma base de regressão estruturada, o desenvolvedor não percebe a quebra até que usuários finais relatem erros em produção.

A literatura acadêmica documenta esse fenômeno. O estudo de Zheng et al. (2023) sobre avaliação automatizada demonstra que a percepção humana pontual é inconsistente e sujeita a fadiga cognitiva rápida.

Além disso, trocas de modelos de base — como migrar do GPT-4o para o Claude 3.5 Sonnet ou DeepSeek-R1 — alteram a adesão a formatos estruturados e mudam a interpretação de ferramentas externas (function calling).

Como é estruturada a pirâmide de avaliação de LLMs?

A pirâmide de avaliação de LLMs divide a validação de agentes em três camadas consecutivas: testes determinísticos na base, métricas heurísticas e semânticas no meio, e avaliadores baseados em modelo (LLM-as-a-Judge) no topo.

Essa distribuição equilibra velocidade de execução no CI/CD com precisão semântica profunda.

1. Camada Base: Testes Unitários Determinísticos

A base da pirâmide não consome chamadas caras de LLM. Ela valida se a resposta bruta cumpre contratos rígidos de software:

• Conformidade de Schema: Validação estrita de contratos JSON via JSON Schema ou bibliotecas como Zod e Pydantic.
• Asserção de Tool Calling: Verificação de que o agente disparou a função correta com os argumentos tipados exigidos.
• Bloqueio de Regras e Expressões: Detecção de padrões proibidos, vazamento de chaves ou ausência de tags obrigatórias.
• Orçamento de Latência e Tokens: Falha imediata caso a geração ultrapasse limites financeiros ou temporais estipulados.

2. Camada Intermediária: Métricas Heurísticas e Vetoriais (RAGAS)

Para arquiteturas RAG (Retrieval-Augmented Generation), a camada intermediária calcula alinhamento contextual e precisão documental.

Conforme formalizado pelo framework Ragas (Es et al., 2023), três métricas são indispensáveis:

1. Fidelidade (Faithfulness): Mede a razão entre afirmações verificáveis na resposta e fatos presentes no contexto recuperado.
2. Relevância da Resposta (Answer Relevance): Avalia se o output atende diretamente à pergunta formulada, sem divagações.
3. Precisão do Contexto (Context Precision): Quantifica se os chunks relevantes de informação foram ordenados no topo pelo retriever.

3. Camada Superior: Model-Graded Evals (LLM-as-a-Judge)

No topo da pirâmide, modelos de alta capacidade avaliam tarefas abertas seguindo rubricas estritas de pontuação.

A metodologia G-Eval (Liu et al., 2023) demonstrou que LLMs instruídos com cadeias de pensamento (Chain-of-Thought) e rubricas detalhadas atingem alinhamento superior a 80% com juízes humanos especialistas.

Como construir um Golden Dataset representativo?

Um golden dataset representativo é uma coleção versionada de pares de entrada, contexto de referência e saídas esperadas que espelham o tráfego real do sistema.

Sem um dataset de referência, métricas estatísticas não têm ponto de ancoragem para calcular desvios de qualidade.

[
  {
    "id": "eval_fin_042",
    "input": "Qual foi a margem EBITDA consolidada no 3T25?",
    "retrieved_context": [
      "No 3T25, a receita líquida atingiu R$ 450M e o EBITDA ajustado fechou em R$ 112,5M (margem de 25,0%)."
    ],
    "expected_ground_truth": "A margem EBITDA consolidada no 3T25 foi de 25,0%.",
    "required_tool": "query_financial_database",
    "rubric": {
      "numerical_accuracy": 1.0,
      "cite_reference": true,
      "tone": "objective"
    }
  }
]

Para manter o dataset atualizado sem esforço desproporcional, equipes de engenharia adotam três práticas contínuas:

• Curadoria de Falhas Reais: Toda alucinação ou resposta incorreta reportada em produção é sanitizada e adicionada imediatamente à suíte de testes.
• Geração Sintética com Filtragem Humana: Criação de variações sintéticas de perguntas usando modelos auxiliares, com revisão amostral de especialistas.
• Estratificação por Dificuldade: Separação dos casos entre consultas triviais, consultas com contexto ambíguo e casos de ataque adversarial (jailbreak attempts).

Como implementar LLM-as-a-Judge sem viés sistemático?

Para implementar LLM-as-a-Judge sem viés sistemático, o pipeline precisa mitigar os três vieses clássicos identificados pela pesquisa: viés de posição, viés de verbosidade e viés de auto-preferência.

Modelos de linguagem tendem a preferir respostas mais longas e textos posicionados em primeiro lugar na avaliação comparativa.

                    ┌────────────────────────┐
                    │  Entrada + Contexto    │
                    └───────────┬────────────┘
                                │
                 ┌──────────────┴──────────────┐
                 ▼                             ▼
        ┌─────────────────┐           ┌─────────────────┐
        │ Resposta A (v1) │           │ Resposta B (v2) │
        └────────┬────────┘           └────────┬────────┘
                 │                             │
                 └──────────────┬──────────────┘
                                │
                    ┌───────────▼────────────┐
                    │ Inversão de Posição    │  -> [A vs B] e [B vs A]
                    └───────────┬────────────┘
                                │
                    ┌───────────▼────────────┐
                    │ Juiz com Rubrica CoT   │  -> Formato JSON Estrito
                    └───────────┬────────────┘
                                │
                    ┌───────────▼────────────┐
                    │ Score Médio Ponderado  │
                    └────────────────────────┘

A mitigação técnica desses desvios requer quatro regras estruturais:

1. Permutação de Ordem (Position Swapping): Ao comparar duas respostas (A e B), o juiz deve avaliar [A, B] e [B, A]. Casos divergentes são marcados como inconclusivos.
2. Penalização de Verbosidade: A rubrica deve instruir explicitamente que concisão técnica recebe nota superior a prolixidade explicativa.
3. Juiz Neutro ou Cruzado: Evitar que o modelo avalie a si mesmo quando houver alternativas viáveis (exemplo: usar Claude 3.5 Sonnet para julgar saídas do GPT-4o).
4. Decodificação com Temperatura Zero: O prompt do juiz deve rodar estritamente com temperature = 0.0 e requerer justificativa passo a passo antes da emissão da nota numérica.

Como integrar o pipeline de Evals ao CI/CD no GitHub Actions?

A integração de Evals ao CI/CD no GitHub Actions funciona executando suítes de teste a cada Pull Request, bloqueando o merge caso métricas fiquem abaixo dos thresholds definidos.

Frameworks abertos como o OpenAI Evals e suítes customizadas em Python ou TypeScript facilitam esse processo.

O exemplo a seguir demonstra uma action configurada com portão de qualidade bloqueante:

name: LLM Regression & Quality Gate

on:
  pull_request:
    paths:
      - 'prompts/**'
      - 'agents/**'
      - 'src/rag/**'

jobs:
  run-evals:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Execute Deterministic Schema Evals
        run: pnpm test:evals-deterministic

      - name: Execute RAGAS & Semantic Benchmark
        env:
          EVAL_PROVIDER_API_KEY: ${{ secrets.EVAL_PROVIDER_API_KEY }}
        run: |
          pnpm exec tsx scripts/evals/run-golden-suite.ts \
            --dataset datasets/golden-v2.jsonl \
            --min-faithfulness 0.90 \
            --min-relevance 0.85 \
            --output-report reports/eval-summary.json

      - name: Evaluate Threshold Gate
        run: |
          pnpm exec tsx scripts/evals/check-gate-thresholds.ts reports/eval-summary.json

Se a métrica de fidelidade (faithfulness) cair abaixo de 0.90 ou se houver quebra de schema em qualquer cenário, o CI/CD falha imediatamente e impede o deploy de versões degradadas.

Como a Consultoria 1:1 da Produtora MaxVision estrutura essa transição?

A consultoria técnica da Produtora MaxVision atua lado a lado com times de engenharia para substituir testes manuais por arquiteturas robustas de avaliação contínua.

No Programa MaxVision, o fundador constrói o projeto do cliente ao vivo ao longo de um sprint imersivo de 15 dias, com 2 chamadas técnicas por semana. O programa opera com apenas 2 vagas por mês mediante aplicação prévia.

Durante o programa, estruturamos a suíte completa de Golden Datasets, configuramos os juízes automatizados e implementamos os gates de CI/CD para garantir que seus agentes de IA operem com estabilidade de software crítico.

Perguntas Frequentes

Quanto custa rodar uma suíte de LLM Evals no CI/CD?

O custo operacional depende do tamanho do golden dataset e do modelo escolhido como juiz. Suítes determinísticas têm custo zero de API. Para a camada de LLM-as-a-Judge, uma suíte típica de 200 casos executada com modelos intermediários custa menos de R$ 3,00 por execução de pipeline.

O que fazer quando o juiz LLM discorda da avaliação humana?

Quando há divergência sistemática, a causa quase sempre reside na ambiguidade da rubrica de avaliação. Deve-se refinar o prompt do juiz adicionando exemplos few-shot de calibração que explicitem os critérios de tolerância e penalidade adotados pelo time técnico.

É possível rodar Evals em agentes com chamadas recursivas de ferramentas?

Sim. Para agentes recursivos, a avaliação mede não apenas o output final, mas o grafo completo de execução (trajectory evaluation): a sequência de ferramentas invocadas, os argumentos intermediários e o encerramento no estado correto.