O Stack de Evals para LLMs: Como Realmente Medir Sua Feature de IA

A Habilidade Para a Qual Ninguém Foi Treinado

Todo time está entregando features de LLM. Quase nenhum time tem uma forma real de saber se essas features são boas.

A cohort AI Evals For Engineers & PMs de Hamel Husain e Shreya Shankar já treinou mais de 2.000 praticantes, incluindo engenheiros e PMs da OpenAI e da Anthropic. A razão de ter lotado não é teoria. É que as pessoas construindo essas coisas perceberam que o processo de QA delas era "peça ao prompt engineer para ler 30 outputs e confiar no feeling".

Hamel chama isso de "vibes eval". É a prática dominante, e é a razão pela qual tantas features de IA são lançadas, fazem uma boa demo e depois degradam silenciosamente. No podcast da Lenny's Newsletter, Hamel e Shreya defenderam que evals agora são a habilidade de maior alavancagem no trabalho de produto de IA, mais importante que o craft do prompt, mais importante que escolher o modelo certo. A razão é estrutural. Se você não consegue medir qualidade, você não consegue melhorá-la.

A maioria dos times sabe disso. Mesmo assim, não fazem. Por quê? Porque evals parecem trabalho de infraestrutura, não têm um dono claro, e a primeira versão sempre parece pior do que ler outputs na mão. O truque é perceber que "ler outputs na mão" é a eval. A disciplina é fazer isso uma vez, escrever o que você viu e nunca mais fazer da mesma forma.

Este texto é o playbook. É agnóstico de ferramentas de propósito. Você pode rodar este stack com Inspect AI do UK AI Safety Institute, Phoenix da Arize, Promptfoo, Langfuse, o OpenAI Evals framework, o ferramental de eval da Anthropic, ou uma pilha de scripts Python e uma planilha do Google. A metodologia é que sustenta tudo.

Por Que "Parece Bom" Para de Funcionar em Escala

A primeira vez que você lança uma feature de LLM, "parece bom" é uma régua aceitável. Você escreveu o prompt, testou dez inputs, os outputs parecem razoáveis, você aperta deploy.

Na segunda vez, você está em apuros.

Outputs de LLMs são não-determinísticos por design. Temperatura 0 reduz variância mas não elimina. O mesmo prompt com o mesmo modelo pode produzir respostas sutilmente diferentes entre execuções e absolutamente diferentes entre versões de modelo. Some a isso as coisas que mudam por baixo:

Model drift. Provedores atualizam modelos com o mesmo nome. O GPT-4o de hoje não é o GPT-4o de três meses atrás. Mesma string na sua config, comportamento diferente. Você não vai receber uma notificação.
Distribution shift. Os inputs que usuários reais enviam não são os inputs com os quais você testou. Prompts mais curtos, idiomas diferentes, formatação estranha, anexos. A cauda longa é onde evals mais importam.
Prompt entropy. Toda vez que alguém edita o system prompt para resolver a reclamação de um usuário, você corre o risco de quebrar outros três casos de uso que esqueceu que existiam. Sem evals, isso fica invisível até os tickets de suporte explodirem.
Retrieval drift. Se você usa RAG, seu índice muda constantemente. A fatia de retrieval do seu pipeline degrada silenciosamente.

O imposto oculto é o tempo do seu time. Toda mudança vira meio dia de alguém clicando em prompts. Toda atualização de modelo vira um exercício de "deixa eu checar algumas coisas" que leva uma semana. Toda escalada vira uma investigação isolada porque ninguém consegue responder "isso é uma regressão, ou sempre esteve quebrado para queries assim?"

Evals reais tornam essas perguntas baratas de responder. O custo é adiantado. A economia compõe.

A Anatomia de um Stack de Evals para LLMs

São cinco camadas. Elas se constroem umas sobre as outras. Pular uma camada significa que as camadas acima estão pontuando ruído.

Camada	Propósito	Exemplos de ferramentas	Pegadinhas
1. Traces	Capturar todo input, output, tool call, retrieval set, latência e custo das execuções em produção	Langfuse, Phoenix, exportadores OpenTelemetry	Amostragem agressiva demais; payloads de tool call faltando; PII em logs
2. Análise de erros	Open-code em 50-100 traces reais, clusterizar modos de falha, construir uma taxonomia de erros	Notion, Airtable, um CSV	Pular esse passo; uma pessoa fazendo sozinha sem calibração
3. Golden dataset	50-100 exemplos rotulados à mão cobrindo cada modo de falha e o caminho feliz	Formato de dataset do Inspect AI, JSONL, seu próprio schema	Dados apenas sintéticos; sem cobertura dos modos de falha encontrados no passo 2
4. LLM-as-judge	Um modelo de pontuação com uma rubrica, validado contra rótulos humanos com agreement >=85%	OpenAI Evals, Promptfoo, Inspect AI, customizado	Usar um judge que você nunca validou; pontuação com um único judge; rubric drift
5. Integração de CI	Rodar a eval em cada PR, travar merges em caso de regressão, alertar em degradação	GitHub Actions, GitLab CI, runners customizados	Rodar lento demais; sem teto de custo; pico de preço do modelo judge

