Écrire des Evals

Vous écrivez des évaluations qui prouvent que les capacités de l'IA fonctionnent. Les evals sont la suite de tests pour les systèmes non-déterministes : elles mesurent si une capacité se comporte toujours correctement après chaque modification.

Prérequis

• Complétez le Axiom AI SDK Quickstart (instrumentation + authentification)

Vérifiez que le SDK est installé :

ls node_modules/axiom/dist/

Si non installé, installez-le avec le gestionnaire de paquets du projet (ex. pnpm add axiom).

Vérifiez toujours node_modules/axiom/dist/docs/ en premier pour les bonnes signatures API, les chemins d'importation et les motifs pour la version du SDK installée. La documentation groupée est la source de vérité — ne vous fiez pas aux exemples dans cette compétence s'ils entrent en conflit.

Philosophie

1. Les evals sont des tests pour l'IA. Chaque eval répond à : « cette capacité fonctionne-t-elle toujours ? »
2. Les scoreurs sont des assertions. Chaque scoreur vérifie une propriété de la sortie.
3. Les flags sont des variables. Les schémas de flag vous laissent faire varier les modèles, les températures, les stratégies sans changements de code.
4. Les données couvrent. Cas de chemin heureux, adversariaux, limites et négatifs.
5. Validez avant d'exécuter. Ne devihez jamais les chemins d'importation ou les types — utilisez les docs de référence.

Terminologie Axiom

Comment démarrer

Quand l'utilisateur vous demande d'écrire des evals pour une fonctionnalité IA, lisez d'abord le code. Ne posez pas de questions — inspectez la base de code et déduisez tout ce que vous pouvez.

Étape 1 : Comprendre la fonctionnalité

1. Trouvez la fonction IA — cherchez la fonction que l'utilisateur a mentionnée. Lisez-la complètement.
2. Tracez les entrées — quelles données entrent ? Un prompt en chaîne, un objet structuré, un historique de conversation ?
3. Tracez les sorties — qu'est-ce qui revient ? Une chaîne, une étiquette de catégorie, un objet structuré, un résultat d'agent avec des appels d'outils ?
4. Identifiez l'appel du modèle — quel LLM/modèle est utilisé ? Quels paramètres (température, maxTokens) ?
5. Vérifiez les evals existants — cherchez les fichiers *.eval.ts. Ne dupliquez pas ce qui existe.
6. Vérifiez la portée de l'app — cherchez createAppScope, flagSchema, axiom.config.ts.

Étape 2 : Déterminer le type d'eval

En fonction de ce que vous avez trouvé :

Étape 3 : Choisir les scoreurs

Chaque eval a besoin d'au moins 2 scoreurs. Utilisez cette stratification :

