Exécuter des évaluations hors connexion

L'évaluation hors connexion vous permet de mesurer les performances, la sécurité et la qualité de vos agents en analysant les données historiques collectées lors du développement ou de la production. Vous pouvez évaluer des traces individuelles (chemins d'exécution uniques) ou des sessions complètes (historiques de conversations multitours) par rapport à un ensemble de métriques prédéfinies ou personnalisées.

Traces et sessions

  • Trace : enregistrement factuel et immuable du comportement de l'agent, y compris les entrées, les réponses et les appels d'outils du modèle. Une trace représente un chemin d'exécution unique.
  • Session : englobe l'ensemble de l'interaction multiconversationnelle entre un utilisateur et un agent. Utilisez les sessions pour évaluer la conservation du contexte et le flux de conversation au fil du temps.

Avant de commencer

Pour vous assurer de disposer des données et de l'environnement nécessaires à l'évaluation hors connexion, procédez comme suit :

  • Assurez-vous d'avoir déployé un environnement d'exécution de l'agent fonctionnel avec Cloud Trace activé.
  • Configurez un bucket Cloud Storage pour stocker les résultats de l'évaluation. Vous n'avez besoin de fournir ce chemin qu'une seule fois. Il sera prérempli pour les futures exécutions.
  • Si vous prévoyez d'utiliser le SDK Agent Platform pour l'évaluation, initialisez le client comme décrit dans Évaluer vos agents.

Exigences concernant la télémétrie

L'évaluation hors connexion nécessite que votre agent exporte des signaux OpenTelemetry spécifiques pour fournir le contexte nécessaire à l'évaluation. Ces exigences sont identiques à celles des moniteurs en ligne :

  1. Portée d'appel de l'agent : doit inclure les attributs suivants :

    • gen_ai.agent.name : identifiant de l'agent.
    • gen_ai.agent.description : brève description de l'objectif de l'agent.
    • gen_ai.conversation.id : identifiant unique de la session de conversation spécifique.

  2. Événements d'inférence : l'événement gen_ai.client.inference.operation.details doit capturer les éléments suivants :

    • gen_ai.input.messages : requêtes envoyées à l'agent.
    • gen_ai.output.messages : réponses générées par l'agent.
    • gen_ai.system_instructions : requêtes système sous-jacentes.
    • gen_ai.tool.definitions : métadonnées sur les outils disponibles pour l'agent.

Si vous utilisez le kit de développement de l'agent, vous devez activer ces fonctionnalités de télémétrie en définissant les variables d'environnement suivantes :

OTEL_SEMCONV_STABILITY_OPT_IN='gen_ai_latest_experimental'
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT='EVENT_ONLY'

Enregistrer des contenus multimédias dans Cloud Storage

Si votre agent utilise des données multimodales, telles que des images ou des documents volumineux, nous vous recommandons d'enregistrer les entrées et les sorties dans un bucket Cloud Storage au lieu de les intégrer directement dans les étendues de trace. Pour l'activer, configurez les variables d'environnement suivantes :

OTEL_INSTRUMENTATION_GENAI_UPLOAD_FORMAT='jsonl'
OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK='upload'
OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH='gs://STORAGE_BUCKET_NAME/PATH'

Pour en savoir plus, consultez Collecter des requêtes et des réponses multimodales.

Créer une évaluation à partir du registre

  1. Dans la console Google Cloud , accédez à la page Agent Platform > Agents > Evaluation.

    Accéder à la page "Évaluation"

  2. Cliquez sur Nouvelle évaluation.

  3. Sélectionnez l'onglet Traces ou Sessions en fonction de votre objectif d'évaluation.

  4. Utilisez l'icône de filtre et le sélecteur de date et heure pour filtrer les données (par exemple, par Version ou "Les deux dernières semaines") et sélectionnez les ID spécifiques que vous souhaitez évaluer.

  5. Cliquez sur Continuer.

  6. (Facultatif) Dans le champ Nom de l'évaluation, saisissez un nom pour l'évaluation ou utilisez la valeur par défaut préremplie.

  7. Dans le champ Chemin d'accès aux données privées de sortie, saisissez l'URI de votre bucket Cloud Storage. Après la première utilisation, ce chemin d'accès est prérempli pour les exécutions futures.

  8. Par défaut, les quatre métriques principales sont ajoutées. Vous pouvez ajouter ou supprimer des métriques selon vos besoins.

  9. Cliquez sur Évaluer l'agent.

Évaluer une trace ou une session unique

Vous pouvez déclencher des évaluations directement lors de l'inspection des chemins d'exécution individuels :

  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. Sélectionnez l'onglet Traces.
  5. Cliquez sur Vue de la session ou Vue de la trace pour inspecter le chemin d'exécution.
  6. Sélectionnez une ligne spécifique du tableau pour ouvrir le panneau de détails.
  7. Sélectionnez l'onglet Évaluation.
  8. Si la trace ou la session n'a pas été évaluée, cliquez sur Évaluer pour effectuer une évaluation ponctuelle.

Afficher les résultats de l'évaluation

Une fois l'évaluation terminée, vous pouvez analyser les résultats pour identifier les écarts de performances et les problèmes systémiques :

  • Afficher les résultats d'une exécution : dans la console Google Cloud , accédez à la page Plate-forme d'agents > Agents > Évaluation, puis sélectionnez l'onglet Évaluations. Cliquez sur le nom d'une évaluation pour afficher le rapport détaillé.

    Accéder à la page "Évaluation"

  • Afficher les traces en détail : dans un rapport de résultats, cliquez sur n'importe quelle ligne pour accéder directement à la trace associée et examiner le raisonnement (les justifications) derrière les scores.

Pour en savoir plus, consultez Analyser les résultats de l'évaluation.