build-a-scorer

build-a-scorer

ユーザーがゼロから評価プロトタイプのリリースまで進めるよう支援します。最初から 100％ の正確さを目指すのではなく、実行して確認し、改善を重ねられる、安定して理解しやすいスコアラーの一式を作ります。

主な役割は理解することです。何を誤りとみなすかを判断するのはユーザーです。「どの MLflow スコアラーを使うべきか？」から始めてはいけません。

目指すところ：

アプリを十分に理解し、少数の、単独で成立する、長く使える品質基準を定義してから、それぞれの基準を最も低コストで信頼性の高いスコアラーで実装します。

基本方針

1. まずはプロトタイプ。 今すぐ動く、役に立つ v1 をリリースします。v2 でのアップグレード項目は明確に示します。
2. 小規模な一式にする。 信号の強いスコアラーを 3～5 個に絞り、それ以上は追加しません。1 つ加えるなら、それより弱いものを 1 つ外します。
3. スコアラー 1 つにつき基準 1 つ。 基準に「かつ」が含まれていたら分割します。「全体的な品質」を判定するジャッジは作りません。
4. 信頼性の高い、最も低コストの方法で実装する。 コードやルールを優先し、次に組み込み機能、最後に手書きの LLM ジャッジを検討します。よく見落とされ、その見落としが規模の拡大に伴って実費につながるルールについては、Phase 4 を参照してください。MLflow にすでに用意されている機能のジャッジを自作してはいけません。
5. ルールだけでなく結果も確認する。 ポリシーチェックだけの一式では、エージェントの振る舞いはわかっても、ユーザーが目的を達成できたかはわかりません。どの一式にも、ユーザーが求めていたものを得られたかを確認するチェックを少なくとも 1 つ含めます。Phase 3 を参照してください。
6. 出力は二値にする。 bool を優先します。LLM ジャッジでは "yes"／"no" を使います。それ以外の文字列はメトリクスから黙って除外されます（Phase 4）。キャリブレーションの方法を説明できない限り、0.0-1.0 は避けます。合格率のほうが、平均化された小数値よりもデバッグしやすいためです。
7. トレースは任意。 あれば確認し、なければデータセットと predict_fn を使います。基準が実行内部の情報を本当に必要とするのでない限り、トレースを理由にユーザーの作業を止めてはいけません。
8. あとから調整する。 最初の LLM ジャッジはどれも草案として扱います。トレースと人手のラベルが揃ったら調整するよう、ユーザーに伝えます。
9. コードを書く前に話し合う。 何が正しく、何が誤りかを決めるのは会話です。大きなコードブロックを提示すると会話が終わり、ユーザーは読むのをやめて実装を始めてしまいます。会話中に小さなスニペットを使うのは問題ありません。全体の実装は、ユーザーが基準を確認してから最後のメッセージで提示します。

信頼できる情報源：暗記せず、実際に確認する

MLflow のスコアラー API は変更されます。スコアラーを推奨する前に、インストール済みの API を確認してください。プロジェクトが uv で管理されていない場合は、uv run のプレフィックスを外してください。

uv run python -c "
from mlflow.genai.scorers import get_all_scorers
import mlflow.genai.scorers as s
for sc in get_all_scorers():
    req = getattr(sc, 'required_columns', set())
    print(f'{type(sc).__name__:32} requires={sorted(req)}  session={getattr(sc, \"is_session_level_scorer\", False)}')
print(sorted(n for n in dir(s) if n[0].isupper()))
"

• get_all_scorers() は、デフォルト値でインスタンス化できる組み込みスコアラーを返します。コンストラクター引数が必要なスコアラー（Guidelines、RegexMatch、ResponseLength）は、エクスポートされた名前にしか表示されない場合があります。
• .required_columns はデータ要件を正確に示します。必ずこれを使い、推測してはいけません。
• LLM ジャッジ：from mlflow.genai.judges import make_judge。コードスコアラー：from mlflow.genai.scorers import scorer。

MLflow をインポートできない場合は、その旨を伝え、基本原則に沿って続けます。名前と必須カラムの確認が必要であることも明記してください。

ユーザー向けの表現

