O Eval Gate Mínimo Viável

Por que um gate, não um dashboard

A maioria das equipes que lançam uma funcionalidade de LLM tem um dashboard em algum lugar — um notebook, uma planilha com exemplos de saídas, um canal do Slack onde alguém cola “isso está melhor agora.” Nada disso bloqueia algo. Um ajuste de prompt, um salto de versão do modelo, uma mudança no retrieval: todos são lançados porque parecem estar bons, e a regressão que causaram aparece três semanas depois em uma reclamação de cliente que ninguém consegue rastrear até o diff.

Um gate é diferente de um dashboard em uma coisa que importa: um gate pode dizer não. Ele fica no seu pipeline de pull request, roda em cada mudança que toca a IA, e quando a pontuação de qualidade cai abaixo de um piso que você combinou, o merge fica vermelho. Essa é a ideia inteira. Você não precisa de uma plataforma, um contrato com fornecedor, nem uma equipe de rotulagem de dados para chegar lá. Você precisa de trinta exemplos, uma regra de pontuação e um job de CI.

As três partes

Reduza um sistema de eval ao seu núcleo irredutível e você obtém três coisas. Tudo o mais — executores de segurança, métricas de retrieval de RAG, orçamentos de custo, pisos que só sobem — é elaboração em cima dessas três.

1. O conjunto padrão-ouro

Uma coleção pequena de entradas reais pareadas com o que uma boa resposta parece. Trinta a cinquenta é suficiente para começar — tiradas dos seus logs reais e tickets de suporte, não inventadas na sua mesa. Esse conjunto é a sua definição de “funcionando,” então precisa refletir os casos que você realmente se importa: o caminho comum, os casos extremos que mordem, e os que um cliente já reclamou. (Existe um guia inteiro sobre como construir isso bem; a versão curta é: colha, não imagine.)

2. O juiz

Algo que pontua cada saída. Para saídas estruturadas, isso são asserções determinísticas — correspondência exata, regex, validação de esquema JSON, uma substring obrigatória. Para texto aberto, é um LLM-as-judge: um segundo modelo recebe a entrada, a resposta e uma rubrica, e é solicitado a pontuar fidelidade, relevância ou segurança em uma escala fixa. O truque que torna um juiz confiável é uma rubrica escrita com critérios concretos de aprovado/reprovado — não “avalie isso de 1 a 10,” mas “pontue 0 se a resposta afirma um fato não respaldado pelo contexto fornecido.”

3. O gate

Uma etapa de CI que passa o conjunto padrão-ouro pelo juiz, agrega as pontuações e compara o resultado com um piso. Acima do piso: exit 0, o merge é permitido. Abaixo: exit diferente de zero, o check fica vermelho, o merge é bloqueado. Ela roda em todo pull request que toca um prompt, uma config de modelo, um índice de retrieval, ou o código ao redor deles.

A construção de uma tarde

Aqui está a sequência honesta. Nenhuma dessas etapas é pesquisa; são montagem.

• Hora 1 — colheita. Puxe 30–50 entradas reais dos seus logs de produção ou da sua fila de suporte. Para cada uma, escreva (ou combine) o que uma boa resposta contém. Guarde isso como um arquivo simples — JSONL ou YAML — no repo, ao lado do código que ele testa.
• Hora 2 — o juiz. Escreva a rubrica. Para cada saída, decida se é uma verificação determinística (asserção) ou uma aberta (LLM-as-judge). Mantenha a rubrica também no controle de versão — ela muda conforme sua definição de bom muda, e você quer esse histórico.
• Hora 3 — o executor. Um script que faz o conjunto padrão-ouro passar pela sua funcionalidade em loop, pontua cada saída e imprime um resumo. Executores open-source como Promptfoo ou DeepEval te dão esse loop, tipos de asserção e um harness de LLM-judge prontos de fábrica, então você escreve config, não encanamento.
• Hora 4 — o gate. Conecte o executor ao CI como um check obrigatório nos pull requests. Falhe o job quando a pontuação agregada estiver abaixo do piso. Essa é a linha que transforma um script em um gate.

A etapa de CI é menor do que as pessoas esperam. Conceitualmente:

# .github/workflows/eval-gate.yml (shape, not gospel)
on: pull_request
jobs:
  eval-gate:
    steps:
      - run: npm ci
      - run: npx promptfoo eval -c eval/gate.yaml --output out.json
      - run: node eval/check-floor.js out.json --floor 0.85
        # check-floor.js exits 1 if the aggregate pass-rate < 0.85

Marque o job como required status check na sua branch protegida, e a plataforma faz a aplicação por você: um gate vermelho significa que o botão de merge fica desabilitado. Nenhum humano precisa lembrar de olhar.

Definindo o piso sem mentir para si mesmo

O primeiro piso é fácil de errar em duas direções opostas. Coloque alto demais e todo PR honesto fica vermelho, então a equipe aprende a burlar o check — um gate que todo mundo contorna é pior que nenhum gate, porque ele lava mudanças ruins com um selo verde. Coloque baixo demais e nada nunca falha, então você construiu um dashboard com etapas extras.

A jogada que funciona: rode a suíte na sua main atual para obter a pontuação base de hoje, e então defina o piso nesse ponto base. Agora o único trabalho do gate no primeiro dia é “não piorar do que já estamos.” Essa é uma afirmação que você consegue defender e uma barra que toda melhoria real ultrapassa. Com o tempo você vai subindo: quando uma mudança eleva a pontuação de forma legítima e se sustenta, você sobe o piso para acompanhar. O piso só sobe, e sobe com evidência.

Mais uma disciplina: quando o gate bloqueia um PR, a saída da falha precisa ser legível para a pessoa que escreveu o diff — quais traços falharam, o que o juiz disse, e o delta em relação à base. Um gate que só diz “pontuação 0.81, piso 0.85, bloqueado” gera ressentimento. Um gate que diz “esses 3 de 40 traços regrediram em fidelidade, aqui está o que cada um disse” gera confiança, e gates confiáveis sobrevivem.

---

Essa é a versão mínima viável. A elaboração — uma bateria de sondas de segurança, métricas de retrieval de RAG, orçamentos de custo por execução, pisos que sobem automaticamente — é a próxima seção do mesmo sistema. Mas nada disso importa até que as três partes acima existam e o gate possa ficar vermelho. Construa isso primeiro.