Bancada de Evals

Intenção

Rodar os casos de teste automaticamente a cada mudança de prompt, modelo ou código, e comparar com a versão anterior. Serve para qualquer sistema com IA que muda com frequência e precisa provar que não piorou.

Problema

O time de dados de Joana tem um sistema de perguntas em linguagem natural para SQL. Eles já têm um dataset: 120 perguntas reais com a consulta correta. O problema é que rodar o eval é um ritual de meia hora: abrir um notebook, apontar para a versão certa do prompt, esperar, copiar a tabela de resultados para uma planilha e comparar com a planilha da semana passada.

Na prática, o eval roda quando alguém lembra. Na semana em que três pessoas mudaram o prompt, ninguém rodou. A acurácia caiu e foi preciso bisseccionar à mão para descobrir qual das três mudanças causou a queda.

Ter os casos não basta. Eles precisam rodar sozinhos, do mesmo jeito, toda vez, e o resultado precisa chegar a quem fez a mudança antes do merge.

A pergunta que este padrão responde: como transformar um dataset de eval numa verificação automática que roda a cada mudança?

Solução

Construa uma bancada de evals com quatro partes fixas: carregar os casos, rodar o sistema de verdade sobre cada um, corrigir cada saída com a regra certa, e comparar o resultado com a linha de base guardada. Ligue a bancada na CI: toda mudança em prompt, modelo, ferramenta ou código do pipeline dispara o eval e anexa o relatório ao pull request.

A bancada roda o sistema como ele roda em produção (mesmo código, mesmo prompt versionado), não uma cópia simplificada. E ela guarda cada execução, para que dê para abrir um caso que falhou e ver exatamente o que o modelo devolveu.

Exemplo trabalhado

Na segunda-feira o PR da Joana muda só o exemplo de JOIN. A CI sobe a bancada, carrega evals/sql@19, roda os 120 casos no pipeline real e cola isto no PR:

categoria          baseline   atual     delta
agregação          94.2%      94.0%     -0.2%
join               88.1%      71.3%     -16.8%  REGRESSÃO
filtro_data        91.0%      90.5%     -0.5%

O merge bloqueia. O relatório lista os 11 casos de join que saíram de certo para errado. Joana abre o primeiro, vê a SQL gerada e percebe que o novo exemplo inverteu a tabela de fatos. Sem a bancada, essa queda só apareceria na planilha da sexta, misturada com as outras duas mudanças da semana.

A correção dos casos de SQL não compara o texto da consulta. Duas SQLs diferentes podem devolver a mesma tabela. A bancada executa a SQL gerada e a esperada no banco de teste e compara as linhas. Caso sql-041:

{ "id": "sql-041", "input": "Quantos pedidos tivemos em março por estado?", "expected_rows": "fixtures/sql-041.csv", "category": "agregação", "grader": "rule" }

Se o modelo escrever date_trunc no lugar de EXTRACT(MONTH ...) e o resultado for o mesmo, o caso passa. Se escrever um JOIN a mais e duplicar linhas, falha. Comparar string de SQL teria recusado a primeira (boa) e, às vezes, aceitado a segunda (ruim).

Estrutura

flowchart LR
  PR(["1. Pull request"]):::io --> L["2. Carregar casos"]:::tool
  DS[("Dataset versionado")]:::store --> L
  L --> R(["3. Rodar o sistema real"]):::llm
  R --> G{"4. Corrigir cada saída"}
  G --> A["5. Agregar por categoria"]:::tool
  BL[("Linha de base")]:::store --> C{"6. Comparar"}
  A --> C
  C --> REP(["7. Relatório no PR e bloqueio"]):::io

1. Uma mudança é proposta.
2. A bancada carrega a versão atual do dataset.
3. Cada caso roda pelo pipeline real, em paralelo, com repetições quando a saída varia.
4. Cada saída é corrigida por comparação exata, regra em código ou juiz.
5. As notas viram taxas por categoria, custo e latência.
6. O resultado é comparado com a linha de base da branch principal.
7. O relatório vai para o PR, e regressões acima do limite bloqueiam o merge.

Pseudocódigo

schema Case { id: string, input: any, expected: any, category: string, grader: "exact" | "rule" | "judge" }
schema Result { case_id: string, output: any, score: float, cost: float, latency: float }

function run_eval(system_version, dataset, repeats=3):
    results = []
    parallel {                                       # 3. em paralelo
        for case in dataset, r in range(repeats):
            out = system(system_version).run(case.input)
            score = grade(case, out)                 # 4
            results.append(Result(case.id, out, score, out.cost, out.latency))
    }
    return aggregate(results, by="category")         # 5

function grade(case, out):
    if case.grader == "exact": return 1.0 if out == case.expected else 0.0
    if case.grader == "rule":  return RULES[case.category](out, case.expected)
    return llm(JUDGE_RUBRIC, case, out) -> float     # juiz, quando não há alternativa

