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 en plusieurs tours) 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 du modèle, les réponses et les appels d'outils. Une trace représente un chemin d'exécution unique.
  • Session : englobe l'ensemble de l'interaction en plusieurs tours 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 qu'un environnement d'exécution de l'agent fonctionnel est déployé 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 exécutions futures.
  • 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 processus de surveillance en ligne :

  1. Étendue 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 : invites envoyées à l'agent.
    • gen_ai.output.messages : réponses générées par l'agent.
    • gen_ai.system_instructions : invites système sous-jacentes.
    • gen_ai.tool.definitions: métadonnées sur les outils disponibles pour l'agent.

Si vous utilisez le Agent Development Kit, 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. Configurez les variables d'environnement suivantes pour activer cette fonctionnalité :

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 invites et des réponses multimodales.

Créer une évaluation à partir du registre

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

    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 pour filtrer les données (par exemple, par Version ou "Les 2 dernières semaines"), puis 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 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 seule trace ou session

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

  1. Dans la Google Cloud console, 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 Affichage des sessions ou Affichage des traces pour inspecter le chemin d'exécution.
  6. Sélectionnez une ligne spécifique dans le 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 exécuter une évaluation ad hoc.

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 Google Cloud console, accédez à la page Agent Platform > 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"

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

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