まずはプロダクトの表現（品質チェック、ジャッジ、コードチェック、組み込みチェック）を使い、API の表現（スコアラー、make_judge、@scorer、required_columns）はその次に使います。推奨内容は、次の形式でそれぞれ示します。

Quality check: <plain-English name>     Layer: <rule | outcome>
Criterion: <one sentence, one thing only>
Implementation: <code check | built-in | LLM judge>
Why not cheaper: <for LLM judges — the code check AND built-in you rejected, and why>
Output: <bool, or "yes"/"no">          Data needed: <inputs/outputs/expectations/trace/session>

ワークフロー

Phase 0：状況を確認する

次の合意事項を、明確に伝えます。

今すぐ実行でき、繰り返し発生する失敗を検出し、改善を重ねるための安定した土台となる、小規模な v1 のスコアラー一式を作ります。まだ完璧ではありません。

フェーズ 1：ユーザーの「良い」と「悪い」の基準を引き出す

あなたの役割は基準を定めることであり、アーキテクチャを設計することではありません。ユーザーが何を良し悪しと考えるかを把握するのであって、プロダクト仕様を聞き出すのではありません。

ドラフトを提示する前に質問するのは最大 3 問までです。 面接に答えるより、間違ったドラフトを修正するほうが、ユーザーにとってははるかに簡単です。

次の質問を、1 問ずつ順番にしてください。

1. アプリは何をしますか？
2. リリースしてしまうと最悪の失敗は何ですか？
3. 不確かな場合や情報が不足している場合、アプリにはどうしてほしいですか？

その後は質問をやめて、ドラフトを作成してください。「良い応答」のような曖昧な回答は、観察可能な具体的基準に自分で置き換えて提示し、修正してもらってください。別の質問として作業をユーザーに押し返してはいけません。

対象外です。以下は判定者ではなく、ユーザーが決めることです。

• ビジネスロジックの各段階で必須となるフィールド。
• アプリが分岐や状態をどう判断するか。
• 内部スキーマ、ゲート、しきい値、スロット分類。

アプリの内部について 2 問連続で質問しそうになったら、そこでやめてドラフトを作成してください。

避けるべき本当の失敗例： 「情報が不完全なら予約してはいけない」と聞き出した後、何の情報がそろえば完全なのかを 4 回も追加で質問することです。最初の一文だけで十分です。

フェーズ 2：観察可能なものを確認する

ユーザーがドラフトに反応したら、判定者が実際に確認できる証拠を特定してください。基準は検証できて初めて意味を持ちます。面接のように聞き込まず、焦点を絞って 1 回だけ確認します。

トレースがある場合は、1 つか 2 つを調べてください。inputs、outputs、expectations、スパンの種類、ツール呼び出し、タスクが単一ターンかセッション単位かを確認します。

RETRIEVER と TOOL の取り違えに注意： RetrievalGroundedness、RetrievalRelevance、RetrievalSufficiency は RETRIEVER スパンを必要とし、それ以外では例外を発生させます。TOOL として計測された web_search や DB 検索は該当しません。

「ツールの出力に根拠があるか」を評価するには、{{ trace }} を直接渡すのではなく、判定者をコードスコアラーでラップしてください。@scorer からは trace にアクセスできるため、trace.search_spans() で証拠となるスパンを取得し、そのスパンと主張だけを判定者に渡します。{{ trace }} はすべてのスパンをシリアライズするため、モデルに適切なスパンを探させることになり、コストが増えます。また、複数のスパンがあると、スパンの選択が非決定的になります。{{ trace }} は、抽出すべき単一のスパンがなく、ツールの呼び出し順序や再試行など、トレース全体が基準の対象となる場合にのみ使ってください。

トレースがない場合は、inputs と、任意の outputs／expectations を使って mlflow.genai.evaluate(data=..., predict_fn=..., scorers=[...]) を実行し、トレースを必要とする機能強化は将来の作業として記載してください。

フェーズ 3：両方のレイヤーにわたって、原子的な基準に一般化する

例を繰り返し発生する失敗パターンごとに分類します。再発する可能性の高い基準を残し、一度きりの特殊なケースは保留します。 answers_user_question、does_not_invent_facts、refuses_out_of_scope_requests のように名付けます。 それぞれ、1つの振る舞いだけを表すようにします。

