05 Boucler la boucle

Guide d'animation de la leçon 05 Boucler la boucle.

Timing

~25 minutes au total.

• 5 min — créer et promouvoir les trois enregistrements issus de la production.
• 5 min — lancer les expériences appariées policy-v1 et policy-v2.
• 5 min — comparer la correction et calibrer business-policy-adherence.
• 5 min — activer la règle protégée d'observation et rejouer quatre types de métriques.
• 5 min — examiner les preuves et discuter du rollback, du coût et de la prochaine boucle de feedback.

Les deux expériences et les evaluators asynchrones peuvent dépasser ces créneaux. Lancez-les rapidement, profitez de l'attente pour le fil conducteur conceptuel et répétez la latence du fournisseur la veille.

Preflight du formateur

Exécutez depuis la racine du laboratoire ces commandes de vérification non mutantes et assurez-vous avant la session que la configuration sélectionnée existe :

cd ClickHouse_Demos/workshops/agent_arena
.venv/bin/python -m scripts.promote_to_golden --help
.venv/bin/python -m scripts.provision_online_evaluators --help
.venv/bin/python -m eval.harness --help
.venv/bin/python -m scripts.verify_online_scores --help

Confirmez ensuite que :

• le Module 03 possède une unique racine chat_turn de référence avec sql-execution-success=true et le Boolean user-thumbs=false ;
• la tâche production-investigation-<session> du Module 04, réalisée uniquement dans l'interface, est terminée, son SQL corrigé a été exécuté, son véritable ID de trace est disponible en privé et l'ID de la tâche a été consigné lorsque Langfuse l'expose ;
• reviewed.json sera créé à partir de cette revue authentique et ne correspond pas au fixture synthétique suivi dans le dépôt ;
• WINNER_MODEL, WINNER_PROMPT et WINNER_CONFIG_ID décrivent tous le même gagnant de la salle ;
• la connexion LLM Langfuse agent-arena-openrouter peut atteindre son modèle juge et dispose d'identifiants valides ;
• la sortie catégorielle structurée du juge accepte exactement PASS, FAIL et NOT_APPLICABLE, avec un raisonnement ; et
• le dispatcher de l'evaluator est opérationnel et la salle peut recevoir des scores asynchrones.

Pour chaque répétition, créez un suffixe unique et conservez ensemble la paire référence/candidat :

export LOOP_RUN_SUFFIX="$(date +%Y%m%d-%H%M%S)"
export BASELINE_RUN_ID="online-loop-baseline-${LOOP_RUN_SUFFIX}"
export CANDIDATE_RUN_ID="online-loop-candidate-${LOOP_RUN_SUFFIX}"

Ne réutilisez pas les ID d'une session antérieure. Le harness ajoute la version de politique et la configuration ; un ID de base unique évite aux participants de comparer des preuves sans rapport ou partiellement écrasées.

Limite de l'annotation manuelle

L'annotation humaine du Module 04 n'est volontairement pas automatisée. Les scripts d'exécution ne créent pas la file, ne remplissent pas les jugements humains, ne saisissent pas la sortie corrigée, n'approuvent pas l'élément et ne terminent pas la tâche. Un fixture synthétique suivi est utile lors d'une répétition sans revue réelle, mais il reste source=synthetic-reviewed-fixture et ne prouve pas qu'une boucle d'annotation humaine a été menée à son terme.

Pour le parcours participant, utilisez le véritable fichier ignoré reviewed.json. La formulation originale est une vraie question issue du feedback. Les deux autres entrées exactes sont des paraphrases rédigées par le relecteur à partir de cet incident :

How many active customers do we have?
What is our active customer count right now?
How many customers qualify as active under our business definition?

Les trois conservent la même trace source réelle et la même provenance d'annotation. Dites-le clairement afin que les participants ne prennent pas un seul incident de production pour trois traces de feedback indépendantes.

Fiabilité et provenance de la promotion

Avant la promotion, inspectez reviewed.json sans le projeter. Il doit contenir le SQL corrigé exact en lecture seule, la provenance de production requise et trois ID uniques et sûrs. La promotion valide d'abord tout le lot local, puis effectue une lecture authentifiée des métadonnées avant toute exécution ClickHouse ou mise à jour du dataset. Elle échoue de façon fermée si les métadonnées ne peuvent pas être lues et refuse un ID en collision avec une provenance de production authentique différente.

