ombharatiya/ai-evals

AI evals

Um eval é um teste repetível que mede se um sistema de IA faz seu trabalho. Este skill faz você trabalhar da forma que o guia aievals.co ensina: veja as saídas reais antes de medir algo, meça as falhas que você realmente encontrou, verifique cada juiz LLM contra rótulos humanos antes de confiar nele e coloque um intervalo em cada número.

O guia está em https://www.aievals.co. Cite suas páginas ao explicar uma escolha ao usuário. Os arquivos de referência listados no final carregam os detalhes e as fontes.

Regras básicas

Siga estas em toda tarefa de eval, independentemente do que o usuário pediu.

1. Veja os traços antes de escrever métricas. Você não pode especificar modos de falha de um sistema que não observou. Se o usuário não tem traços, obtenha alguns primeiro: logs de produção, ou o sistema executado em 100 entradas realistas. Então leia-os.
2. Pessoas rotulam; você propõe. Nunca escreva rótulos de verdade absoluta (ground-truth) e os apresente como julgamentos humanos. Você pode rascunhar rótulos marcados como "provisional": true para uma pessoa confirmar. Nunca deixe um modelo escrever tanto a entrada quanto sua resposta ideal, exceto quando o código computa a resposta (resultados SQL, testes, uma calculadora).
3. Código antes de juízes. Qualquer coisa que uma correspondência de string, parser, verificação de esquema, regex ou teste unitário possa decidir é uma verificação de código. Corrija o que uma edição de prompt pode corrigir antes de construir qualquer eval. Deixe o juiz LLM para falhas subjetivas que permanecem.
4. Um juiz binário por modo de falha. PASS ou FAIL mais uma crítica de uma frase. Sem escalas de 1 a 5. Várias dimensões de qualidade significam vários juízes binários, relatados como uma taxa de aprovação total com um detalhamento por verificação.
5. Calibre antes de confiar em um juiz. Compare-o com rótulos humanos e relate a revocação (recall) PASS e a revocação FAIL separadamente, cada uma com seu N. A concordância bruta nunca é o destaque: um juiz que sempre diz PASS concorda 95% das vezes quando 5% das saídas falham.
6. Treino, dev, teste. Exemplos few-shot vêm apenas do treino. Itere no dev. Leia o teste uma vez, no final. Ler o teste novamente após mais edições o transforma em um segundo conjunto de dev.
7. Prenda o juiz. ID do modelo, esforço, texto da rubrica, esquema de saída e ordem few-shot são partes do instrumento. Registre-os com cada resultado e calibre novamente quando qualquer um deles mudar. Não assuma determinismo: execute o dev duas vezes e conte as inversões de rótulo.
8. Cada número recebe N e um intervalo. Use o intervalo de Wilson para taxas, nunca a aproximação normal. Compare duas versões nas mesmas entradas como dados pareados.
9. O conjunto de regressão passa 100% das vezes. Ele contém bugs de produção reproduzidos e limites de política. Uma falha bloqueia o lançamento, e um caso instável é um bug de processo.
10. Portão na diferença, não na taxa absoluta. Use as quatro faixas em references/ci-and-release-gates.md.
11. Limite os gastos no executor. Execuções de juízes custam dinheiro. Imponha um orçamento no código (EVAL_BUDGET_USD), não como um aviso impresso.
12. Construa a menor coisa que funciona. Asserções e cerca de 30 exemplos rotulados vêm antes de um juiz, e um juiz calibrado vem antes de painéis ou ensembles de juízes.

Escolha o fluxo de trabalho

O usuário quer	Faça	Leia
Evals para uma funcionalidade que não tem nenhum	Fluxo de trabalho A	error-analysis, judges, datasets
Um prompt de juiz LLM escrito ou corrigido	Fluxo de trabalho B	judges, templates
Saber se um eval existente pode ser confiável	Fluxo de trabalho C	judges, statistics
Saber se a versão B é melhor que a versão A	Fluxo de trabalho D	statistics, ci-and-release-gates
Evals sendo executados em CI	Fluxo de trabalho E	ci-and-release-gates, datasets

Fluxo de trabalho A: adicionar evals a uma funcionalidade

