04 人が調査する

受講者レッスン 04 人が調査する の ファシリテーター向け手引きです。

タイミング

合計 ~20 分。

• 3 min — 否定的なフィードバックでフィルタし、正典となる Chat のルートを検証する。
• 4 min — 3 つの score config を作り、そのうえで紐づけが固定されるキューを作る。
• 4 min — 診断を議論する前に、観測できる振る舞いをオープンコーディングする。
• 5 min — trace のエビデンスを調べ、policy-v1／policy-v2 の SQL を並べて実行する。
• 4 min — 修正を入力し、承認し、完了させ、由来を記録する。

講師のプリフライト

受講者が来る前に、Module 03 が Boolean の user-thumbs=false と sql-execution-success=true を持つ正典となる chat_turn を 1 つ生み出していることを確認して ください。その trace ID は非公開に保ち、ルートの output に質問、生成された SQL、返ってきた行、 outcome が含まれていることを確認します。

下稽古が必要なら使い捨てのテストプロジェクトで 3 つの score config を作ってもよいですが、 受講者の最終的なキューを事前に作っておかないでください。キューに紐づく score config の ID の集合は 作成時に固定されるので、教室ではまず config を作ってから 3 つすべてを紐づけるべきです:

この annotation の演習は UI だけで行います。ランタイムのスクリプトは trace の score を検証したり、 あとでレビュー済みのエクスポートを昇格したりはできますが、キューを作ったり、人の判断を書き込んだり、 annotation タスクを完了させたりはしません。

トークトラック

1. Tracing を user-thumbs = false でフィルタし、Module 03 のワークシートにある trace ID と 突き合わせます。こう言ってください。「フィードバックが決めるのは次に何を調査するかであって、 何を結論するかではありません。」

2. score config ごとに Settings → Scores → Create を使います。そのうえで Annotations → Queues → Create を使い、一意なセッションのサフィックスを付けた production-investigation-<session> という名前でキューを作り、3 つの config すべてを 紐づけます。

3. ルートの chat_turn observation を選択し、その Annotate ドロップダウンを開いて、新しい キューを選びます。子の llm_call も見せつつ、それが対象として間違っている理由を説明して ください。エンドツーエンドの構造化された実行結果を欠いており、論理的なフィードバックの インシデントではないからです。

4. Module 03 が仕込みのセットアップを開示していたことを受講者に思い出させ、そのうえでその事前 知識を括弧に入れて、観測できることのオープンコーディングを練習するよう促してください。 良い最初のメモはこうなります:

   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. 教室がそのメモを記録してから初めて、エビデンスの全体を明かします。送出されたメタデータ policyversion=policy-v1、サインアップベースの SQL と結果、そして 2 つの score です。 ソース側のフィールドは policy_version で、OpenTelemetry のアダプターがサニタイズされた Langfuse のキー policyversion を送出します。

6. 2 つのポリシー定義を並べて実行します。policy-v1 の参照はこちらです:

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

   policy-v2 の、現在のポリシーの参照はこちらです:

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

7. その比較のあとで初めて、診断を当てはめます。failure-category=stale-business-policy を記録し、 Corrected Output を plain-text モード に切り替えて、現在のクエリを生のまま貼り付け ます。Langfuse は SQL を実行しないので、approved-for-golden=true を設定してタスクを完了させる 前に、Step 6 の読み取り専用クライアントでそのテキストそのものを検証してください。

8. Module 05 のために source_trace_id、failure_category、source_policy_version、修正、 そして任意の annotation タスク ID を保存します。

つい飛びつきたくなるが間違っている 3 つの診断

• 「モデルがプロンプトを無視した。」 trace の SQL は明示的な policy-v1 の文脈に従って います。失敗はデプロイされたポリシーが古びていることであり、与えられた指示への不服従では ありません。
• 「sql-execution-success が壊れている。」 SQL は実行できたので、運用 evaluator は正しく true を返しました。その設計は統制されたビジネス上の意味を検査しません。
• 「👎 は SQL が間違っていることを証明する。」 フィードバックはレビューに値する trace を 特定します。ユーザーの意図の曖昧さを解いたり、検証済みの代替クエリを与えたりはしません。 それをやるのは、ポリシーの並列比較と人によるレビューです。

受講者が trace をオープンコーディングし終えるまで、これらの代替仮説を見えるところに置いて おいてください。仕込まれた答えは講師には分かっていますが、それでも調査は本物のエビデンス優先の レビューを手本として示すべきです。

ルートの observation を対象にする

trace の中で関係する observation は 2 つあります:

受講者が誤って子を追加してしまった場合、それを本番の調査として完了させないでください。正しい キューにルートの chat_turn を追加し、間違って作られたタスクはプロジェクトの保持方針に従って 残すか削除します。source_trace_id として保存するのは trace ID であり、子の observation の ID では ありません。

キューの紐づけの固定と、リセットしても安全な命名

Langfuse は、キューが作成された時点でそのキューに紐づく score config の ID の集合を固定します。 キューはあとから漏れた config を紐づけられないので、先にすべての config を作るのが最も安全な やり方です。score config そのものは変更可能です。名前、スキーマ、カテゴリ値の、サポートされた 編集には監査される score config の更新が必要で、その更新は既存の score を書き換えません。

リセットしても安全なサフィックスを、たとえば次のように使ってください:

production-investigation-<session>-retry-1

キューが config を取りこぼしていたり、間違った config ID を紐づけていた場合は、正しい 3 つの ID を すべて備えた、新しいサフィックス付きのキューを作り、正典となるルートをもう一度追加し、古い キューは置き換えられたことを明確に示してください（プロジェクトの方針が許す場合のみ削除します）。 すでに紐づいている config に対するサポートされた編集には、キューの作り直しではなく監査される score config の更新を使ってください。完了したキューの名前を、どのタスクが判断を供給したのかを 分からなくするような形で使い回さないでください。

修正済み出力の信頼性

修正は将来のゴールデンな正解データになるので、構文もポリシーもどちらも重要です。生の SQL を 貼り付ける前に Corrected Output を plain-text モード に切り替えてください。Langfuse は テキストを保存しますが実行はしません。承認の前に、Step 6 の読み取り専用 ClickHouse クライアントで そのテキストそのものを実行してください。正しそうに見えても、壊れている、生のテーブルを参照して いる、複数のステートメントを含んでいる、あるいは ClickHouse で失敗するクエリは、未承認のまま にしなければなりません。

壊れた SQL の場合は:

1. approved-for-golden=false を設定する、あるいはそのままにする;
2. タスクを承認済みとして完了させない;
3. 許可された v_* ビューに対して修正を直す;
4. それを再実行し、結果を確認する; そして
5. 検証のあとで初めて承認して完了させる。

誰かが壊れた修正を完了させてしまった場合は、新しいキュー／タスクのサフィックスを作ってレビューを やり直してください。監査の跡をこっそり編集して消すのではありません。Module 05 の昇格コマンドも 読み取り専用の SQL を検証して実行しますが、そのガードは人によるレビューの代わりにはなりません。

よくある失敗

• フィルタしても trace が出てこない — score の型が Boolean で、フィルタが user-thumbs=false であることを確認してください。古い score 名を探さないこと。評価を付けなかった curl 診断を選んでしまわないよう、ワークシートの trace ID と突き合わせてください。
• 対象が間違っている — llm_call が追加されたため、タスクにトランスクリプトと SQL しか 表示されません。trace に戻ってルートの chat_turn を追加してください。
• キューの次元が欠けている — 必要な config ID が紐づけられずにキューが作られました。新しい サフィックス付きのキューを作ってください。不完全なレビューフォームで続けないこと。すでに 紐づいている config に対するサポートされた編集には、キューの作り直しではなく監査される config の 更新を使ってください。
• ポリシーのメタデータが見当たらない — ソース側の policy_version ではなく、送出された policyversion を探し、そのうえでルートの policy-v1 タグを確認してください。
• カウントが予期せず一致する — 診断をやめてください。Module 03 のシナリオのプリフライトを 再実行し、コントラストのないデータスナップショットからエビデンスを作り出さないでください。
• 修正が生の SQL ではなく整形されている — Corrected Output を plain-text モードに切り替え、 クエリだけを貼り付けてください。
• 修正が実行できない — Langfuse はこれを捕まえません。承認は false のままにし、修正して、 タスクを完了させる前に Step 6 のクライアントでそのテキストそのものを再実行してください。

完了と引き渡し

Module 05 に移る前に、完了したタスクが正典となる chat_turn に対するものであること、観測が診断より 前に記録されていること、修正が現在のポリシーの SQL そのものであること、そしてタスクが承認されて いることを確認してください。受講者のワークシートは次を運んでいなければなりません:

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>

否定的なユーザーの score は、トリアージのシグナルとして本番の trace に残ります。人による annotation がレビュー済みの正解データを供給します。Module 05 は、修正を昇格させ予防的な evaluator を 組み立てるときに、その両方の出自を保持します。