É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 des agents au fil du temps, causée par des changements dans le comportement des utilisateurs ou dans 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. Vous vous assurez ainsi 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 de respecter les exigences suivantes :

  • 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 les instructions d'initialisation du SDK Agent Platform.

Exigences concernant la télémétrie

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

  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 spans 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.

Fonctionnement des moniteurs en ligne

Les moniteurs 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 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 Google Cloud , accédez à la page Agent Platform > Agents > Evaluation.

    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 filtrage : choisissez d'évaluer Toutes les traces pour 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, 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 les données 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 direct à é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éé une surveillance, vous pouvez la gérer depuis la liste Surveillances en ligne :

  • Bouton bascule de l'é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 à côté d'autres signaux de performances :

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

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érifiez la télémétrie : assurez-vous que votre agent exporte correctement les événements et les spans OpenTelemetry requis. Consultez Cloud Trace pour voir 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. Pour trouver ces journaux, recherchez l'ID de votre moniteur dans l'explorateur de journaux : sh resource.type="aiplatform.googleapis.com/OnlineEvaluator" resource.labels.online_evaluator_id="YOUR_MONITOR_ID"