Dataset de Ouro

Intenção

Manter um conjunto curado de entradas com a resposta esperada, que cresce a cada bug real e serve de referência para toda mudança. Serve para qualquer sistema com IA que precisa de um eval confiável ao longo do tempo.

Problema

Marcos montou o primeiro eval do classificador de tickets em uma tarde: pediu ao próprio modelo para gerar 100 tickets de exemplo com a fila certa. O eval dava 96%. Em produção, o time de suporte reclamava de tickets na fila errada todos os dias.

Quando ele olhou os tickets reais, entendeu. Clientes escrevem com erros, misturam dois assuntos, colam prints, respondem a um email antigo. Os 100 tickets gerados eram limpos, curtos e sempre sobre uma coisa só. O eval media um mundo que não existia.

Tinha um segundo problema, mais sutil. O mesmo modelo que gerou os tickets também os classificava. Ele escrevia casos do jeito que ele próprio entendia, então acertava quase todos. O eval era um espelho.

Pior: quando um ticket real caía na fila errada, alguém corrigia o prompt, mas o caso nunca entrava no eval. Três meses depois, o mesmo erro voltou com outra mudança de prompt, e ninguém percebeu até o suporte reclamar de novo.

A pergunta que este padrão responde: de onde vêm os casos de um eval que represente de verdade a produção, e como ele continua representando com o tempo?

Solução

Trate o dataset como um ativo do produto, com dono, versão e regras de entrada:

• Origem real. Os casos vêm de produção, anonimizados. Dados sintéticos só entram para cobrir lacunas conhecidas e ficam marcados.
• Rótulo revisado. A resposta esperada é anotada por quem entende do domínio, e casos difíceis passam por uma segunda pessoa.
• Cobertura por categoria. O dataset tem casos de todas as categorias, inclusive as raras, e casos difíceis de propósito.
• Crescimento por bug. Todo erro de produção vira um caso antes de ser corrigido.
• Separação. Uma parte do dataset é usada para desenvolver; outra fica guardada para a decisão final, para não sobreajustar.

Das cinco regras, o crescimento por bug é a que mais rende com o tempo. Um dataset que só recebe casos no dia em que foi criado envelhece junto com o produto. Um que recebe cada erro de produção vira a memória do time: tudo que já quebrou uma vez fica vigiado para sempre.

A ordem “caso antes da correção” também importa. Você grava o caso, roda o eval e vê o caso falhar. Só então corrige. Se o caso não falha antes da correção, ele não reproduz o bug, e o teste não protege nada.

Estrutura

flowchart LR
  P[("1. Produção: traces e feedback")]:::store --> S["2. Amostrar e anonimizar"]:::tool
  B(["1. Bug reportado"]):::io --> S
  S --> L((("3. Rotular e revisar"))):::human
  L --> D[("4. Dataset versionado")]:::store
  D --> DEV["5a. Parte de desenvolvimento"]:::tool
  D --> HO["5b. Parte reservada"]:::tool
  DEV --> E(["6. Eval"]):::llm
  HO --> E

1. Casos novos vêm de amostras de produção e de bugs reportados.
2. Os dados pessoais são removidos ou mascarados antes de qualquer coisa.
3. Uma pessoa do domínio anota a resposta esperada; casos ambíguos têm segunda revisão.
4. O dataset é versionado como código, com histórico de quem adicionou o quê e por quê.
5. Uma parte serve para iterar no prompt; a outra só é usada na decisão de deploy.
6. A Bancada de Evals roda o sistema contra o dataset.

Pseudocódigo

schema GoldenCase {
    id: string, input: any, expected: any, category: string,
    source: "production" | "bug" | "synthetic", difficulty: "easy" | "hard",
    split: "dev" | "holdout", added_by: string, reason: string
}

