Avant de commencer
Pour afficher et analyser les résultats de l'évaluation, assurez-vous de disposer des éléments suivants :
- Exécutez au moins une évaluation comme décrit dans Évaluer vos agents ou Exécuter des évaluations hors connexion.
- Configurez un bucket Cloud Storage pour la sortie de l'évaluation si vous exécutez des évaluations hors connexion.
- (Facultatif) Si vous utilisez le SDK pour récupérer les résultats, assurez-vous que votre environnement est authentifié.
Après avoir exécuté une évaluation, la plate-forme d'agents fournit des outils de diagnostic pour vous aider à identifier les causes racines de l'échec. Vous pouvez analyser les résultats à trois niveaux : les tendances agrégées dans le tableau de bord, les groupes sémantiques dans les clusters d'échec et les chemins logiques granulaires dans les traces individuelles.
Tableau de bord d'évaluation pour les moniteurs en ligne
Pour les agents avec des moniteurs en ligne actifs, vous pouvez afficher les tendances agrégées des performances dans le tableau de bord :
- Dans la Google Cloud console, accédez à la page Plate-forme d'agents > Agents.
- Dans le menu de navigation de gauche, sélectionnez Déploiements.
Sélectionnez votre agent.
Cliquez sur l'onglet Tableau de bord , puis sélectionnez la sous-section Évaluation.
- Tendances des performances : visualisez l'évolution des scores pour des métriques telles que Tâche réussie ou Qualité de l'utilisation des outils sur différentes versions d'agent ou périodes.
- État zéro : pour les agents sans moniteurs en ligne actifs, cette vue identifie les lacunes de couverture et fournit un appel à l'action pour commencer l'évaluation.
Afficher les résultats de l'évaluation avec le SDK
Vous pouvez accéder aux résultats de l'évaluation de manière programmatique à l'aide du SDK de la plate-forme d'agents. Le SDK fournit des visualisations interactives intégrées pour les environnements de notebook Colab et Jupyter, qui affichent à la fois des métriques récapitulatives agrégées et des résultats détaillés par cas.
Après avoir exécuté une évaluation, appelez .show() sur l'objet de résultat pour afficher un rapport interactif directement dans votre notebook :
from vertexai import evals, types
# Run an evaluation
result = client.evals.evaluate(
dataset=eval_dataset,
metrics=[
types.RubricMetric.FINAL_RESPONSE_QUALITY,
types.RubricMetric.TOOL_USE_QUALITY,
types.RubricMetric.HALLUCINATION,
types.RubricMetric.SAFETY,
],
)
# Visualize aggregate and per-case results in your notebook
result.show()
La visualisation inclut les éléments suivants :
- Métriques récapitulatives : scores agrégés pour tous les cas d'évaluation, y compris le score moyen et le taux de réussite pour chaque métrique.
- Résultats par cas : scores individuels des cas d'évaluation que vous pouvez développer pour inspecter les résultats détaillés.
L'exemple suivant montre les métriques récapitulatives de result.show() :
Vous pouvez développer des cas d'évaluation individuels pour afficher les scores par métrique, les verdicts de la grille d'évaluation et les justifications :
Interpréter les résultats de l'évaluation
Les métriques prédéfinies renvoient des résultats dans deux formats différents, selon le type de métrique :
- Les métriques de grille d'évaluation adaptative génèrent automatiquement des grilles d'évaluation en fonction de la configuration de l'agent et du prompt de l'utilisateur. Chaque grille d'évaluation reçoit un verdict Réussite ou Échec individuel, ainsi qu'une justification en langage naturel expliquant le raisonnement du LLM de l'évaluateur. Le score global représente le taux de réussite, c'est-à-dire la proportion de grilles d'évaluation ayant reçu un verdict Réussite.
- Les métriques de grille d'évaluation statique utilisent un ensemble fixe de critères d'évaluation. Par exemple, la métrique "Hallucination" segmente la réponse en affirmations atomiques et vérifie chacune d'elles par rapport aux preuves d'utilisation des outils. Les vérifications de sécurité concernent les informations personnelles, l'incitation à la haine, les contenus dangereux et autres violations des règles. Ces métriques renvoient un seul score numérique (de 0 à 1).
Identifier et trier les échecs
Après avoir examiné les résultats de l'évaluation, l'étape suivante consiste à identifier les schémas d'échec systémiques et à les trier pour améliorer votre agent. La plate-forme d'agents fournit une analyse automatique des pertes, qui analyse les signaux de réussite ou d'échec des métriques basées sur des grilles d'évaluation, classe les échecs en schémas de perte prédéfinis, et les regroupe en clusters sémantiques. Cela vous aide à comprendre non seulement que votre agent a échoué, mais aussi pourquoi et comment il a échoué.
Accéder aux clusters d'échec dans la console
- Accédez à la page Plate-forme d'agents > Agents > Évaluation.
- Sélectionnez l'onglet Évaluations.
- Cliquez sur le nom d'une exécution d'évaluation terminée pour ouvrir le rapport.
- Si l'évaluation a détecté des clusters, ils s'affichent dans la section Clusters d'échec du rapport.
Générer des clusters d'échec avec le SDK
Vous pouvez également générer des clusters d'échec de manière programmatique à l'aide de la méthode generate_loss_clusters :
# Generate failure clusters from evaluation results
loss_clusters = client.evals.generate_loss_clusters(
eval_result=result,
)
# Visualize the loss pattern analysis in your notebook
loss_clusters.show()
L'exemple suivant montre l'analyse des schémas de perte de loss_clusters.show() :
Taxonomies des schémas de perte
L'analyse automatique des pertes classe chaque échec dans un ou plusieurs schémas de perte prédéfinis. Ces schémas sont conçus pour être concrets et exploitables, et sont directement associés à des domaines spécifiques de votre agent que vous pouvez améliorer.
Il existe deux taxonomies prédéfinies, chacune alignée sur une métrique spécifique :
Taxonomie de réussite des tâches de l'agent
Cette taxonomie est utilisée avec la métrique Réussite des tâches multitour de l'agent (multi_turn_task_success_v1). Elle couvre les échecs comportementaux de haut niveau de l'agent en matière d'hallucination, de suivi des instructions, d'appel d'outils, de gestion des résultats d'outils et de qualité des outils :
| Catégorie | Schéma de perte | Description |
|---|---|---|
| Hallucination | Hallucination d'action | L'agent affirme avoir effectué une action sans exécuter l'appel d'outil nécessaire. |
| Hallucination d'informations manquantes | L'agent invente un détail (tel qu'une valeur, un fait ou une date) qui n'est pas présent dans la requête de l'utilisateur ni dans le résultat de l'outil. | |
| Hallucination d'outil ou de fonctionnalité | L'agent affirme disposer d'un outil ou d'une fonctionnalité qu'il ne possède pas. | |
| Suivi des instructions | Non-respect des contraintes | L'agent effectue la tâche, mais enfreint les contraintes explicites de l'utilisateur (telles que les règles de mise en forme ou les contraintes négatives). |
| Action futile (sous-traitement) | L'agent effectue une action non pertinente au lieu d'indiquer que la tâche est impossible avec les outils disponibles. | |
| Exécution incomplète | L'agent effectue partiellement une tâche, mais s'arrête prématurément ou demande une autorisation inutile pour les étapes explicitement demandées. | |
| Sur-traitement | L'agent refuse une tâche, affirmant qu'il ne dispose pas d'un outil ou d'une fonctionnalité qu'il possède en réalité. | |
| Appel d'outils | Sélection d'outil incorrecte | L'agent sélectionne le mauvais outil parmi les options disponibles. |
| Paramètres d'outil sémantiquement incorrects | L'appel d'outil est syntaxiquement valide, mais contient une erreur logique ou sémantique dans les valeurs des paramètres. | |
| Appel d'outil syntaxiquement incorrect | L'appel d'outil comporte des erreurs de syntaxe, des paramètres obligatoires manquants, ou des valeurs d'arguments non valides. | |
| Gestion des résultats d'outils | Traitement incorrect des résultats d'outils | L'agent reçoit des résultats d'outils valides, mais extrait, traite ou interprète les informations de manière inexacte. |
| Qualité des outils | Résultats d'outils insuffisants | L'outil s'exécute correctement, mais renvoie des données insuffisantes ou manquantes pour que l'agent puisse continuer. |
| Échec de l'outil | L'outil échoue en raison de problèmes d'infrastructure tels que des échecs d'authentification , des délais d'attente ou des erreurs internes. |
Taxonomie de la qualité de l'utilisation des outils
Cette taxonomie est utilisée avec la métrique Qualité de l'utilisation des outils multitour de l'agent (multi_turn_tool_use_quality_v1). Elle se concentre spécifiquement sur l'exactitude de l'appel d'outil et la gestion des réponses d'outil :
| Catégorie | Schéma de perte | Description |
|---|---|---|
| Hallucination | Hallucination de la valeur du paramètre | L'agent invente une valeur spécifique pour un paramètre qui n'a pas fourni par l'utilisateur ou qui ne peut pas être déduit du contexte. |
| Hallucination d'outil | L'agent tente d'appeler une fonction qui n'existe pas dans son ensemble d'outils défini. | |
| Appel d'outils | Échec de la définition du paramètre | L'agent omet un paramètre nécessaire pour répondre aux contraintes de l'utilisateur, ce qui entraîne une valeur par défaut non intentionnelle. |
| Type de données de paramètre incorrect | L'agent fournit une valeur de type de données incorrect pour un paramètre (par exemple, une chaîne alors qu'un entier est requis). | |
| Mappage de paramètre incorrect | L'agent attribue une valeur au mauvais paramètre (par exemple, en inversant les dates de début et de fin). | |
| Valeur de paramètre incorrecte | L'agent fournit une valeur de paramètre qui est logiquement ou factuellement incorrecte, ou n'applique pas les transformations de données nécessaires. | |
| Sélection d'outil incorrecte | L'agent sélectionne la mauvaise fonction dans son ensemble d'outils disponible. | |
| Syntaxe d'appel d'outil non valide | L'agent génère un appel de fonction avec une erreur de syntaxe qui empêche l'analyse ou l'exécution. | |
| Paramètre inexistant | L'agent inclut un argument de paramètre qui n'est pas défini dans la signature de l'outil. | |
| Omission de l'appel d'outil requis | L'agent n'exécute pas une fonction nécessaire, que ce soit en répondant directement, en ignorant une partie d'une requête composée ou en ignorant une étape prérequise step. | |
| Sous-traitement | L'agent force un appel d'outil alors qu'il devrait répondre en langage naturel (par exemple, en demandant des clarifications ou en refusant une requête hors champ ). | |
| Réponse de l'outil | Réponse d'outil non pertinente | L'outil s'exécute correctement, mais renvoie des données qui ne sont pas pertinentes pour la requête spécifique de l'utilisateur. |
| Erreur d'outil | L'outil renvoie une erreur explicite ou un état d'échec en raison d'un problème externe (tel qu'une indisponibilité d'API ou des autorisations non valides). |
Workflow de triage recommandé
Utilisez le workflow suivant pour trier systématiquement les échecs d'évaluation :
- Commencez par les métriques récapitulatives pour identifier les métriques les moins bien notées dans votre ensemble de données d'évaluation.
- Explorez les résultats par cas pour trouver les cas d'évaluation spécifiques qui ont échoué.
- Générez des clusters d'échec pour identifier les schémas de perte systémiques dans les échecs.
- Explorez les traces pour trouver le tour ou l'appel d'outil exact où l'échec s'est produit. Dans la console, accédez à Plate-forme d'agents > Agents > Déploiements, sélectionnez votre agent, puis ouvrez l'onglet Traces. Sélectionnez une trace pour afficher l'historique complet de la conversation et la séquence exacte des entrées de modèle, des appels d'outils et des réponses.
- Identifiez la cause racine : utilisez la catégorie de schéma de perte pour déterminer si le problème est lié à un prompt, à une configuration d’outil ou à des données.
- Appliquez un correctif ciblé aux instructions système, aux définitions d'outils ou aux exemples few-shot de l'agent.
- Réexécutez l'évaluation et comparez les scores pour vérifier l'amélioration.