Annoter les traces avec des retours humains (version préliminaire)

Important

Les éléments marqués comme préversion dans cet article sont actuellement en préversion. Cette préversion est fournie sans contrat de niveau de service et Microsoft ne le recommande pas pour les charges de travail de production. Certaines fonctionnalités peuvent ne pas être prises en charge ou avoir des fonctionnalités contraintes. Pour plus d’informations, consultez Conditions d'utilisation supplémentaires pour les versions préliminaires de Microsoft Azure.

Ajoutez des annotations « pouce vers le haut » ou « pouce vers le bas » aux traces dans Microsoft Foundry afin de recueillir des signaux humains sur la qualité de chaque interaction de l’agent. Les annotations de trace vous permettent de marquer si une réponse de l’agent était utile ou non utile et qu’elles apparaissent en ligne sur la page de détails de la trace afin de pouvoir identifier rapidement les modèles dans le comportement de l’agent.

Les annotations de trace prennent en charge deux flux de travail :

Annotations des concepteurs : Les concepteurs et les experts métier annotent les traces depuis le portail Foundry lorsqu’ils examinent les interactions de l’agent. Ces annotations sont automatiquement étiquetées avec builder comme source.
Retour des utilisateurs finaux : Enregistrez les annotations par programmation depuis votre application lorsque les utilisateurs finaux donnent un avis positif ou négatif. Ces annotations ont pour source end_user et s’affichent sur la page de trace aux côtés des annotations du builder. Pour plus d’informations sur l’enregistrement des commentaires des utilisateurs finaux, consultez Enregistrer les commentaires des utilisateurs finaux.

Toutes les annotations sont ajoutées à la trace — l’ajout d’une annotation du créateur n’écrase ni ne remplace jamais les commentaires existants des utilisateurs finaux, et vice versa. Chaque annotation porte un attribut source afin que les signaux restent interrogeables et filtrables indépendamment.

Prerequisites

Projet Foundry avec une ressource Application Insights connectée. Consultez Configurer le suivi.
Instrumentation OpenTelemetry configurée dans votre application. Consultez Set up tracing in Microsoft Foundry pour obtenir des instructions de configuration.
Pour les annotations programmatiques : les packages azure-ai-projects et azure-monitor-opentelemetry installés.
```
pip install "azure-ai-projects>=2.0.0" azure-monitor-opentelemetry python-dotenv
```
Pour les annotations programmatiques qui utilisent l’ingestion Application Insights authentifiée Microsoft Entra : l’identité qui émet des données de télémétrie a le rôle Monitoring Metrics Publisher sur la ressource Application Insights connectée. Pour obtenir des instructions spécifiques à l’installation et à l’identité, consultez Configurer l’authentification Microsoft Entra pour l’ingestion de trace.

Modèle de scoring par défaut

Chaque projet Foundry est prédéfini avec un modèle de scoring haut/bas par défaut qui est immédiatement disponible sans configuration supplémentaire. Vous pouvez commencer à annoter les traces le jour 1. Le modèle par défaut utilise le score de réussite/échec binaire :

Pouces vers le haut = score 1.0, étiquette pass
Pouces vers le bas = score 0.0, étiquette fail

Chaque modèle de scoring nécessite que l’attribut gen_ai.evaluation.name ait la valeur task_completion afin que chaque annotation soit attribuable à une dimension d’évaluation spécifique. task_completion prend en charge les pouces vers le haut et vers le bas.

Annoter les traces dans le portail Foundry

Ajoutez des annotations directement à partir de la page de détails de la trace pour enregistrer votre évaluation des réponses de l’agent.

Ouvrez votre projet Foundry et accédez à Traçage dans le menu de navigation de gauche.
Sélectionnez une trace pour ouvrir l’affichage des détails de la trace.
Dans la page des détails de la trace, sélectionnez le bouton Annoter dans le coin supérieur droit.
Sélectionnez Pouces vers le haut ou Pouces vers le bas pour envoyer votre score. Ajoutez éventuellement une explication de texte libre.
L’annotation est enregistrée immédiatement et apparaît dans la trace.