1. Colete traços. Obtenha pelo menos 100 traços diversos, ou execute o sistema em entradas realistas se ele não estiver ao vivo. Armazene-os como JSONL com um id estável por linha. Os campos de traço que valem a pena registrar estão em references/templates.md.
2. Execute análise de erros com o usuário (detalhes em references/error-analysis.md). Uma pessoa lê os traços e escreve uma nota de uma linha sobre a primeira coisa que deu errado em cada um. Você pode construir um visualizador simples e agrupar as notas em 4 a 7 modos de falha nomeados assim que a pessoa tiver codificado pelo menos 30. Conte cada modo e classifique por frequência vezes gravidade.
3. Corrija os baratos. Correções de prompt e código vêm primeiro. Reexecute e reconte.
4. Escreva verificações de código para cada modo restante que uma regra possa detectar.
5. Escreva um juiz por modo subjetivo restante (Fluxo de trabalho B).
6. Obtenha rótulos humanos: 100 a 200 por modo de falha é o alvo, com 30 a 50 PASS e 30 a 50 FAIL em cada um de dev e teste. Uma divisão de 40% dev de 100 linhas não pode conter 30 de cada classe, e a uma baixa taxa de falha você precisa superamostrar falhas para preencher o lado FAIL. Comece com o que você tem e diga quão amplos são os intervalos.
7. Calibre cada juiz no dev e confirme no teste uma vez.
8. Construa o conjunto de regressão a partir de falhas reproduzidas e conecte a suíte em CI (Fluxo de trabalho E).

Entregáveis no repositório do usuário, a menos que eles já tenham uma estrutura:

evals/
  data/            labeled.jsonl (rótulos humanos), regression.jsonl, traces/
  rubrics/         um arquivo por modo de falha
  codebook.md      rótulo, definição, 2 exemplos PASS e 2 FAIL, último kappa
  checks.*         verificações de código
  judge.*          a chamada do juiz, configuração fixa
  calibrate.*      divisão, pontuação, relatório, discordâncias
  run_eval.*       pontuar saídas, comparar com linha de base, código de saída para CI
  runs/            uma pasta por execução: sumário, previsões, cópia da rubrica

Iniciadores funcionais em Python e TypeScript estão em https://github.com/ombharatiya/ai-evals-skills/tree/main/starters. Copie um em vez de escrever o harness do zero.

Fluxo de trabalho B: escrever ou corrigir um juiz LLM

1. Confirme que o modo de falha veio da análise de erros e que uma verificação de código não pode pegá-lo.
2. Escreva o prompt em quatro partes (modelo em references/templates.md): função e definições exatas; critérios binários ("PASS se X. FAIL se Y, mesmo que o resto da resposta esteja correto. Em caso de dúvida, FAIL e diga o porquê."); 2 ou 3 exemplos few-shot do treino, incluindo um FAIL que parece um pass; e um esquema de saída estrito, {"label": "PASS" | "FAIL", "critique": "..."}, imposto por saída estruturada onde a API suportar. O parser deve falhar ruidosamente em saída malformada.
3. Calibre: execute no dev, calcule a revocação PASS, revocação FAIL e o kappa de Cohen, e leia cada discordância. Leia falsos passes e falsos fails separadamente. Se o rótulo humano estiver errado, corrija o rótulo, não a rubrica.
4. Mude uma coisa por iteração, nesta ordem de impacto típico: especificidade da rubrica, exemplos few-shot, esquema de saída e troca de modelo por último.
5. Espere um platô por volta da segunda ou terceira iteração. Então adicione few-shots para os casos extremos: dois exemplos PASS que parecem FAIL em uma leitura descuidada e dois exemplos FAIL que parecem PASS. Se a revocação FAIL ainda não se mover, o modelo juiz pode ser o teto: tente um mais forte antes de mudar a rubrica novamente e trate o novo modelo como um novo instrumento a ser calibrado do zero.
6. Pare quando a revocação PASS e FAIL ambas atingirem a barra no dev (o padrão deste guia é 0,90; defina-a a partir do custo de uma falha perdida versus um alarme falso), então leia o teste uma vez.

Fluxo de trabalho C: auditar um eval existente

Verifique cada item e relate o que falha, com arquivo e linha:

• As métricas remontam a modos de falha que alguém observou em traços reais.
• Verificações de código cobrem o que o código pode decidir; juízes são binários, um por modo de falha.
• Cada juiz tem um registro de calibração: revocação PASS e FAIL com N e intervalos, em um divisão de teste que o juiz nunca viu. Apenas concordância não conta.
• Exemplos few-shot não aparecem no dev ou teste.
• A configuração do juiz (modelo, esforço, rubrica, esquema, few-shots) está fixa e corresponde à configuração que foi calibrada.
• Cada taxa relatada tem N e um intervalo; as comparações são pareadas.
• Um conjunto de regressão existe, é executado em todo PR e passa 100%.
• As decisões de lançamento leem o delta pareado e seu intervalo, não um limite absoluto.
• O conjunto de dados é versionado (hash de conteúdo) e os resultados nomeiam o hash.
• Uma suíte que está sentada em 100% por meses não está testando nada. O conjunto de regressão é a única exceção.

Fluxo de trabalho D: comparar duas versões

