03 リリースして検知する

受講者レッスン 03 リリースして検知する の ファシリテーター向け手引きです。

タイミング

合計 ~15 分。

• 3 min — 運用評価とユーザー価値の対比を枠付けする。
• 4 min — プリフライトを見せ、教室が選んだ構成を policy-v1 でリリースする。
• 4 min — 統制された質問を Chat で尋ね、その回答に 👎 を集める。
• 4 min — その Chat trace を特定し、両方の score を検証し、curl で再現する。

前日のプリフライト

教室が選ぶと想定している勝者そのもので、これを実行してください。検証済みのフォールバックは 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

プリフライトが限定的な再試行を 1 回だけ行うのは、ある言い換えの最初の結果が ok/unknown だった場合に限ります。再試行するのも、その同じ言い換えと構成だけです。 それ以外の失敗はすべて最終結果として扱われ、どの言い換えも 1 回を超えて再試行されません。

記憶に頼って先に進まないでください。教室の実際の環境で、以下のすべてを確認します:

• stale_count と current_count の両方が存在し、かつ異なっている;
• 3 つの分類すべてが policy-v1 である;
• 最後の行がインシデントが再現可能だと言っている;
• evaluator sql-execution-success が存在する; そして
• ルール agent-arena-sql-execution-online が有効になっている。

Qwen では、Alibaba のルートが対象になるように、OpenRouter の Settings → Privacy → Data Policies → Zero Data Retention → Non-frontier を無効にしておく必要があります。この変更は、 イベントにおけるデータ取り扱いの要件を確認したうえでのみ行ってください。受講者に必要なのは 上限付きのランタイムキーであり、講師のプロビジョニング用キーは決して渡さないでください。

トークトラック

• 教室の実際の Module 02 勝者から始め、WINNER_CONFIG_ID を全員に見える場所に書いてください。 エージェントのコアと選ばれた構成は変わっていません。デプロイされたビジネスポリシーの文脈だけが 意図的に 1 バージョン遅れています。

• 結果を見せる前に evaluator の境界を名指ししてください。sql-execution-success が証明できるのは ClickHouse が SQL を受け付けたことであって、その SQL が統制された指標の今日の意味を実装して いることではありません。

• Chat で尋ね、生成された SQL、結果、policy_version=policy-v1 を見せ、そのうえで 👎 を クリックして feedback sent を待ちます。この Chat のルート trace が唯一の正典となる インシデントです。

• 現在の定義を並べて聴衆に見せてください:

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

• 生成されたサインアップベースの SQL は、モデルに与えられた古い policy-v1 の下では妥当だと 明言してください。これはリリース／プロセスの失敗であり evaluator の盲点であって、モデルが 明確な指示を無視したという主張ではありません。

• Langfuse で user-thumbs = false でフィルタし、一致する最も新しい Chat の chat_turn を開き、 sql-execution-success=true の隣に user-thumbs=false があることを見せます。このシグナルは 調査の優先度を上げるだけです。それ自体が診断を与えたり正解データになったりはしません。

• そのあとで、必須の curl 再現を評価を付けない診断として実行します。その識別子を CURL_TRACE_ID と名付け、sql-execution-success=true だけを検証し、それに対して フィードバックを POST したり Module 04 への引き渡しに使ったりは決してしないでください。

• Module 04 のためにルート trace の ID／URL と両方のカウントを記録します。生きた識別子は Langfuse プロジェクトとワークショップのワークシートの中に留めてください。

期待される trace のエビデンス

子の llm_call だけでなく、ルートの chat_turn observation を開いてください。期待するのは:

serving のソースはこのフィールドを policy_version と名付けます。OpenTelemetry のアダプターが メタデータのキーを英数字にサニタイズするため、Langfuse は送出されたキーを policyversion として 表示します。

運用 evaluator は非同期です。まだ現れていない score を失敗とみなすのではなく、検証ツールを 使ってください:

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

よくある失敗

• ZDR によってプロバイダーがブロックされる — OpenRouter の non-frontier な Zero Data Retention の要件が有効で、対象となる Alibaba のルートが許可されていないと、Qwen は SQL を 生成する前に失敗します。このワークショップではその ZDR 制限を無効にするか、プライバシー要件を 確認したうえで開示済みのフォールバックを使ってください。
• evaluator のディスパッチャーが動いていない — trace は届くのに sql-execution-success が現れません。Langfuse の evaluator 実行サービス／ディスパッチャーが 健全で、agent-arena-sql-execution-online ルールが有効になっていることを確認してください。 評価のワーカーが使えない状態では、ルールをプロビジョニングしても score は処理されません。
• OpenTelemetry の依存関係が欠けている — /ask が返るのに trace が現れません。 .venv/bin/python -m pip install -r requirements.txt でラボのピン留めされた requirements を 再インストールしてください。ランタイムは Langfuse v4 の OpenTelemetry 経路を使い、互換の OTel パッケージを必要とします。
• 古いサーバープロセス — シェルのコマンドは policy-v1 と言っているのにレスポンスは policy-v2 を報告します。古いプロセスがまだポート 8100 を掴んでいます。仕込まれたリリースを 起動する前に、それを完全に停止してください。
• ポートの間違い — Chat UI は既定で http://localhost:8100 を使います。serving が別の ポートを使う場合は VITE_SERVING_BASE を同じアドレスに設定するか、実際のポートに対して 素の curl を使ってください。
• フィードバックの重複 — フィードバックは決定論的な score ID user-thumbs-<trace_id> を 使います。1 つの trace につき評価は 1 回だけ送ってください。同じ trace を相反する評価に 使い回すと、フィードバックサービスのエラーが返るか、曖昧なデモが残ります。代わりに新しい セッション／trace を作ってください。
• score がまだ pending — 評価は非同期です。構成を変える前に scripts.verify_online_scores に score をポーリングさせてください。
• 参照カウントが一致してしまう — このデータスナップショットには仕込まれたコントラストが ありません。失敗を作り出さないでください。セッションの前に再シードするか、データを診断して ください。

リセット手順

既存のサーバーを止め、そのうえでクリーンな 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 は、serving API がターミナルを占有する前に、ダッシュボードと Web UI を バックグラウンドで復帰させます。新しいセッションを作るには Chat のページを再読み込みして ください。素の API を使う場合は、新しいセッション ID を渡すか、/ask が自動的に作れるように 省略してください。プリフライトとプロビジョナーは 2 つ目のターミナルで再実行します。どちらも 繰り返して安全です。

フォールバックの方針

講師の既知の良好な qwen3.7-flash__P2_fewshot 構成を使うのは、3 問のプリフライトで教室の勝者が もう明示的な古いポリシーに従わなくなった場合だけにしてください。差し替えたことは口に出して 述べてください。フォールバックは決定論的な教育用インシデントを保つためのもので、リーダーボードの 勝者は教室が測った結果のままです。黙ってモデルを入れ替えないでください。また、カウントが等しい 問題、認証情報の問題、プロバイダーのルーティングの問題、evaluator のインフラの問題を隠すために フォールバックを使わないでください。

Module 04 への引き渡し

先に進む前に、ワークシートに正典となる Chat のルート trace の ID／URL、古いカウント、現在の カウント、sql-execution-success=true、そして Boolean の user-thumbs=false が含まれていることを 確認してください。Module 04 はまさにその食い違いから始まり、人の判断を加えます。本番の trace から 切り離された、あらかじめ書かれた診断から始めてはいけません。