A ordem importa. Você não consegue construir um golden dataset sem primeiro descobrir quais modos de falha existem (análise de erros), e você não consegue fazer análise de erros sem traces. Você não consegue validar um judge sem um golden set rotulado. Você não consegue rodar o pipeline em CI até que o judge seja realmente confiável.

O passo a passo de Aakash Gupta sobre o currículo Hamel/Shreya percorre esse mesmo esqueleto com nomenclatura ligeiramente diferente, e é a coisa mais próxima de um formato consensual que o campo tem. Vamos por camada.

Passo 1: Capturar Traces

Um trace é o registro completo de uma interação com o LLM. Não só input e output, mas tudo que o sistema fez no meio.

Um trace útil contém:

O histórico completo de mensagens (system prompt, turnos do usuário, turnos do assistente)
O nome e a versão do modelo, exatamente como chamados
Todas as tool calls, seus argumentos e suas respostas
Para RAG: a query de retrieval, os documentos retornados, os scores, os documentos efetivamente usados no prompt final
Contagens de tokens, latência detalhada por estágio e custo em dólares
Um request ID que você possa ligar de volta à sessão do usuário
Qualquer sinal de feedback (thumbs up, clique de copiar, regenerar, abandonado)

O princípio: o trace é a fonte da verdade. Se você não consegue reconstruir exatamente o que o modelo viu e fez apenas a partir do trace, sua eval está a jusante de chutes.

Sobre amostragem, o trade-off é volume versus custo. Para um produto de alto tráfego, logue 100% dos traces mas retenha payloads completos apenas para uma amostra (5-10%), com o resto reduzido a metadados. Logue 100% dos traces de erro (falhas de tool call, timeouts, retrieval de baixa confiança, feedback negativo). Essa é sua mina de ouro.

Sobre PII: traces vão conter dados de usuário. Aplique as mesmas regras de redação e retenção que você usa para qualquer outro log de produção. A maioria dos times faz hash de user IDs, remove e-mails e rotaciona logs em um cronograma de 30-90 dias.

Se você está implementando do zero, escreva um wrapper pequeno em volta do seu SDK de LLM que emita JSON estruturado para seu pipeline de logs. O formato importa menos do que a disciplina de sempre logar.

Passo 2: Análise de Erros (Open Coding)

Esse é o passo que todo mundo pula, e é o passo que faz todo o resto funcionar.

A pesquisa de Shreya Shankar pega emprestada uma técnica da pesquisa qualitativa chamada open coding. Você senta com 50-100 traces reais. Você lê. Você anota o que está errado (ou certo). Você não impõe categorias de antemão. Você deixa as categorias emergirem dos dados.

Concretamente:

Puxe 100 traces de produção. Misture amostras aleatórias com traces sinalizados por feedback negativo, erros ou latência alta.
Abra uma planilha. Colunas: ID do trace, resumo do input, resumo do output, problema (texto livre), severidade (1-3), tags (comece vazias).
Para cada trace, escreva o que está errado em linguagem clara. Não "output ruim". Específico: "alucinou um nome de função que não existe no código do usuário", ou "respondeu na língua errada", ou "recusou um pedido benigno".
Depois de 20-30 traces, os mesmos problemas vão se repetir. Comece a taguear. Tags de duas palavras estão de bom tamanho.
Depois de todos os 100, agrupe as tags. Você normalmente vai terminar com 5-15 modos de falha distintos mais "parece ok".

Essa é sua taxonomia de erros. Hamel descreve isso nas suas Field Notes on LLM Evals como o momento em que preocupações vagas viram alegações testáveis. "O bot está alucinando às vezes" vira "o bot alucina nomes de função em 8% das queries relacionadas a código, especialmente quando os nomes de variável são incomuns". Isso é algo para o qual você pode escrever uma eval.

Um segundo par de olhos importa. Tenha outra pessoa codificando os mesmos 30 traces independentemente. Onde vocês discordam, a taxonomia está nebulosa e precisa ser afiada. Esse é o mesmo check de inter-annotator agreement que você vai depois aplicar ao judge LLM.

