Você conheceu essa história nas duas últimas aulas. Uma linha mudou no extrator de notas. Três notas de teste pareceram ok. E em produção, as notas com desconto pioraram.
Hoje a gente faz a refatoração que evita isso. E ela tem um primeiro passo estranho. Antes de mudar qualquer coisa, você não muda nada.
Essa refatoração trata três smells. O untested prompt, em que mudanças saem sem conjunto de testes.
O vibe check eval, em que alguém faz umas perguntas e olha as respostas.
E o model pinned prompt. Um classificador que ninguém tem coragem de levar para outro modelo há oito meses, porque o prompt foi ajustado para esse. Nesta aula, você vai montar a rede de segurança que faz os três sumirem.
A solução cabe numa frase. Antes de qualquer ajuste, monte um conjunto de casos reais com respostas esperadas, rode a versão atual neles e guarde o resultado como linha de base. A partir daí, toda mudança é comparada com essa linha de base.
A linha de base é a peça que normalmente falta. Sem ela, um número solto, como 91% de acerto, não diz se a mudança ajudou ou atrapalhou. Com ela, toda discussão vira uma comparação.
Antes, a mudança sai com uma opinião. Alguém muda o prompt, olha três casos e publica.
Depois, a mudança sai com um número. Alguém propõe uma mudança no prompt, no modelo ou num parâmetro.
O eval roda a versão nova no dataset versionado, algumas vezes.
O resultado é comparado com a versão anterior, campo a campo, categoria a categoria.
Sem regressão, a mudança segue.
Com regressão, a mudança para, e os casos que pioraram aparecem para análise.
É assim que isso aparece no pull request, como um relatório ilustrativo. Versão seis contra versão sete. O campo emissor se mantém. A data se mantém. E o total cai seis pontos, nas notas com desconto.
A execução falha, em três rodadas. O bug de sexta nunca chega à produção.
O problema de testar na mão não é preguiça. É estatística. Três exemplos não pegam uma queda de seis pontos numa categoria que aparece em 15% dos casos. Um conjunto de dezenas de casos reais, rodado algumas vezes, pega.
A linha de base transforma um número numa comparação. É isso que acaba com o debate do melhorou, piorou.
E o eval muda o comportamento do time. Quando apagar um parágrafo do prompt custa alguns minutos de medição, as pessoas começam a limpar o prompt, em vez de só acrescentar regras.
Passo zero. Não mude nada ainda. Congele o prompt atual. A linha de base é da versão que está no ar, não da que você quer publicar.
Junte casos reais. Comece com trinta a cem entradas de produção, anonimizadas, cobrindo as categorias principais e os bugs que você já conhece. Notas com desconto, com imposto de serviço, com mais de um item.
Rotule o resultado esperado. Para extração e classificação, o valor certo. Para texto aberto, critérios verificáveis, ou uma rubrica.
Escolha a nota mais simples que funciona. Comparação exata, uma regra no código, ou um modelo como juiz quando não há alternativa. E se o juiz é um modelo, meça o quanto ele concorda com uma pessoa.
Rode a versão atual de três a cinco vezes e guarde a média e a variação, por categoria. Essa é a sua linha de base.
Versione o dataset e o script no mesmo repositório do prompt.
Agora, finalmente, faça a mudança e rode o mesmo eval.
Compare por categoria, não só pela média. Combine com o time qual queda bloqueia um deploy. E ligue o eval no seu pipeline, para que toda mudança de prompt rode ele sozinha.
Uma pergunta para você. Você rodou o eval uma vez na versão nova e deu 94%. A linha de base é 92%, com variação de três pontos para mais ou para menos, em cinco rodadas. Dá para publicar?
Ainda não. Uma rodada só, dentro da faixa de ruído da linha de base, não é melhora. Você pode estar só vendo uma variação que a linha de base já tinha. Rode a versão nova de três a cinco vezes e compare média e faixa, por categoria, com a linha de base. Aí decida.
E escreva a regra de publicar ou bloquear antes de ver os números. Depois, todo mundo acha um motivo para gostar do resultado que queria.
Agora, as armadilhas. A primeira é a média que esconde uma fila rara. O acerto geral sobe um ponto. A fila de chargeback cai vinte. Se o seu pipeline só olha a média, o pull request passa. A correção é falhar o pull request quando qualquer categoria combinada cair além do limite, e imprimir os casos que pioraram. Isso transforma o número numa correção.
Um dataset que não parece produção. Um time tinha quarenta casos, inventados num quadro branco, todos fáceis. O pipeline sempre passava, e a produção falhava nas notas de serviço. Troque o quadro branco por notas reais anonimizadas, incluindo os erros que você já viu.
Sobreajuste ao eval. Ajustar o prompt até passar nos cinquenta casos pode piorar o resto da produção. Separe uma parte do dataset e use só na decisão final.
Um juiz que ninguém avaliou. Se a nota usa um modelo, confira de tempos em tempos se ele concorda com uma pessoa.
E ruído confundido com melhora. Esse a gente acabou de ver.
Agora, a recompensa. O time quer levar o classificador de tickets para um modelo mais barato. O que precisa existir antes de rodar o teste?
Um dataset de tickets reais com a fila certa, cobrindo todas as filas, inclusive as raras.
A linha de base do modelo atual. Acerto por fila, em média de algumas rodadas.
Uma regra de decisão, escrita antes do teste. Por exemplo, nenhuma fila pode cair mais de dois pontos, e a média não pode cair.
E o custo por mil tickets dos dois modelos, para pesar contra a diferença de qualidade.
Com isso, a troca vira uma tarde de trabalho, e uma decisão apoiada num número. Não uma aposta. E não espere o provedor aposentar o seu modelo atual. É o pior momento para começar, trocando com prazo e sem linha de base. Monte o eval agora, enquanto o modelo atual ainda roda.
Então, a ideia para levar. O eval vem antes da mudança, nunca depois. Congele o que está no ar, meça em casos reais, algumas vezes, e escreva a regra. Depois mude, e compare por categoria. É isso que transforma o medo de mexer no prompt numa tarde de trabalho medido.
Na próxima aula, vamos olhar a máquina que roda tudo isso para você, a cada mudança: o eval harness. Até lá.
Add Eval Before Changing the Prompt
Criar Eval Antes de Mexer no Prompt (Add Eval Before Changing the Prompt) é uma refatoração de IA para sistemas com LLM, do grupo Operação. Montar um conjunto de casos e medir a versão atual antes de qualquer ajuste.
O extrator de NF-e mudou uma linha do prompt: “com duas casas decimais”. Três notas de teste ficaram bonitas. Em produção, notas com desconto caíram. Ninguém tinha um conjunto contra o qual comparar. O prompt muda sem um conjunto de testes que prove que não piorou. São os smells Prompt Sem Eval, Eval no Olhômetro e Prompt Preso ao Modelo, quando ninguém tem coragem de trocar de modelo.
Antes de qualquer ajuste, monte um conjunto de casos reais com a resposta esperada, rode a versão atual e guarde o resultado como linha de base. Toda mudança passa a ser comparada com essa linha.
# PR: ajuste de formato no extrator
-# Testado com 3 notas, ficou bom.
-PROMPT = "Extraia o valor total da nota."
+PROMPT = "Extraia o valor total da nota, com duas casas decimais."
+
+# evals/nfe.jsonl (82 casos reais anonimizados, versionados)
+# $ python -m evals.run --prompt nfe@v7 --baseline nfe@v6
+#
+# campo v6 v7 diferença
+# total 97.6% 91.5% -6.1 <- notas com desconto
+# emitente 98.8% 98.8% 0.0
+# data 100% 100% 0.0
+# FALHOU: total abaixo da linha de base em 3 rodadasAntes: a mudança vai para produção com uma opinião.
flowchart LR
C["1. Mudança"]:::tool --> V((("2. Olho humano em 3 casos"))):::human
V --> D["3. Deploy"]:::tool
Depois: a mudança vai para produção com um número.
flowchart LR
C["1. Mudança"]:::tool --> E["2. Rodar eval"]:::tool
DS[("Dataset versionado")]:::store --> E
E --> R{"3. Pior que a linha de base?"}
R -->|não| D["4. Deploy"]:::tool
R -->|sim| X(["5. Bloqueia e mostra os casos"]):::io
O problema de testar à mão não é preguiça, é estatística. Três exemplos não detectam uma queda de 6 pontos em uma categoria que aparece em 15% dos casos. Um dataset com dezenas de casos reais, rodado algumas vezes, detecta. Os 82 casos e os percentuais do diff acima são um exemplo ilustrativo de relatório, não uma medição publicada.
A linha de base é a peça que costuma faltar. Sem ela, um número sozinho (“91% de acerto”) não diz se a mudança melhorou ou piorou. Com ela, toda discussão vira uma comparação.
O eval também muda o comportamento do time. Quando apagar um parágrafo do prompt tem um custo medido em minutos, as pessoas passam a limpar o prompt em vez de só acrescentar regras. O guia “Building effective agents”, da Anthropic (dez. 2024), trata evals como parte do desenho, não como enfeite posterior. A base está em O que é um eval.
A acurácia geral sobe 1 ponto. A fila “chargeback” cai 20. A média mente. O relatório por categoria é o que a CI deve olhar. Outra armadilha: mexer no prompt até passar nos 50 casos do eval e piorar o resto da produção. Separe um pedaço do dataset que só entra na decisão final.
Variação de amostragem também engana. Uma rodada a 93% e outra a 89% não são “melhorou”. Três a cinco rodadas, média e faixa. Escreva a regra de publicar ou bloquear antes de ver os números.
O time quer trocar o modelo do classificador de tickets por um mais barato. O que precisa existir antes de rodar o teste?
Com isso, a troca vira uma tarde de trabalho e uma decisão com número, não uma aposta.
Responda as 5 perguntas para concluir a aula. Só assistir não conclui: a checagem é o que conta para a trilha e para o certificado.
Criar Eval Antes de Mexer no Prompt (Add Eval Before Changing the Prompt) é uma refatoração de IA para sistemas com LLM, do grupo Operação. Montar um conjunto de casos e medir a versão atual antes de qualquer ajuste.
Trata Prompt Sem Eval, Prompt Preso ao Modelo e Eval no Olhômetro.
Ao padrão de projeto Bancada de Evals e Dataset de Ouro.