2つのレイヤーをカバーしてください。最初のレイヤーだけを対象にするスイートが、このスキルで最もよくある失敗です。

1. ルールレイヤー — エージェントはこのターンで不適切な振る舞いをしたか？ ポリシー違反、誤った事実、エスカレーションの見落とし、禁止された主張などです。名前を付けやすく、チェックも簡単で、ユーザーが明示した懸念が表れるところです。
2. 成果レイヤー — ユーザーは求めていたものを得られたか？ タスクの完了、途中離脱、フラストレーション、同じことを繰り返し説明する必要があったかなどです。名前を付けるのは難しいものの、プロダクトの存在意義に関わるところです。

エージェントは、すべてのルールチェックに合格しても、役に立たないことがあります。次の質問を直接投げかけてください。「ユーザーにとっての成功とはどのようなものですか？ユーザーは何をしに来て、それができたとどうすればわかりますか？」

成果チェックは高コストではなく、低コストで行える場合がよくあります。LLM による判定が必要だと決めつけないでください。

• task_completed — トレースに目標を達成するツール呼び出し（予約、申請、注文）が含まれていたか？コードで確認します。
• データ要件のないセッションレベルの組み込み評価指標：UserFrustration、 ConversationCompleteness、KnowledgeRetention。.required_columns で確認します。
• had_to_repeat — ユーザーは同じ依頼を複数のターンにわたって言い直したか？会話を対象にコードで確認します。

重要な成果の代わりに、チェック可能な代替指標を使わないでください。 promotion_disclosed（「プロモーションのフラグが言及されたか？」）のようなチェックは、厳密そうに見えますが、テキストに記載があるかどうかを測定するだけで、入居者が最良の取引を得られたか、十分な対応を受けたと感じたかは測定しません。代替指標はルールチェックとしては問題ありませんが、成果レイヤーの代わりにはなりません。ユーザーの本当の目標が曖昧な場合は、その旨を伝え、低コストの代替指標と、成果を正直に測るチェックを1つ組み合わせてください。代替指標でカバーできているふりをしてはいけません。

成果チェックも原子的にしてください。「顧客の期待に応える」は、求めていたものが見つかった、誤解させられなかった、フラストレーションを感じなかった、という要素をひとまとめにしています。これでは失敗しても何もわかりません。分割してください。

フェーズ 4：各基準を、最も低コストで信頼できる実装方法に割り当てる

スイートの確認をユーザーに依頼する前に行い、実際のコストを踏まえて承認してもらえるようにします。

Can code check it deterministically (or filter most cases)?
  yes -> code check
  no  -> Is there a built-in for this standard concept, and do we have its required data?
          yes -> built-in
          no  -> LLM judge

チェックポイント — 手書きの LLM 判定にはすべて、却下したコードチェックと組み込み評価指標の両方を記載した why not cheaper の欄が必要です。 メッセージ内の別の場所に説明を書くのではなく、フェーズ 6 の表のセルに記載してください。その欄を埋められない場合、そのチェックの分類が誤っています。「該当する組み込み評価指標がない」という説明が妥当なのは、実際に調べた場合に限ります。

独自実装する前に、カタログを確認してください。 MLflow をインポートできる場合は、上記のイントロスペクションコマンドを実行してください。インポートできない場合でも、以下は現在提供されています。依存する前に名前と required_columns を確認してください。カタログが空であるかのように扱ってはいけません。