Passo 3: Construir um Golden Dataset

Um golden dataset é um conjunto fixo de inputs, comportamentos esperados e rótulos contra o qual seu pipeline é avaliado. Pense nele como sua suíte de regression test para um LLM.

Tamanho: 50-100 exemplos é um ponto de partida real. Não 10 (barulhento demais). Não 1.000 (caro demais, lento demais). Cresça à medida que encontra novos modos de falha, mas a primeira versão deve ser pequena o suficiente para um humano ler cada exemplo numa tarde.

Cobertura: cada modo de falha da análise de erros precisa de pelo menos 5-10 exemplos. Mais 20-30 exemplos de caminho feliz. Mais alguns edge cases (muito longo, muito curto, não-inglês, adversarial). O paper do arXiv Constructing Domain-Specific Evaluation Sets for LLM-as-a-judge vale a leitura sobre estratégia de cobertura.

Critérios de inclusão:

Inputs reais de usuário em vez de sintéticos. Apenas sintéticos é uma armadilha conhecida: tende a parecer com prompts que o seu time escreveria, não com o que os usuários realmente mandam.
Cada exemplo tem um resultado esperado rotulado. Para geração aberta, isso é uma rubrica (deve X, não deve Y, idealmente Z), não uma string literal esperada.
Cada exemplo é tagueado com um ou mais modos de falha.
Dados sensíveis estão limpos.

Rubrica de rotulagem: escreva o que "bom" significa. Para algumas tarefas, exact-match (chamou a API certa). Para a maioria, é uma rubrica de propriedades: "deve citar pelo menos um documento recuperado", "não deve recusar", "deve estar na língua do usuário", "não deve inventar nomes de função". Cada propriedade é um check binário.

Cadência de atualização: uma vez por trimestre, puxe um lote novo de 50-100 traces de produção e repita o open coding. Modos de falha novos são adicionados. Os antigos que não ocorrem mais ficam (você quer cobertura de regressão). Quando o modelo ou prompt muda de forma significativa, faça uma atualização fora de ciclo.

A armadilha a evitar: não deixe o time que está escrevendo o prompt também escrever o golden dataset sozinho. Vai dar overfit nas forças do prompt. Tenha alguém fora do trabalho diário de prompt rotulando pelo menos metade dos exemplos.

Passo 4: LLM-as-Judge com Validação Humana

Para tarefas sem uma única resposta certa (sumarização, classificação com categorias fuzzy, Q&A aberto), você precisa de uma forma de pontuar outputs em escala. Pontuação manual não roda em cada PR.

LLM-as-judge é a técnica: use uma chamada separada a um LLM para pontuar o output do seu pipeline contra a rubrica. Funciona. A análise de métodos de LLM-as-judge da Confident AI reporta que o agreement judge-humano cruzou 85% em múltiplos benchmarks em 2025-2026, o que é aproximadamente o nível de agreement que dois humanos mostram entre si em tarefas subjetivas. Não é perfeito, mas é bom o bastante para ser útil, se você validar.

A metodologia, em ordem:

Escreva uma rubrica para o judge. Não "essa resposta é boa". Específico: "A resposta cita pelo menos um dos documentos fornecidos? S/N. A resposta recusa quando não deveria? S/N. A resposta inventa nomes de função que não estão no código do usuário? S/N." Binário ou Likert curto. Judges são ruins em escalas de 1-10.
Escolha um modelo judge. Um modelo geral forte (classe GPT-4 ou classe Claude Sonnet/Opus) normalmente supera modelos menores, mas para runs de eval de alto volume, um judge mais barato funciona se você validar.
Rotule seu golden set à mão. Dois humanos, independentemente. Calcule inter-annotator agreement (kappa de Cohen ou simples percentual de concordância em um binário). Se humanos não concordam acima de 80-85%, sua rubrica está fuzzy demais. Afie.
Rode o judge no mesmo conjunto. Compare os rótulos do judge com os rótulos humanos. Se o agreement judge-humano está abaixo de 80%, o prompt da sua rubrica para o judge está errado, ou o modelo judge é fraco demais. Itere no prompt do judge.
Coloque o judge em produção só quando o agreement estiver em 85% ou acima. Abaixo disso, você está automatizando ruído.

Erros comuns:

Usar uma única chamada de judge sem validar. O agreement pode ser 60%. Você nunca saberia.
Usar o mesmo modelo para gerar e julgar. Existe um viés conhecido de auto-preferência. Use uma família de modelos diferente para o judge quando puder.
Deixar a rubrica do judge derivar da rubrica humana. Elas têm que ser o mesmo prompt. Se você ajustar uma, re-valide.
Usar uma chamada de judge como ground truth. Para evals de alto risco, rode o judge com três chamadas independentes e tire o voto majoritário. A discordância entre as chamadas de judge é ela própria um sinal.