function check(pr):
    current = run_eval(pr.version, load("evals/dataset@latest"))
    baseline = load_baseline("main")
    diff = compare(current, baseline)                # 6
    report(pr, diff)                                 # 7
    if any(cat.drop > THRESHOLD for cat in diff): fail(pr)

Cenários reais

• Perguntas em linguagem natural para SQL. A correção é executar a consulta gerada e a esperada no mesmo banco de teste e comparar os resultados, não o texto do SQL.
• Bot de suporte com escalonamento humano. Conversas reais anonimizadas viram casos; a bancada confere a rota, as ferramentas chamadas e se ações com efeito pediram confirmação.
• Revisor automático de PR. PRs antigos com bugs conhecidos são os casos; a bancada mede quantos bugs o revisor encontra e quantos comentários inúteis ele faz.

Aplicabilidade

• Mais de uma pessoa muda o prompt, o modelo ou o pipeline.
• Você já tem (ou vai montar) um dataset com resposta esperada.
• Mudanças acontecem toda semana, ou mais.
• Uma regressão em produção custa caro: dinheiro, dados errados, clientes.

Quando não usar

• Ainda não existe dataset. Comece por ele: Dataset de Ouro e Criar Eval Antes de Mexer no Prompt.
• O sistema muda uma vez por trimestre. Um script rodado à mão antes da mudança pode bastar.
• Você quer medir o comportamento com usuários reais. Isso é experimento em produção ou Deploy Sombra, que complementam a bancada.

Como implementar

1. Defina o formato do caso: entrada, esperado, categoria e tipo de correção.
2. Escreva um ponto de entrada que roda o sistema real a partir de uma versão (de prompt e de código).
3. Implemente as correções, começando pela comparação exata.
4. Rode em paralelo, com limite de concorrência para não estourar o rate limit.
5. Agregue por categoria e calcule custo e latência por caso.
6. Guarde o resultado da branch principal como linha de base.
7. Ligue na CI com gatilho em mudanças de prompt, configuração de modelo e código do pipeline.
8. Publique o relatório no PR com os casos que mudaram de resultado.

Qual correção usar

Comece pelo que o código consegue decidir sozinho. Rota de um classificador: string exata. SQL: executar e comparar linhas. Agente: a trajetória das ferramentas (chamou buscar_pedido, não chamou reembolsar sem aprovação). Texto livre, quando não houver outra via: LLM como juiz, com rubrica, medido contra uma pessoa numa amostra.

O juiz é o último recurso. Ele custa uma chamada a mais por caso e pode concordar com uma resposta ruim. Se a regra em código cobre 80% dos casos, deixe o juiz nos 20% que sobram, não o contrário.

Eval rápido e limite de regressão

Um subconjunto de 20 casos canário roda em todo commit, em poucos minutos. Os 120 completos rodam antes do merge e de noite. O canário pega o erro óbvio; o completo pega a categoria rara.

O limite de queda (2 pontos percentuais no código de exemplo) não é um gosto. Rode a mesma versão duas vezes, sem mudar nada, e veja quanto o resultado oscila. Se a variação natural for 1 ponto, um limite de 0 recusa PRs inocentes. Se for 4 pontos, um limite de 2 vai deixar regressão passar. O limite fica um pouco acima do ruído medido.

Erros comuns

• Cópia simplificada. A bancada chama o modelo direto, sem a busca, sem o roteador, sem a ferramenta. O eval passa e a produção falha. O ponto de entrada é o mesmo classify ou run da produção.
• Notebook como CI. Funciona uma vez. Na semana de três PRs, ninguém abre.
• Comparar texto de SQL. Recusa consultas equivalentes e às vezes aceita a errada que “parece” a esperada.
• Dataset parado. A bancada só é tão boa quanto os casos. Todo bug de produção vira caso, na ordem da refatoração Criar Eval Antes de Mexer no Prompt. Sem isso, você mede um mundo velho. Veja também o smell Eval no Olhômetro.
• Limite zero com temperatura alta. O mesmo caso passa e falha. Repetições e média entram antes de apertar o limite.

Frameworks prontos (Promptfoo, LangSmith, o runner de eval do seu provedor) economizam o andaime. O que você não terceiriza: o dataset, a correção e o gatilho no PR.

Variações

• Eval rápido e eval completo. Um subconjunto pequeno roda em todo commit; o dataset inteiro roda antes do merge ou à noite.
• Eval de trajetória. Para agentes, além do resultado final, confere se as ferramentas certas foram chamadas e se ações perigosas pediram aprovação.
• Eval online. A mesma correção roda sobre uma amostra do tráfego de produção, sem resposta esperada, com regras e juiz. Mede deriva.
• Ferramentas prontas. Existem frameworks de eval que dão a estrutura (datasets, correções, relatórios). Use quando economizar código; o importante é o dataset e a correção, não a ferramenta.