Une promotion authentique identique est idempotente. Un fixture synthétique exige le flag explicite --synthetic-fixture ; il ne peut pas être fourni comme chemin direct ni combiné avec reviewed.json. Ne l'exécutez jamais après une promotion réelle. En cas de collision, préservez les deux sources, examinez l'élément existant et choisissez un nouvel ID audité seulement si les éléments représentent réellement des cas revus distincts.

Règle d'expérience et règle d'observation

Gardez ces deux contextes visibles sur une diapositive ou au tableau :

Le provisionneur installe un evaluator général piloté par catalogue, pas un evaluator limité au décompte des clients. Son catalogue policy-v2 couvre les clients actifs, le chiffre d'affaires, la conversion vue-achat et la marge brute ; les questions sans rapport doivent recevoir NOT_APPLICABLE.

La phase --business-policy-experiments doit signaler online rule enabled=False. Vérifiez aussi l'interface des règles Langfuse comme second garde-fou. La commande d'activation ultérieure prouve qu'au moins un score business-policy-adherence limité au dataset existe, mais ne remplace pas la revue complète de calibration du formateur.

Portes de calibration

Comparez référence et candidat sur les mêmes ID d'éléments, modèle et prompt. Le dépôt contient 20 questions YAML, mais q019 et q020 sont des exemples few-shot réservés ; un projet propre démarre donc avec 18 éléments d'expérience et atteint 21 après les trois promotions. Le projet partagé réutilisé qui a été vérifié comptait 22 éléments uniquement parce qu'un ancien élément approuvé sans rapport subsistait ; sa nouvelle exécution appariée est passée de 16/22 à 19/22. Considérez cela comme une preuve qualifiée de vérification, pas comme le nombre exigé des participants ni comme la promesse que les fournisseurs stochastiques reproduiront exactement chaque agrégat.

N'activez rien tant que toutes les portes ne sont pas franchies :

• les trois cas prod-active-* passent de FAIL et incorrects sous policy-v1 à PASS et corrects sous policy-v2 ;
• le chiffre d'affaires (q005) et la conversion (q018) du candidat sont PASS ;
• un simple décompte (q001) est NOT_APPLICABLE ;
• la correctness de chaque élément préexistant est comparée individuellement et aucune régression 1→0 n'apparaît ;
• la correction agrégée ne régresse pas ; et
• chaque élément d'expérience possède correctness, agent-arena-llm-judge et le score exact business-policy-adherence avec une sortie structurée valide.

Un juge qui attribue PASS à tous les décomptes a échoué à la calibration, même si le candidat semble bon. Utilisez la sonde NOT_APPLICABLE pour montrer que déterminer l'applicabilité d'une politique constitue une véritable étape de classification.

Scores asynchrones et dépannage des scores absents

Les évaluations d'expériences et d'observations sont asynchrones. Le harness attend les scores requis des expériences, tandis que scripts.verify_online_scores interroge les scores de traces en direct pendant 180 secondes par défaut. N'actualisez pas frénétiquement, ne recréez pas les règles et ne les activez pas trop tôt sous prétexte qu'un score est en attente.

Si les scores n'apparaissent pas :

1. Confirmez le nom exact attendu. Les expériences utilisent business-policy-adherence ; les observations du service utilisent agent-arena-business-policy-online.
2. Confirmez que le dispatcher ou worker d'exécution de l'evaluator fonctionne.
3. Vérifiez la connexion agent-arena-openrouter et la disponibilité du modèle juge. Un retard du fournisseur, une limite de débit ou une restriction de routage peut laisser l'évaluation en attente ou en échec alors que la réponse de l'agent a réussi.
4. Vérifiez que la règle d'expérience cible le dataset arena-golden et que la règle d'observation cible les observations racines chat_turn. Le mapping doit exposer $.question et $.sql.
5. Inspectez la sortie structurée. Une catégorie absente, extérieure aux trois valeurs permises ou dépourvue de raisonnement constitue un échec de calibration.
6. Si le provisionnement signale un nom de règle ambigu, arrêtez-vous et résolvez les doublons exacts dans Langfuse avant de réessayer ; ne devinez pas lequel a été mis à jour.

Préservez les traces en échec et les preuves de l'evaluator. Ne transformez pas une indisponibilité du fournisseur en PASS inventé et ne sautez pas la porte des scores manquants.

Guide de replay

