04 Enquêter

Guide d'animation de la leçon 04 Enquêter.

Timing

~20 minutes au total.

• 3 min — filtrer le feedback négatif et vérifier la racine Chat de référence.
• 4 min — créer les trois configurations de score, puis la file avec ses associations fixes.
• 4 min — coder ouvertement les comportements observables avant de discuter d'un diagnostic.
• 5 min — examiner les preuves de la trace et exécuter côte à côte les SQL policy-v1 et policy-v2.
• 4 min — saisir la correction, approuver, terminer et consigner la provenance.

Preflight du formateur

Avant l'arrivée des participants, confirmez que le Module 03 a produit l'unique chat_turn de référence avec le Boolean user-thumbs=false et sql-execution-success=true. Gardez son ID de trace privé et vérifiez que la sortie racine contient la question, le SQL généré, les lignes renvoyées et le résultat.

Créez les trois configurations de score dans un projet de test jetable si vous devez répéter l'exercice, mais ne précréez pas la file finale des participants. L'ensemble d'ID de configurations associé à une file est figé lors de sa création ; la salle doit donc commencer par créer les configurations et les associer toutes les trois :

Cet exercice d'annotation s'effectue uniquement dans l'interface. Les scripts d'exécution peuvent vérifier les scores de traces et promouvoir plus tard un export revu, mais ils ne créent pas la file, ne rédigent pas les jugements humains et ne terminent pas la tâche d'annotation.

Fil conducteur

1. Filtrez Tracing sur user-thumbs = false et faites correspondre l'ID à celui de la feuille du Module 03. Dites : « Le feedback décide de ce que nous allons enquêter, pas de ce que nous allons conclure. »

2. Utilisez Settings → Scores → Create pour chaque configuration. Allez ensuite dans Annotations → Queues → Create, nommez la file production-investigation-<session> avec un suffixe de session unique et associez les trois configurations.

3. Sélectionnez l'observation racine chat_turn, ouvrez son menu Annotate et choisissez la nouvelle file. Montrez l'enfant llm_call, mais expliquez pourquoi il constitue une mauvaise cible : il ne contient pas le résultat d'exécution structuré de bout en bout et ne représente pas l'incident logique signalé par le feedback.

4. Rappelez que le Module 03 a dévoilé le scénario préparé, puis demandez aux participants de mettre ce savoir préalable entre parenthèses et de pratiquer un codage ouvert de ce qui est observable. Une bonne première note serait :

   The SQL executed and returned a count. The observed count differs from the second
   reference count. The query uses a 90-day customer signup window, and the trace
   metadata reports policy-v1.

5. Une fois seulement cette note consignée, révélez toutes les preuves : les métadonnées émises policyversion=policy-v1, le SQL fondé sur les inscriptions et son résultat, ainsi que les deux scores. Le champ source est policy_version ; l'adaptateur OpenTelemetry émet dans Langfuse la clé nettoyée policyversion.

6. Exécutez les deux définitions de politique côte à côte. La référence policy-v1 est :

   SELECT count() FROM v_customers
   WHERE signup_date >= today() - INTERVAL 90 DAY

   La référence de la politique actuelle policy-v2 est :

   SELECT uniqExact(customer_id) FROM v_orders
   WHERE order_ts >= now() - INTERVAL 30 DAY
   AND status NOT IN ('cancelled', 'returned')

7. Après cette comparaison seulement, posez le diagnostic : enregistrez failure-category=stale-business-policy, basculez Corrected Output en plain-text mode et collez la requête actuelle brute. Langfuse n'exécute pas le SQL ; vérifiez donc le texte exact avec le client en lecture seule de l'étape 6 avant de définir approved-for-golden=true et de terminer la tâche.

8. Conservez source_trace_id, failure_category, source_policy_version, la correction et, facultativement, l'ID de la tâche d'annotation pour le Module 05.

Trois diagnostics tentants mais erronés

• « Le modèle a ignoré le prompt. » Le SQL de la trace suit le contexte explicite policy-v1. L'échec tient à la politique obsolète publiée, pas à une désobéissance aux instructions fournies.
• « sql-execution-success est cassé. » Le SQL s'est exécuté ; l'evaluator opérationnel a donc correctement renvoyé true. Sa conception ne teste pas le sens métier gouverné.
• « Un pouce vers le bas prouve que le SQL est faux. » Le feedback désigne une trace à examiner. Il ne désambiguïse pas l'intention de l'utilisateur et ne fournit pas une requête de remplacement vérifiée ; la comparaison des politiques et la revue humaine s'en chargent.

Gardez ces possibilités visibles jusqu'à ce que les participants aient codé ouvertement la trace. Le formateur connaît la réponse préparée, mais l'enquête doit tout de même modéliser une véritable revue fondée d'abord sur les preuves.

