03 Publier et détecter

Guide d'animation de la leçon 03 Publier et détecter.

Timing

~15 minutes au total.

• 3 min — distinguer évaluation opérationnelle et valeur pour l'utilisateur.
• 4 min — présenter le preflight et publier la configuration choisie avec policy-v1.
• 4 min — poser la question gouvernée dans Chat et recueillir un 👎.
• 4 min — retrouver la trace, vérifier les deux scores et reproduire avec curl.

Preflight la veille

Exécutez ceci avec le gagnant que la salle devrait choisir. La solution de repli vérifiée est qwen3.7-flash__P2_fewshot :

cd ClickHouse_Demos/workshops/agent_arena
source .env
export WINNER_CONFIG_ID="${WINNER_CONFIG_ID:-qwen3.7-flash__P2_fewshot}"
.venv/bin/python -m schema.gen_schema_context
.venv/bin/python -m scripts.check_online_eval_scenario \
  --config-id "$WINNER_CONFIG_ID"
.venv/bin/python -m scripts.provision_online_evaluators --operational

Le preflight effectue un seul nouvel essai limité lorsque le premier résultat d'une paraphrase est ok/unknown, uniquement pour cette même paraphrase et cette configuration. Tous les autres échecs sont définitifs et il ne réessaie jamais plus d'une fois.

Ne vous fiez pas à votre mémoire. Confirmez dans l'environnement réel de la salle que :

• stale_count et current_count sont présents et différents ;
• les trois classifications valent policy-v1 ;
• la dernière ligne indique que l'incident est reproductible ;
• l'evaluator sql-execution-success existe ; et
• la règle agent-arena-sql-execution-online est activée.

Pour Qwen, OpenRouter Settings → Privacy → Data Policies → Zero Data Retention → Non-frontier doit être désactivé afin que la route Alibaba soit éligible. Ne modifiez ce réglage qu'après avoir examiné les exigences de traitement des données de l'événement. Les participants ont besoin d'une clé d'exécution plafonnée, jamais de la clé de provisionnement du formateur.

Fil conducteur

• Commencez par le véritable gagnant du Module 02 et écrivez WINNER_CONFIG_ID à la vue de tous. Le cœur de l'agent et la configuration restent inchangés ; seul le contexte de politique publié accuse volontairement une version de retard.

• Nommez la limite de l'evaluator avant d'afficher un résultat : sql-execution-success peut prouver que ClickHouse a accepté le SQL, pas qu'il applique la définition actuelle d'une métrique gouvernée.

• Posez la question dans Chat, montrez le SQL généré, le résultat et policy_version=policy-v1, puis cliquez sur 👎 et attendez feedback sent. Cette trace racine de Chat est l'unique incident de référence.

• Affichez côte à côte la définition actuelle :

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

• Dites clairement que le SQL fondé sur les inscriptions est valide au regard de la policy-v1 obsolète fournie au modèle. Il s'agit d'un échec de publication ou de processus et d'un angle mort de l'evaluator, pas d'un modèle qui aurait ignoré des instructions explicites.

• Dans Langfuse, filtrez sur user-thumbs = false, ouvrez le dernier chat_turn Chat correspondant et montrez sql-execution-success=true à côté de user-thumbs=false. Ce signal priorise une enquête ; il ne fournit pas le diagnostic et ne devient pas à lui seul une vérité de référence.

• Exécutez ensuite la reproduction curl obligatoire comme diagnostic non noté. Nommez son identifiant CURL_TRACE_ID, vérifiez uniquement sql-execution-success=true et n'envoyez jamais de feedback pour cette trace ni ne l'utilisez comme transmission au Module 04.

• Notez l'ID ou l'URL de la trace racine et les deux décomptes pour le Module 04. Conservez les identifiants réels dans le projet Langfuse et la feuille de l'atelier.

Preuves attendues dans la trace

Ouvrez l'observation racine chat_turn, pas seulement son enfant llm_call. Attendez-vous à :

Le code du service appelle ce champ policy_version ; l'adaptateur OpenTelemetry nettoie les clés pour ne conserver que des caractères alphanumériques, si bien que Langfuse affiche la clé émise sous la forme policyversion.

