Die Python-API

Alles, was die CLI tut, tut auch die Bibliothek. Verwenden Sie sie, wenn die Evaluierung in ein Skript, ein Notebook oder eine Testsuite gehört statt neben eine Konfigurationsdatei.

from oloproof import evaluate, system, current_case
from oloproof.evaluators import ExactMatch, Contains, JsonSchema, Regex, RubricJudge, evaluator

Alles unter oloproof_core sind Interna der Engine und nicht Teil dieser Schnittstelle.

Ein System erhält die Eingabe eines Falls, nicht den Fall

Das ist das Eine, das Sie zuerst richtig machen sollten, denn wer es falsch macht, scheitert still.

@system(name="support-bot", version="1")
def answer(case):
    return {"label": "refund" if "refund" in case["question"].lower() else "other"}

Eine Zeile des Datensatzes sieht so aus:

{"id":"refund_00","input":{"question":"Can I get a refund? #0"},"expected":{"label":"refund"}}

Die Funktion erhält das input-Objekt, also ist case["question"] die Frage, und es gibt kein case["expected"]. Was sie zurückgibt, ist die Ausgabe, die ein Evaluator liest, sodass ExactMatch(field="label") das zurückgegebene label mit dem erwarteten label des Falls vergleicht.

Einen Lauf ausführen

result = evaluate(
    system=answer,
    dataset="data/example.jsonl",
    evaluators=[ExactMatch(criterion="exact_label", field="label")],
)

for metric in result.metrics:
    print(metric.metric, metric.estimate, metric.interval, metric.n_observed, metric.n_missing)

exact_label 1.0 lower=0.8842966917779722 upper=1.0 30 0

Dreißig Fälle, alle korrekt, und das Intervall reicht trotzdem bis 88,4 % hinunter. Mehr können dreißig Fälle nicht belegen, gleich was die Schätzung sagt.

Einen fehlgeschlagenen Fall lesen

Wenn das System eine Ausnahme auslöst, fehlt dieser Fall, statt falsch zu sein, und die Metrik meldet das:

exact_label None lower=0.0 upper=1.0 0 30

Eine Schätzung von None mit einem Intervall über den ganzen Bereich bedeutet, dass nichts beobachtet wurde. Prüfen Sie n_missing, bevor Sie einer Schätzung vertrauen: Ein System, bei dem jeder Fall eine Ausnahme auslöste, erzeugt ein strukturell einwandfreies Ergebnisobjekt, und erst die Zählung sagt Ihnen, dass es leer ist.

Das ist der Nenner-Vertrag, der seine Arbeit tut, nicht sein Versagen — ein Fall mit Fehler wird begrenzt, nicht verworfen —, aber nichts löst für Sie eine Ausnahme aus, also liegt die Prüfung bei Ihnen.

Einen eigenen Evaluator schreiben

@evaluator macht aus einer Funktion einen Evaluator. Die Funktion nimmt ein Argument, den Fall, und liest daraus, was sie braucht: case.output ist das, was das System zurückgegeben hat, und case.expected ist das expected-Objekt der Zeile.

from oloproof.evaluators import evaluator

@evaluator(criterion="known_label", reads=("output",))
def known_label(case):
    return case.output["label"] in {"refund", "other"}

result = evaluate(system=answer, dataset="data/example.jsonl", evaluators=[known_label])

known_label 1.0 lower=0.8842966917779722 upper=1.0 30 0

reads deklariert für die Herkunftsnachweise, welche Teile des Falls gelesen werden; die Voreinstellung ist ("output", "expected"). Der Evaluator gibt True oder False zurück, oder einen Score, wenn er value_type="score" und den score_range deklariert, in dem seine Scores liegen. Seine Version enthält einen Digest der Datei, die ihn definiert, sodass eine Änderung daran seine gecachten Urteile ungültig macht.

Eine als def f(output, expected) geschriebene Funktion wird bereits bei der Deklaration abgelehnt, zusammen mit der Form, die funktioniert, statt bei jedem Fall fehlzuschlagen.

Eine Policy anwenden

evaluate nimmt eine Policy entgegen und entscheidet den Lauf, nach denselben Regeln, die die CLI aus release.yaml liest:

result = evaluate(
    system=answer,
    dataset="data/example.jsonl",
    evaluators=[ExactMatch(criterion="exact_label", field="label")],
    policy="release.yaml",
)
print(result.gate)

Ohne Policy ist result.gate gleich None: Es gibt keine Regel, die verfehlt werden könnte, also gibt es nichts zu entscheiden.

Wie es weitergeht

• Eine Suite schreiben behandelt dieselben Evaluatoren als Konfiguration.
• Festhalten, was ein System getan hat behandelt current_case() und das Lesen

von Artefakten in einem Evaluator.

• Einen Kandidaten mit einer Baseline vergleichen behandelt den Arbeitsablauf,

für den es die Intervalle gibt.