Avaliação (Evals) e Testes de Sistemas com LLM

3.1 Por que "parece bom" não é métrica

Em software tradicional, soma(2, 2) devolve 4 sempre, e um teste unitário prova isso. Em sistemas com LLM, a mesma entrada pode gerar saídas diferentes, "certo" muitas vezes é uma questão de grau, e uma melhora num caso pode piorar outros dez. O olhômetro (rodar três exemplos e achar bonito) falha de formas previsíveis:

• Viés de seleção: você testa os exemplos de que lembra, que costumam ser os fáceis.
• Regressões invisíveis: o ajuste que conserta o caso A quebra os casos B e C, que você não olhou.
• Ruído confundido com sinal: uma resposta melhor pode ser só sorte da amostragem.
• Decisões caras sem base: "o modelo barato serve?" vira opinião contra opinião.

As quatro peças de um eval

3.2 Montando o dataset de avaliação

De onde vêm os casos

1. Tráfego real (anonimizado): a melhor fonte, porque é o que o sistema enfrenta de verdade.
2. Casos de borda escritos à mão: o recibo sem CNPJ, o OCR ruim, o texto que nem é recibo, o documento com instrução maliciosa.
3. Bugs que já aconteceram: cada falha em produção vira um caso, para nunca voltar.
4. Casos sintéticos gerados por LLM: úteis para variedade, mas revise uma amostra. Se algo sai errado, corrija o gerador, não caso a caso.

Regras de um bom dataset

• Critério de sucesso inequívoco. Dois especialistas olhando a mesma saída devem concordar se passou. "Um bom resumo" não é critério; "cita o valor e o prazo" é.
• Registre a origem do gabarito. Escrito por uma pessoa, verificado por uma pessoa, ou saída de um modelo? Nunca use as respostas do modelo A como gabarito para comparar A com B: você estaria medindo o quanto B imita A.
• Cobertura nos dois sentidos. Se o sistema deve sinalizar recibos com problema, também precisa de casos em que não deve sinalizar. Senão, "sinalizar tudo" tira nota máxima.
• Distribuição realista e balanceada. Compare com a produção. Informe sempre a linha de base da classe majoritária: se 72% dos casos são "dúvida", um sistema que sempre responde "dúvida" já acerta 72%.
• Sem vazamento. A resposta não pode aparecer no texto de entrada, nos exemplos do prompt nem em lugar que o sistema consiga ler.
• Tags por caso (ocr, desconto, seguranca): permitem ver onde o sistema falha, não só quanto.
• Versionado junto com o código. Notas de antes e depois de mudar o dataset não são comparáveis.

python python/01_auditar_dataset.py

[campo vazio]      c13: categoria
[campo vazio]      c18: texto, categoria
[duplicata exata]  c02, c05
[quase duplicata]  c02, c05, c06
[vazamento]        c16: o texto contém o próprio rótulo 'bug'

Distribuição dos rótulos:
  duvida          13  █████████████
  cobranca         2  ██
  bug              2  ██
  cancelamento     1  █

Linha de base da classe majoritária: responder sempre 'duvida' acerta 72%.
[desbalanceado]    mais da metade dos casos é de uma única classe

3.3 Avaliadores baseados em código

Sempre que der para verificar com código, verifique com código: é rápido, barato, determinístico e não tem opinião. O desafio é calibrar o rigor.

Checagens atômicas, não uma nota única

Avalie cada propriedade separadamente (total, data, cnpj, sinalizacao…). Uma nota única como "7,3" esconde o que piorou. Checagens separadas mostram que a data piorou nos recibos com ano de dois dígitos, e isso aponta direto para a correção.

Teste o seu avaliador

Antes de confiar em qualquer nota, rode duas verificações baratas:

• Oráculo: passe o próprio gabarito pelo avaliador. Tem que dar 100%. Se não der, o avaliador ou o caso estão errados.
• Linha de base nula: passe uma saída vazia ou boba. Tem que dar perto de 0%. Se não der, o avaliador é frouxo.

O projeto deste módulo faz as duas coisas como testes automatizados.

python python/02_avaliadores.py

saída                                     certo?   exato  normal.  contém
"Brasília"                                     ✓       ✓        ✓       ✓
"brasilia."                                    ✓      ✗!        ✓      ✗!
"  Brasília "                                  ✓      ✗!        ✓       ✓
"A capital do Brasil é Brasília."              ✓      ✗!       ✗!       ✓
"Não é Brasília, é o Rio de Janeiro."          ✗       ✗        ✗      ✓!
"Rio de Janeiro"                               ✗       ✗        ✗       ✗

