Concepts fondamentaux pour l'observabilité des agents
Observabilité et qualité des agents : tout repose sur une boucle itérative permanente : reérer un problème dans votre agent, le mesurer de manière systématique, le corriger, valider la correction et le surveiller pour éviter qu'il ne se reproduise. Chaque concept de cette page fait partie de cette boucle.
Cette page explique chaque élément et la manière dont ils sont reliés.
La boucle de qualité
Chaque section ci-dessous correspond à une étape de cette boucle.
Traces et spans
Une trace est un enregistrement structuré d'une exécution complète de votre agent — les entrées et sorties de haut niveau, chaque étape intermédiaire (appels LLM, recherches de récupérateurs, appels d'outils), la latence et les éventuelles erreurs. Les traces constituent la matière première qui alimente toutes les autres étapes de la boucle.
En interne, une trace est une arborescence de spans . Chaque span représente une opération : il enregistre les données entrantes, les données sortantes, la durée de l'opération et les éventuelles métadonnées. Le span racine représente la requête d'agent complète, tandis que les spans enfants représentent les sous-opérations qui se sont produites au cours de cette requête.
Les traces sont stockées dans Unity Catalog sous forme de tables Delta (recommandé). Vous bénéficiez ainsi d’un accès gouverné, d’une interrogeabilité en SQL et d’aucun plafond de stockage par expérimentation (le même modèle de gouvernance que n’importe quelle autre table UC). Une fois stockées, vous pouvez explorer les traces dans l’interface utilisateur, les interroger avec SQL ou poser des questions en langage naturel à l’aide de Genie Code.
Sur le même sujet : Instrumenter votre agent · Afficher les traces dans l'interface utilisateur · Rechercher et query des traces
Sessions
Une session est une étiquette qui regroupe les traces associées d'une conversation à plusieurs tours : définissez mlflow.trace.session sur chaque trace. Le regroupement de sessions vous permet d'évaluer la qualité des conversations de bout en bout, et pas seulement tour par tour.
Évaluations : commentaires et attentes
Une évaluation est une mesure de qualité associée à une trace. Il existe deux types :
Type | Who adds it | Ce qu'il capture |
|---|---|---|
Commentaires | Évaluateurs, utilisateurs finaux, experts du domaine | Jugement qualitatif : réussite/échec, score numérique ou commentaire en texte libre. Exemples : un scorer |
Attentes | Experts du domaine | La sortie correcte pour une entrée donnée — la vérité terrain. Exemples : la réponse attendue à une question ; les faits requis qu'une réponse doit contenir. |
Le feedback est le principal signal du travail de qualité de routine ; vous n’avez pas besoin d’expectations pour tirer de la valeur de MLflow. Les attentes sont facultatives, mais permettent un score plus précis : les évaluateurs tels que Correctness comparent la réponse de l'agent à une réponse de référence connue.
Sur le même sujet : Annotations de développement · Avis d’expert · Recueillir les commentaires des utilisateurs
Évaluateurs
A scorer is a function that evaluates a trace and returns a feedback assessment. Chaque évaluateur suit le même contrat : recevoir une trace → extraire les champs pertinents → évaluer → renvoyer Feedback. Le même évaluateur fonctionne lors de l’évaluation hors ligne et lors du monitoring de la production en direct — vous écrivez une seule fois la logique de qualité et elle s’applique partout.
Types d’évaluateurs
Type | Comment il s’évalue | À utiliser lorsque |
|---|---|---|
Juges LLM intégrés | Évaluateurs préconfigurés alimentés par LLM pour les dimensions courantes : exactitude, pertinence, sécurité, ancrage, respect des directives, et plus encore. | Vous souhaitez une couverture de qualité immédiate sans écrire de code personnalisé. |
Juges LLM personnalisés | Un juge LLM doté d’un prompt d’évaluation personnalisé et d’une grille de notation que vous définissez. | Les juges intégrés ne couvrent pas vos critères spécifiques au domaine, ou vous avez besoin d’une notation granulaire (notes numériques, catégories personnalisées). |
Évaluateurs basés sur le code | Une fonction Python déterministe — correspondance exacte, validation du format, contrôles de latence, règles métier. | Vous avez besoin d’une logique précise et reproductible qui ne nécessite pas de modèle de langage. |
Juges et scorers
Les juges (par exemple, mlflow.genai.judges.is_correct) évaluent le texte en fonction de critères spécifiques — mais ils ne savent pas lire une trace. Les scorers sont les adaptateurs : ils extraient les champs pertinents d’une trace (requête, réponse, contexte récupéré, etc.) et les transmettent à un juge ou à une logique personnalisée. Lorsque vous utilisez un juge intégré directement dans scorers=[Correctness()], MLflow l’enveloppe automatiquement dans un scorer.
Associé : Vue d’ensemble des évaluateurs · Juges intégrés · Juges LLM personnalisés · Évaluateurs basés sur du code
Datasets et exécutions d'évaluation
Jeux de données d’évaluation
An evaluation dataset is a versioned, curated collection of test cases. Each record has:
inputs: ce qu'il faut envoyer à l'agentexpectations(facultatif) : la sortie correcte, utilisée par les scorers qui ont besoin de la vérité terrain
Vous créez des datasets en sélectionnant des traces représentatives de la production ou du développement, en écrivant des cas à partir de zéro ou en important à partir de sources externes. Les datasets sont versionnés afin de vous permettre de suivre l'évolution de votre suite de tests au fil du temps.
Connexe : Créer un dataset d’évaluation
Exécutions d'évaluation
Une exécution d’évaluation est le résultat de l’appel de mlflow.genai.evaluate(). Fournissez-lui un dataset et une liste d’évaluateurs pour qu’il :
- Exécute votre agent sur chaque input du dataset, en capturant les traces.
- Applique chaque évaluateur à chaque trace, ce qui produit des évaluations de commentaires.
- Stocke les taux de réussite agrégés et les métriques aux côtés des traces individuelles.
Use evaluation runs to answer: did this change improve quality? et a-t-il entraîné une régression quelconque ? Comparez les exécutions côte à côte pour suivre la progression entre les différentes itérations. Evaluation runs are a special type of MLflow Run and are queryable programmatically.
Sur le même sujet : Exécuter une évaluation · Fonctionnement de l'évaluation
Monitoring de la production
Le monitoring de production programme l’exécution automatique de scorers sur le trafic d’agents en direct. Attachez un évaluateur à votre agent déployé et le service de monitoring évalue les traces entrantes au fil de l’eau, en écrivant des retours d’évaluation dans la même trace.
Le format de feedback est identique à celui de l'évaluation hors ligne, de sorte que les tendances de qualité sont directement comparables entre l'environnement de développement (dev) et de production (prod). Le monitoring de la production boucle la boucle : elle met en évidence de nouvelles défaillances dans le trafic en direct, que vous intégrez ensuite à votre dataset d’évaluation pour les corriger lors de l'itération suivante.
Articles connexes : Aperçu du monitoring de production · Start et configuration du monitoring
Comment tout s’articule
Chaque concept dessert une étape spécifique de la boucle de qualité :
Étape | Concept(s) clé(s) |
|---|---|
Tracer votre agent | Traces, spans |
Trouver un problème | Traces, sessions, interface utilisateur et requêtes SQL, analyse en langage naturel via Genie Code |
Recueillir des commentaires et élaborer un dataset | Assessments (feedback + expectations), dataset d’évaluation |
Rédigez un scoreur, corrigez l’agent et évaluez la correction | Évaluateurs, exécutions d’évaluation |
Surveiller la production | Monitoring de la production, évaluateurs programmés |
La boucle les relie : le monitoring de la production identifie les nouveaux cas d'échec → vous les intégrez dans un dataset → vous rédigez ou ajustez un évaluateur → vous procédez à une évaluation pour confirmer la correction → l'agent amélioré passe en production → le monitoring surveille le problème suivant.
Étapes suivantes
- Instrumentez votre agent — ajoutez le traçage à votre agent en quelques lignes
- Observer et rechercher des problèmes — explorer et analyser les traces capturées
- Créer un dataset d’évaluation — organiser des traces en cas de test structurés
- Lancez une évaluation — évaluez votre agent par rapport à un dataset
- Configurer le monitoring de production — détecter les régressions de qualité dans le trafic en direct