Ingénierie d'évaluation en ligne

Construisez des évaluateurs en ligne itérativement :

inspecter les traces et interroger l'utilisateur -> proposer des directions -> l'utilisateur choisit
-> construire l'évaluateur -> tester, attacher, vérifier -> réviser et répéter

Lisez references/langsmith-api.md avant de créer ou modifier des évaluateurs.

1. Inspecter les traces

Demandez à l'utilisateur le nom de son projet LangSmith. Récupérez les traces récentes de niveau racine et affichez leur structure. Lisez references/trace-inspection.md. Identifiez :

• le nom et le type de la run ;
• les noms de champs d'entrée et de sortie disponibles ;
• la forme et le contenu des données (échantillons tronqués) ;
• les champs qui contiennent les données dont un évaluateur aurait besoin.

Résumez la structure des traces dans la conversation :

Projet : nom
Type de run : chain | llm | tool | ...
Champs d'entrée : noms et contenu
Champs de sortie : noms et contenu
Échantillon : une paire entrée/sortie représentative (tronquée)

Impliquez l'utilisateur : expliquez la structure des traces et ses implications, puis posez uniquement les questions que les traces ne peuvent pas établir. Par exemple : « Que fait cette application ? », « Quel problème de qualité compte le plus ? », ou « Quel type d'échec ne doit jamais se produire ? »

Demandez si l'utilisateur souhaite un préfixe de nommage pour les évaluateurs de cette session (par exemple, monapp-, v2-, dogfood-). S'il en fournit un, appliquez-le à tous les noms d'évaluateurs, les handles du prompt hub et les noms d'affichage des règles de run. Sinon, utilisez des noms descriptifs simples.

Ne proposez pas d'évaluateurs tant que la structure des traces n'est pas comprise et que l'utilisateur n'a pas décrit ses préoccupations.

2. Discuter et choisir une direction d'évaluation

Lisez references/evaluator-design.md. Proposez deux ou trois critères d'évaluation fondés sur les données des traces. Appliquez le préfixe de nommage de l'étape 1 si l'utilisateur en a fourni un. Pour chacun, fournissez :

Nom : nom descriptif de l'évaluateur (avec préfixe si défini)
Type : LLM-as-judge ou code
Mesure : quelle dimension de qualité ceci évalue
Notation : bool, float (0-1), ou int ; ce que signifie réussite/échec
Champs nécessaires : quels champs de trace sont utilisés et comment
Justification : pourquoi ce type et cette approche

Exemple :

Nom : relevance-reponse
Type : LLM-as-judge
Mesure : si la réponse aborde la question de l'utilisateur
Notation : bool ; True = pertinent, False = hors-sujet ou non-réactif
Champs nécessaires : entrée (question utilisateur), sortie (réponse assistant)
Justification : la pertinence est sémantique et nécessite la compréhension de texte ; n'est pas décidable par code

Recommandez-en une et demandez à l'utilisateur laquelle construire. Ne l'implémentez pas tant que l'utilisateur n'a pas choisi.

3. Construire un évaluateur

Lisez references/langsmith-api.md. Construisez l'évaluateur sélectionné. Affichez la configuration complète à l'utilisateur et obtenez son approbation avant d'exécuter des appels API.

Chemin LLM-as-judge. Définissez une ResponseSchema avec reasoning en premier, puis le champ de score. Écrivez les messages de prompt avec une grille d'évaluation claire qui évalue le résultat, non s'il correspond à une réponse de référence. Définissez variable_mapping en utilisant les noms de champs découverts à l'étape 1. Présentez le schéma, le prompt, le mappage de variables et le nom de l'évaluateur pour approbation. Après approbation, poussez le prompt et créez l'évaluateur. Rapportez l'ID de l'évaluateur.

Chemin code evaluator. Écrivez une fonction perform_eval(run, example=None). Elle doit être autonome (seuls builtins et standard library), accéder à run comme dict (run.get("outputs")), et retourner {"key": ..., "score": ..., "comment": ...}. Présentez le code de la fonction et le nom de l'évaluateur pour approbation. Après approbation, créez l'évaluateur. Rapportez l'ID de l'évaluateur.

4. Tester, attacher et vérifier

Avant d'attacher, demandez à l'utilisateur quel taux d'échantillonnage il souhaite (1.0 = chaque trace, 0.5 = la moitié, 0.1 = 10 %, ou personnalisé). Ne définez pas silencieusement. Si l'utilisateur est incertain, recommandez 1.0 pour les tests initiaux.

Demandez à l'utilisateur s'il souhaite tester l'évaluateur sur quelques traces existantes avant d'attacher. Les règles de run ne s'exécutent que sur les nouvelles traces, donc les tests historiques sont le seul moyen de vérifier avant l'arrivée du nouveau trafic.

Pour les code evaluators, exécutez perform_eval directement sur les traces de niveau racine récupérées, en passant un dict avec les clés inputs, outputs et attachments. Cela détecte les erreurs d'exécution (noms de champs erronés, accès dict-vs-objet, données manquantes) avant la production. Pour les évaluateurs LLM, vérifiez la configuration : confirmez que les clés variable_mapping correspondent aux espaces réservés du prompt, confirmez que les champs de trace mappés existent, et vérifiez que les données mappées sont significatives.

Si le test révèle des erreurs, corrigez et recréez avant d'attacher. Si l'utilisateur décline le test, procédez à l'attachement.

Créez une règle de run pour connecter l'évaluateur au projet de tracing. Appliquez le préfixe de nommage de l'utilisateur au display_name. Confirmez que l'évaluateur apparaît dans la liste des évaluateurs avec l'attachement du projet correct. Inspectez :

• l'attachement de l'évaluateur et le statut de la règle de run ;
• les scores et commentaires de trace récents (à partir des tests historiques ou des nouvelles traces) ;
• si les scores correspondent aux attentes pour les traces inspectées ;
• la gestion des cas limites (sortie vide, runs en erreur, structure inattendue).

Corrigez et réattachez quand l'évaluateur plante, note incorrectement, ou échoue sur les cas limites. Avant approbation, confirmez que l'évaluateur a noté la dimension de qualité visée, pas une défaillance d'infrastructure ou de forme de données.

5. Réviser avec l'utilisateur

Expliquez le nom et l'ID de l'évaluateur, la dimension de qualité et l'approche de notation, les champs de trace utilisés, le taux d'échantillonnage et toute limitation. Demandez à l'utilisateur d'approuver, de réviser, d'abandonner ou de choisir la direction suivante. Si vous continuez, réutilisez les découvertes de traces, puis proposez une dimension de qualité distincte.

Invariants

• Une dimension de qualité par évaluateur.
• Pas de devinette sur les noms de champs ; inspectez toujours les traces avant d'implémenter.
• Affichez la configuration et obtenez l'approbation de l'utilisateur avant de faire des appels API.
• Les code evaluators doivent être autonomes : seuls builtins et standard library.
• Les code evaluators reçoivent run comme plain dict ; utilisez run.get("inputs") et run.get("outputs"), non l'accès par attribut. Le paramètre example doit valoir par défaut None.
• Traitez les défaillances API, les erreurs d'authentification et les défaillances de règles de run comme des erreurs d'infrastructure, pas des bugs d'évaluateur.