Evals Cookbook (OpenAI)

Les evals transforment « ça semble mieux » en preuve. Ce cookbook reflète les objectifs du cours Academy Evaluate AI Applications ; c’est une préparation indépendante. La posture correcte qu’il enseigne : construire un dataset à partir du trafic et des échecs réels, choisir le grader le moins cher qui suffit, exécuter des graders indépendants de la chose évaluée, reporter par segment, et verrouiller les changements avec une suite de régression en CI avant tout déploiement online.

Pourquoi les evals précèdent l’ajustement des prompts

Ajuster un prompt sans eval, c’est deviner avec assurance. Vous ne pouvez pas dire si un changement a aidé, nui, ou aidé un segment tout en cassant un autre. La séquence sur laquelle insistent les objectifs de Evaluate AI Applications :

  define the task and success criteria
             │
             ▼
  build a dataset (real traffic + failures)   ◄── the eval is the ruler
             │
             ▼
  measure the current baseline
             │
             ▼
  change ONE thing (prompt / model / retrieval)
             │
             ▼
  re-measure ─── better? keep. worse/flat? revert.

Construisez le mètre avant de commencer à couper. Un changement de prompt qui « semble mieux » sur trois exemples fait régresser régulièrement un segment que vous ne regardiez pas ; seuls une baseline plus un dataset peuvent l’attraper.

Construction du dataset à partir du trafic réel et des logs d’échecs

1. Échantillonnez depuis la production, à travers les segments — type de document, langue, difficulté, cohorte d’utilisateurs — pas seulement les cas faciles ou synthétiques.
2. Exploitez les logs d’échecs — chaque réponse fausse signalée, chaque refus ou plainte est un cas difficile étiqueté qui attend d’être ajouté ; les échecs sont la source au meilleur rendement.
3. Étiquetez avec des sorties attendues ou des rubrics — réponses exactes là où la tâche est déterministe ; une rubric claire là où elle est subjective.
4. Dimensionnez pour des taux stables — visez assez d’items par segment (environ 30–50) pour détecter une régression plutôt que du bruit.
5. Versionnez et figez — le dataset est un actif contrôlé ; le changer invalide les comparaisons entre runs.
6. Gardez un holdout — un ensemble contre lequel vous n’ajustez jamais, pour attraper le surapprentissage sur l’eval elle-même.

Assainissez le trafic réel avant qu’il n’entre dans le dataset : retirez ou masquez les PII, et ne stockez que ce dont l’eval a besoin. Un golden set de cas réels est bien plus prédictif qu’un ensemble paraphrasé depuis du contenu marketing.

Types de graders et quand chacun est valide

N’escaladez qu’autant que la tâche l’exige : essayez le match exact, puis un code grader, puis un model grader, puis l’humain. Un model grader doit s’exécuter indépendamment du modèle évalué — une requête séparée, idéalement un modèle différent — et doit être calibré contre des labels humains avant que vous ne lui fassiez confiance. La boucle de calibration : des humains étiquettent un ensemble, le model grader note le même ensemble, vous mesurez l’accord, resserrez la rubric ou ajoutez des exemplars notés jusqu’à ce que l’accord dépasse votre barre, puis recalibrez chaque fois que la tâche, la rubric ou le modèle change.

Évaluation offline vs online

Elles sont complémentaires, pas alternatives. Les evals offline verrouillent le changement ; l’évaluation online attrape ce que le golden set n’a jamais contenu — nouvelles formes de requête, dérive et cas limites qui réalimentent ensuite l’ensemble offline. Livrer sur les seules evals offline suppose que votre golden set connaît déjà chaque échec, ce qui est faux.

Portes de régression en CI

Exécutez le golden set à chaque changement de prompt, de modèle ou de retrieval et bloquez le merge 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:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: python eval/run.py --golden eval/golden.jsonl --out eval/report.json
      - name: Gate on per-segment thresholds
        run: python eval/gate.py --report eval/report.json --tolerance 0.02

Verrouillez sur des seuils par segment, pas seulement l’agrégat — c’est ce qui attrape un type de document ou une langue en échec avant qu’il n’atteigne les utilisateurs.

La boucle d’analyse d’échecs

1. Collecter — récupérez les cas en échec depuis les evals et depuis les logs de production.
2. Regrouper — groupez par cause racine : retrieval miss, ambiguïté de prompt, contexte manquant, limite du modèle, mauvais label.
3. Attribuer — assignez chaque groupe à l’étape qui en est propriétaire, pour que le correctif atterrisse au bon endroit.
4. Corriger d’abord le plus grand groupe — le plus grand groupe est le changement à plus fort levier.
5. Ajouter les cas au golden set — un échec corrigé qui n’est pas dans l’eval régressera silencieusement plus tard.
6. Re-mesurer et répéter — la boucle est continue, pas un audit ponctuel.

Évaluation de workflows d’agents

La précision en un seul tour ne vous dit pas si un agent a terminé le travail. Évaluez la trajectoire autant que la réponse.