Custo, latência e falhas

Os números abaixo são ilustrativos. Suponha 120 casos, 3 repetições, sem juiz, concorrência 8.

O canário barato não substitui o completo. Ele só evita esperar o job longo para descobrir que o prompt não parseia mais.

Como avaliar

A bancada também precisa ser avaliada:

• Concordância do juiz com uma pessoa, numa amostra, quando houver juiz.
• Estabilidade: rode a mesma versão duas vezes e veja quanto o resultado varia. Isso define o limite de regressão.
• Cobertura: quantos bugs de produção do último trimestre têm um caso no dataset.

{ "id": "sql-041", "input": "Quantos pedidos tivemos em março por estado?", "expected_rows": "fixtures/sql-041.csv", "category": "agregação", "grader": "rule" }

Se o eval noturno cai sem mudança de código, o suspeito é o provedor (modelo atualizado) ou o banco de teste. Esse alerta é tão útil quanto o do PR: a linha de base também envelhece.

Em produção

• Traces de eval separados dos de produção, com a versão testada.
• Histórico do resultado por categoria ao longo do tempo, para ver tendência.
• Alerta quando o eval noturno cai mesmo sem mudança no código: sinal de mudança no modelo do provedor ou nos dados.
• Rotina para transformar incidentes de produção em casos novos.

Prós e contras

Código

As duas abas implementam uma bancada mínima com casos em JSONL, correção exata, execução paralela e comparação com a linha de base.

import asyncio
import json
from collections import defaultdict
from statistics import mean

from my_app.pipeline import classify  # 3. o sistema real, não uma cópia

THRESHOLD = 0.02  # queda máxima tolerada por categoria


async def run_case(case: dict, repeats: int, sem: asyncio.Semaphore) -> list[float]:
    async with sem:
        outs = await asyncio.gather(*(classify(case["input"]) for _ in range(repeats)))
    return [1.0 if o == case["expected"] else 0.0 for o in outs]  # 4. correção exata


async def run_eval(path: str, repeats: int = 3) -> dict[str, float]:
    cases = [json.loads(line) for line in open(path, encoding="utf-8")]
    sem = asyncio.Semaphore(8)  # respeita o rate limit
    scores = await asyncio.gather(*(run_case(c, repeats, sem) for c in cases))
    by_cat = defaultdict(list)
    for case, s in zip(cases, scores):
        by_cat[case["category"]].extend(s)
    return {cat: mean(v) for cat, v in by_cat.items()}  # 5


def main() -> None:
    current = asyncio.run(run_eval("evals/tickets.jsonl"))
    baseline = json.load(open("evals/baseline.json"))  # gerado na branch principal
    failed = False
    for cat, base in sorted(baseline.items()):
        now = current.get(cat, 0.0)
        flag = "REGRESSÃO" if base - now > THRESHOLD else ""
        failed |= bool(flag)
        print(f"{cat:20} {base:6.1%} {now:6.1%} {now - base:+6.1%} {flag}")  # 7
    raise SystemExit(1 if failed else 0)


if __name__ == "__main__":
    main()

import { readFileSync } from "node:fs";
import { classify } from "../src/pipeline"; // 3. o sistema real

type Case = { input: string; expected: string; category: string };
const THRESHOLD = 0.02;

async function pool<T, R>(items: T[], limit: number, fn: (t: T) => Promise<R>): Promise<R[]> {
  const out: R[] = new Array(items.length);
  let next = 0;
  const workers = Array.from({ length: limit }, async () => {
    while (next < items.length) {
      const i = next++;
      out[i] = await fn(items[i]);
    }
  });
  await Promise.all(workers);
  return out;
}

export async function runEval(path: string, repeats = 3): Promise<Record<string, number>> {
  const cases: Case[] = readFileSync(path, "utf8").trim().split("\n").map((l) => JSON.parse(l));
  const scores = await pool(cases, 8, async (c) => {
    const outs = await Promise.all(Array.from({ length: repeats }, () => classify(c.input)));
    return outs.map((o) => (o === c.expected ? 1 : 0)); // 4
  });
  const byCat: Record<string, number[]> = {};
  cases.forEach((c, i) => (byCat[c.category] ??= []).push(...scores[i]));
  return Object.fromEntries(
    Object.entries(byCat).map(([k, v]) => [k, v.reduce((a, b) => a + b, 0) / v.length]),
  ); // 5
}

const current = await runEval("evals/tickets.jsonl");
const baseline: Record<string, number> = JSON.parse(readFileSync("evals/baseline.json", "utf8"));
const regressions = Object.entries(baseline).filter(([cat, base]) => base - (current[cat] ?? 0) > THRESHOLD);
console.table(Object.keys(baseline).map((cat) => ({ cat, base: baseline[cat], now: current[cat] })));
process.exit(regressions.length ? 1 : 0); // 6 e 7

Teste seu entendimento