Évaluations IA
Une évaluation est un test reproductible qui mesure si un système d'IA fait son travail. Cette compétence vous fait travailler comme l'enseigne le guide aievals.co : regarder les sorties réelles avant de mesurer quoi que ce soit, mesurer les échecs que vous avez réellement trouvés, vérifier chaque juge LLM contre des étiquettes humaines avant de lui faire confiance, et mettre un intervalle sur chaque nombre.
Le guide se trouve sur https://www.aievals.co. Citez ses pages lorsque vous expliquez un choix à l'utilisateur. Les fichiers de référence listés à la fin portent les détails et les sources.
Règles de base
Suivez celles-ci dans chaque tâche d'évaluation, quoi que l'utilisateur ait demandé.
- Regardez les traces avant d'écrire des métriques. Vous ne pouvez pas spécifier les modes d'échec d'un système que vous n'avez pas observé. Si l'utilisateur n'a pas de traces, commencez par en obtenir : journaux de production, ou exécution du système sur 100 entrées réalistes. Lisez-les ensuite.
- Les gens étiquettent ; vous proposez. N'écrivez jamais vous-même des étiquettes de vérité terrain et ne les présentez pas
comme des jugements humains. Vous pouvez rédiger des étiquettes marquées
"provisional": truepour qu'une personne les confirme. Ne laissez jamais un modèle écrire à la fois l'entrée et sa réponse de référence, sauf si le code calcule la réponse (résultats SQL, tests, une calculatrice). - Le code avant les juges. Tout ce qu'une correspondance de chaîne, un analyseur, une vérification de schéma, une expression régulière ou un test unitaire peut décider est un contrôle de code. Corrigez ce qu'une édition d'invite peut corriger avant de construire une évaluation. Gardez le juge LLM pour les échecs subjectifs qui subsistent.
- Un juge binaire par mode d'échec. PASS ou FAIL plus une critique d'une phrase. Pas d'échelles de 1 à 5. Plusieurs dimensions de qualité signifient plusieurs juges binaires, rapportés comme un taux de passage de tous les tests avec une ventilation par vérification.
- Calibrez avant de faire confiance à un juge. Comparez-le avec des étiquettes humaines et rapportez le rappel PASS et le rappel FAIL séparément, chacun avec son N. L'accord brut n'est jamais le titre : un juge qui dit toujours PASS a 95 % d'accord quand 5 % des sorties échouent.
- Entraînement, développement, test. Les exemples few-shot proviennent uniquement de l'entraînement. Itérez sur le développement. Lisez le test une fois, à la fin. Relire le test après d'autres modifications le transforme en un deuxième ensemble de développement.
- Épinglez le juge. L'ID du modèle, l'effort, le texte de la rubrique, le schéma de sortie et l'ordre few-shot font partie de l'instrument. Enregistrez-les avec chaque résultat, et recalibrez lorsque l'un d'eux change. Ne présumez pas de la déterminisme : exécutez le développement deux fois et comptez les inversions d'étiquette.
- Chaque nombre a N et un intervalle. Utilisez l'intervalle de Wilson pour les taux, jamais l'approximation normale. Comparez deux versions sur les mêmes entrées en tant que données appariées.
- L'ensemble de régression passe 100 % du temps. Il contient des bugs de production reproduits et des limites de politique. Un échec bloque la version, et un cas instable est un bug de processus.
- Filtrez sur la différence, pas sur le taux absolu. Utilisez les quatre bandes dans references/ci-and-release-gates.md.
- Limitez les dépenses dans l'exécuteur. Les exécutions de juges coûtent de l'argent. Appliquez un budget dans le code
(
EVAL_BUDGET_USD), pas comme un avertissement imprimé. - Construisez le plus petit truc qui fonctionne. Les assertions et environ 30 exemples étiquetés viennent avant un juge, et un juge calibré vient avant les tableaux de bord ou les ensembles de juges.
Choisissez le workflow
| L'utilisateur veut | Faire | Lire |
|---|---|---|
| Des évaluations pour une fonctionnalité qui n'en a pas | Workflow A | error-analysis, judges, datasets |
| Rédiger ou corriger une invite de juge LLM | Workflow B | judges, templates |
| Savoir si une évaluation existante est fiable | Workflow C | judges, statistics |
| Savoir si la version B bat la version A | Workflow D | statistics, ci-and-release-gates |
| Des évaluations qui tournent dans CI | Workflow E | ci-and-release-gates, datasets |
Workflow A : ajouter des évaluations à une fonctionnalité
- Collectez des traces. Récupérez au moins 100 traces diverses, ou exécutez le système sur des entrées
réalistes s'il n'est pas en production. Stockez-les en JSONL avec un
idstable par ligne. Les champs de trace qui valent la peine d'être journalisés sont dans references/templates.md. - Effectuez une analyse d'erreurs avec l'utilisateur (détails dans references/error-analysis.md). Une personne lit les traces et écrit une note d'une ligne sur la première chose qui a mal tourné dans chacune. Vous pouvez construire une visionneuse simple et regrouper les notes en 4 à 7 modes d'échec nommés une fois que la personne a codé au moins 30. Comptez chaque mode et classez par fréquence multipliée par gravité.
- Corrigez les bon marché. Les corrections d'invite et de code viennent en premier. Relancez et recomptez.
- Écrivez des contrôles de code pour chaque mode restant qu'une règle peut détecter.
- Écrivez un juge par mode subjectif restant (Workflow B).
- Obtenez des étiquettes humaines : 100 à 200 par mode d'échec est l'objectif, avec 30 à 50 PASS et 30 à 50 FAIL dans chacun des développement et test. Une division 40 % développement de 100 lignes ne peut pas contenir 30 de chaque classe, et avec un faible taux d'échec, vous devez sur-échantillonner les échecs pour remplir le côté FAIL. Commencez avec ce que vous avez et dites à quel point les intervalles sont larges.
- Calibrez chaque juge sur le développement, puis confirmez sur le test une fois.
- Construisez l'ensemble de régression à partir des échecs reproduits, et câblez la suite dans CI (Workflow E).
Livrables dans le dépôt de l'utilisateur, sauf s'il a déjà une disposition :
evals/
data/ labeled.jsonl (étiquettes humaines), regression.jsonl, traces/
rubrics/ un fichier par mode d'échec
codebook.md étiquette, définition, 2 exemples PASS et 2 FAIL, dernier kappa
checks.* contrôles de code
judge.* l'appel du juge, configuration épinglée
calibrate.* fractionnement, score, rapport, désaccords
run_eval.* score des sorties, comparaison avec la ligne de base, code de sortie pour CI
runs/ un dossier par exécution : résumé, prédictions, copie de la rubrique
Des starters fonctionnels en Python et TypeScript sont sur https://github.com/ombharatiya/ai-evals-skills/tree/main/starters. Copiez-en un plutôt que écrire le harnais à partir de zéro.
Workflow B : écrire ou corriger un juge LLM
- Confirmez que le mode d'échec provient de l'analyse d'erreurs et qu'un contrôle de code ne peut pas l'attraper.
- Écrivez l'invite en quatre parties (modèle dans references/templates.md) :
rôle et définitions exactes ; critères binaires ("PASS si X. FAIL si Y, même si le reste de la
réponse est correct. En cas de doute, FAIL et dites pourquoi.") ; 2 ou 3 exemples few-shot
de l'entraînement, y compris un FAIL qui ressemble à un PASS ; et un schéma de sortie strict,
{"label": "PASS" | "FAIL", "critique": "..."}, imposé par une sortie structurée là où l'API le supporte. L'analyseur doit échouer bruyamment sur une sortie malformée. - Calibrez : exécutez sur le développement, calculez le rappel PASS, le rappel FAIL et le kappa de Cohen, et lisez chaque désaccord. Lisez les faux PASS et les faux FAIL séparément. Si l'étiquette humaine est fausse, corrigez l'étiquette, pas la rubrique.
- Changez une chose par itération, dans cet ordre d'impact typique : spécificité de la rubrique, exemples few-shot, schéma de sortie, et changement de modèle en dernier.
- Attendez-vous à un plateau autour de la deuxième ou troisième itération. Ajoutez ensuite des few-shots pour les cas limites : deux exemples PASS qui ressemblent à des FAIL à une lecture négligente et deux exemples FAIL qui ressemblent à des PASS. Si le rappel FAIL ne bouge toujours pas, le modèle de juge peut être le plafond : essayez un plus fort avant de changer à nouveau la rubrique, et traitez le nouveau modèle comme un nouvel instrument à calibrer depuis zéro.
- Arrêtez-vous lorsque le rappel PASS et FAIL atteignent tous deux la barre sur le développement (la valeur par défaut de ce guide est 0,90 ; fixez-la à partir du coût d'un échec manqué par rapport à une fausse alerte), puis lisez le test une fois.
Workflow C : auditer une évaluation existante
Vérifiez chaque élément et signalez ce qui échoue, avec le fichier et la ligne :
- Les métriques remontent aux modes d'échec que quelqu'un a observés dans des traces réelles.
- Les contrôles de code couvrent ce que le code peut décider ; les juges sont binaires, un par mode d'échec.
- Chaque juge a un dossier de calibration : rappel PASS et FAIL avec N et intervalles, sur un ensemble de test que le juge n'a jamais vu. L'accord seul ne compte pas.
- Les exemples few-shot n'apparaissent pas dans le développement ou le test.
- La configuration du juge (modèle, effort, rubrique, schéma, few-shots) est épinglée et correspond à la configuration qui a été calibrée.
- Chaque taux rapporté a N et un intervalle ; les comparaisons sont appariées.
- Un ensemble de régression existe, s'exécute sur chaque PR, et passe à 100 %.
- Les décisions de version lisent le delta apparié et son intervalle, pas un seuil absolu.
- L'ensemble de données est versionné (hash de contenu) et les résultats nomment le hash.
- Une suite qui est restée à 100 % pendant des mois ne teste rien. L'ensemble de régression est la seule exception.
Workflow D : comparer deux versions
Exécutez les deux versions sur les mêmes entrées. Rapportez chaque taux de réussite avec son intervalle de Wilson et la différence appariée avec son intervalle : le test de McNemar ou un bootstrap apparié pour les résultats binaires. Déterminez la plus petite différence digne d'être détectée en premier, puis la taille de l'échantillon (references/statistics.md). Segmentez par segment lorsque cela compte, et corrigez les comparaisons multiples lorsque vous segmentez de plusieurs façons. "Aucune différence significative" d'une exécution sous-puissante n'est pas une preuve d'absence de différence : dites à quel point un changement l'exécution aurait pu détecter.
Workflow E : évaluations dans CI
Trois niveaux : un niveau fumée de 10 à 50 assertions déterministes à chaque poussée (pas de juge), un niveau complet avec le juge calibré sur les PR qui modifient les invites ou les modèles, et un niveau nocturne avec l'ensemble de régression et de robustesse élargi. Publiez un tableau baseline-versus-candidat sur le PR avec le delta, son intervalle à 95 % et un verdict expédier, mettre en attente, enquêter ou bloquer. Faites échouer le job sur enquêter, bloquer, un échec de l'ensemble de régression ou une mesure cassée (lignes sans verdict, lignes manquantes d'un côté ou de l'autre, un juge qui n'est pas le juge calibré), et signalez une mise en attente pour qu'une personne nommée la lise : une mise en attente signifie que l'intervalle ne peut pas faire la différence entre le changement et l'absence de changement. Taille de la fenêtre d'indifférence à partir d'une exécution A/A du système inchangé, pas à partir du zéro-bruit plancher. Pas de dérogations silencieuses : une dérogation nécessite une personne nommée et une raison écrite. Les fourchettes PR n'obtiennent pas de secrets d'API. Détails dans references/ci-and-release-gates.md.
Comment rapporter les résultats
Rapportez un tableau, pas une phrase :
| Métrique | Valeur | IC 95 % | N | Juge | Ensemble de données |
|---|---|---|---|---|---|
| Rappel FAIL, juge politique de remboursement (test) | 0,92 | [0,80, 0,97] | 48 | claude-opus-5-5, moyen, rubrique a1b2c3 | labeled.jsonl @ 9f8e7d |
Dites ce que les nombres ne peuvent pas soutenir. Écrivez "l'intervalle est large ; étiquetez plus d'exemples FAIL" plutôt que d'arrondir un résultat faible en une affirmation. Nommez la classe positive lorsque vous dites TPR ou TNR : certains écrits, dont la FAQ de Hamel Husain, traitent FAIL comme positif, donc son TPR est la part des vrais échecs attrapés. "Rappel PASS" et "Rappel FAIL" simples évitent la confusion.
Valeurs par défaut
Utilisez celles-ci sauf si la situation de l'utilisateur en appelle d'autres. "Valeur par défaut du site" signifie le propre nombre de travail
d'aievals.co, pas une norme publiée.
| Décision | Valeur par défaut | Source |
|---|---|---|
| Premier passage d'analyse d'erreurs | 100+ traces, premier échec seulement (FAQ Hamel et Shankar) ; 15 à 45 secondes chacune | FAQ, et aievals.co pour le rythme |
| Catégories de modes d'échec | 4 à 7 après codage axial | Guide de codage ouvert aievals.co |
| Étiquettes par mode d'échec | 100 à 200 | FAQ Hamel et Shankar |
| Division | 15 % entraînement, 40 % développement, 45 % test, stratifiée (les starters divisent par un hash de chaque id à la place, donc une ligne ne change jamais de division ; les ratios ne correspondent alors qu'en moyenne) | Recette de calibration aievals.co |
| Par classe dans développement et test | 30 à 50 PASS et 30 à 50 FAIL | FAQ Hamel et Shankar |
| Barre de rappel du juge | Rappel PASS et FAIL d'au moins 0,90 sur développement, confirmé sur test | Valeur par défaut du site |
| Accord humain avant automatisation | kappa d'au moins 0,6 pour continuer, 0,8 pour un ensemble de référence ou une porte | Politique d'équipe, selon le guide |
| Intervalle pour un taux | Wilson, 95 % | Chapitre statistiques d'aievals.co |
| Fenêtres de porte de version | Fenêtre d'indifférence de 1 point ; fenêtre de régression mineure de 2 points sur la métrique principale | Chapitre portes de version d'aievals.co |
| Ensemble de régression | 100 % de réussite sur chaque PR | Chapitre ensembles de régression d'aievals.co |
Références
Chargez le fichier qui correspond à la tâche :
- references/error-analysis.md : codage ouvert, axial et structuré, saturation, priorisation, la visionneuse de traces, échantillonnage dimensionnel.
- references/judges.md : conception de juges, calibration, biais et comment les tester, direct versus par paire, déclencheurs de recalibration.
- references/datasets.md : tailles par objectif, approvisionnement, règles pour les données synthétiques, ensembles de régression, grilles de couverture, versioning.
- references/statistics.md : intervalles de Wilson, tests appariés, erreurs groupées, taille d'échantillon, comparaisons multiples, correction des taux évalués par juge.
- references/ci-and-release-gates.md : niveaux CI, bandes de portes de version, évaluations en ligne, échantillonnage, dérive.
- references/templates.md : invite de juge, entrée de codebook, enregistrement d'annotation, schéma de trace, commentaire de résultat de PR.