Uma vez validado, o judge pode pontuar milhares de outputs em minutos por alguns dólares. Esse é o retorno. Você sai de "fazemos eval antes de cada release" para "fazemos eval em cada PR".

Passo 5: Conectar ao CI/CD

O ponto inteiro desse stack é que ninguém tem que lembrar de rodar evals. O CI roda.

Um formato viável:

Em cada PR que toca prompts, configs de modelo ou código de pipeline: rode a golden eval. Bloqueie merge se qualquer métrica cair mais que um threshold (digamos 3 pontos percentuais em acurácia, ou qualquer regressão em um check duro como "não deve recusar pedidos benignos").
Em cada bump de versão de modelo: rode a eval completa em infra equivalente a produção. Compare lado a lado.
Num cronograma noturno: rode a eval contra uma amostra de traces novos de produção. Isso captura distribution shift que o golden set estático perde.
Tetos de custo: limite o orçamento de eval por PR. Um padrão sensato é US$ 1-5 por execução. Se sua eval custa mais, amostre o golden set ou use um judge mais barato para evals em PR e o judge completo para releases.

Um padrão que funciona: uma "eval rápida" de 20-30 exemplos em cada commit (sub 2 minutos) e uma "eval completa" de 100-300 exemplos na aprovação do PR e na main. Mesmo pipeline, tamanhos de amostra diferentes.

Relatório importa. O comentário do PR deve mostrar taxa de aprovação geral, taxa de aprovação por modo de falha, diff contra a main e links para os traces que falharam. Não enterre isso num arquivo de log.

Alerte em baseline drift. Se a taxa de aprovação noturna cair 5 pontos e ficar lá por dois dias, algo mudou (uma atualização de modelo, uma mudança no índice de retrieval, um serviço downstream). A eval também é sua camada de monitoramento.

Antipadrões Que os Builders Continuam Enviando

Alguns padrões para ficar de olho, porque aparecem o tempo todo em times reais:

Vibes evals indo para prod. Um engenheiro olha 20 outputs, fala "ship it", e a feature vai ao ar. Três semanas depois, ninguém consegue responder "isso está melhor que semana passada".

Pontuar com um judge único e não validado. Alguém lê sobre LLM-as-judge, escreve um prompt de uma linha ("dê uma nota de 1 a 10") e começa a tomar decisões com base nas notas. As notas são ruído.

Sem taxonomia de erros. O time pulou o open coding. O golden set foi escrito do alto da cabeça de alguém. Dá overfit em casos óbvios e perde todo modo de falha interessante que usuários reais batem.

Sem check de agreement humano. Quando dois humanos não concordaram com os rótulos, o "agreement" do judge com um deles não significa nada.

Apenas dados sintéticos. O golden set foi gerado por outro LLM. Parece ótimo. Passa em toda eval. Produção quebra porque inputs reais de usuário não parecem inputs gerados por LLM.

Um número resumindo tudo. "Nossa eval score é 87%." Em quê? Em quais modos de falha? Taxas de aprovação por modo de falha são obrigatórias. Um agregado esconde as falhas que importam.

Eval como pensamento posterior. Tratada como exercício trimestral em vez de pipeline contínuo. Fica desatualizada dentro de um ciclo de release. Ninguém confia.

O Plano de Evals de 7 Dias para um Time Sem Evals

Se você está partindo do zero, eis uma semana que te leva a um pipeline funcional.

Dia 1: Capturar traces. Escolha uma feature de LLM. Adicione logs que capturem input, output, tool calls, contexto de retrieval (se houver), versão do modelo e um request ID. Mande para onde seus logs moram. Não escolha uma ferramenta ainda; um arquivo JSONL serve para a semana um. Meta no fim do dia: 100+ traces de produção.

Dia 2: Open coding, rodada um. Puxe 50 traces. Uma pessoa lê. Anotação em texto livre do que está errado ou certo. Não categorize ainda. Só descreva.

Dia 3: Open coding, rodada dois. Uma segunda pessoa faz os mesmos 50. Comparem notas. Construam a taxonomia de modos de falha a partir dos padrões. Mire em 5-12 modos de falha nomeados. Estimem frequência aproximada para cada um.

Dia 4: Golden dataset v0. Pegue 50-80 exemplos que cubram cada modo de falha mais o caminho feliz. Rotule cada um com uma rubrica: o que precisa ser verdade em uma boa resposta. Armazene como JSONL ou planilha, não importa, mas armazene em controle de versão.

