Évaluation continue avec des surveillances en ligne

La surveillance en ligne vous permet d'évaluer en continu la qualité de vos agents en production. Cette approche proactive vous aide à identifier la dérive de qualité, c'est-à-dire une diminution observable des performances de l'agent au fil du temps, causée par des changements dans le comportement des utilisateurs ou des données externes. En configurant des moniteurs en ligne, vous pouvez attribuer des scores de manière asynchrone aux traces en direct à l'aide de métriques prédéfinies et personnalisées, ce qui garantit que votre agent reste fiable et conforme à vos normes de performances.

Avant de commencer

Pour activer la surveillance en ligne de vos agents, assurez-vous que les conditions suivantes sont remplies :

  • Déployez votre agent comme décrit dans Déployer un agent.
  • Assurez-vous que Cloud Trace est activé pour votre projet.
  • (Facultatif) Si vous prévoyez de créer des moniteurs par programmation, consultez la page Évaluer vos agents pour obtenir des instructions d'initialisation du SDK Agent Platform.

Exigences concernant la télémétrie

La surveillance en ligne nécessite que votre agent exporte des signaux OpenTelemetry spécifiques pour fournir le contexte nécessaire à l'évaluation :

  1. Étendue de l'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.

Fonctionnement des moniteurs en ligne

Les moniteurs en ligne s'exécutent sur une boucle d'évaluation planifiée, généralement toutes les 10 minutes. La boucle suit les étapes suivantes :

  1. Requête : échantillonne les données de Cloud Trace et de Cloud Logging en fonction de vos filtres.
  2. Évaluation : exécute les métriques configurées à l'aide du service d'évaluation Gemini Enterprise Agent Platform.
  3. Rapport : réécrit les résultats dans Cloud Logging et exporte les scores numériques vers Cloud Monitoring.

Créer un moniteur en ligne

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

    Accéder à la page "Évaluation"

  2. Sélectionnez l'onglet Moniteurs en ligne , puis cliquez sur Nouveau moniteur.

  3. Spécifiez les traces de filtre :

    • Moteur d'agent : sélectionnez l'agent que vous souhaitez surveiller dans le menu déroulant.
    • Critères de filtrage : choisissez d'évaluer Toutes les traces de l'agent ou d'appliquer des critères de filtrage spécifiques.

  4. Définissez les critères de filtrage (si vous utilisez des traces filtrées) :

    • Inspection initiale : sélectionnez une période (par exemple, 1 dernier jour) pour afficher un aperçu des traces de production correspondant à votre filtre.
    • Filtres : saisissez des critères pour cibler un trafic spécifique. Vous pouvez filtrer par propriétés telles que Duration (par exemple, Duration > 2) ou Token usage.

  5. Configurez les métriques : ajoutez les métriques que vous souhaitez suivre en continu, telles que Sécurité.

  6. Définissez l'échantillonnage :

    • Pourcentage d'échantillonnage : définissez le pourcentage de votre trafic en temps réel à évaluer.
    • Nombre maximal d'échantillons par exécution : définissez une limite pour gérer les coûts d'évaluation.

  7. Cliquez sur Créer.

Gérer les moniteurs

Une fois que vous avez créé un moniteur, vous pouvez le gérer à partir de la liste Moniteurs en ligne :

  • Bouton d'état : cliquez sur Plus d'options puis sélectionnez Activer ou Désactiver pour suspendre l'évaluation sans supprimer la configuration.
  • Mettre en pause et reprendre : utilisez Plus d'options pour arrêter temporairement l'évaluation.
  • Dupliquer : créez un moniteur avec des paramètres préremplis à partir d'un moniteur existant.
  • Afficher les traces : cliquez sur le lien Afficher les traces dans la colonne Traces échantillonnées d'un moniteur pour accéder directement aux traces filtrées dans l'onglet Traces de l'agent.

Afficher les résultats dans le tableau de bord d'observabilité

Pour afficher vos métriques d'évaluation avec d'autres signaux de performances :

  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. Dans la vue Tableau de bord , sélectionnez la sous-section Évaluation pour afficher des graphiques de séries temporelles pour les métriques configurées, telles que la qualité des réponses, la sécurité et les taux d'hallucination.

Afficher les résultats pour des traces individuelles

Vous pouvez également inspecter les résultats de l'évaluation pour des conversations spécifiques directement dans la vue des traces :

  1. Dans la Google Cloud console, accédez à l'onglet Traces de l'agent.
  2. Sélectionnez une session ou une trace dans le tableau pour ouvrir le panneau de détails.
  3. Sélectionnez l'onglet Évaluation pour afficher les scores et les justifications de cette interaction spécifique.

Résoudre les problèmes liés aux moniteurs en ligne

Si votre moniteur en ligne est actif, mais qu'aucun résultat n'apparaît dans votre tableau de bord :

  1. Vérifiez la télémétrie : assurez-vous que votre agent exporte correctement les étendues et les événements OpenTelemetry requis. Vérifiez dans Cloud Trace si les traces en direct contiennent les attributs gen_ai..
  2. Vérifiez les filtres : examinez les critères de filtrage de votre moniteur. Utilisez la fonctionnalité Inspection initiale pour vérifier que vos filtres correspondent à votre trafic de production.

  3. Vérifiez les journaux internes : les moniteurs en ligne écrivent des informations de diagnostic dans Cloud Logging. Si une évaluation échoue, un journal d'erreurs est généré. Vous pouvez trouver ces journaux dans l'explorateur de journaux en recherchant l'ID de votre moniteur, ou des traces et des agents spécifiques :

    resource.labels.online_evaluator="projects/YOUR_PROJECT_ID/locations/YOUR_REGION/onlineEvaluators/YOUR_MONITOR_ID"
# Or search by trace or agent
labels.trace="YOUR_TRACE_ID"
labels.reasoning_engine_id="YOUR_AGENT_ID"