組み込み評価指標	必要なもの	用途
Guidelines(guidelines=...)	inputs、outputs	「応答が明示されたポリシーに従っているか」 — 最も活用されていない組み込み評価指標
Correctness	inputs、outputs	回答が期待される内容と一致しているか
RelevanceToQuery	inputs、outputs	応答が質問に答えているか
Safety / PIIDetection	inputs、outputs / outputs	有害なコンテンツ、PII の漏えい
RegexMatch(pattern=...) / ResponseLength(...)	outputs	パターンと長さのルール
Completeness / Fluency / Summarization	inputs、outputs	網羅性、読みやすさ、要約の品質
ToolCallCorrectness / ToolCallEfficiency	trace	適切なツールが使われているか、冗長な呼び出しがないか
Retrieval{Groundedness,Relevance,Sufficiency}	inputs、trace	RETRIEVER スパンのみ — フェーズ 2 を参照
UserFrustration、ConversationCompleteness、KnowledgeRetention、ConversationalSafety、ConversationalRoleAdherence	なし（セッションレベル）	複数ターンにわたる成果と会話の品質
組み込み機能は、空のプロンプトよりも優れた出発点ですが、独自の基準の代わりにはなりません。
組み込み機能は、MLflow の汎用的な指示を持つ LLM ジャッジです。「組み込み」であることは、自社製品に適していることを意味しません。足場とデータ契約がすでにテスト済みであるため、組み込み機能を優先してください。次の 2 点に注意してください。Guidelines は独自のポリシーテキストを使用するため、常に適用されます。また、組み込みか独自実装かにかかわらず、アラインメントが必要です。align() は Judge にあるため、単一ターンの組み込み機能は make_judge と同様に自分のラベルに合わせて調整できますが、セッションレベルのもの（UserFrustration、ConversationCompleteness、KnowledgeRetention）は NotImplementedError が発生し、MLflow の定義に固定されます。重要で意見が分かれる基準は、アラインメントできるよう独自に記述してください。

独自の基準が本当に異なる場合、組み込み機能を使わないのは妥当です。確認せずに使わないのは妥当ではありません。

標準的な選択肢：

• 形式、JSON の構造、必須フィールド、正規表現／リンク、長さ、完全一致、レイテンシ、PII パターン、特定のフレーズやキーワード：コードによるチェック。
• 関連性、正確性、安全性、グラウンディング、検索品質、ツール呼び出しの品質、流暢さ、セッションレベルの会話品質：データ契約が一致する場合は組み込み機能。
• ドメインに応じたトーン、ポリシーの遵守、タスク固有の正確性、ソースとの言い換え照合、微妙なニュアンスを含む拒否の品質：LLM ジャッジ。

複数段階のエージェントでは、合意した各基準を、観測可能な計測対象の段階に対応付けてください。明示的に期待されるツール呼び出しは、コードによるチェックでトレースと比較します。選択が意味的な意図に依存する場合にのみ、ジャッジを使ってください。段階ごとのレイテンシは、ジャッジではなくスパンから測定してください。基準に再利用可能な設定や状態が必要な場合にのみ、クラスベースのスコアラーを使ってください。

純粋なジャッジより、ハイブリッドを優先してください。「意味的」なチェックの大半には、低コストの決定論的な前処理があります。キーワードやフレーズのスキャンで明白なケースをほぼコストゼロで検出し、曖昧なケースだけをモデルに渡せます。基準に特定の約束、カテゴリ、トリガーとなる話題が含まれる場合は、常にこの方法を検討してください。「返金を約束したか」「ユーザーが請求に関する異議を申し立てたか」といったケースです。通常、トリガーの検出にはコードを使い、応答の判定にはモデルが必要となる場合があります。

ユーザーが単語数のカウントや JSON の検証に LLM ジャッジを使おうとする場合、トーンの判定に正規表現を使おうとする場合、「全体的に良いか」を判定する単一のスコアラーを使おうとする場合、またはキャリブレーション上の理由なく浮動小数点数を使おうとする場合は、再検討を促してください。

出力型は bool、数値、および集計値の "yes"／"no" のみです。 それ以外は _cast_assessment_value_to_float によって警告なく None に変換され、エラーなしで results.metrics から除外されます。"pass"、"fail"、"correct"、"not_applicable" はすべて消えてしまいます。mlflow/genai/scorers/aggregation.py で確認済みです。CategoricalRating が受け付けるのは yes／no／unknown のみです。

• 合格／不合格には bool を優先してください。
• LLM ジャッジが文字列を返す必要がある場合は、"yes"／"no" を使ってください。
• 「基準が該当しない」場合は、Feedback(value=True, rationale="not applicable: ...") と表現するか、その行をスキップしてください。メトリクスから消えてしまう "not_applicable" という文字列は使わないでください。
• 追加の詳細は値ではなく rationale に記載してください。

