Guias

Uma segunda opinião sobre as pontuações de outra ferramenta

Sua pontuação de avaliação subiu. Isso é real? E dá para confiar no juiz que a mediu? Se você já avalia com outra ferramenta, exporte os resultados dela por caso antes e depois de uma mudança, e o Oloproof responde às duas perguntas sobre eles sem executar nada de novo.

O que ele lê

Um arquivo por versão do sistema, CSV ou JSON Lines, com uma linha por caso e critério:

Coluna	O que contém
case_id	O id do caso. Dois arquivos só se pareiam em um id que ambos contêm
criterion	O nome da métrica, que se torna a métrica que uma regra nomeia
score	Um número na escala da métrica, ou vazio se a ferramenta não pontuou aquele caso
passed	true ou false no lugar de uma pontuação, ou vazio
score_min, score_max	A escala em que uma pontuação se situa (0 e 1 na maioria das ferramentas), obrigatória para uma pontuação
judge, judge_version	O modelo que julgou, se foi um modelo. Opcional

Nada mais é lido, e um arquivo com qualquer outra coluna é recusado: um arquivo contém ids de casos e pontuações, nunca uma pergunta, uma resposta ou qualquer outro conteúdo. As receitas abaixo transformam os resultados de cada ferramenta nesse arquivo.

Executando

oloproof init --example second-opinion second-opinion
cd second-opinion

O exemplo contém duas exportações da fidelidade (faithfulness) de um assistente de suporte em 150 perguntas, antes e depois de uma mudança de prompt, tal como o juiz de outra ferramenta as pontuou: uma pontuação de 0 a 1 e o seu aprovado ou reprovado em 0.7. make_exports.py é a simulação que as escreveu. A pontuação média subiu cerca de 0.02.

oloproof scores import before.csv after.csv --policy release.yaml

faithfulness: +0.023 [-0.024, +0.068] · 150 paired · 0 missing · 0 excluded
faithfulness_passed: +5.3 points [-6.9, +18.0] · 150 paired · 0 missing · 0 excluded
Decisions
  score-went-up  faithfulness  superiority  INSUFFICIENT_EVIDENCE  evaluator_not_validated
  more-answers-pass  faithfulness_passed  superiority  INSUFFICIENT_EVIDENCE  evaluator_not_validated
Gate: BLOCK (exit 3)
score-went-up, more-answers-pass: the judge (or model or custom evaluator) behind these rules has not been measured against people yet, so it may not decide.

Cada arquivo virou uma execução, e as duas execuções foram comparadas caso a caso. A resposta tem duas metades.

É real? Ainda não. A pontuação subiu 0.023, mas o intervalo vai de 0.024 abaixo a 0.068 acima: com 150 perguntas, uma mudança tão pequena não pode ser distinguida do ruído. A proporção de respostas que o juiz aprova subiu 5.3 pontos, com um intervalo de 6.9 pontos abaixo a 18.0 acima.
Dá para confiar no juiz? Ninguém o verificou. release.yaml só deixa um juiz decidir um lançamento depois que rótulos de pessoas o tiverem medido (require_validated_evaluators: true), então as duas regras param em evaluator_not_validated antes de chegar ao intervalo.

Para ver só a primeira metade, como se o juiz já tivesse sido verificado:

oloproof scores import before.csv after.csv --policy statistics-only.yaml

  score-went-up  faithfulness  superiority  INSUFFICIENT_EVIDENCE  interval_overlaps_zero
  more-answers-pass  faithfulness_passed  superiority  INSUFFICIENT_EVIDENCE  interval_overlaps_zero

No CI, adicione --summary markdown >> "$GITHUB_STEP_SUMMARY": o pull request então abre com "Is it real?" e uma linha por regra, que diz "not established" e por quê, e o código de saída é o mesmo. As linhas da própria importação vão para a saída de erro padrão, então o resumo recebe só a resposta (CI).

Sem --policy, o comando informa a comparação e não decide nada. Com um único arquivo, ele informa essa execução, e --policy aplica a ela um gate com as regras de execução da política.

Verificando o juiz

Pessoas rotulam uma amostra aleatória dos casos de uma execução importada, sem ver o juiz, e o Oloproof mede o juiz contra esses rótulos:

oloproof labels export RUN_ID --criterion faithfulness_passed --sample 60 --out sample.csv
oloproof labels import sample.csv
oloproof evaluators validate EVALUATOR_ID --by NAME

A amostra mostra o id de cada caso e nada do veredito do juiz. Quem rotula lê o caso na ferramenta que o guarda, pelo seu id, e escreve pass ou fail em passed. oloproof evaluators list fornece o id do avaliador. Uma vez validado o juiz, as regras que o leem decidem apenas com base na evidência.

Rótulos são aprovado ou reprovado, então verificam o veredito de aprovado ou reprovado de um juiz, não a sua pontuação. Importe o veredito ao lado da pontuação, como o exemplo faz com faithfulness_passed: esse é o critério que as pessoas podem validar.

A partir da sua ferramenta

A pasta recipes/ do exemplo contém um script curto por ferramenta. Cada um lê os resultados daquela ferramenta e escreve o arquivo, mantendo apenas ids e pontuações. Execute um por versão e depois importe os dois arquivos.

Ferramenta	Receita	O que identifica um caso entre duas execuções	Observações
DeepEval	deepeval_results.py RESULTS_JSON OUT	O name do caso de teste	Salve os resultados com DisplayConfig(results_folder=...) e dê nome a cada LLMTestCase. Cada métrica fornece a sua pontuação e o seu aprovado ou reprovado como <metric>_passed, com o modelo juiz
Braintrust	braintrust_experiment.py PROJECT EXPERIMENT OUT	O registro do conjunto de dados que o experimento executou (origin.id)	Pontuações de 0 a 1; --judge nomeia o modelo, se um único modelo julgou todas elas
LangSmith	langsmith_experiment.py EXPERIMENT OUT --scale LOW HIGH	O exemplo do conjunto de dados (reference_example_id)	Uma pontuação true ou false vira aprovado ou reprovado; um número precisa da sua escala
Langfuse	langfuse_experiment.py EXPERIMENT SINCE OUT	O item do conjunto de dados (experiment_item_id)	Os experimentos do Langfuse 5; pontuações numéricas na faixa da sua configuração de pontuação, ou --scale

As receitas seguem o SDK de cada ferramenta tal como publicado em 16 de outubro de 2026 (DeepEval 4.3.1, braintrust 0.46.1, langsmith 0.14.11, langfuse 5.0.2) e são testadas em resultados com esse formato, não contra uma conta real. Uma ferramenta que renomeia um campo quebra a sua receita, não a importação: o contrato é o arquivo que a receita escreve.

O que um arquivo precisa acertar

Um caso presente em apenas um arquivo fica ausente do outro lado, contado e limitado no seu pior valor; ele nunca é pareado com outro caso.
Uma segunda linha para o mesmo caso e critério, uma pontuação fora de score_min e score_max, uma linha com uma pontuação e também um aprovado ou reprovado, e um critério que é uma pontuação em um arquivo e aprovado ou reprovado no outro são recusados, com a linha indicada.
Arquivos comparados precisam concordar quanto à escala e ao juiz de cada critério: pontuações de dois juízes são dois instrumentos, e a diferença entre elas seria em parte a dos instrumentos.
Cada arquivo é uma versão do sistema identificada pelo seu conteúdo. Importar o mesmo arquivo de novo reutiliza o que foi armazenado; nada é executado nunca, então nenhuma reexecução pode reproduzir ou alterar uma pontuação importada.
--tool registra de onde vieram as pontuações, e --name dá nome ao sistema de cada arquivo; ambos ficam guardados com a execução.

O que não foi construído

Ler diretamente o próprio formato de exportação de uma ferramenta: uma receita o transforma no arquivo acima.
Enviar os arquivos ao site hospedado sem instalar nada.
Validar as pontuações de um juiz, em vez dos seus vereditos de aprovado ou reprovado.

Próximos passos

Comparando um candidato com uma linha de base: o que uma comparação pareada lê.
Regras de comparação: superioridade, não inferioridade e equivalência.
Juízes: como um juiz é medido contra pessoas antes de poder aplicar um gate.