05 ループを閉じる

受講者レッスン 05 ループを閉じる の ファシリテーター向け手引きです。

タイミング

合計 ~25 分。

• 5 min — 本番由来の 3 レコードを組み立てて昇格する。
• 5 min — 対になった policy-v1 と policy-v2 の experiment を起動する。
• 5 min — correctness を比較し、business-policy-adherence を校正する。
• 5 min — ガード付きの observation ルールを有効化し、4 種類の指標をリプレイする。
• 5 min — エビデンスを確認し、ロールバック、コスト、次のフィードバックループを議論する。

2 つの experiment と非同期の evaluator は、これらのファシリテーションのブロックより長くかかる ことがあります。run は早めに開始し、待ち時間を概念的なトークトラックに使い、プロバイダーの レイテンシは前日に下稽古しておいてください。

講師のプリフライト

これらの変更を伴わないコマンド確認をラボのルートから実行し、セッション前に選ばれた構成が 存在することを検証してください:

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

そのうえで次を確認します:

• Module 03 が sql-execution-success=true と Boolean の user-thumbs=false を持つ正典となる ルート chat_turn を 1 つ持っている;
• Module 04 の UI だけで行う production-investigation-<session> タスクが完了し、その修正済み SQL が 実行され、その実際の trace ID が非公開に利用でき、Langfuse がそれを見せている場合は annotation タスクの ID も記録されている;
• reviewed.json がその本物のレビューから作られる予定であり、git 管理された合成のフィクスチャでは ない;
• WINNER_MODEL、WINNER_PROMPT、WINNER_CONFIG_ID がすべて同じ教室の勝者を指している;
• Langfuse の LLM connection agent-arena-openrouter が設定された judge モデルに到達でき、有効な 認証情報を持っている;
• judge の構造化されたカテゴリ出力が、理由付けとともに PASS、FAIL、NOT_APPLICABLE を ちょうど受け付ける; そして
• evaluator のディスパッチャーが健全で、教室が非同期の score を受け取れる。

下稽古のたびに一意なサフィックスを 1 つ作り、ベースラインと候補のペアをまとめて保ってください:

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}"

前のセッションの run ID を使い回さないでください。ハーネスはポリシーのバージョンと構成を 付け足すので、一意なベース ID があることで、受講者が無関係な、あるいは部分的に上書きされた エビデンスを比べてしまうのを防げます。

手作業の annotation の境界

Module 04 の人による annotation は、意図的に自動化されていません。ランタイムのスクリプトは、 キューを作ったり、人の判断を埋めたり、修正済み出力を入力したり、アイテムを承認したり、タスクを 完了させたりはしません。git 管理された合成のフィクスチャは、本物のレビューが存在しないときの 講師の下稽古には役立ちますが、それは source=synthetic-reviewed-fixture のままであり、人による annotation のループが完了したことを証明しません。

受講者の経路では、git 管理外の本物の reviewed.json を使ってください。元の言い回しは、実際の ユーザーフィードバックの質問 1 件です。他の 2 つの入力そのものは、そのレビュー済みインシデントから 導かれた、レビュアーが書いた言い換えです:

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?

3 つすべてが同じ実際のソース trace と annotation の由来を保っています。受講者が 1 件の本番 インシデントを 3 件の独立したフィードバック trace と取り違えないよう、これを声に出して言って ください。

昇格の信頼性と由来

教室が昇格を実行する前に、reviewed.json を投影せずに確認してください。正確な修正済みの 読み取り専用 SQL、必須の本番の由来、そして安全で一意な 3 つの ID を含んでいなければなりません。 昇格はまずローカルのバッチ全体を検証し、そのうえで ClickHouse での実行やデータセットの upsert の 前に認証済みのメタデータ読み取りを行います。メタデータが読めない場合は失敗して閉じ、異なる本物の 本番由来を持つ ID の衝突は拒否します。

同一の本物の昇格は冪等です。合成のフィクスチャには明示的な --synthetic-fixture フラグが必要で、 直接のパスとして与えることも reviewed.json と組み合わせることもできません。本物の昇格のあとに それを実行しないでください。衝突が報告された場合は、両方のソースを保存し、既存のデータセット アイテムを調査し、それらのアイテムが本当に異なるレビュー済みのケースを表しているときだけ、 新しい監査された ID を選んでください。