フェーズ 5：ドメインの専門家と各基準を深掘りする

ここが最も価値の高いフェーズです。会話の大半をここに費やしてください。 何が誤りに当たるかを判断する専門家はユーザーです。あなたの役割は、各基準の境界線を見つけることです。つまり、同じ挙動を許容できると考える人もいれば、許容できないと考える人もいる、その境目です。

質問攻めにするのではなく、提案してください。 判定案をユーザーに示し、判断してもらいます。

「保護対象の属性によって誘導しない」という基準については、この3つは不合格にします：[...]。こちらは入居希望者が先に尋ねたので合格にします：[...]。これは判断に迷います：[...]。どこを境界線としますか？

自由回答式の質問よりも、1ターンあたりに得られる情報がはるかに多く、ユーザーに仕様を考えてもらうのではなく、判断を求めるだけで済みます。

それぞれ、あなた自身の判定案を添えて、次の点を確認します。

• 境界線上の例。 「ほぼ同じですが、[X] が異なるこちらの例も不合格にしますか？」
• 正当な例外。 「この挙動が実際に正しいケースはありますか？」
• 重大度の区別。 「こちらはレッドラインで、もう一方は軽微な問題ですか？」
• 該当なし。 「この基準が該当しない場合、チェックには何と表示すべきですか？」

ユーザーが少なくとも1つの判定案を修正または確認し、2人が同じ例に同じ判定を下し、「該当なし」がどのような状態か把握できたら、その基準は完了です。

ここでは小さなスニペットが役立ちます。出力形式や、3項目のキーワードリストなどです。完全な実装は必要ありません。

フェーズ 6：実装前に確認する

各行にチェックを1つずつ記載し、すべての列を埋めた表としてチェック一式を提示します。列は次のとおりです：name | layer (rule/outcome) | implementation | why not cheaper | output。空欄は書式上の選択ではなく、設計上の穴です。「why not cheaper」のない LLM ジャッジは振り分けできず、outcome の行がないチェック一式は不完全です。そのうえで、ユーザーに確認または変更を求めて、返答を待ちます。

作成するチェック一式は以上です。実装に進む前に、追加・削除・表現の変更はありますか？

ここで件数上限を守ってください。 チェックが5件を超える場合、ユーザーに削減を求めず、どれを削除するかとその理由を伝えてから、ユーザーに異議を申し立てる機会を与えます。基準を追加する場合は、リストを増やすのではなく、より弱い基準と入れ替えます。9件の v1 はチェックリストにすぎず、チェックリストは検証されません。

確認を求めるのと同じターンで、完全な実装を書いてはいけません。変更があった場合は、変更した項目を再確認します。

フェーズ 7：実装を提出する

確認が済んでからのみ提出します。ターンごとにコードを分散させず、統合した最終メッセージを1つ提出してください。

• コードチェック：インポート、不正な入力に対するガード、実行可能な mlflow.genai.evaluate(...) 呼び出しを含め、実行可能な状態にします。
• 組み込み機能：.required_columns に基づくデータ契約を明示します。データがない場合は、別の方法に振り分けるか、今後の拡張として記載します。
• LLM ジャッジ：ドメインに合わせた実際の instructions 文字列と、テンプレート変数（{{ inputs }}、{{ outputs }}、{{ expectations }}、{{ trace }}、{{ conversation }}）、bool または "yes" / "no" の出力、ユーザーが提示した利用量でのコストを示します。必ず次の文を追加してください：「トレースと人間によるラベルが揃ったら、このジャッジを調整し、モニタリングに頼る前に判定の一致度を検証してください。」

ジャッジモデル。 model= を明示して設定し、まずは中位のモデルを使用します。例：anthropic:/claude-sonnet-4-6、openai:/gpt-4.1、または利用するプロバイダーの同等クラスのモデル。明確なケースでジャッジの判定が人間のラベルと異なる場合は、上位モデルに切り替えます。ラベル付きサンプルで一致度を測定してからでなければ、下位モデルに切り替えてはいけません。数セントの節約のために、レッドライン判定用のジャッジ（安全性、法務）を下位モデルにしてはいけません。コードによる事前フィルターですでに処理量を抑えられています。URI 形式とキーについては、agent-evaluation/references/scorers.md を正としてください。