Dia 5: Construir o judge. Escreva um prompt de judge que pontue cada propriedade da rubrica como um binário. Escolha um modelo de judge de uma família diferente do seu modelo de produção. Rode no golden set.

Dia 6: Validar o judge. Tenha dois humanos rotulando o mesmo golden set contra a mesma rubrica. Calcule agreement humano-humano e agreement judge-humano. Se o judge-humano está abaixo de 80%, itere o prompt do judge. Pare quando bater 85% ou acabar o dia seis. Se não conseguir chegar a 85%, sua rubrica é o problema. Afie as perguntas binárias.

Dia 7: Conectar o CI. Uma GitHub Action que roda a eval em PRs que tocam prompts ou código de pipeline. Saída como comentário com taxa de aprovação, breakdown por modo de falha e links para traces que falharam. Defina um orçamento. Defina um threshold de regressão.

Fim da semana: você tem traces, taxonomia, golden set, judge validado e um gate de CI. O stack inteiro. É pequeno, e esse é o ponto. Compõe a partir daqui.

Depois da semana um, você vai gastar a maior parte do tempo de evals em três coisas: crescer o golden set, refinar a rubrica conforme encontra ambiguidade e investigar regressões capturadas pelo CI. Nada disso requer outro grande build.

Perguntas Frequentes

Qual a diferença entre um vibes eval e uma eval real?

Um vibes eval é "li 20 outputs e parece melhor". Uma eval real tem: um conjunto fixo de inputs, uma rubrica escrita, um mecanismo de pontuação que não depende de quem está lendo, e uma forma de comparar duas execuções. O teste rápido mais infalível: se você não consegue responder "qual foi a eval score semana passada e essa semana, e quais modos de falha regrediram", você não tem uma eval real.

Qual deve ser o tamanho do meu golden dataset?

50-100 exemplos para a primeira versão. Grande o suficiente para cobrir cada modo de falha com 5-10 casos, pequeno o suficiente para um humano ler tudo numa tarde. Cresça com o tempo conforme encontra novos modos de falha em produção. A maioria dos pipelines maduros fica entre 200-500 exemplos; muito poucos se beneficiam de passar de 1.000, a menos que estejam avaliando em muitos casos de uso distintos.

LLM-as-judge realmente concorda com humanos?

Quando você valida, sim. A pesquisa da Confident AI reporta agreement judge-humano acima de 85% em rubricas validadas em 2025-2026, o que é aproximadamente o nível em que dois humanos concordam entre si. A pegadinha: isso só vale quando você calibrou o judge contra rótulos humanos primeiro. Um prompt de judge copiado de um tutorial, nunca validado, é só uma máquina de opinião.

Preciso de uma ferramenta de eval especializada ou posso fazer a minha?

Para a semana um, faça a sua. Arquivos JSONL, um script Python, uma planilha para rótulos. Quando você cresce além disso (normalmente quando múltiplas pessoas precisam rotular, ou quando você quer uma UI para navegar nos traces), escolha uma ferramenta. Inspect AI, Phoenix, Promptfoo, Langfuse e o framework OpenAI Evals todos cobrem o mesmo formato básico com ergonomias diferentes. A metodologia é o moat, não a ferramenta.

Quando devo re-rotular meu golden dataset?

Trimestralmente como baseline. Fora de ciclo quando você troca modelos, quando você muda o prompt significativamente, quando tickets de suporte explodem com um novo modo de falha, ou quando sua eval noturna contra traces novos de produção mostra que o golden set não é mais representativo.

Considerações Finais

Os times que vencem os próximos dois anos do trabalho de produto de IA não são os que têm os prompts mais inteligentes. São os que conseguem responder, em qualquer terça-feira, "nossa feature de IA está melhor hoje do que estava mês passado, e em quais dimensões, e para quais usuários". Essa é uma pergunta de evals, não uma pergunta de prompt.

A metodologia se estabilizou: traces, análise de erros, golden dataset, judge validado, loop de CI. Cinco camadas, cada uma construível em um ou dois dias por um time pequeno. O gap entre os times que têm um stack de evals e os times que não têm está se alargando rápido.

Se você já lançou uma feature de LLM e não consegue responder à pergunta de regressão com confiança, sua tarefa da semana um não é mais um ajuste de prompt. É um arquivo JSONL, cinquenta traces e uma planilha de rótulos. O resto do stack cai daí. Comece pequeno, valide implacavelmente, entregue o pipeline antes da próxima feature.