Experiment のルールと observation のルール

この 2 つの文脈をスライドかホワイトボードに見えるように置いておいてください:

プロビジョナーが入れるのは、カタログ駆動の汎用 evaluator が 1 つであり、顧客数カウント専用の evaluator ではありません。その policy-v2 のカタログは、アクティブ顧客、売上、閲覧から購入への コンバージョン、粗利益を扱います。無関係な質問は NOT_APPLICABLE になるべきです。

--business-policy-experiments のフェーズは online rule enabled=False を報告しなければなりません。 2 つ目のガードとして Langfuse のルール UI も確認してください。あとの有効化コマンドは、データセット スコープの business-policy-adherence score が少なくとも 1 つ存在することを証明しますが、講師による 校正レビュー全体の代わりにはなりません。

校正のゲート

同じアイテム ID、モデル、プロンプトの上でベースラインと候補を比較します。リポジトリには YAML の 質問が 20 個ありますが、q019 と q020 は few-shot holdout なので、クリーンな project は Experiment item 18 個から始まり、3 件の昇格後は 21 個になります。検証済みの再利用 shared project が 22 アイテムだったのは、以前の無関係な承認済みアイテムが 1 件残っていたためだけです。その最新の ペア run は 16/22 から 19/22 へ移りました。これは条件付きの検証エビデンスであり、受講者に必須の 件数でも、確率的なプロバイダーが同じ集計値を再現するという約束でもありません。

すべてのゲートを通過しない限り、有効化しないでください:

• 3 つの prod-active-* のケースがすべて、policy-v1 での FAIL かつ不正から policy-v2 での PASS かつ正解へ移ること;
• 候補の売上 (q005) とコンバージョン (q018) が PASS であること;
• 素のカウント (q001) が NOT_APPLICABLE であること;
• 既存のすべてのアイテムの correctness がアイテム単位で比較され、1→0 の退行がないこと;
• correctness の集計値が退行しないこと; そして
• すべての Experiment アイテムが correctness、agent-arena-llm-judge、そして正確に business-policy-adherence の score を、妥当な構造化出力とともに持つこと。

あらゆるカウントに PASS を付ける judge は、たとえ候補が良く見えても校正に失敗しています。 NOT_APPLICABLE のプローブを使って、ポリシーの適用可能性が実際の分類ステップであることを 示してください。

非同期の採点と、score が出ないときの切り分け

experiment と observation のどちらの評価も非同期です。ハーネスは必要な experiment の score を待ち、 scripts.verify_online_scores は既定で 180 秒のあいだ稼働中の trace の score をポーリングします。 score が pending だからといって、慌てて再読み込みしたり、ルールを作り直したり、早まって有効化したり しないでください。

score が現れない場合は:

1. 期待される名前が正確かを確認します。Experiment は business-policy-adherence を使い、 serving の observation は agent-arena-business-policy-online を使います。
2. evaluator のディスパッチャー／実行ワーカーが健全かを確認します。
3. agent-arena-openrouter の connection と judge モデルの可用性を確認します。プロバイダーの遅延、 レート制限、ルーティングの制限は、エージェントの応答が成功していても評価を pending や失敗の まま残すことがあります。
4. experiment のルールが arena-golden データセットを対象にし、observation のルートが ルート chat_turn の observation を対象にしていることを確認します。マッピングは $.question と $.sql を公開していなければなりません。
5. 構造化出力を調べます。カテゴリの欠落、許可された 3 つの値の外にあるカテゴリ、理由付けの不在は、 いずれも校正の失敗です。
6. プロビジョニングがルール名の曖昧さを報告した場合は止めて、再試行する前に Langfuse 上で完全に 同名の重複ルールを解消してください。どちらの重複が更新されたのかを当て推量しないこと。

失敗した trace と evaluator のエビデンスは保存してください。プロバイダーの障害を捏造した PASS に 変えたり、score 欠落のゲートを飛ばしたりしないでください。

リプレイの手引き

有効化のあと、serving を明示的に policy-v2 で再起動し、受講者と同じ 4 つの質問そのものを 使ってください:

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?