Remarque

L’affichage d’une trace et l’enregistrement d’une annotation sont des opérations d’autorisation distinctes. Si la trace est visible, mais que l’annotation ne peut pas être enregistrée, vérifiez la destination de l’annotation, l’identité réelle utilisée pour l’écriture et le chemin d’authentification. Un autre rôle Lecteur de traces n’accorde pas d’accès d’écriture à la télémétrie.

Les annotations que vous ajoutez à partir du portail sont automatiquement marquées avec :

microsoft.gen_ai.human_evaluation.source = "builder"
microsoft.gen_ai.evaluation.actor.type = "human"

Modification du score

Chaque utilisateur peut annoter plusieurs fois :

Plusieurs utilisateurs peuvent avoir chacun leur propre annotation du même type sur une même trace.
Les annotations précédentes ne sont pas supprimées dans Application Insights. De nouvelles annotations sont ajoutées et le portail affiche toutes les annotations dans la section Historique des annotations du panneau d’annotations.

Journaliser les commentaires des utilisateurs finaux en tant qu’annotations de trace

Lorsque les utilisateurs finaux donnent un avis positif ou négatif dans votre application, vous pouvez consigner ce retour afin qu’il apparaisse sous forme d’annotations dans la trace correspondante. Cette approche utilise l’événement gen_ai.evaluation.result OpenTelemetry, avec les commentaires automatiquement corrélés à la trace d’origine.

Schéma d’attribut d’annotation

Utilisez les attributs suivants lorsque vous émettez une annotation vers le haut ou vers le bas :

Attribute	Valeur	Description
`gen_ai.evaluation.name`	`task_completion`	Nom de la métrique d’évaluation
`gen_ai.evaluation.score.value`	`1.0` (pouce levé) ou `0.0` (pouce baissé)	Score numérique
`gen_ai.evaluation.score.label`	`"pass"` ou `"fail"`	Étiquette catégorielle
`gen_ai.evaluation.explanation`	Commentaire de texte libre facultatif	Explication du réviseur
`gen_ai.response.id`	Par exemple : `"chatcmpl-123"`	ID de réponse IA utilisé pour mettre en corrélation l’annotation avec la réponse trace
`microsoft.gen_ai.human_evaluation.source`	`"end_user"` ou `"builder"`	Type de fournisseur de commentaires
`microsoft.gen_ai.evaluation.actor.type`	`"human"`	Indique que l’annotation a été envoyée par un réviseur humain, la distinguer des évaluations automatisées
`operation_Id`	`trace_Id`	Lie l’annotation à la demande de trace d’origine dans Application Insights
`operation_ParentId`	`span_Id`	Inclut l’ID du span spécifique au sein de la trace en cours d’annotation.
`gen_ai.agent.id`	Chaîne d’identificateur de ressource de l’agent	Identificateur unique de l’agent qui a produit la réponse annotée
`gen_ai.agent.name`	Chaîne de nom complet de l’agent	Nom complet de l’agent qui a produit la réponse annotée
`gen_ai.agent.version`	Chaîne de version `1`, `2`, ou `3`	Située à l’intérieur de `internal_properties`, la version de l’agent au moment où la réponse annotée a été produite

Vous devez émettre l’événement d’évaluation dans le même contexte de traçage (en utilisant le même ID de trace et le même ID de span) que l’interaction de l’agent qu’il sert à annoter. Cette corrélation garantit que l’annotation apparaît sur la trace correcte dans le portail.

Pour obtenir un exemple d’exécution complet, consultez sample_human_evaluations.py.

Afficher les annotations sur la page de trace

Après avoir ajouté des annotations (à partir du portail ou par programmation), elles apparaissent sur la page de détails de la trace.

Ouvrez votre projet Foundry et accédez à Tracing.
Sélectionnez une trace contenant des annotations.
Dans la page de détails de la trace, les icônes d’annotation apparaissent en regard des étendues annotées. Une icône vers le haut indique des commentaires positifs et une icône vers le bas indique des commentaires négatifs.
Pointez sur une annotation pour afficher les métadonnées, y compris la source (builder ou end_user), le nom d’évaluation et l’horodatage.

