ombharatiya/ai-evals

KI-Evaluierungen

Eine Evaluierung ist ein wiederholbarer Test, der misst, ob ein KI-System seine Aufgabe erfüllt. Dieser Skill bringt dich dazu, so zu arbeiten, wie es der aievals.co-Leitfaden lehrt: Sieh dir echte Ergebnisse an, bevor du irgendetwas misst, misse die Fehler, die du tatsächlich gefunden hast, überprüfe jeden LLM-Richter anhand menschlicher Labels, bevor du ihm vertraust, und füge jeder Zahl ein Intervall hinzu.

Der Leitfaden ist unter https://www.aievals.co. Zitiere seine Seiten, wenn du dem Benutzer eine Wahl erklärst. Die am Ende aufgeführten Referenzdateien enthalten die Details und Quellen.

Grundregeln

Befolge diese bei jeder Evaluierungsaufgabe, unabhängig davon, was der Benutzer verlangt hat.

1. Sieh dir Traces an, bevor du Metriken schreibst. Du kannst die Fehlermodi eines Systems nicht spezifizieren, das du nicht beobachtet hast. Wenn der Benutzer keine Traces hat, besorge dir zuerst welche: Produktionslogs oder das System, das auf 100 realistischen Eingaben läuft. Dann lies sie.
2. Menschen labeln; du schlägst vor. Schreibe niemals selbst Ground-Truth-Labels und präsentiere sie als menschliche Urteile. Du darfst Labels mit dem Vermerk "provisional": true entwerfen, die eine Person bestätigen soll. Lasse niemals ein Modell sowohl die Eingabe als auch seine Gold-Antwort schreiben, außer wenn Code die Antwort berechnet (SQL-Ergebnisse, Tests, ein Taschenrechner).
3. Code vor Richtern. Alles, was ein String-Match, Parser, Schema-Check, Regex oder Unit-Test entscheiden kann, ist ein Code-Check. Behebe, was eine Prompt-Bearbeitung beheben kann, bevor du eine Evaluierung baust. Verwende den LLM-Richter nur für subjektive Fehler, die übrig bleiben.
4. Ein binärer Richter pro Fehlermodus. PASS oder FAIL plus eine ein-sätzige Kritik. Keine 1-5-Skalen. Mehrere Qualitätsdimensionen bedeuten mehrere binäre Richter, gemeldet als eine Bestehen-alle-Rate mit einer Aufschlüsselung pro Prüfung.
5. Kalibriere, bevor du einem Richter vertraust. Vergleiche ihn mit menschlichen Labels und melde den PASS-Recall und FAIL-Recall getrennt, jeweils mit N. Rohübereinstimmung ist niemals die Hauptaussage: Ein Richter, der immer PASS sagt, stimmt zu 95 % überein, wenn 5 % der Ausgaben fehlschlagen.
6. Train, Dev, Test. Few-Shot-Beispiele stammen nur aus Train. Optimiere auf Dev. Lies Test einmal, am Ende. Das erneute Lesen von Test nach weiteren Änderungen macht ihn zu einem zweiten Dev-Set.
7. Fixiere den Richter. Modell-ID, Aufwand, Rubriktext, Ausgabeschema und Few-Shot-Reihenfolge sind Teil des Instruments. Zeichne sie mit jedem Ergebnis auf und kalibriere neu, wenn sich eine von ihnen ändert. Gehe nicht von Determiniertheit aus: Führe Dev zweimal aus und zähle die Label-Flips.
8. Jede Zahl erhält N und ein Intervall. Verwende das Wilson-Intervall für Raten, niemals die Normalapproximation. Vergleiche zwei Versionen auf denselben Eingaben als gepaarte Daten.
9. Das Regressions-Set besteht zu 100 %. Es enthält reproduzierte Produktionsfehler und Richtlinien-Grenzen. Ein Fehler blockiert den Release, und ein fluktuierender Fall ist ein Prozessfehler.
10. Entscheide über die Differenz, nicht über die absolute Rate. Verwende die vier Bänder in references/ci-and-release-gates.md.
11. Begrenze die Ausgaben im Runner. Richterläufe kosten Geld. Erzwinge ein Budget im Code (EVAL_BUDGET_USD), nicht als gedruckte Warnung.
12. Baue das kleinste Ding, das funktioniert. Assertions und etwa 30 gelabelte Beispiele kommen vor einem Richter, und ein kalibrierter Richter kommt vor Dashboards oder Richter-Ensembles.

