Evals Cookbook

Les evals transforment « ça semble mieux » en preuve. La posture correcte à l’examen : un golden set, le grader suffisant le moins cher, des juges dans une session séparée, un reporting par segment et un gate de régression CI sur les changements de prompt/modèle.

Golden-set design

1. Couvrir la distribution — échantillonnez des entrées réelles sur tous les segments (type de document, langue, difficulté, cas limites), pas seulement les faciles.
2. Inclure des cas difficiles/adversariaux — tentatives d’injection, entrées ambiguës, échecs passés connus.
3. Étiqueter avec des sorties attendues ou des grilles — réponses exactes quand c’est possible ; grilles pour les tâches subjectives.
4. Taille — assez par segment pour détecter les régressions (visez ≥ 30–50 par segment pour des taux stables).
5. Versionner et geler — un golden set est un actif contrôlé ; le changer invalide les comparaisons.
6. Holdout séparé — gardez un ensemble contre lequel vous ne réglez jamais pour détecter le surapprentissage sur l’eval.

Graders — cheapest sufficient first

Escaladez seulement autant que la tâche l’exige — exact match avant rubric avant LLM-judge.

LLM-as-judge calibration

Le juge doit s’exécuter dans une session séparée, idéalement un modèle différent, et être calibré contre des étiquettes humaines avant que vous ne lui fassiez confiance.

1. Rédigez la grille avec des critères explicites, non chevauchants, et une échelle.
2. Faites étiqueter par des humains un jeu de calibration (par exemple 100 items).
3. Exécutez le juge sur le même jeu ; mesurez l’accord (par exemple le κ de Cohen, ou le % d’accord).
4. Si l’accord est faible, resserrez la grille, ajoutez des exemplaires few-shot de chaque note, ou réduisez l’échelle (le binaire est plus facile à calibrer que 1–10).
5. Remesurez ; ne déployez le juge qu’une fois l’accord atteignant votre seuil (par exemple κ ≥ 0.6).
6. Recalibrez quand le modèle, la grille ou la tâche change.

A/B testing with significance

Comparaison par paires du prompt/modèle B contre A. Ne jugez pas à l’œil quelques sorties — testez.

Exemple travaillé : B gagne 118 des 200 comparaisons en tête-à-tête (égalités partagées). B est-il vraiment meilleur ?

n = 200, wins = 118, p̂ = 0.59
Two-sided test of p = 0.5:
  z = (118 − 100) / sqrt(200 × 0.5 × 0.5) = 18 / 7.07 ≈ 2.55
  p-value ≈ 0.011  → significant at α = 0.05
95% CI on win rate: 0.59 ± 1.96 × sqrt(0.59×0.41/200) = 0.59 ± 0.068 → [0.52, 0.66]

B est significativement meilleur. Si B avait gagné 108/200 : z ≈ 1.13, p ≈ 0.26 — non significatif ; ne déployez pas sur cette seule base.

CI regression gate

Exécutez le golden set à chaque changement de prompt/modèle ; bloquez le déploiement si un segment régresse au-delà de la tolérance.

name: evals
on: [pull_request]
jobs:
  eval:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install -r eval/requirements.txt
      - name: Run golden set
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: python eval/run.py --golden eval/golden.jsonl --out eval/report.json
      - name: Gate
        run: |
          python - <<'PY'
          import json, sys
          r = json.load(open("eval/report.json"))
          # per-segment gate: no segment below its baseline minus 2 points
          fails = [s for s, m in r["by_segment"].items() if m["accuracy"] < r["baseline"][s] - 0.02]
          if fails:
              print("Regressed segments:", fails); sys.exit(1)
          print("All segments within tolerance.")
          PY

Conditionnez sur des seuils par segment, pas seulement sur l’agrégat — c’est ce qui attrape un unique type de document défaillant.

Per-segment reporting

Segment          n     Accuracy   Faithfulness   Δ vs baseline
--------------   ---   --------   ------------   -------------
invoices         120   0.94       0.95            +0.01
contracts         90   0.88       0.91            −0.00
receipts (scan)   60   0.61 ◄     0.72 ◄          −0.18 ◄
--------------   ---   --------   ------------   -------------
OVERALL          270   0.86       0.90            −0.03

L’agrégat de 0.86 paraît correct ; le segment des reçus scannés à 0.61 est la vraie histoire. Reportez toujours la ventilation.

Cost / latency dashboards

Reportez les p95/p99, pas seulement les moyennes — une moyenne masque la traîne qui viole le SLO.

Idées fausses courantes

Étude de cas guidée

Une équipe veut faire passer le pipeline d’extraction de Sonnet 5 à Haiku 4.5 pour réduire les coûts. L’exactitude agrégée sur un test rapide semble « à peu près la même ». Comment décider correctement ?

1. Golden set, par segment — exécutez les deux modèles sur le jeu gelé, ventilez les résultats par type de document.
2. Le bon grader — exact/structural match sur les champs extraits (déterministe), pas un LLM-juge.
3. Significativité — là où c’est subjectif, un A/B par paires avec un test de significativité, pas un jugement à l’œil.
4. Trouver la régression cachée — Haiku correspond sur les PDF propres mais chute de 18 points sur les reçus scannés (l’agrégat l’a masqué).
5. Décider par contrainte — si les reçus scannés comptent, gardez Sonnet 5 pour ce segment (cascade), Haiku pour le reste.
6. Le conditionner — ajoutez les seuils par segment à la CI pour qu’un futur changement ne puisse pas régresser silencieusement.
7. Surveiller coût + latence — confirmez que l’économie est réelle sur le dashboard (p95, coût par 1k).

Alternatives rejetées : basculer sur l’exactitude agrégée (métrique agrégée), juger avec le même modèle dans la même session (revue en même session) et juger à l’œil « à peu près la même » sans significativité (distracteur jugement-à-l’œil).

À retenir

• Le golden set d’abord : couvrez la distribution, incluez les cas difficiles, versionnez et gelez-le.
• Utilisez le grader suffisant le moins cher ; le LLM-as-judge doit être en session séparée et calibré.
• Prouvez les améliorations par un A/B par paires + significativité, pas quelques sorties.
• Conditionnez les déploiements par une suite de régression CI sur des seuils par segment.
• Surveillez coût et latence aux p95/p99, et la qualité en continu — les evals sont permanentes, pas ponctuelles.