Dans l’affichage liste des traces, les annotations s’affichent avec un traitement compact : seules les annotations les plus récentes sont affichées inline et lorsque plusieurs annotations existent sur une trace, un indicateur « +X more » signale que des annotations supplémentaires sont disponibles. Sélectionnez la trace pour afficher toutes les annotations.

Filtrer les traces par annotation

Vous pouvez filtrer la liste de traces par :

Type d’évaluation (gen_ai.evaluation.name) : valeur est "task_completion".
Valeur ou libellé du score (gen_ai.evaluation.score.value, gen_ai.evaluation.score.label) : par exemple, affichez uniquement les traces avec une évaluation « pouce vers le bas ».
Source (microsoft.gen_ai.human_evaluation.source) : affichez uniquement les annotations du générateur ou uniquement les commentaires des utilisateurs finaux.

Ces dimensions de filtre apparaissent en même temps que les filtres de trace existants (intervalle de temps, agent, état, modèle).

Interroger des annotations dans Application Insights

Toutes les annotations sont publiées dans Azure Monitor /Application Insights et attachées à la trace d’origine. Vous pouvez interroger des annotations à l’aide du langage de requête Kusto (KQL) pour analyser les modèles de commentaires, générer des tableaux de bord ou configurer des alertes.

Résumer les commentaires par source et par jour

customEvents
| where name == "gen_ai.evaluation.result"
| extend
    eval_name = tostring(customDimensions["task_completion"]),
    score = todouble(customDimensions["gen_ai.evaluation.score.value"]),
    label = tostring(customDimensions["gen_ai.evaluation.score.label"]),
    eval_source = tostring(customDimensions["microsoft.gen_ai.human_evaluation.source"]),
    trace_id = tostring(customDimensions["trace_id"])
| where eval_source in ("builder", "end_user")
| summarize
    thumbs_up = countif(score == 1.0),
    thumbs_down = countif(score == 0.0),
    total = count()
  by eval_source, bin(timestamp, 1d)
| order by timestamp desc

Trouver des traces avec des retours négatifs

customEvents
| where name == "gen_ai.evaluation.result"
| extend
    eval_name = tostring(customDimensions["task_completion"]),
    score = todouble(customDimensions["gen_ai.evaluation.score.value"]),
    eval_source = tostring(customDimensions["microsoft.gen_ai.human_evaluation.source"]),
    explanation = tostring(customDimensions["gen_ai.evaluation.explanation"]),
    trace_id = tostring(customDimensions["trace_id"])
| where score == 0.0
| project timestamp, trace_id, eval_name, eval_source, explanation
| order by timestamp desc

Résolution des problèmes d’écriture d’annotation

Symptôme	Vérifier
Vous pouvez afficher une trace, mais l’enregistrement d’une annotation de générateur échoue avec une erreur d’autorisation	Traitez l’enregistrement comme une opération d’écriture distincte. Vérifiez la ressource Application Insights connectée, l’identité utilisée pour l’écriture et le mode d’authentification de connexion. N’ajoutez pas un autre rôle Lecteur en tant que correctif générique.
Une annotation programmatique retourne `401` ou `403`	Vérifiez que l’application envoie des données de télémétrie à la ressource Application Insights attendue. Pour l’ingestion authentifiée par Microsoft Entra, accordez Monitoring Metrics Publisher à l’identité émettrice de télémétrie sur cette ressource.
L’application signale la réussite, mais l’annotation n’apparaît pas	Vérifiez que l’événement d’évaluation utilise le contexte de trace et d’étendue d’origine, qu’il a été envoyé à la même ressource Application Insights que la trace et que l’ingestion est terminée.
Une annotation apparaît sur la trace incorrecte	Vérifiez `operation_Id`, `operation_ParentId`puis `gen_ai.response.id` avant d’émettre l’événement.

Commentaires

Cette page a-t-elle été utile ?

Dernière mise à jour : 2026-10-08