Wähle den Workflow

Der Benutzer möchte	Mach	Lese
Evaluierungen für eine Funktion, die keine hat	Workflow A	error-analysis, judges, datasets
Einen LLM-als-Richter-Prompt schreiben oder korrigieren	Workflow B	judges, templates
Wissen, ob eine vorhandene Evaluierung vertrauenswürdig ist	Workflow C	judges, statistics
Wissen, ob Version B Version A schlägt	Workflow D	statistics, ci-and-release-gates
Evaluierungen, die in CI laufen	Workflow E	ci-and-release-gates, datasets

Workflow A: Evaluierungen zu einer Funktion hinzufügen

1. Sammle Traces. Ziehe mindestens 100 diverse Traces oder führe das System auf realistischen Eingaben aus, wenn es nicht live ist. Speichere sie als JSONL mit einer stabilen id pro Zeile. Die Trace-Felder, die es wert sind, protokolliert zu werden, findest du in references/templates.md.
2. Führe eine Fehleranalyse mit dem Benutzer durch (Details in references/error-analysis.md). Eine Person liest die Traces und schreibt für jeden eine einzeilige Notiz zum ersten, was schiefgelaufen ist. Du kannst einen einfachen Viewer bauen und die Notizen in 4 bis 7 benannte Fehlermodi clustern, sobald die Person mindestens 30 codiert hat. Zähle jeden Modus und ordne ihn nach Häufigkeit mal Schweregrad.
3. Behebe die günstigen. Prompt- und Code-Korrekturen zuerst. Führe erneut aus und zähle neu.
4. Schreibe Code-Checks für jeden verbleibenden Modus, den eine Regel erkennen kann.
5. Schreibe einen Richter pro verbleibendem subjektivem Modus (Workflow B).
6. Hole menschliche Labels: 100 bis 200 pro Fehlermodus ist das Ziel, mit 30 bis 50 PASS und 30 bis 50 FAIL in jeweils Dev und Test. Ein 40 % Dev-Split von 100 Zeilen kann nicht 30 von jeder Klasse halten, und bei einer niedrigen Fehlerrate musst du Fehler überabtasten, um die FAIL-Seite zu füllen. Beginne mit dem, was du hast, und sage, wie breit die Intervalle sind.
7. Kalibriere jeden Richter auf Dev, dann bestätige auf Test einmal.
8. Baue das Regressions-Set aus reproduzierten Fehlern und binde die Suite in CI ein (Workflow E).

Liefergegenstände im Repository des Benutzers, es sei denn, sie haben bereits ein Layout:

evals/
  data/            labeled.jsonl (menschliche Labels), regression.jsonl, traces/
  rubrics/         eine Datei pro Fehlermodus
  codebook.md      Label, Definition, 2 PASS- und 2 FAIL-Beispiele, letztes Kappa
  checks.*         Code-Checks
  judge.*          der Richter-Aufruf, Konfiguration fixiert
  calibrate.*      Split, Score, Report, Diskrepanzen
  run_eval.*       Score-Ausgaben, Vergleich mit Baseline, Exit-Code für CI
  runs/            ein Ordner pro Lauf: Zusammenfassung, Vorhersagen, Rubrik-Kopie

Erste Schritte in Python und TypeScript findest du unter https://github.com/ombharatiya/ai-evals-skills/tree/main/starters. Kopiere einen, anstatt das Harness von Grund auf neu zu schreiben.

Workflow B: Einen LLM-Richter schreiben oder korrigieren

