Analyser les résultats de l'évaluation et les clusters d'échecs

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.
• Vous avez configuré un bucket Cloud Storage pour les résultats 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, Agent Platform fournit des outils de diagnostic pour vous aider à identifier les causes premières des échecs. Vous pouvez analyser les résultats à trois niveaux : les tendances globales dans le tableau de bord, les groupes sémantiques dans les clusters de défaillances et les chemins logiques précis 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 consulter les tendances globales des performances dans le tableau de bord :

1. Dans la console Google Cloud , accédez à la page Agent Platform > Agents.
2. Dans le menu de navigation de gauche, sélectionnez Déploiements.

3. Sélectionnez votre agent.

   Accéder à la page "Déploiements"

4. Cliquez sur l'onglet Tableau de bord, puis sélectionnez la sous-section Évaluation.

• Tendances des performances : visualisez l'évolution des scores de métriques telles que Tâche réussie ou Qualité de l'utilisation de l'outil pour différentes versions d'agent ou périodes.
• État zéro : pour les agents sans surveillance en ligne active, cette vue identifie les lacunes de couverture et fournit un bouton d'incitation à 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 Agent Platform. Le SDK fournit des visualisations interactives intégrées pour les environnements Colab et de notebook 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 d'évaluation individuels que vous pouvez développer pour examiner 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, selon le type de métrique :

• Les métriques de rubriques adaptatives génèrent automatiquement des rubriques en fonction de la configuration de l'agent et de la requête de l'utilisateur. Chaque grille reçoit un verdict Réussite ou Échec, accompagné d'une explication en langage naturel qui détaille le raisonnement du LLM évaluateur. Le score global représente le taux de réussite, c'est-à-dire la proportion de rubriques ayant reçu la mention Réussite.
• Les métriques de rubriques statiques utilisent un ensemble fixe de critères d'évaluation. Par exemple, la segmentation des hallucinations divise la réponse en affirmations atomiques et vérifie chacune d'elles par rapport aux preuves d'utilisation des outils. Vérifications de sécurité pour les informations permettant d'identifier personnellement l'utilisateur, l'incitation à la haine, le contenu dangereux et d'autres cas de non-respect des règles. Ces métriques renvoient un score numérique unique (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. Agent Platform fournit l'analyse automatique des pertes, qui analyse les signaux de réussite ou d'échec à partir de métriques basées sur des grilles d'évaluation, classe les échecs dans des modèles de perte prédéfinis et les regroupe dans des 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'échecs dans la console

1. Accédez à la page Agent Platform > Agents > Évaluation.
2. Sélectionnez l'onglet Évaluations.
3. Cliquez sur le nom d'une exécution d'évaluation terminée pour ouvrir le rapport.
4. Si l'évaluation a détecté des clusters, ils sont affichés dans la section Clusters d'échecs du rapport.

Générer des clusters de défaillance avec le SDK

Vous pouvez également générer des clusters de défaillance 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 à partir 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 modèles sont conçus pour être concrets et exploitables. Ils correspondent directement à des zones spécifiques de votre agent que vous pouvez améliorer.

Il existe deux taxonomies prédéfinies, chacune étant alignée sur une métrique spécifique :

Taxonomie du succès des tâches de l'agent

Cette taxonomie est utilisée avec la métrique Réussite de la tâche multitour de l'agent (multi_turn_task_success_v1). Elle couvre les échecs comportementaux de haut niveau de l'agent en termes d'hallucination, de respect des instructions, d'appel d'outil, de gestion de la sortie de l'outil et de qualité de l'outil :

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 (comme 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'un outil ou d'une fonctionnalité	L'agent affirme disposer d'un outil ou d'une capacité qu'il ne possède pas.
Suivi des instructions	Non-respect des contraintes	L'agent effectue la tâche, mais ne respecte pas les contraintes explicites de l'utilisateur (par exemple, les règles de mise en forme ou les contraintes négatives).
	Action futile (sous-dégagement)	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 des étapes explicitement demandées.
	Dégagement trop long	L'agent refuse une tâche en 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 incorrecte des outils	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 de l'outil	Traitement incorrect du résultat de l'outil	L'agent reçoit une sortie d'outil valide, mais extrait, traite ou interprète les informations de manière inexacte.
Qualité de l'outil	Résultat d'outil insuffisant	L'outil s'exécute correctement, mais renvoie des données insuffisantes ou manquantes nécessaires à l'agent pour poursuivre.
	É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 par l'agent (multi_turn_tool_use_quality_v1). Elle se concentre spécifiquement sur l'exactitude de l'appel d'outil et sur la gestion de la réponse de l'outil :

Catégorie	Schéma de perte	Description
Hallucination	Hallucination de la valeur d'un paramètre	L'agent invente une valeur spécifique pour un paramètre qui n'a pas été 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 souhaitée.
	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ètres 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 incorrecte d'un point de vue logique ou factuel, ou n'applique pas les transformations de données nécessaires.
	Sélection incorrecte des outils	L'agent sélectionne la mauvaise fonction dans son ensemble d'outils disponibles.
	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 d'un appel d'outil obligatoire	L'agent ne parvient pas à exécuter une fonction nécessaire, que ce soit en répondant directement, en ignorant une partie d'une requête complexe ou en ignorant une étape requise.
	Under-Punting	L'agent force un appel d'outil alors qu'il devrait répondre en langage naturel (par exemple, en demandant des précisions ou en refusant une demande 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 de l'outil	L'outil renvoie une erreur explicite ou un état d'échec en raison d'un problème externe (par exemple, une panne d'API ou des autorisations non valides).

Workflow de triage recommandé

Utilisez le workflow suivant pour trier systématiquement les échecs d'évaluation :

1. Commencez par les métriques récapitulatives pour identifier les métriques ayant obtenu les scores les plus bas dans votre ensemble de données d'évaluation.
2. Analysez les résultats par cas pour trouver les cas d'évaluation spécifiques qui ont échoué.
3. Générez des clusters de défaillances pour identifier les schémas de perte systémiques entre les défaillances.
4. Analysez les traces pour trouver le tour ou l'appel d'outil exact où l'échec s'est produit. Dans la console, accédez à Agent Platform > Agents > Déploiements, sélectionnez votre agent, puis ouvrez l'onglet Traces. Sélectionnez une trace pour afficher l'intégralité de l'historique des conversations et la séquence exacte des entrées de modèle, des appels d'outils et des réponses.
5. Identifier la cause première : utilisez la catégorie de modèle de perte pour déterminer si le problème est lié à une requête, à la configuration d'un outil ou à des données.
6. Appliquez une correction ciblée aux instructions système, aux définitions d'outils ou aux exemples few-shot de l'agent.
7. Exécutez à nouveau l'évaluation et comparez les scores pour vérifier l'amélioration.