function add_from_bug(report):
    raw = traces.find(report.trace_id)
    case = GoldenCase(input=redact_pii(raw.input), source="bug", difficulty="hard",
                      split=assign_split(), reason=report.summary)
    case.expected = human.label(case)                     # 3
    if disagreement(case): case.expected = human.review(case)
    dataset.append(case)                                  # 4
    dataset.commit("bug " + report.id)

function sample_production(n):
    for raw in traces.sample(n, stratify_by="category"):  # 1 e 2
        queue_for_labeling(redact_pii(raw.input))

function coverage_report():
    return dataset.count(by=["category", "difficulty", "source"])

Cenários reais

• Extração de NF-e e contratos. Cada layout de nota que falhou vira caso, com o valor certo de cada campo. O dataset é organizado por emitente e por tipo de documento, porque um emitente novo costuma trazer um layout novo.
• Perguntas em linguagem natural para SQL. Perguntas reais de analistas com a consulta correta e o resultado esperado num banco de teste fixo. O eval compara o resultado, não o texto da consulta, porque duas consultas diferentes podem estar certas.
• Triagem automática de tickets. Tickets reais com a fila correta, estratificados para que filas raras tenham casos suficientes. É o caso do Marcos, e o exemplo trabalhado abaixo.

Aplicabilidade

• Você vai rodar evals mais de uma vez.
• O sistema tem categorias com frequências muito diferentes.
• Bugs de produção acontecem e são corrigidos no prompt.
• Mais de uma pessoa precisa confiar no resultado do eval.
• Você vai trocar de modelo um dia e quer saber o que muda antes de trocar.

Quando não usar

• Protótipo sem usuários reais. Comece com 20 casos escritos à mão e troque pelos reais assim que eles existirem.
• Tarefas sem resposta esperada (texto criativo). Use critérios escritos e uma rubrica avaliada por pessoas ou por um modelo juiz; o dataset vira um conjunto de entradas sem gabarito.
• Exemplos para o prompt. O dataset de eval não deve ser a mesma coisa que os exemplos do Seletor de Exemplos; se for, o eval mede decoreba.

Como implementar

1. Puxe 100 a 200 entradas de produção, estratificadas por categoria.
2. Remova dados pessoais com uma rotina automática e revise uma amostra.
3. Rotule com quem entende do domínio, com instruções escritas de rotulagem.
4. Marque dificuldade e origem em cada caso.
5. Separe 20% a 30% como reserva, por sorteio dentro de cada categoria.
6. Versione em arquivos de texto (JSONL) no repositório ou num armazenamento com histórico.
7. Crie a regra: nenhum bug é fechado sem virar caso.
8. Revise o dataset a cada trimestre: rótulos errados, categorias novas, casos que não fazem mais sentido.

A instrução de rotulagem

Dois rotuladores só concordam se a regra estiver escrita. A instrução é um documento curto que responde às dúvidas que vão aparecer. Um trecho do guia da triagem:

Fila de um ticket com dois assuntos:
  use a fila do assunto que impede o cliente de usar o produto.
  "paguei e o pedido segue pendente, e quero trocar o tamanho"
  -> billing (o pagamento não confirmado bloqueia o pedido)

Ticket só com print, sem texto:
  rotule pelo conteúdo do print; se ilegível, marque "unclear" e não use no eval.

Na dúvida entre duas filas:
  marque as duas em "alternatives" e mande para segunda revisão.

Cada vez que uma revisão encontra um empate novo, a regra entra no guia. O guia é versionado junto com o dataset, porque rótulo e regra andam juntos.

Quantos casos bastam

A conta é simples e assusta. Numa categoria com 20 casos, cada erro move a taxa em 5 pontos. Numa com 4 casos, em 25.

Suponha que a fila “jurídico” seja 2% dos tickets. Uma amostra aleatória de 200 casos traz uns 4 dela. Um erro e a fila aparece com 75%; nenhum erro e ela aparece com 100%. Nenhum dos dois números diz muito.

Por isso a amostra é estratificada: você puxa de propósito mais casos das filas raras, até cada uma ter algumas dezenas. O efeito colateral é que a média simples do dataset deixa de refletir a produção. Resolva assim:

• Reporte a taxa de cada categoria separadamente.
• Calcule a taxa global ponderada pela frequência real de cada categoria em produção.
• Antes de comemorar uma melhora de dois ou três pontos, olhe quais casos mudaram. Em 100 casos, dois pontos são dois tickets.

Exemplo trabalhado: do bug ao caso

Uma segunda-feira, o suporte avisa: um cliente escreveu “oi, paguei o boleto mas o pedido 4521 continua como pendente e quero trocar o tamanho”. O ticket foi para a fila de pedidos. O financeiro só viu dois dias depois.

1. Achar o trace. A pessoa de plantão clica em “mandar para o dataset” no trace do ticket. A entrada vai para a fila de rotulagem já mascarada.
2. Rotular. A rotuladora aplica o guia: dois assuntos, o pagamento bloqueia o pedido, então billing. Como é caso difícil, uma segunda pessoa confirma.
3. Gravar e ver falhar. O caso entra como tk-0912, com source: "bug" e o motivo. O eval roda com o prompt atual:

golden/tickets v41  (212 casos: 158 dev, 54 reserva)   exemplo ilustrativo
prompt triage@v17
  dev      91,1%   reserva  88,9%
  FALHA tk-0912  esperado=billing  obtido=orders  motivo: dois assuntos

4. Corrigir. O prompt ganha a regra do assunto que bloqueia, com um exemplo que não é o tk-0912.
5. Ver passar e comparar. O eval roda de novo. O tk-0912 passa, e você confere se algum caso que passava começou a falhar. Só então o bug é fechado.

O passo 5 é o que protege o futuro. Daqui a seis meses, quando alguém reescrever o prompt para outra coisa, o tk-0912 continua lá e avisa se o erro voltar.

Armadilhas comuns

• O autor do prompt rotula sozinho. Ele tende a rotular do jeito que o prompt já responde. Chame alguém do suporte ou do financeiro.
• Apagar o caso que sempre falha. Se um caso falha em todas as versões, revise o rótulo. Se o rótulo estiver certo, o caso é exatamente o que o dataset precisa.
• Espiar a reserva. Olhar a reserva a cada iteração e escolher a versão que foi melhor nela transforma a reserva em parte de desenvolvimento.
• Copiar casos para o prompt. O caso vira exemplo few-shot, o eval acerta por memória e a nota sobe sem a produção melhorar.

Variações

• Dataset sintético dirigido. Um modelo gera variações de casos reais difíceis (com erro de digitação, dois assuntos, outro idioma). Útil para cobrir lacunas, sempre marcado como sintético.
• Dataset vivo a partir de feedback. Respostas com polegar para baixo entram numa fila de rotulagem.
• Dataset por versão de política. Quando a regra de negócio muda, os rótulos mudam junto; mantenha a versão da política em cada caso.

Custo, latência e falhas

Como avaliar

• Concordância entre rotuladores num subconjunto: se duas pessoas discordam muito, a tarefa ou a instrução está mal definida. A medida mais comum é o kappa de Cohen, que desconta a concordância que aconteceria por acaso.
• Correlação com produção: a taxa no eval acompanha as reclamações e correções em produção? Se o eval sobe e as reclamações não caem, o dataset não representa a produção.
• Cobertura: casos por categoria e por dificuldade, e fração de bugs do trimestre que viraram caso.

{ "id": "tk-0912", "input": "oi, paguei o boleto mas o pedido 4521 continua como pendente e quero trocar o tamanho", "expected": "billing", "category": "billing", "source": "bug", "difficulty": "hard", "split": "holdout", "reason": "dois assuntos; roteado para pedidos em 2026-08" }

Em produção