Ciblage de l'observation racine

La trace contient deux observations pertinentes :

Si un participant ajoute l'enfant par erreur, ne le terminez pas comme enquête de production. Ajoutez la racine chat_turn à la bonne file et conservez ou supprimez la tâche erronée selon la politique de rétention du projet. Enregistrez l'ID de trace, pas l'ID de l'observation enfant, comme source_trace_id.

Associations fixes de la file et noms résistants aux reprises

Langfuse fige lors de la création d'une file l'ensemble d'ID de configurations de score associés. Une configuration omise ne peut pas être ajoutée plus tard ; le plus sûr est donc de toutes les créer d'abord. Les configurations elles-mêmes restent modifiables : tout changement pris en charge de nom, de schéma ou de valeurs catégorielles exige une mise à jour auditée et ne réécrit pas les scores existants.

Utilisez un suffixe sûr pour les reprises, par exemple :

production-investigation-<session>-retry-1

Si la file a omis une configuration ou associé un mauvais ID, créez une nouvelle file suffixée avec les trois bons ID, ajoutez à nouveau la racine de référence et marquez clairement l'ancienne file comme remplacée (ou supprimez-la uniquement si la politique du projet le permet). Pour modifier de façon prise en charge une configuration déjà associée, utilisez la mise à jour auditée plutôt que de recréer la file. Ne réutilisez jamais le nom d'une file terminée d'une manière qui masquerait la tâche à l'origine de la décision.

Fiabilité de la sortie corrigée

La correction deviendra une vérité de référence dorée ; syntaxe et politique comptent donc toutes deux. Basculez Corrected Output en plain-text mode avant de coller le SQL brut. Langfuse stocke le texte mais ne l'exécute pas ; avant approbation, exécutez ce texte exact avec le client ClickHouse en lecture seule de l'étape 6. Une requête qui semble correcte mais est mal formée, référence des tables brutes, contient plusieurs instructions ou échoue dans ClickHouse doit rester non approuvée.

Pour un SQL mal formé :

1. définissez ou laissez approved-for-golden=false ;
2. ne terminez pas la tâche comme approuvée ;
3. corrigez la requête pour utiliser les vues v_* autorisées ;
4. réexécutez-la et inspectez le résultat ; et
5. n'approuvez et ne terminez qu'après vérification.

Si quelqu'un a terminé une correction mal formée, créez un nouveau suffixe de file et de tâche, puis refaites la revue au lieu d'effacer silencieusement la piste d'audit. La commande de promotion du Module 05 valide et exécute également le SQL en lecture seule, mais ce garde-fou ne remplace pas la revue humaine.

Problèmes fréquents

• Aucune trace après filtrage — confirmez que le score est de type Boolean et que le filtre est user-thumbs=false ; ne recherchez pas un ancien nom de score. Faites correspondre l'ID de la feuille au lieu de sélectionner le diagnostic curl non noté.
• Mauvaise cible — la tâche ne montre que la transcription et le SQL parce que llm_call a été ajouté. Revenez à la trace et ajoutez la racine chat_turn.
• Dimension manquante dans la file — la file a été créée sans l'ID d'une configuration requise. Créez une nouvelle file suffixée ; ne poursuivez pas avec un formulaire de revue incomplet. Pour une modification prise en charge d'une configuration déjà associée, utilisez une mise à jour auditée et non une recréation de file.
• Métadonnées de politique apparemment absentes — recherchez la clé émise policyversion, pas le champ source policy_version, puis confirmez le tag policy-v1 de la racine.
• Décomptes identiques contre toute attente — arrêtez le diagnostic. Relancez le preflight du Module 03 et n'inventez pas de preuves à partir d'un instantané de données sans contraste.
• Correction formatée au lieu d'un SQL brut — basculez Corrected Output en plain-text mode et collez uniquement la requête.
• Correction non exécutable — Langfuse ne le détectera pas. Laissez l'approbation à false, corrigez-la et réexécutez le texte exact avec le client de l'étape 6 avant de terminer la tâche.

Finalisation et transmission

Avant le Module 05, vérifiez que la tâche terminée vise le chat_turn de référence, que l'observation a été consignée avant le diagnostic, que la correction est le SQL exact de la politique actuelle et que la tâche est approuvée. La feuille doit contenir :

source=production-feedback
source_trace_id=<authoritative Chat trace ID>
failure_category=stale-business-policy
source_policy_version=policy-v1
annotation_id=<task ID when available>

Le score utilisateur négatif reste sur la trace de production comme signal de triage. L'annotation humaine fournit la vérité de référence revue. Le Module 05 préservera les deux origines lorsqu'il promouvra la correction et créera un evaluator préventif.