1. Bestätige, dass der Fehlermodus aus der Fehleranalyse stammt und dass ein Code-Check ihn nicht abfangen kann.
2. Schreibe den Prompt in vier Teilen (Vorlage in references/templates.md): Rolle und genaue Definitionen; binäre Kriterien ("PASS, wenn X. FAIL, wenn Y, auch wenn der Rest der Antwort korrekt ist. Bei Zweifel FAIL und sag warum."); 2 oder 3 Few-Shot-Beispiele aus Train, einschließlich eines FAIL, das wie ein PASS aussieht; und ein striktes Ausgabeschema, {"label": "PASS" | "FAIL", "critique": "..."}, erzwungen durch strukturierte Ausgabe, wo die API es unterstützt. Der Parser muss bei fehlerhafter Ausgabe laut scheitern.
3. Kalibriere: Führe auf Dev aus, berechne PASS-Recall, FAIL-Recall und Cohens Kappa und lies jede Diskrepanz. Lies falsche Bestehen und falsche Fehler getrennt. Wenn das menschliche Label falsch ist, korrigiere das Label, nicht die Rubrik.
4. Ändere eine Sache pro Iteration, in dieser Reihenfolge typischer Auswirkung: Rubrik-Spezifität, Few-Shot-Beispiele, Ausgabeschema und Modellwechsel zuletzt.
5. Erwarte ein Plateau um die zweite oder dritte Iteration. Füge dann Few-Shots für die Grenzfälle hinzu: zwei PASS-Beispiele, die bei oberflächlichem Lesen wie FAIL aussehen, und zwei FAIL-Beispiele, die wie PASS aussehen. Wenn sich der FAIL-Recall immer noch nicht bewegt, könnte das Richter-Modell die Obergrenze sein: Versuche ein stärkeres, bevor du die Rubrik wieder änderst, und behandle das neue Modell als neues Instrument, das von Grund auf kalibriert werden muss.
6. Höre auf, wenn PASS- und FAIL-Recall beide die Barriere auf Dev erreichen (dieser Leitfaden verwendet standardmäßig 0,90; setze sie basierend auf den Kosten eines verpassten Fehlers vs. eines Fehlalarms), dann lies Test einmal.

Workflow C: Eine bestehende Evaluierung prüfen

Überprüfe jeden Punkt und melde, was fehlschlägt, mit Datei und Zeile:

• Die Metriken führen auf Fehlermodi zurück, die jemand in echten Traces beobachtet hat.
• Code-Checks decken ab, was Code entscheiden kann; Richter sind binär, einer pro Fehlermodus.
• Jeder Richter hat einen Kalibrierungsnachweis: PASS- und FAIL-Recall mit N und Intervallen, auf einem Test-Split, den der Richter nie gesehen hat. Übereinstimmung allein zählt nicht.
• Few-Shot-Beispiele erscheinen nicht in Dev oder Test.
• Die Richter-Konfiguration (Modell, Aufwand, Rubrik, Schema, Few-Shots) ist fixiert und stimmt mit der Konfiguration überein, die kalibriert wurde.
• Jede gemeldete Rate hat N und ein Intervall; Vergleiche sind gepaart.
• Ein Regressions-Set existiert, läuft bei jedem PR und besteht zu 100 %.
• Release-Entscheidungen lesen das gepaarte Delta und sein Intervall, nicht einen absoluten Schwellenwert.
• Das Dataset ist versioniert (Inhalts-Hash) und die Ergebnisse nennen den Hash.
• Eine Suite, die monatelang bei 100 % steht, testet nichts. Das Regressions-Set ist die eine Ausnahme.

Workflow D: Zwei Versionen vergleichen

Führe beide Versionen auf denselben Eingaben aus. Berichte jede Bestehen-Rate mit ihrem Wilson-Intervall und der gepaarten Differenz mit ihrem Intervall: McNemars Test oder ein gepaarter Bootstrap für binäre Ergebnisse. Entscheide zuerst den kleinsten erkennbaren Unterschied, dann die Stichprobengröße (references/statistics.md). Schichte nach Segment, wenn es wichtig ist, und korrigiere für Mehrfachvergleiche, wenn du viele Arten schichtest. "Kein signifikanter Unterschied" aus einem unterpowered Lauf ist kein Beleg für keinen Unterschied: Sage, wie groß eine Änderung der Lauf hätte erkennen können.

Workflow E: Evaluierungen in CI

Drei Stufen: eine Smoke-Stufe mit 10 bis 50 deterministischen Assertions bei jedem Push (kein Richter), eine vollständige Stufe mit dem kalibrierten Richter bei PRs, die Prompts oder Modelle ändern, und eine nächtliche Stufe mit dem erweiterten Regressions- und Robustheits-Sets. Poste eine Baseline-gegen-Kandidaten- Tabelle im PR mit dem Delta, seinem 95 %-Intervall und einem Urteil: Ship, Hold, Investigate oder Block. Schlage den Job bei Investigate, Block, einem Regressions-Set-Fehler oder einer beschädigten Messung fehl (Zeilen ohne Urteil, auf einer Seite fehlende Zeilen, ein Richter, der nicht der kalibrierte ist), und melde einen Hold für eine benannte Person zum Lesen: Ein Hold bedeutet, dass das Intervall die Änderung nicht von keiner Änderung unterscheiden kann. Bemesse das Indifferenzfenster aus einem A/A-Lauf des unveränderten Systems, nicht aus dem Null-Rauschen-Boden. Keine stillen Overrides: Ein Override braucht eine benannte Person und einen schriftlichen Grund. Fork-PRs erhalten keine API-Geheimnisse. Details in references/ci-and-release-gates.md.

Wie man Ergebnisse berichtet

Berichte eine Tabelle, keinen Satz:

Metrik	Wert	95 %-KI	N	Richter	Dataset
FAIL-Recall, Rückerstattungsrichtlinien-Richter (Test)	0,92	[0,80, 0,97]	48	claude-opus-5-5, medium, Rubrik a1b2c3	labeled.jsonl @ 9f8e7d

Sage, was die Zahlen nicht unterstützen können. Schreibe "das Intervall ist breit; label mehr FAIL-Beispiele", anstatt ein schwaches Ergebnis zu einer Behauptung zu runden. Nenne die positive Klasse, wenn du TPR oder TNR sagst: Einige Texte, darunter Hamel Husains FAQ, behandeln FAIL als positiv, daher ist sein TPR der Anteil der erkannten echten Fehler. Einfach "PASS-Recall" und "FAIL-Recall" vermeiden die Verwirrung.

Standardwerte

Verwende diese, es sei denn, die Situation des Benutzers erfordert andere. "Site-Standard" bedeutet aievals.cos eigene Arbeitsnummer, kein veröffentlichter Standard.

Entscheidung	Standard	Quelle
Erster Fehleranalyse-Durchlauf	100+ Traces, nur erster Fehler (Hamel und Shankar FAQ); 15 bis 45 Sekunden pro Stück	FAQ und aievals.co für das Tempo
Fehlermodus-Kategorien	4 bis 7 nach axialer Codierung	aievals.co Open-Coding-Leitfaden
Labels pro Fehlermodus	100 bis 200	Hamel und Shankar FAQ
Split	15 % Train, 40 % Dev, 45 % Test, geschichtet (die Starter splitten stattdessen durch einen Hash jeder ID, sodass eine Zeile nie den Split wechselt; Verhältnisse stimmen dann nur im Durchschnitt überein)	aievals.co Kalibrierungsrezept
Pro Klasse in Dev und Test	30 bis 50 PASS und 30 bis 50 FAIL	Hamel und Shankar FAQ
Richter-Recall-Barriere	PASS- und FAIL-Recall mindestens 0,90 auf Dev, bestätigt auf Test	Site-Standard
Menschliche Übereinstimmung vor Automatisierung	Kappa mindestens 0,6 zum Fortfahren, 0,8 für ein Gold-Set oder Gate	Teamrichtlinie, gemäß Leitfaden
Intervall für eine Rate	Wilson, 95 %	aievals.co Statistik-Kapitel
Release-Gate-Fenster	1-Punkt-Indifferenzfenster; 2-Punkt-Minor-Regressionsfenster auf der primären Metrik	aievals.co Release-Gates-Kapitel
Regressions-Set	100 % Bestehen bei jedem PR	aievals.co Regressions-Sets-Kapitel

Referenzen

Lade die Datei, die zur Aufgabe passt:

• references/error-analysis.md: offene, axiale und strukturierte Codierung, Sättigung, Priorisierung, der Trace-Viewer, dimensionale Stichprobenziehung.
• references/judges.md: Richter-Design, Kalibrierung, Verzerrungen und wie man sie testet, direkt vs. paarweise, Neukalibrierungsauslöser.
• references/datasets.md: Größen nach Zweck, Beschaffung, synthetische Datenregeln, Regressions-Sets, Abdeckungsgitter, Versionierung.
• references/statistics.md: Wilson-Intervalle, gepaarte Tests, geclusterte Fehler, Stichprobengröße, Mehrfachvergleiche, Korrektur von richterbewerteten Raten.
• references/ci-and-release-gates.md: CI-Stufen, Release-Gate-Bänder, Online-Evaluierungen, Stichprobenziehung, Drift.
• references/templates.md: Richter-Prompt, Codebook-Eintrag, Annotationsdatensatz, Trace-Schema, PR-Ergebniskommentar.