langsmith-online-eval-engineering

オンライン評価エンジニアリング

オンライン評価器を段階的に構築します：

inspect traces and interview user -> propose directions -> user chooses
-> build evaluator -> test, attach, verify -> review and repeat

評価器を作成または変更する前に、references/langsmith-api.mdを読んでください。

1. トレースを調べる

ユーザーにLangSmithのプロジェクト名を尋ねます。最近のルートレベルのトレースを取得し、その構造を表示します。references/trace-inspection.mdを読んでください。次の点を確認します：

• 実行名と種類；
• 利用可能な入力および出力フィールド名；
• データの形状と内容（省略したサンプル）；
• 評価器が必要とするデータを含むフィールド。

トレース構造を会話内で要約します：

Project: name
Run type: chain | llm | tool | ...
Input fields: field names and what they contain
Output fields: field names and what they contain
Sample: one representative input/output pair (truncated)

ユーザーにも参加してもらいましょう。トレース構造とそこから分かることを説明したうえで、トレースからは判断できない情報だけを尋ねます。たとえば、「このアプリケーションは何をしますか？」「最も重視する品質上の懸念は何ですか？」「決して起きてはならない失敗は何ですか？」などです。

このセッションの評価器に名前のプレフィックスを付けたいか、ユーザーに尋ねます（例：myapp-、v2-、dogfood-）。プレフィックスが提示された場合は、すべての評価器名、プロンプトハブのハンドル、実行ルールの表示名に適用します。希望しない場合は、説明的な名前のみを使用します。

トレース構造を理解し、ユーザーが懸念事項を説明するまでは、評価器を提案しないでください。

2. 評価の方向性を話し合って選ぶ

references/evaluator-design.mdを読んでください。トレースデータに基づいて、評価基準を2つか3つ提案します。ユーザーが指定した場合は、手順1の名前のプレフィックスを適用します。それぞれについて、次の情報を提示します：

Name: descriptive evaluator name (with prefix if set)
Type: LLM-as-judge or code
Measures: what quality dimension this evaluates
Scoring: bool, float (0-1), or int; what pass/fail means
Fields needed: which trace fields are used and how
Rationale: why this type and approach

例：

Name: response-relevance
Type: LLM-as-judge
Measures: whether the response addresses the user's question
Scoring: bool; True = relevant, False = off-topic or non-responsive
Fields needed: input (user question), output (assistant response)
Rationale: relevance is semantic and requires reading comprehension; not decidable by code

1つを推奨し、どれを構築するかユーザーに尋ねます。ユーザーが選ぶまでは実装しないでください。

3. 評価器を1つ構築する

references/langsmith-api.mdを読んでください。選択された評価器を構築します。設定全体をユーザーに提示し、API呼び出しを実行する前に承認を得てください。

LLM-as-judge の方法。 reasoningを最初に、次にスコアフィールドを配置したResponseSchemaを定義します。参照回答との一致ではなく、結果そのものを評価する明確な基準を含むプロンプトメッセージを作成します。手順1で特定したフィールド名を使ってvariable_mappingを設定します。スキーマ、プロンプト、変数マッピング、評価器名を承認用に提示します。承認されたら、プロンプトをプッシュして評価器を作成します。評価器IDを報告します。

コード評価器の方法。 perform_eval(run, example=None)関数を作成します。関数は自己完結型（組み込み関数と標準ライブラリのみを使用）とし、runには辞書としてアクセスし（run.get("outputs")）、{"key": ..., "score": ..., "comment": ...}を返す必要があります。関数コードと評価器名を承認用に提示します。承認されたら、評価器を作成します。評価器IDを報告します。

4. テスト、アタッチ、検証

アタッチする前に、希望するサンプリング率をユーザーに確認します（1.0 = すべてのトレース、0.5 = 半数、0.1 = 10％、またはカスタム）。黙ってデフォルト値を設定しないでください。ユーザーが決めかねている場合は、初期テストには1.0を推奨します。

アタッチする前に、既存のトレースをいくつか使って評価器をテストするか、ユーザーに確認します。実行ルールが適用されるのは新しいトレースのみなので、新たなトラフィックが発生する前に検証するには、過去のトレースを使ったテストが唯一の方法です。

コード評価器の場合は、取得したルートレベルのトレースに対してperform_evalを直接実行し、inputs、outputs、attachmentsキーを持つdictを渡します。これにより、本番環境に導入する前に実行時エラー（フィールド名の誤り、dictとオブジェクトのアクセス方法の混同、データの欠落）を検出できます。LLM評価器の場合は、設定を検証します。variable_mappingのキーがプロンプトのプレースホルダーと一致すること、マッピングされたトレースフィールドが存在すること、マッピングされたデータに意味があることを確認します。

テストでエラーが見つかった場合は、アタッチする前に修正して作り直します。ユーザーがテストを希望しない場合は、アタッチに進みます。

評価器をトレースプロジェクトに接続する実行ルールを作成します。ユーザー指定の命名プレフィックスをdisplay_nameに適用します。評価器が正しいプロジェクトにアタッチされた状態で、評価器リストに表示されていることを確認します。以下を確認します。

• 評価器のアタッチ状態と実行ルールのステータス。
• 最近のトレースのフィードバックとスコア（過去のトレースを使ったテスト、または新しいトレースによるもの）。
• スコアが、確認したトレースに対する期待と一致しているかどうか。
• エッジケースへの対応（出力が空、実行エラー、予期しない構造）。

評価器がクラッシュする、誤ったスコアを付ける、またはエッジケースで失敗する場合は、修正して再アタッチします。承認を求める前に、評価器がインフラストラクチャやデータ構造の問題ではなく、意図した品質の側面を評価していることを確認します。

5. ユーザーとレビューする

評価器の名前とID、品質の側面とスコアリング方法、使用したトレースフィールド、サンプリング率、制限事項を説明します。承認、修正、取り下げ、または次に進む方向の選択をユーザーに依頼します。続行する場合はトレースから得た知見を再利用し、異なる品質の側面を提案します。

不変条件

• 評価器1つにつき、品質の側面は1つです。
• フィールド名を推測せず、実装前に必ずトレースを確認します。
• APIを呼び出す前に設定を提示し、ユーザーの承認を得ます。
• コード評価器は自己完結している必要があります。使用できるのは組み込み機能と標準ライブラリのみです。
• コード評価器が受け取るrunは通常のdictです。属性アクセスではなく、run.get("inputs")とrun.get("outputs")を使用します。exampleパラメーターのデフォルト値はNoneにする必要があります。
• APIの失敗、認証エラー、実行ルールの失敗は、評価器のバグではなくインフラストラクチャエラーとして扱います。