discordâncias com o humano: {'exato': 3, 'normalizado': 1, 'contem': 2}

3.4 LLM como juiz, e como calibrá-lo

Algumas qualidades não cabem em código: o resumo é fiel? A explicação aponta o problema certo? O tom é adequado? Para isso, um LLM avalia a saída de outro com uma rubrica. Funciona bem, desde que você trate o juiz como mais um componente a ser testado.

Como escrever um bom juiz

• Rubrica concreta. Critérios verificáveis ("cita o valor ou o prazo"), não "avalie se é bom".
• Um critério por chamada quando o diagnóstico importa: fidelidade, completude e formato como notas separadas.
• Justificativa antes do veredito, no formato estruturado: o juiz raciocina antes de decidir, e você consegue auditar.
• Saída estruturada ({"justificativa": "...", "aprovado": true}): nada de procurar "SIM" no texto.
• A saída avaliada é dado, não instrução. Coloque-a entre tags e diga ao juiz para ignorar instruções dentro dela.

Os vieses conhecidos

Calibração: o juiz concorda com pessoas?

Peça a uma pessoa que avalie algumas dezenas de casos de forma independente e compare com o juiz. Duas métricas:

• Concordância: % de casos em que juiz e pessoa decidiram igual.
• Kappa de Cohen: concordância descontado o acaso. Um juiz que aprova tudo pode ter 50% de concordância e kappa 0: não sabe nada.

Regra prática: abaixo de ~90% de concordância em casos claros, melhore a rubrica antes de usar o juiz para tomar decisões. Teste também casos negativos óbvios (resposta vazia, "não sei", resposta a outra pergunta): o juiz precisa reprovar todos.

python python/03_llm_juiz.py
python python/03_llm_juiz.py --rubrica-vaga

3.5 Evals no CI: regressão bloqueada antes do merge

Um eval que só roda quando alguém lembra não protege nada. Coloque-o no pipeline, como os testes. Como evals custam dinheiro e tempo, use camadas:

Cuidados que separam um eval de CI útil de um irritante

• Erro de infraestrutura não é nota zero. Um 429 ou timeout vai para uma lista separada. Se houver erros demais, o job falha por infraestrutura, não por qualidade.
• Limiar com folga. Com poucos casos o ruído é grande (aula 3.6). Um limiar exatamente na nota atual vai falhar aleatoriamente e o time vai aprender a ignorá-lo.
• Mesma configuração de produção. O eval deve chamar o código real, com o mesmo prompt e modelo. Uma reimplementação "parecida" mede outra coisa.
• Confira o modelo que respondeu (campo model da resposta). Uma troca silenciosa invalida o resultado.
• Guarde tudo: entrada, saída, checagens, custo e latência por caso, como artefato do job. Quando a nota cair, você precisa ver por quê sem rodar de novo.
• Segredo da API só como secret do CI, e nunca em PRs vindos de forks.

O projeto traz exemplo-github-actions.yml com essas camadas: testes rápidos em todo PR, eval de fumaça com limiar de 90% e suíte completa com juiz todas as noites.

3.6 Comparar modelos e prompts sem se enganar

Um eval com N casos dá uma estimativa da taxa real de acerto. Toda estimativa tem margem de erro, e ela é maior do que a intuição sugere. Uma aproximação útil para a meia-largura do intervalo de 95% de uma taxa: ±1/√casos (é o pior caso, com a taxa perto de 50%; perto de 0% ou 100% a margem é menor). Com 25 casos, ±20 pontos percentuais. Com 100, ±10.

python python/04_ruido_estatistico.py

    casos  B parece melhor   empate  A parece melhor  diferença detectada*
       10              49%      23%              27%                    4%
       25              61%      13%              26%                    6%
       50              70%       8%              22%                   10%
      100              80%       5%              16%                   14%
      200              89%       2%               8%                   28%
      500              98%       0%               1%                   55%
     1000             100%       0%               0%                   83%

Na prática

• Sempre informe o intervalo, não só a taxa: "82% (61%–93%)" conta uma história bem diferente de "82%".
• Compare em pares: os dois sistemas nos mesmos casos. A diferença caso a caso tem muito menos ruído do que comparar duas notas gerais.
• Repetições reduzem o ruído do não determinismo dentro de cada caso; mais casos reduzem o ruído de quais casos você escolheu. Não são equivalentes: se a dúvida é "o sistema funciona nos problemas reais?", só casos novos e independentes respondem. Use repetições para saber se um caso é estável, não para inflar o N.
• Olhe caso a caso mesmo quando o agregado é inconclusivo: dois casos que falham sempre com o modelo B são uma pista concreta.
• Custo por tarefa concluída, não por chamada: inclua as tentativas extras, o juiz e a revisão humana dos casos sinalizados.

