Évaluation continue avec des moniteurs 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é (une baisse observable des performances de l'agent au fil du temps) causée par des changements dans le comportement des utilisateurs ou les données externes. En configurant des moniteurs en ligne, vous pouvez évaluer de manière asynchrone les 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 de manière programmatique, 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. Segment 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 :

   • gen_ai.input.messages : prompts envoyés à 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 l'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 segments de trace. Configurez les variables d'environnement suivantes pour l'activer :

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.

Fonctionnement des moniteurs en ligne

Les surveillances en ligne s'exécutent selon 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 Cloud Logging en fonction de vos filtres.
2. Évaluer : exécute les métriques configurées à l'aide du service d'évaluation de 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 une surveillance en ligne

1. Dans la console Cloud de Confiance , 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écifier les traces de filtre :

   • Moteur de l'agent : sélectionnez l'agent que vous souhaitez surveiller dans le menu déroulant.
   • Critères de filtre : choisissez d'évaluer Toutes les traces pour l'agent ou d'appliquer des Critères de filtre 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, Dernier jour) pour prévisualiser les 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. Configurer les métriques : ajoutez les métriques que vous souhaitez suivre en continu, comme Sécurité.

6. Définir l'échantillonnage :

   • Pourcentage d'échantillonnage : définissez le pourcentage de votre trafic en ligne à évaluer.
   • Nombre maximal d'exemples par exécution : définissez un plafond pour gérer les coûts d'évaluation.

7. Cliquez sur Créer.

Gérer les surveillances

Une fois que vous avez créé une surveillance, vous pouvez la gérer à partir de la liste Surveillances en ligne :

• Bouton d'activation/désactivation de l'état : cliquez sur Autres options more_vert, puis sélectionnez Activer ou Désactiver pour suspendre l'évaluation sans supprimer la configuration.
• Mettre en pause et reprendre : utilisez Plus d'options more_vert 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 ainsi que d'autres signaux de performances :

1. Dans la console Cloud de Confiance , 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 les graphiques de séries temporelles des métriques que vous avez configurées, telles que la qualité des réponses, la sécurité et les taux d'hallucination.

Afficher les résultats de traces individuelles

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

1. Dans la console Cloud de Confiance , accédez à l'onglet Traces de l'agent.
2. Sélectionnez une session ou une trace dans le tableau pour ouvrir le panneau des 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 surveillances en ligne

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

1. Vérifier la télémétrie : assurez-vous que votre agent exporte correctement les segments et événements OpenTelemetry requis. Vérifiez Cloud Trace pour voir si les traces actives contiennent les attributs gen_ai..
2. Vérifier les filtres : examinez les critères de filtrage de votre surveillance. Utilisez la fonctionnalité d'inspection initiale pour vérifier que vos filtres correspondent à votre trafic de production.

3. Vérifier 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"