Après activation, redémarrez explicitement le service avec policy-v2 et utilisez exactement les quatre questions du participant :

How many active customers do we have?
What was revenue in the last 30 days?
What is our view-to-purchase conversion rate for the last 7 days?
How many products are there?

Exigez la réussite opérationnelle de chaque trace. Les clients actifs, le chiffre d'affaires et la conversion doivent avoir agent-arena-business-policy-online=PASS ; le décompte des produits doit être NOT_APPLICABLE.

La demande de conversion présente une limite stochastique vérifiée. Autorisez au maximum un nouvel essai avec la même configuration, conservez les deux ID de trace et résultats, puis arrêtez si aucun ne réussit. Un échec répété est une nouvelle preuve de production à examiner, pas une raison de boucler jusqu'au vert.

Échantillonnage, coût et fiabilité

Les règles de l'atelier utilisent un échantillonnage de 1 afin que chaque trace éligible produise une preuve visible. En production, un juge LLM sur chaque requête ajoute un coût fournisseur, consomme la limite de débit et peut rendre ses scores après la réponse utilisateur. Choisissez l'échantillonnage selon le trafic, le risque d'incident, le coût et la latence de l'evaluator, ainsi que la couverture requise. Gardez larges les contrôles opérationnels déterministes ; réservez le jugement sémantique coûteux au trafic et aux métriques pour lesquels il est rentable.

L'evaluator sert à la surveillance, pas à l'autorisation dans le chemin de requête. Un juge retardé ne doit pas bloquer silencieusement la réponse du service. Acheminez les scores absents, les dérives de catégories et les désaccords entre signaux vers des alertes opérationnelles ou un backlog de revue selon les objectifs de niveau de service du système.

Rollback et réinitialisation

Si le juge d'observation produit de faux succès, de faux échecs, une sortie mal formée ou un coût ou une latence inacceptable après activation :

1. Ouvrez Evaluations dans Langfuse, trouvez la règle d'observation exacte agent-arena-business-policy-online et basculez-la sur disabled.
2. Confirmez que les nouvelles observations chat_turn ne reçoivent plus le score de cette règle en ligne.
3. Gardez policy-v2, sql-execution-success et 👍/👎 actifs sauf si leurs propres preuves indiquent le contraire ; désactiver un juge défaillant ne doit pas réintroduire la politique obsolète connue.
4. Ajoutez les traces touchées à une file d'annotation humaine suffixée, améliorez le catalogue ou prompt de l'evaluator et les données dorées, puis répétez la calibration appariée avant de le réactiver.

Pour arrêter les services locaux sans supprimer les preuves distantes :

scripts/arena.sh stop

scripts/arena.sh down supprime aussi la base ClickHouse de l'atelier et l'utilisateur en lecture seule, mais pas les datasets, expériences, files d'annotation ou scores Langfuse. Ne l'utilisez pas pour annuler un evaluator.

Fil conducteur : la boucle reste ouverte

• L'evaluator initial a réussi parce que son contrat se limitait à « le SQL s'est exécuté ». Le 👎 de l'utilisateur a révélé un échec de valeur hors de ce contrat.
• La revue humaine a transformé un signal incertain en diagnostic et correction testés.
• La provenance de production a rendu l'incident auditable lors de son entrée dans le jeu doré ; les paraphrases ont élargi la couverture de formulation sans inventer de traces utilisateur supplémentaires.
• Les expériences appariées ont isolé le changement de politique d'un changement de modèle ou de prompt et testé le juge général avant la production.
• Un PASS en ligne ne rend pas le feedback obsolète. Un futur agent-arena-business-policy-online=PASS accompagné de user-thumbs=false est précisément le type de désaccord qui doit relancer l'enquête.

Porte de finalisation

Ne terminez pas le module avant que la salle puisse montrer les six artefacts :

1. la trace de production avec réussite opérationnelle et signal utilisateur négatif ;
2. l'annotation humaine terminée et le SQL corrigé vérifié ;
3. trois éléments dorés avec une provenance de production authentique ;
4. des preuves référence/candidat sur le même dataset sans régression de correction existante ;
5. des preuves d'expérience calibrées pour FAIL, PASS et NOT_APPLICABLE ; et
6. des scores en direct activés pour les clients actifs, le chiffre d'affaires, la conversion et un décompte simple, tandis que 👍/👎 reste disponible pour la prochaine boucle.