1. Scoreur de correction (obligatoire) — La sortie correspond-elle à la valeur attendue ? Choisissez dans le tableau de type eval ci-dessus (correspondance exacte, correspondance d'ensemble, correspondance de champ, etc.).
2. Scoreur de qualité (recommandé) — La sortie est-elle bien formée ? Vérifiez les seuils de confiance, la longueur de la sortie, la validité du format ou la complétude des champs.
3. Scoreur sans référence (ajouter pour le texte orienté utilisateur) — La sortie est-elle cohérente, pertinente, non toxique ? Utilisez LLM-as-judge ou autoevals.

Étape 4 : Générer

1. Créez le fichier .eval.ts colocalisé à côté du fichier source
2. Importez la fonction actuelle — ne créez pas de stub
3. Écrivez les scoreurs en fonction du type de sortie (minimum 2, voir étape 3)
4. Générez des données de test (voir Directives de conception de données)
5. Définissez les noms de capacité et d'étape correspondant à l'objectif de la fonctionnalité
6. Si des flags existent, utilisez pickFlags pour les circonscrire

Posez la question uniquement si vous ne pouvez pas déterminer :

• Ce que « correct » signifie pour des sorties ambiguës (ex. qualité de résumé)
• Si l'utilisateur veut un scoring passe/échoue ou crédit partiel
• Quels paramètres doivent être réglables via flags (s'ils n'utilisent pas déjà de flags)

Disposition du projet

Recommandé : Colocalisé avec la source

Placez les fichiers .eval.ts à côté de leurs fichiers d'implémentation, organisés par capacité :

src/
├── lib/
│   ├── app-scope.ts
│   └── capabilities/
│       └── support-agent/
│           ├── support-agent.ts
│           ├── support-agent-e2e-tool-use.eval.ts
│           ├── categorize-messages.ts
│           ├── categorize-messages.eval.ts
│           ├── extract-ticket-info.ts
│           └── extract-ticket-info.eval.ts
axiom.config.ts
package.json

Minimal : Structure plate

Pour les petits projets, gardez tout dans src/ :

src/
├── app-scope.ts
├── my-feature.ts
└── my-feature.eval.ts
axiom.config.ts
package.json

Le glob par défaut **/*.eval.{ts,js} découvre les fichiers eval n'importe où dans le projet. axiom.config.ts se trouve toujours à la racine du projet.

Structure du fichier Eval

Structure standard d'un fichier eval :

import { pickFlags } from '@/app-scope';       // ou chemin relatif
import { Eval } from 'axiom/ai/evals';
import { Scorer } from 'axiom/ai/scorers';
import { Mean, PassHatK } from 'axiom/ai/scorers/aggregations';
import { myFunction } from './my-function';

const MyScorer = Scorer('my-scorer', ({ output, expected }: { output: string; expected: string }) => {
  return output === expected;
});

Eval('my-eval-name', {
  capability: 'my-capability',
  step: 'my-step',                              // optionnel
  configFlags: pickFlags('myCapability'),        // optionnel, circonscrit l'accès aux flags
  data: [
    { input: '...', expected: '...', metadata: { purpose: '...' } },
  ],
  task: async ({ input }) => {
    return await myFunction(input);
  },
  scorers: [MyScorer],
});

Référence

Pour les motifs détaillés et les signatures de type, lisez-les à la demande :

• reference/scorer-patterns.md — Tous les motifs de scoreur (correspondance exacte, correspondance d'ensemble, structuré, utilisation d'outils, autoevals, LLM-as-judge), types de retour de score, conseils de typage
• reference/api-reference.md — Signatures de type complètes, chemins d'importation, agrégations, tâches de streaming, chargement de données dynamique, suivi manual des tokens, options CLI
• reference/flag-schema-guide.md — Règles de schéma de flag, validation, pickFlags, remplacements CLI, motifs courants
• reference/templates/ — Modèles de fichier eval prêts à l'emploi (voir section Modèles ci-dessous)

Configuration d'authentification

Avant d'exécuter les evals, l'utilisateur doit s'authentifier. Vérifiez qu'il l'a déjà fait avant de le suggérer.

Définissez les variables d'environnement (fonctionne pour les evals offline et online). Stockez dans .env à la racine du projet :

AXIOM_URL="https://api.axiom.co"
AXIOM_TOKEN="API_TOKEN"
AXIOM_DATASET="DATASET_NAME"
AXIOM_ORG_ID="ORGANIZATION_ID"

Référence CLI

Directives de conception des données

Étape 1 : Vérifiez les données existantes

Avant de générer des données de test, vérifiez si l'utilisateur a déjà des données :

1. Posez la question à l'utilisateur — « Avez-vous un ensemble de données eval, des cas de test ou des exemples d'entrées/sorties ? »
2. Cherchez dans la base de code — cherchez les fichiers JSON/CSV, les données de départ, les fixtures de test ou les tableaux data: existants dans d'autres fichiers eval
3. Vérifiez les logs de production — l'utilisateur peut avoir des entrées réelles dans Axiom qui peuvent être exportées

Si l'utilisateur a des données, utilisez-les directement dans le tableau data: ou chargez-les avec le chargement de données dynamique (data: async () => ...).

Étape 2 : Générez les données de test à partir du code

Si aucune donnée n'existe, générez-la en lisant le code de la fonctionnalité IA :

1. Lisez le prompt système — il définit ce que la fonctionnalité fait et quelles sorties sont valides. Extrayez les catégories, les étiquettes ou le comportement attendu qu'il décrit.
2. Lisez le type d'entrée — comprenez la forme de données que la fonction accepte. Générez des exemples réalistes de cette forme.
3. Lisez toute validation/analyse — si le code analyse ou valide la sortie, cela vous dit à quoi ressemble une sortie correcte.
4. Regardez les valeurs d'énumération ou les constantes — si la fonctionnalité se classe en catégories, utilisez-les comme valeurs attendues.

Étape 3 : Couvrez toutes les catégories

Générez au moins un cas par catégorie :

Minimum : 5-8 cas pour un eval basique. 15-20 pour une couverture de production.

Convention de métadonnées

Ajoutez toujours metadata: { purpose: '...' } à chaque cas de test pour la catégorisation.

Scripts

Types eval-scaffold

Flux de travail

1. Initialiser : scripts/eval-init pour créer app-scope + config
2. Générer : scripts/eval-scaffold <type> <capability> [step]
3. Personnaliser : remplacez les placeholders TODO par des données réelles et une fonction
4. Valider : scripts/eval-validate <file> pour vérifier la structure
5. Couverture : scripts/eval-add-cases <file> pour trouver les lacunes
6. Tester : npx axiom eval --debug pour une exécution locale
7. Déployer : npx axiom eval pour envoyer les résultats à Axiom
8. Examiner : scripts/eval-results <deployment> pour interroger les résultats depuis Axiom

Evals en ligne (Production)

Les évaluations en ligne évaluent les sorties de votre capacité IA sur le trafic de production en direct. Contrairement aux evals offline qui s'exécutent contre une collection fixe avec des valeurs attendues, les evals online sont sans référence — les scoreurs reçoivent input et output mais pas expected.

Utilisez les evals online pour : surveiller la qualité en production, capturer les régressions de format, exécuter les vérifications heuristiques, ou échantillonner le trafic pour le scoring LLM-as-judge sans affecter la réponse de votre capacité.

Quand utiliser online vs offline

Chemins d'importation

import { onlineEval } from 'axiom/ai/evals/online';
import { Scorer } from 'axiom/ai/scorers';

Signature de fonction

onlineEval prend un nom obligatoire (premier arg) et des paramètres :

void onlineEval('my-eval-name', {
  capability: 'qa',
  step: 'answer',           // optionnel
  input: userMessage,        // optionnel, passé aux scoreurs
  output: response.text,
  scorers: [formatScorer],
});

Le nom doit correspondre à [A-Za-z0-9\-_] uniquement.

Les scoreurs online utilisent la même API Scorer que offline (voir reference/scorer-patterns.md), mais sont sans référence — ils reçoivent input et output mais pas expected. Les evals online ne jettent jamais d'erreurs dans le code de votre app ; les défaillances de scoreur sont enregistrées sur l'intervalle eval comme des événements OTel.

Les différences clés par rapport à offline : échantillonnage par scoreur (nombre ou fonction async), liaison de trace via paramètre links ou auto-détection dans withSpan, et fire-and-forget (void) vs await pour les processus courte durée.

Avant d'écrire du code eval online, lisez toujours les docs groupées du SDK en premier — elles correspondent à la version installée et contiennent la dernière API, les paramètres et les motifs :

cat node_modules/axiom/dist/docs/evals/online/functions/onlineEval.md

Pièges courants

Recherche de documentation API

Pour les signatures de type exactes, vérifiez d'abord les docs groupées du SDK (correspond à la version installée) :

ls node_modules/axiom/dist/docs/

Chemins clés :

• node_modules/axiom/dist/docs/evals/functions/Eval.md
• node_modules/axiom/dist/docs/scorers/scorers/functions/Scorer.md
• node_modules/axiom/dist/docs/evals/online/functions/onlineEval.md
• node_modules/axiom/dist/docs/scorers/aggregations/README.md
• node_modules/axiom/dist/docs/config/README.md