Exemplo: comparando dois modelos no projeto

O comando npm run comparar faz a comparação pareada. Abaixo, um exemplo ilustrativo, gerado com um modelo simulado que erra o total de dois recibos:

caso                                A (claude-opus-5-5)   B (claude-haiku-5-5)
academia-desconto-percentual                       100%                     0%  ▼
farmacia-desconto                                  100%                   100%
...
posto-quantidade-decimal                           100%                     0%  ▼

Diferença B − A: -18.2 p.p.  (IC 95%: -42.1 p.p. a +5.7 p.p.)
Conferência por reamostragem de casos: IC 95% -45.5 p.p. a +0.0 p.p.
→ Inconclusivo: a diferença cabe no ruído. Mais casos independentes ajudariam; repetições só reduzem a variação dentro de cada caso.

As duas linhas de intervalo usam a mesma unidade, o caso. A primeira supõe distribuição normal; a segunda reamostra os casos e não supõe nada sobre a forma. Quando elas discordam muito, desconfie da primeira: com poucos casos e diferenças que só valem 0 ou −100%, a aproximação normal é fraca.

Repare: B errou sempre nos mesmos dois casos, mas com só 11 casos o agregado é inconclusivo. A leitura certa: "não há evidência de que B seja equivalente; há dois padrões de erro concretos (quantidade decimal e desconto percentual) para investigar e transformar em mais casos".

3.7 Avaliação em produção

O dataset de avaliação é uma fotografia; a produção é o filme. Usuários fazem perguntas que você não previu, os dados mudam e o comportamento do modelo pode mudar entre versões. Avaliação online completa a offline:

• Sinais explícitos: 👍/👎, "esta resposta ajudou?", correções feitas pelo usuário.
• Sinais implícitos: o usuário copiou a resposta? Reformulou a pergunta logo depois? Abriu um chamado humano?
• Checagens automáticas nas respostas reais: as mesmas regras de negócio do eval (soma fecha? JSON válido?).
• LLM-juiz por amostragem: avaliar 1% a 5% do tráfego com a rubrica já calibrada.
• Métricas operacionais: taxa de recusa, de max_tokens, de erros, latência e custo por tarefa.

O ciclo que faz o sistema melhorar

Projeto do módulo: evals do extrator de recibos

Uma suíte de avaliação completa para o extrator do Módulo 2. Ela importa e executa o extrator real, sem cópias nem reimplementações, e aplica tudo o que este módulo ensinou.

cd projeto
npm install
npm test                                        # 14 testes: avaliadores, oráculo, linha nula, estatística
npm run eval                                    # 11 casos × 1 repetição
npm run eval -- --reps 3 --juiz                 # com repetições e LLM-juiz
npm run eval -- --modelo claude-haiku-5-5 --reps 3
npm run comparar -- resultados/A.json resultados/B.json
npm run eval -- --limiar 0.9                    # código de saída 1 se ficar abaixo (CI)

O que tem dentro

Entregáveis

1. Rode a suíte com claude-opus-5-5 e claude-haiku-5-5, com 3 repetições cada, e compare. Registre taxa com intervalo, custo por recibo e latência.
2. Expanda para pelo menos 30 casos, incluindo os recibos que você criou no Módulo 2. Mantenha cobertura nos dois sentidos.
3. Calibre o juiz: rotule você mesmo as explicações de 10 execuções e meça a concordância.
4. Faça uma mudança no prompt do extrator que você acha que melhora. Prove (ou refute) com o eval e o comparador.
5. Coloque o workflow no seu repositório e mostre um PR bloqueado por regressão.

Critérios de avaliação

Recursos para aprofundar

• Documentação da API da Anthropic · guias de definição de critérios de sucesso e de criação de testes
• Hamel Husain — Your AI Product Needs Evals · o argumento prático para evals desde o começo
• Eugene Yan — Evaluating the Effectiveness of LLM-Evaluators · panorama de LLM-como-juiz e seus vieses
• Judging LLM-as-a-Judge (2023) · artigo que mediu os vieses de posição, verbosidade e autopreferência
• promptfoo · ferramenta aberta de evals por configuração, boa para comparar com o que você construiu