すべての trace で運用上の成功を必須としてください。アクティブ顧客、売上、コンバージョンは agent-arena-business-policy-online=PASS を持たなければならず、製品数のカウントは NOT_APPLICABLE でなければなりません。

コンバージョンのリクエストには検証済みの確率的な境界があります。同じ構成で再試行は最大 1 回まで 許し、両方の trace ID と outcome を保存し、どちらの試行も通らなければ止めてください。繰り返す失敗は 調査すべき新しい本番のエビデンスであり、グリーンになるまでループを回す理由ではありません。

サンプリング、コスト、信頼性

ワークショップのルールはサンプリング 1 を使い、対象となるすべての trace が目に見えるエビデンスを 生むようにしています。本番のボリュームでは、あらゆるリクエストに LLM judge をかけると、 プロバイダーのコストが増え、レート制限を消費し、ユーザーへの応答よりあとに score が出ることも あります。サンプリングは、トラフィック、インシデントのリスク、evaluator のコスト／レイテンシ、 必要なカバレッジから選んでください。決定論的な運用チェックは広く保ち、高価な意味的判断は、 それがコストに見合うトラフィックと指標のために取っておいてください。

evaluator は監視であって、リクエスト経路上の認可ではありません。遅れた judge が serving の応答を 黙ってブロックしてはいけません。score の欠落、カテゴリのドリフト、シグナルの食い違いは、 システムのサービスレベル目標に従って運用アラートかレビューのバックログへ回してください。

ロールバックとリセット

有効化のあとに observation の judge が誤った合格、誤った不合格、壊れた出力、あるいは受け入れられない コスト／レイテンシを生んだ場合は:

1. Langfuse の Evaluations を開き、observation のルール agent-arena-business-policy-online そのものを見つけて、disabled に切り替えます。
2. 新しい chat_turn の observation がそのオンラインルールの score をもう受け取らないことを 確認します。
3. それら自身のエビデンスが別のことを示さない限り、policy-v2、sql-execution-success、 👍/👎 は動かしたままにしてください。不具合のある judge を無効にすることが、既知の古い ポリシーを呼び戻すべきではありません。
4. 影響を受けた trace をサフィックス付きの人による annotation キューに追加し、evaluator の カタログ／プロンプトとゴールデンデータを改善し、そのうえで再度有効化する前に対になった experiment の校正を繰り返してください。

リモートのエビデンスを削除せずにローカルのサービスを止めるには:

scripts/arena.sh stop

scripts/arena.sh down はワークショップの ClickHouse データベースと読み取り専用ユーザーも 削除しますが、Langfuse のデータセット、Experiment の run、annotation のキュー、score は削除 しません。evaluator のロールバックとしては使わないでください。

トークトラック: ループは開いたままにする

• 元の evaluator が合格したのは、その契約が「SQL が実行できた」だけだったからです。ユーザーの 👎 は、その契約の外にある価値の失敗をあらわにしました。
• 人によるレビューが、不確かなシグナルを検証済みの診断と修正へ変えました。
• 本番の由来が、インシデントがゴールデンセットに入るときにそれを監査可能にしました。言い換えは、 余分なユーザー trace を捏造することなく、言い回しのカバレッジを改善しました。
• 対になった experiment は、ポリシーの変更をモデル／プロンプトの変更から切り分け、汎用の judge を 本番より前に検証しました。
• オンラインの PASS はユーザーフィードバックを不要にしません。将来の agent-arena-business-policy-online=PASS と user-thumbs=false の組み合わせは、まさに調査を 再開すべき種類の食い違いです。

完了のゲート

教室が 6 つの成果物すべてを示せるようになるまで、このモジュールを閉じないでください:

1. 運用上は合格で、ユーザーのシグナルは否定的な、本番の trace;
2. 完了した人による annotation と、検証済みの修正済み SQL;
3. 本物の本番の由来を持つ 3 つのゴールデンアイテム;
4. 既存の correctness の退行がない、同じデータセットでのベースライン／候補のエビデンス;
5. 校正された FAIL、PASS、NOT_APPLICABLE の Experiment のエビデンス; そして
6. アクティブ顧客、売上、コンバージョン、そして素のカウントにわたって有効化された稼働中の score。 同時に、次のループのために 👍/👎 が引き続き利用できる状態。