Guide

Un secondo parere sui punteggi di un altro strumento

Il tuo punteggio di valutazione è salito. È reale? E puoi fidarti del giudice che l'ha misurato? Se valuti già con un altro strumento, esportane i risultati per caso prima e dopo una modifica, e Oloproof risponde a entrambe le domande su quei risultati senza eseguire di nuovo nulla.

Che cosa legge

Un file per versione del sistema, CSV o JSON Lines, con una riga per caso e per criterio:

Colonna	Che cosa contiene
case_id	L'id del caso. Due file si appaiano solo su un id che entrambi contengono
criterion	Il nome della metrica, che diventa la metrica nominata da una regola
score	Un numero sulla scala della metrica, oppure vuoto se lo strumento non ha valutato quel caso
passed	true o false al posto di un punteggio, oppure vuoto
score_min, score_max	La scala su cui si trova un punteggio (0 e 1 per la maggior parte degli strumenti), obbligatoria per un punteggio
judge, judge_version	Il modello che ha giudicato, se a giudicare è stato un modello. Facoltativo

Nient'altro viene letto, e un file con qualsiasi altra colonna viene rifiutato: un file contiene id di casi e punteggi, mai una domanda, una risposta o qualsiasi altro contenuto. Le ricette qui sotto trasformano i risultati di ciascuno strumento in questo file.

Eseguirlo

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

L'esempio contiene due esportazioni della fedeltà di un assistente di supporto su 150 domande, prima e dopo una modifica del prompt, così come le ha valutate il giudice di un altro strumento: un punteggio da 0 a 1, e il suo pass o fail a 0.7. make_exports.py è la simulazione che le ha scritte. Il punteggio medio è salito di circa 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.

Ogni file è diventato un'esecuzione, e le due esecuzioni sono state confrontate caso per caso. La risposta ha due metà.

È reale? Non ancora. Il punteggio è salito di 0.023, ma l'intervallo va da 0.024 in meno a 0.068 in più: con 150 domande, una modifica così piccola non si può distinguere dal rumore. La quota di risposte a cui il giudice dà pass è salita di 5.3 punti, con un intervallo da 6.9 punti in meno a 18.0 in più.
Puoi fidarti del giudice? Nessuno l'ha verificato. release.yaml lascia decidere un rilascio a un giudice solo dopo che le etichette delle persone lo hanno misurato (require_validated_evaluators: true), quindi entrambe le regole si fermano a evaluator_not_validated prima di arrivare all'intervallo.

Per vedere la prima metà da sola, come se il giudice fosse stato verificato:

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

In CI, aggiungete --summary markdown >> "$GITHUB_STEP_SUMMARY": la pull request si apre allora su «Is it real?» e una riga per regola, che dice «not established» e perché, e il codice di uscita è lo stesso. Le righe proprie dell’importazione vanno sullo standard error, così il riepilogo riceve solo la risposta (CI).

Senza --policy il comando riporta il confronto e non decide nulla. Con un solo file riporta quell'esecuzione, e --policy la sottopone a gate secondo le regole di esecuzione della policy.

Verificare il giudice

Le persone etichettano un campione casuale dei casi di un'esecuzione importata, alla cieca rispetto al giudice, e Oloproof misura il giudice rispetto a loro:

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

Il campione mostra l'id di ogni caso e nulla del verdetto del giudice. L'etichettatore legge il caso nello strumento che lo contiene, tramite il suo id, e scrive pass o fail in passed. oloproof evaluators list fornisce l'id dell'evaluator. Una volta validato, le regole che leggono quel giudice decidono sulla sola evidenza.

Le etichette sono pass o fail, quindi verificano il verdetto di pass o fail di un giudice, non il suo punteggio. Importa il verdetto accanto al punteggio, come fa l'esempio con faithfulness_passed: è quello il criterio che le persone possono validare.

Dal tuo strumento

La cartella recipes/ dell'esempio contiene un breve script per strumento. Ciascuno legge i risultati di quello strumento e scrive il file, conservando solo id e punteggi. Eseguine uno per versione, poi importa i due file.

Strumento	Ricetta	Che cosa identifica un caso tra due esecuzioni	Note
DeepEval	deepeval_results.py RESULTS_JSON OUT	Il name del caso di test	Salva i risultati con DisplayConfig(results_folder=...) e dai un nome a ogni LLMTestCase. Ogni metrica fornisce il suo punteggio e il suo pass o fail come <metric>_passed, con il modello giudice
Braintrust	braintrust_experiment.py PROJECT EXPERIMENT OUT	Il record del dataset che l'esperimento ha eseguito (origin.id)	Punteggi da 0 a 1; --judge indica il modello se uno solo li ha giudicati tutti
LangSmith	langsmith_experiment.py EXPERIMENT OUT --scale LOW HIGH	L'esempio del dataset (reference_example_id)	Un punteggio vero o falso diventa pass o fail; un numero ha bisogno della sua scala
Langfuse	langfuse_experiment.py EXPERIMENT SINCE OUT	L'elemento del dataset (experiment_item_id)	Gli esperimenti di Langfuse 5; punteggi numerici sull'intervallo della loro configurazione di punteggio, oppure --scale

Le ricette seguono l'SDK di ciascuno strumento così come pubblicato il 16 ottobre 2026 (DeepEval 4.3.1, braintrust 0.46.1, langsmith 0.14.11, langfuse 5.0.2) e sono testate su risultati di quella forma, non su un account reale. Uno strumento che rinomina un campo rompe la sua ricetta, non l'importazione: il file che la ricetta scrive è il contratto.

Che cosa un file deve rispettare

Un caso presente in un solo file risulta mancante dall'altra parte, contato e limitato al suo caso peggiore; non viene mai appaiato con un altro caso.
Una seconda riga per lo stesso caso e criterio, un punteggio al di fuori di score_min e score_max, una riga con sia un punteggio sia un pass o fail, e un criterio che è un punteggio in un file e pass o fail nell'altro vengono rifiutati, indicando la riga.
I file confrontati devono concordare sulla scala e sul giudice di ciascun criterio: i punteggi di due giudici sono due strumenti di misura, e la loro differenza sarebbe in parte quella degli strumenti.
Ogni file è una versione del sistema identificata dal suo contenuto. Importare di nuovo lo stesso file riusa ciò che era stato memorizzato; nulla viene mai eseguito, quindi nessuna riesecuzione può riprodurre o modificare un punteggio importato.
--tool registra da dove vengono i punteggi, e --name dà un nome al sistema di ciascun file; entrambi sono conservati con l'esecuzione.

Che cosa non è costruito

Leggere direttamente il formato di esportazione proprio di uno strumento: una ricetta lo trasforma nel file descritto sopra.
Caricare i file sul sito ospitato senza installare nulla.
Validare i punteggi di un giudice, anziché i suoi verdetti di pass o fail.

Dove andare dopo

Confrontare un candidato con una baseline: che cosa legge un confronto appaiato.
Regole di confronto: superiorità, non inferiorità ed equivalenza.
Giudici: come un giudice viene misurato rispetto alle persone prima di poter fare da gate.