Un agent qui produit un message final plausible tout en appelant les mauvais tools a échoué — l’évaluation de trajectoire attrape ce qu’un grader centré sur la seule réponse rate.

Le prompt optimizer

Les docs fournissent un prompt optimizer qui affine un prompt contre un dataset et des graders plutôt que par intuition. Utilisez-le comme une boucle disciplinée, pas une baguette magique : fournissez un dataset représentatif et un grader valide, laissez-le proposer des variantes de prompt, et ne gardez une variante que si elle bat la baseline sur l’ensemble figé, par segment. Il automatise la recherche parmi les formulations de prompt ; il ne remplace pas le dataset, le grader, ni votre jugement sur la métrique qui importe.

Où se situe l’Evals API dans les docs

En septembre 2026, les docs regroupent les evals et le fine-tuning sous « Legacy APIs » aux côtés d’Agent Builder et de l’Assistants API. C’est un fait d’organisation de la documentation, pas un verdict sur la pratique : l’évaluation reste une ingénierie correcte et essentielle. Dites « l’Evals API (désormais regroupée avec les legacy APIs) » plutôt que de la présenter comme la surface la plus récente, et n’en déduisez pas que les evals sont dépréciées en tant que discipline — elles ne le sont pas. Le fine-tuning reste de même disponible (supervised, vision, DPO et reinforcement fine-tuning) pour le style et le comportement, pas pour injecter des faits.

Une spec d’eval travaillée

Une spec concrète pour un pipeline d’extraction de factures que vous pourriez exécuter demain.

eval: invoice-extraction-v3
task: Extract {invoice_number, total, currency, due_date} from an invoice document.
dataset:
  source: 300 real invoices sampled across 4 vendors + 40 past-failure cases
  segments: [clean_pdf, scanned, non_english, multi_page]
  labels: gold field values, hand-checked; PII masked
  frozen: true
  holdout: 60 cases never used for tuning
graders:
  - fields: exact match on invoice_number, currency
    kind: code
  - total: numeric within 0.005 tolerance
    kind: code
  - due_date: parses to ISO date and equals gold
    kind: code
baseline:
  model: gpt-5.6-terra
  by_segment: { clean_pdf: 0.97, scanned: 0.79, non_english: 0.88, multi_page: 0.91 }
gate:
  rule: no segment below its baseline minus 0.02
online:
  sample: 2% of production, human-review weekly, feed failures back into dataset

Lecture de la spec : des code graders exacts et numériques parce que la tâche est déterministe (pas de model-judge nécessaire ni souhaité) ; un segment scanned déjà le plus faible à 0,79, donc un changement de modèle qui remonte l’agrégat mais fait chuter davantage scanned doit être bloqué ; un holdout pour attraper le surapprentissage ; et un échantillon online pour que les échecs nouveaux rejoignent le dataset. Reportez toujours par segment — un agrégat de 0,91 ici masque le segment scanned dont les utilisateurs se plaignent réellement.

Idées reçues fréquentes

Déroulé de scénario

Une équipe veut faire passer un pipeline d’extraction de gpt-5.6-terra à gpt-5.6-luna pour réduire le coût. Un test rapide montre une précision agrégée « à peu près pareille ». Comment décider correctement ?

1. Golden set, par segment — exécutez les deux modèles sur le dataset figé et détaillez les résultats par type de document.
2. Le bon grader — code graders exacts et numériques sur les champs extraits ; c’est déterministe, donc un model judge n’ajouterait que du bruit.
3. Trouver la régression cachée — Luna égale Terra sur les PDF clean mais chute nettement sur les factures scannées ; l’agrégat le masquait.
4. Décider selon la contrainte — si les factures scannées comptent, gardez Terra pour ce segment et routez le reste vers Luna, en captant l’économie réelle sans la régression.
5. Verrouiller — ajoutez les seuils par segment à la CI pour qu’un futur changement ne puisse pas régresser silencieusement.
6. Surveiller en online — échantillonnez la production, confirmez que l’économie de coût est réelle, et réalimentez tout nouvel échec dans le dataset.

Alternatives rejetées : changer sur la précision agrégée (piège de la métrique agrégée), juger des champs déterministes avec un model grader dans la même session (piège d’indépendance), et estimer « à peu près pareil » à l’œil sans baseline ni significativité (piège du sans-mètre).

Points clés à retenir

• Construisez l’eval avant d’ajuster : le dataset est le mètre, tiré du trafic réel et des logs d’échecs, versionné et figé.
• Utilisez le grader le moins cher qui suffit ; les model graders doivent être indépendants et calibrés contre des labels humains.
• Combinez les evals offline (verrouiller le changement en CI, par segment) et l’évaluation online (attraper la dérive et les échecs nouveaux).
• Menez une boucle continue d’analyse d’échecs et réalimentez chaque échec corrigé dans le golden set.
• Évaluez les trajectoires d’agent, pas seulement les réponses finales : justesse des tools, efficacité, récupération, boundaries.
• Les evals et le fine-tuning sont regroupés sous les legacy APIs des docs mais restent une pratique correcte et essentielle.