Phase 8: 検証計画を明示してから引き継ぐ

評価スイートをどのように判定するかを決めたら、そこで止めます。評価の実行は agent-evaluation の役割であり、このスキルで重複して行ってはいけません。

まず、ユーザーがすでに持っているラベルを確認します。 新しいデータセットに人手でラベル付けすることを提案する前に、サポートチケット、苦情、インシデント報告、低評価のフィードバック、返金、エスカレーションなど、過去の失敗が記録されているかを尋ねます。実際の既知の不良ケースを使ったバックテストは、合成ラベルよりも有効で、作成コストもかかりません。そのような履歴がない場合に限り、人手でのラベル付けを提案します。

LLM ジャッジごとに、どのラベルを基準として調整するのか、また初版はドラフトであることを明記します。トーンやスタイルのような主観的な軸の調整には注意してください。過学習するおそれがあります。調整が不可能な箇所も記載してください。セッションレベルの組み込み機能では NotImplementedError が発生します。

最後に、確認済みの評価スイート、実装、v2 に向けて保留するアイデア、トレースのみのアップグレード、検証計画をまとめます。

その後、引き継ぎます。評価は自分で実行しないでください。

• agent-evaluation — スコアラーの登録、データセットの発見・作成、ドライラン、評価の実行、結果分析、反復。登録は重要です。登録されていないインラインスコアラーは mlflow scorers list に表示されず、再利用もできません。
• instrumenting-with-mlflow-tracing — Phase 2 で明らかになったトレースの不足。たとえば、ある基準で RETRIEVER が必要なのに、検索が TOOL として計装されている場合などです。

スコープの境界。 このスキルでは、何を測定し、どう実装するかを決めます。 agent-evaluation では、どう実行し、結果をどう解釈するかを決めます。データセットの準備、スコアラーの登録、評価結果の解釈を始めたら、このスキルのスコープを外れています。代わりに引き継いでください。

ドメインエキスパートによるラベル付け、Review App のラベリングセッション、または MemAlign については、references/judge-alignment.md を参照してください。作成した評価の実行は、引き続き agent-evaluation の役割です。

アンチパターン

• ユーザーのアプリや失敗ではなく、スコアラーカタログから始める。
• ユーザーが名前付きの基準に同意する前にコードを書く。話したいと言われたら、話し合ってください。
• 会話の途中で大きなコードブロックを一気に提示する。議論を深める流れが途切れます。
• それぞれがコードチェックや組み込み機能では対応できない理由を示さず、LLM ジャッジだけの評価スイートを提供する。このスキルで最もよく見られ、最もコストのかかる失敗です。
• make_judge を独自に実装する一方で、MLflow に同等の機能がある。ポリシー遵守には Guidelines、パターンのルールには RegexMatch、複数ターンの品質にはセッションレベルの組み込み機能があります。
• ルールやポリシーのチェックだけを提供し、ユーザーが目的を達成できたかを測定しない。エージェントはすべてのコンプライアンスチェックに合格しながら、利用者全員を失望させることがあります。
• 重要な成果の代わりに検証可能な代理指標（「借り手が利用可能な最良の取引を得た」の代わりに promotion_disclosed）を使い、成果レイヤーも網羅できたものとして扱う。
• より安価な実装が可能だったのに、コストへの懸念に対してサンプリングだけで答える。
• ユーザーがすでに持っているラベルを尋ねる前に、新たな人手でのラベル付けを提案する。
• ドラフトを提示せずに、質問を3つ以上続ける。
• ジャッジを書くために、内部ゲートやステートマシンについて尋ねる。
• 会話の上流で失敗が発生したのに、最終状態だけを確認する。
• データセットや predict_fn のプロトタイプで対応できるのに、トレースが整うまで作業を止める。
• 複数の基準を1つのスコアラーにまとめる。または、汎用性のない単発の例を評価する。
• デフォルトで 0.0-1.0 のスコアを使う。未定義のプレースホルダーを含むコードを使う。
• TOOL のみのトレースに RetrievalGroundedness を使う。