Execute ambas as versões nas mesmas entradas. Relate cada taxa de aprovação com seu intervalo de Wilson e a diferença pareada com seu intervalo: teste de McNemar ou um bootstrap pareado para resultados binários. Decida a menor diferença que vale a pena detectar primeiro, então o tamanho da amostra (references/statistics.md). Fatia por segmento quando importa, e corrija para comparações múltiplas quando você fatiar de muitas maneiras. "Nenhuma diferença significativa" de uma execução com poder insuficiente não é evidência de nenhuma diferença: diga quão grande uma mudança a execução poderia ter detectado.

Fluxo de trabalho E: evals em CI

Três camadas: uma camada de fumaça de 10 a 50 asserções determinísticas em cada push (nenhum juiz), uma camada completa com o juiz calibrado em PRs que mudam prompts ou modelos, e uma camada noturna com os conjuntos de regressão e robustez expandidos. Publique uma tabela baseline-versus-candidato no PR com o delta, seu intervalo de 95% e um veredito de enviar, reter, investigar ou bloquear. Falhe o job em investigar, bloquear, uma falha no conjunto de regressão ou uma medição quebrada (linhas sem veredito, linhas faltando em qualquer lado, um juiz que não seja o calibrado), e relate uma retenção para uma pessoa nomeada ler: uma retenção significa que o intervalo não pode distinguir a mudança de nenhuma mudança. Dimensionar a janela de indiferença a partir de uma execução A/A do sistema inalterado, não do piso de ruído zero. Nenhuma substituição silenciosa: uma substituição precisa de uma pessoa nomeada e uma razão escrita. Fork PRs não recebem segredos de API. Detalhes em references/ci-and-release-gates.md.

Como relatar resultados

Relate uma tabela, não uma frase:

Métrica	Valor	IC 95%	N	Juiz	Conjunto de dados
Revocação FAIL, juiz de política de reembolso (teste)	0,92	[0,80, 0,97]	48	claude-opus-5-5, medium, rubrica a1b2c3	labeled.jsonl @ 9f8e7d

Diga o que os números não podem suportar. Escreva "o intervalo é amplo; rotule mais exemplos FAIL" em vez de arredondar um resultado fraco em uma afirmação. Nomeie a classe positiva quando você disser TPR ou TNR: alguma escrita, o FAQ de Hamel Husain entre isso, trata FAIL como positivo, então seu TPR é a parcela de falhas reais capturadas. "Revocação PASS" e "Revocação FAIL" simples evitam a confusão.

Padrões

Use estes a menos que a situação do usuário exija outros. "Padrão do site" significa o número de trabalho do próprio aievals.co, não um padrão publicado.

Decisão	Padrão	Fonte
Primeira passagem de análise de erros	100+ traços, apenas a primeira falha (FAQ Hamel e Shankar); 15 a 45 segundos cada	FAQ, e aievals.co para o ritmo
Categorias de modo de falha	4 a 7 após codificação axial	Guia de codificação aberta aievals.co
Rótulos por modo de falha	100 a 200	FAQ Hamel e Shankar
Divisão	15% treino, 40% dev, 45% teste, estratificada (os iniciadores dividem por um hash de cada id em vez disso, então uma linha nunca muda de divisão; as proporções então correspondem apenas na média)	Receita de calibração aievals.co
Por classe no dev e no teste	30 a 50 PASS e 30 a 50 FAIL	FAQ Hamel e Shankar
Barra de revocação do juiz	Revocação PASS e FAIL pelo menos 0,90 no dev, confirmado no teste	Padrão do site
Acordo humano antes de automatizar	kappa pelo menos 0,6 para prosseguir, 0,8 para um conjunto dourado ou portão	Política da equipe, conforme o guia
Intervalo para uma taxa	Wilson, 95%	Capítulo de estatísticas aievals.co
Janelas de portão de lançamento	Janela de indiferença de 1 ponto; janela de regressão menor de 2 pontos na métrica primária	Capítulo de portões de lançamento aievals.co
Conjunto de regressão	100% de aprovação em todo PR	Capítulo de conjuntos de regressão aievals.co

Referências

Carregue o arquivo que corresponde à tarefa:

• references/error-analysis.md: codificação aberta, axial e estruturada, saturação, priorização, o visualizador de traços, amostragem dimensional.
• references/judges.md: design de juiz, calibração, vieses e como testá-los, direto versus pareado, gatilhos de recalibração.
• references/datasets.md: tamanhos por propósito, sourcing, regras de dados sintéticos, conjuntos de regressão, grids de cobertura, versionamento.
• references/statistics.md: intervalos de Wilson, testes pareados, erros agrupados, tamanho da amostra, comparações múltiplas, correção de taxas pontuadas por juiz.
• references/ci-and-release-gates.md: camadas de CI, faixas de portão de lançamento, evals online, amostragem, deriva.
• references/templates.md: prompt de juiz, entrada de codebook, registro de anotação, esquema de traço, comentário de resultado PR.