• Botão ou comando para mandar um trace de produção direto para a fila de rotulagem.
• Painel com o tamanho do dataset por categoria e a data do último caso de cada uma.
• Alerta quando uma categoria nova aparece na produção sem casos no dataset.
• Fila de rotulagem com dono e prazo. Uma fila sem dono vira um cemitério de traces.

Segurança

O dataset contém dados reais. Mascare dados pessoais antes de gravar, restrinja o acesso e registre a base legal do uso, em linha com a LGPD.

Mascarar só CPF e email não basta. Tickets trazem nome, endereço, telefone, número de cartão e, às vezes, dados de saúde. Rode uma detecção mais completa e revise uma amostra à mão a cada lote.

Prós e contras

Código

As duas abas implementam a entrada de um caso a partir de um bug e o relatório de cobertura.

import hashlib
import json
import re
from collections import Counter
from pathlib import Path

DATASET = Path("evals/golden/tickets.jsonl")
CPF = re.compile(r"\b\d{3}\.?\d{3}\.?\d{3}-?\d{2}\b")
EMAIL = re.compile(r"[\w.+-]+@[\w-]+\.[\w.]+")


def redact(text: str) -> str:  # 2. mascarar antes de gravar
    return EMAIL.sub("<email>", CPF.sub("<cpf>", text))


def assign_split(case_id: str, holdout_share: float = 0.25) -> str:
    bucket = int(hashlib.sha256(case_id.encode()).hexdigest(), 16) % 100
    return "holdout" if bucket < holdout_share * 100 else "dev"  # estável por id


def add_from_bug(bug_id: str, text: str, expected: str, category: str, reason: str, author: str) -> dict:
    case_id = f"bug-{bug_id}"
    case = {
        "id": case_id, "input": redact(text), "expected": expected, "category": category,
        "source": "bug", "difficulty": "hard", "split": assign_split(case_id),
        "added_by": author, "reason": reason,
    }
    with DATASET.open("a", encoding="utf-8") as f:  # 4. versionado com git
        f.write(json.dumps(case, ensure_ascii=False) + "\n")
    return case


def coverage() -> Counter:
    with DATASET.open(encoding="utf-8") as f:
        cases = [json.loads(line) for line in f if line.strip()]
    return Counter((c["category"], c["difficulty"], c["split"]) for c in cases)

import { createHash } from "node:crypto";
import { appendFileSync, readFileSync } from "node:fs";

const DATASET = "evals/golden/tickets.jsonl";

type GoldenCase = {
  id: string; input: string; expected: string; category: string;
  source: "production" | "bug" | "synthetic"; difficulty: "easy" | "hard";
  split: "dev" | "holdout"; added_by: string; reason: string;
};

const redact = (t: string) =>
  t.replace(/[\w.+-]+@[\w-]+\.[\w.]+/g, "<email>").replace(/\b\d{3}\.?\d{3}\.?\d{3}-?\d{2}\b/g, "<cpf>");

const split = (id: string): GoldenCase["split"] =>
  parseInt(createHash("sha256").update(id).digest("hex").slice(0, 8), 16) % 100 < 25 ? "holdout" : "dev";

export function addFromBug(bug: { id: string; text: string; expected: string; category: string; reason: string; author: string }) {
  const id = `bug-${bug.id}`;
  const c: GoldenCase = {
    id, input: redact(bug.text), expected: bug.expected, category: bug.category,
    source: "bug", difficulty: "hard", split: split(id), added_by: bug.author, reason: bug.reason,
  };
  appendFileSync(DATASET, JSON.stringify(c) + "\n");
  return c;
}

export function coverage(): Record<string, number> {
  const cases: GoldenCase[] = readFileSync(DATASET, "utf8").split("\n").filter((l) => l.trim()).map((l) => JSON.parse(l));
  return cases.reduce<Record<string, number>>((acc, c) => {
    const key = `${c.category}/${c.difficulty}/${c.split}`;
    acc[key] = (acc[key] ?? 0) + 1;
    return acc;
  }, {});
}

Teste seu entendimento