L'evaluator opérationnel est asynchrone. Utilisez le vérificateur au lieu de considérer comme un échec un score qui n'est pas encore apparu :

.venv/bin/python -m scripts.verify_online_scores "$CHAT_TRACE_ID" \
  sql-execution-success=true user-thumbs=false

Problèmes fréquents

• Fournisseur bloqué par le ZDR — Qwen échoue avant de produire du SQL lorsque l'exigence Zero Data Retention pour non-frontier est activée et que la route Alibaba éligible est refusée. Désactivez cette restriction pour l'atelier ou utilisez la solution de repli déclarée après examen des exigences de confidentialité.
• Dispatcher de l'evaluator arrêté — la trace arrive, mais sql-execution-success n'apparaît jamais. Confirmez que le service ou dispatcher d'exécution des evaluators Langfuse fonctionne et que la règle agent-arena-sql-execution-online est activée ; provisionner une règle ne produit aucun score si les workers sont indisponibles.
• Dépendances OpenTelemetry absentes — aucune trace n'apparaît alors que /ask répond. Réinstallez les dépendances figées avec .venv/bin/python -m pip install -r requirements.txt ; le runtime suit le chemin OpenTelemetry de Langfuse v4 et nécessite des packages OTel compatibles.
• Ancien processus serveur — la réponse indique policy-v2 alors que la commande du shell précise policy-v1. Un processus plus ancien occupe encore le port 8100 ; arrêtez-le complètement avant de démarrer la version préparée.
• Mauvais port — l'interface Chat utilise par défaut http://localhost:8100. Si le service emploie un autre port, définissez VITE_SERVING_BASE sur la même adresse ou lancez le curl brut vers le port réel.
• Feedback en double — le feedback utilise l'ID de score déterministe user-thumbs-<trace_id>. Envoyez une seule note par trace. Réutiliser la même trace pour des notes contradictoires peut provoquer une erreur du service ou une démonstration ambiguë ; créez plutôt une nouvelle session et une nouvelle trace.
• Score encore en attente — l'évaluation est asynchrone. Laissez scripts.verify_online_scores interroger le score avant de modifier la configuration.
• Décomptes de référence identiques — le contraste préparé est absent de cet instantané. N'inventez pas un échec ; réinitialisez ou diagnostiquez les données avant la session.

Procédures de reprise

Arrêtez tout serveur existant, puis démarrez un processus propre avec policy-v1 :

scripts/arena.sh stop
scripts/arena.sh serve
source .env
.venv/bin/python -m schema.gen_schema_context
AGENT_ARENA_POLICY_VERSION=policy-v1 \
  .venv/bin/uvicorn serving.api:app --port 8100

scripts/arena.sh serve restaure le dashboard et l'interface web en arrière-plan avant que l'API de service n'occupe le terminal. Actualisez la page Chat pour créer une nouvelle session. Si vous utilisez l'API brute, transmettez un nouvel ID de session ou omettez-le afin que /ask en crée un automatiquement. Relancez le preflight et le provisionneur dans un second terminal ; les deux sont répétables sans risque.

Politique de repli

Utilisez la configuration éprouvée du formateur qwen3.7-flash__P2_fewshot uniquement si le gagnant de la salle ne suit plus la politique obsolète explicite lors du preflight à trois questions. Annoncez la substitution : la solution de repli préserve un incident pédagogique déterministe, tandis que le gagnant du leaderboard reste le résultat mesuré de la salle. Ne changez pas silencieusement de modèle et n'utilisez pas ce repli pour masquer des décomptes identiques, des problèmes d'identifiants, de routage fournisseur ou d'infrastructure d'évaluation.

Transmission au Module 04

Avant de poursuivre, confirmez que la feuille contient l'ID ou l'URL de la racine Chat de référence, le décompte obsolète, le décompte actuel, sql-execution-success=true et le Boolean user-thumbs=false. Le Module 04 part de ce désaccord précis et y ajoute le jugement humain ; il ne doit pas commencer par un diagnostic préécrit détaché de la trace de production.