Ce produit n'est pas pris en charge par le site Datadog que vous avez sélectionné. ().
Présentation
Les files d’attente d’annotation offrent un workflow structuré pour l’examen humain des traces LLM. Utilisez les files d’attente d’annotation pour :
Examinez les traces avec un contexte complet, incluant les spans, les métadonnées, les appels d’outils, les entrées, les sorties et les résultats d’évaluation
Appliquez des étiquettes structurées et des observations libres aux traces
Identifiez et catégorisez les modèles de défaillance
Validez la précision de l’évaluation LLM-as-a-Judge
Constituez des jeux de données de référence avec des étiquettes vérifiées par des humains pour les tests et la validation
Création d’une file d’attente d’annotation
Étape 1: Configurer les paramètres de la file d’attente
Name : Nom descriptif reflétant l’objectif de la file d’attente (par exemple, « Failed Evaluations Review - Q1 2026 »)
Project : Projet Agent Observability auquel appartient cette file d’attente
Description (facultatif) : Expliquez l’objectif de la file d’attente et toute instruction particulière pour les annotateurs
Cliquez ensuite sur Next.
Dans l’onglet Schema, définissez le schéma d’étiquetage de votre nouvelle file d’attente. Utilisez le volet de prévisualisation pour voir comment les étiquettes apparaissent aux annotateurs au fur et à mesure que vous les configurez. Chaque étiquette peut être marquée comme obligatoire et peut éventuellement inclure :
Assessment criteria : Permettre aux annotateurs d’indiquer Pass/Fail pour cette valeur d’étiquette
Reasoning : Permettre aux annotateurs d’ajouter une courte explication
Vérifiez la configuration de votre file d’attente et cliquez sur Create pour créer la file d’attente.
Étape 2: Sélectionner les traces pour l’annotation
Vous pouvez ajouter manuellement des traces à une file d’attente depuis le Trace Explorer ou remplir les files d’attente automatiquement à l’aide de règles d’automatisation.
Ajouter manuellement des traces à une file d’attente depuis le Trace Explorer :
Filtrer les traces à l’aide des facettes disponibles (résultats d’évaluation, état d’erreur, application, plage temporelle)
Sélectionner des traces individuelles ou sélectionner plusieurs traces en bloc
Cliquez sur Flag for Annotation
Choisissez Create New Queue ou sélectionnez une file d’attente existante
Au lieu de sélectionner manuellement les traces, utilisez les règles d’automatisation pour acheminer automatiquement les traces vers des files d’attente d’annotation en fonction de filtres et de critères d’échantillonnage. Cela permet une alimentation continue et automatique de la file d’attente sans nécessiter de sélection manuelle des traces. Consultez Automation Rules pour obtenir la référence complète de la fonctionnalité, y compris les champs de filtre pris en charge et les limites.
Les automatisations s'appliquent à l'avenir : les nouvelles traces correspondant à votre règle sont acheminées vers la file d'attente dès leur arrivée. Les traces existantes correspondant au filtre ne sont pas ajoutées rétroactivement.
Pour ajouter une action de file d’attente d’annotation à une règle d’automatisation :
Appliquez des filtres pour identifier les traces que vous souhaitez acheminer (échecs d’évaluation, seuils de latence, applications spécifiques). Consultez Automation Rules > Supported filter fields pour connaître les options autorisées.
Cliquez sur Automate Query
Configurez le taux d’échantillonnage (jusqu’à 5 % pour les files d’attente d’annotation ; par exemple, 2 % des traces correspondantes).
Sous Actions, sélectionnez Add to Annotation Queue.
Choisissez la file d’attente cible.
Enregistrez la règle.
Les traces correspondant aux filtres de la règle sont ajoutées à la file d’attente dès leur arrivée. Les files d’attente d’annotation peuvent contenir jusqu’à 1 000 enregistrements ; l’automatisation se met en pause lorsque la file d’attente atteint cette limite.
Annotation des traces
Accès à vos files d’attente
Accédez à AI Observability > Experiment > Annotations pour voir toutes les files d’attente d’annotation disponibles. Cliquez sur une file d’attente pour voir la liste des traces, puis cliquez sur Review pour commencer l’annotation.
Remarque : lorsqu’une tâche d’annotation vous est nouvellement assignée, Datadog envoie un e-mail avec le nom de la file d’attente, l’utilisateur qui l’a assignée et un lien direct pour ouvrir l’interaction assignée. Pour vous désinscrire, désactivez les e-mails d’assignation d’annotation Agent Observability dans Paramètres personnels abonnements aux e-mails.
Le mode Révision affiche :
Full trace context (panneau de droite) :
Arborescence complète des spans avec entrées, sorties, métadonnées
Appels d’outils et étapes de raisonnement intermédiaires
Résultats d’évaluation sur la trace et les spans individuels
Annotation controls (panneau de gauche) :
Libellés configurés pour cette file d’attente
Indicateur de progression affichant la position dans la file d’attente
Commandes de navigation (Précédent, Suivant)
Application des libellés
Pour chaque trace :
Examinez le contexte complet de la trace : développez les spans si nécessaire pour comprendre les entrées, les sorties, les appels d’outils et les résultats d’évaluation.
Appliquez les libellés : remplissez les libellés configurés en fonction de votre évaluation.
Les annotations sont enregistrées automatiquement.
Meilleures pratiques pour l’annotation
Soyez cohérent :
Examinez la description de la file d’attente et les définitions des libellés avant de commencer.
Lorsque plusieurs annotateurs travaillent sur la même file d’attente, établissez une compréhension commune des critères.
Documentez le raisonnement dans les notes pour les cas limites.
Fournissez un raisonnement :
Utilisez des notes libres pour documenter pourquoi vous avez appliqué des étiquettes spécifiques.
Notez les modèles que vous observez à travers plusieurs traces.
Le raisonnement aide à affiner les critères d’évaluation et à comprendre les modes de défaillance.
Gestion des files d’attente
Suivi de la progression des files d’attente
La page de liste des annotations affiche une barre de progression pour chaque file d’attente indiquant le rapport entre les interactions examinées et le nombre total d’interactions. Utilisez ceci pour surveiller l’achèvement des annotations dans les files d’attente en un coup d’œil.
Gestion de l’accès aux files d’attente
Les propriétaires de files d’attente gèrent la liste des examinateurs, les paramètres d’accès et les attributions à partir des détails de la file d’attente. Seul le propriétaire de la file d’attente peut modifier la liste des examinateurs, les paramètres d’accès ou les attributions.
Les restrictions d’accès s’appliquent indépendamment, vous pouvez donc activer l’une ou l’autre restriction, ou les deux :
La restriction des examinateurs limite les interactions non attribuées aux examinateurs désignés.
La restriction des assignataires limite les interactions attribuées à leurs assignataires.
Lorsque les deux restrictions sont activées, les examinateurs peuvent annoter les interactions non assignées et les assignataires peuvent annoter les interactions qui leur sont assignées.
Le propriétaire de la file d’attente conserve l’accès et peut annoter toutes les interactions.
Filtrage des traces par étiquettes d’annotation
utilisez la facette Annotation Labels pour filtrer les traces par étiquettes appliquées dans les files d’attente d’annotation. Cela vous permet de :
Trouver toutes les traces marquées avec un mode de défaillance spécifique (par exemple, failure_type: hallucination)
Constituer des échantillons ciblés pour une révision ultérieure, la création de jeux de données ou l’exportation CSV pour l’analyse de données
Modification du schéma de file d’attente
Vous pouvez modifier le schéma d’étiquettes d’une file d’attente après sa création :
Le fichier se télécharge sous le nom annotations_<queue-id>.csv. Vous pouvez également récupérer les données de span par programmation en utilisant l’Export API.
Format CSV
Chaque ligne représente une interaction annotée. Le fichier commence par ces colonnes fixes :
Colonne
Description
Content ID
ID du contenu annoté (par exemple, un ID de trace ou un ID de session)
Type
Type d’interaction : trace, experiment_trace ou session
Input
Résumé de l’entrée (vide pour les interactions de session)
Output
Résumé de la sortie (vide pour les interactions de session)
Expected Output
Uniquement présent lorsque Include Expected Output est activé ; renseigné pour les traces d’expérience uniquement
Après les colonnes fixes, il y a un ensemble de colonnes par évaluateur par étiquette. Les évaluateurs sont triés par ordre alphabétique selon leur nom d’affichage (les espaces sont remplacés par des traits de soulignement). Les étiquettes suivent l’ordre défini dans le schéma de la file d’attente :
Colonne
Description
{reviewer}_{label}
Valeur de l’étiquette (chaîne, nombre, booléen ou tableau JSON)
{reviewer}_{label}_assessment
pass ou fail, si les critères d’évaluation sont activés pour cette étiquette
{reviewer}_{label}_reasoning
Raisonnement en texte libre, si le raisonnement est activé pour cette étiquette
Si un évaluateur n’a pas annoté une ligne donnée, ces cellules sont vides.
Exemple : une file d’attente avec les évaluateurs Alice Johnson et Bob Smith et les étiquettes quality (score) et failure_type (catégorielle) produit ces en-têtes de colonne :
Récupérez les spans par ID de trace ou ID de session
Après avoir exporté les données d’annotation, utilisez l’Export API pour récupérer les données complètes des spans des traces ou des sessions dans le CSV et joignez-les à vos étiquettes d’annotation.
From interaction : utilisez la sortie réelle de chaque trace. Pour les traces d’expérience, vous pouvez également choisir Expected output pour utiliser la sortie attendue originale du jeu de données source de l’expérience.
From annotation label : utilisez les valeurs appliquées par les annotateurs. Sélectionnez une ou plusieurs étiquettes. La expected_output de l’enregistrement est construite à partir de votre sélection.
Choisissez un jeu de données existant ou créez un jeu de données.
Lorsque la sortie attendue est construite à partir d’étiquettes d’annotation, la valeur exportée est un objet JSON indexé par nom d’étiquette, par exemple { "is_harmful": false, "tone": ["neutral"], "topics": ["safety", "policy"] }. Le même format s’applique, que vous sélectionniez une ou plusieurs étiquettes. Les étiquettes catégorielles sont toujours exportées sous forme de tableaux d’options sélectionnées, que l’étiquette soit à sélection unique ou multiple.
Comment les valeurs d’annotation sont agrégées entre les annotateurs
Lorsque plusieurs annotateurs ont annoté la même trace, la valeur de chaque étiquette est agrégée entre eux par consensus :
Type d’étiquette
Agrégation
Booléen
Vote majoritaire (les égalités sont tranchées en faveur de true)
Catégoriel
Intersection : l’ensemble trié des options que chaque annotateur a sélectionnées
Score
Moyenne
Texte
Liste des réponses
Pour les étiquettes catégorielles (sélection unique ou multiple), la valeur agrégée est le tableau trié des options que chaque annotateur a sélectionnées. Si la sélection d’un annotateur diffère, la valeur est un tableau vide. Le résultat est toujours un tableau, même lorsqu’un seul annotateur a annoté la trace.
Exemple : catégoriel (consensus). Trois annotateurs évaluent tone et sont tous d’accord :
Annotateur A : polite
Annotateur B : polite
Annotateur C : polite
Agrégé : ["polite"].
Exemple : catégoriel (désaccord). Trois annotateurs évaluent tone et l’un d’eux diffère :
Annotateur A : polite
Annotateur B : rude
Annotateur C : polite
Agrégé : []. L’intersection est vide car rude ne figure pas dans l’ensemble de chaque annotateur.
Exemple : catégoriel (sélection multiple). Trois annotateurs attribuent des tags à topics (chacun peut choisir plusieurs options) :
Annotateur A : ["safety", "policy"]
Annotateur B : ["safety", "billing"]
Annotateur C : ["safety", "policy"]
Agrégé : ["safety"]. Seul safety apparaît dans l’ensemble de chaque annotateur ; policy est absent de la sélection de B et billing est absent de celles de A et C.
Exemple : texte. Deux annotateurs laissent des notes :
Annotateur A : "Confusing phrasing"
Annotateur B : "Tone too casual"
Agrégé : ["Confusing phrasing", "Tone too casual"]. La valeur de chaque annotateur est conservée.
Les valeurs brutes par annotateur sont conservées dans les métadonnées de chaque enregistrement, ainsi que l’identité de l’annotateur. Si le consensus par défaut ne correspond pas à votre workflow, vous pouvez le recalculer avec une stratégie différente (par exemple, médiane, vote pondéré ou choix du réviseur).
Les étiquettes non sélectionnées comme sortie attendue sont également incluses avec chaque trace en tant que métadonnées.
Voir Jeux de données pour plus d’informations sur l’utilisation des jeux de données dans les expériences.
La suppression d'une file d'attente supprime la file d'attente et les associations d'étiquettes, mais ne supprime pas les traces sous-jacentes d'Agent Observability. Les traces restent accessibles dans Trace Explorer.
Utilisation de l’API
Vous pouvez gérer les files d’attente d’annotation par programmation. Les endpoints suivants sont disponibles dans la référence de l’API Agent Observability :
Créez une file d’attente d’annotation. name et project_id sont requis. Incluez un annotation_schema facultatif pour définir des étiquettes lors de la création.
Annotateursa: Chefs de produit, ingénieurs, experts du domaine
Validation des évaluations LLM-as-a-Judge
Trouvez les traces pour lesquelles les évaluateurs automatisés peuvent être incertains ou incorrects, puis demandez à des humains de fournir une vérité terrain.
Échantillonnez les résultats d’évaluation : tous les résultats, ou un score/seuil donné
Ajoutez les traces sélectionnées à une file d’attente d’annotation
Les annotateurs examinent les traces et fournissent des scores humains pour les mêmes critères
Comparez les étiquettes humaines aux scores d’évaluation automatisés
Identifiez les désaccords systématiques (juge trop strict, trop indulgent ou mauvaise compréhension des critères)
Affinez les prompts d’évaluation en fonction des désaccords
Configuration de la file d’attente
Étiquettes: Scores numériques correspondant aux critères d’évaluation (0-10), judge_accuracyétiquette catégorielle, notes de raisonnement
Annotateurs: Experts en la matière qui comprennent les critères d’évaluation
Création d’un jeu de données de référence
Construisez des jeux de données de référence avec des étiquettes vérifiées par des humains pour les tests de régression et la validation continue.
Échantillonnez diverses traces de production depuis Trace Explorer (exemples bons et mauvais)
Ajoutez des traces à la file d’attente d’annotation
Les annotateurs examinent et étiquettent les traces selon plusieurs dimensions de qualité
Ajoutez des exemples bien étiquetés et à haute confiance au jeu de données de référence
Utilisez le jeu de données pour les tests de régression CI/CD des modifications de prompts
Élargissez continuellement le jeu de données avec de nouveaux cas limites
Configuration de la file d’attente
Étiquettes: Plusieurs étiquettes catégorielles couvrant les dimensions de qualité, scores numériques, évaluation réussite/échec, notes
Annotateurs: Équipe d’experts du domaine pour la cohérence
Pour aller plus loin
Documentation, liens et articles supplémentaires utiles:
