mlflow-evaluation

エージェント評価

• 依頼、プロジェクト、設定から、目的、重要な成果、既知の失敗、データ／トレースの選択、合意済みの評価者を確認します。未解決の判断事項についてのみ質問します。

• 明示された基準と実装を再利用します。評価者の設計を依頼された場合は、評価者の設計を読みます。アラインメントを依頼された場合は、評価者のアラインメントも読みます。

• 評価者のみの依頼では、評価者を作成して検証したら終了します。依頼されていない限り、データセットの作成や評価の実行は行いません。

• mlflow.genai.datasets、組み込み機能／@scorer／make_judge、およびmlflow.genai.evaluate()を使用します。並行する評価フレームワークは使用しません。

• 既存のレコード／DataFrameを受け入れ、新たに再利用可能なデータセットを作成する場合はGenAIデータセットAPIを通じて永続化します。

手順 1：セットアップを再利用し、実行モードを選択する

• MLFLOW_TRACKING_URI、MLFLOW_EXPERIMENT_ID、プロバイダーの認証情報、設定済みの評価者モデルを保持します。MLflowの両方の変数が設定されている場合は、セットアップを省略します。バックエンドの置き換え、新しい実験の作成、.envによる上書きは行いません。 設定が不足している場合は、利用可能であればmlflow-onboardingを使用します。
• プロジェクトの環境を使用します（uvで管理されているプロジェクトではuv runを使用します）。MLflowが3.8以上であることと、必要なAPIのインストール済みシグネチャを確認します。構造化された標準出力を取得する場合、標準エラー出力は分離します。
• **再実行モード：**実際のエージェントのエントリーポイントとその設定を確認します。利用可能であれば、計装にmlflow-trace-instrumentationを使用し、動作しているトレースを再利用します。代表的な呼び出しを実行し、意図した実験でトレースをフラッシュして永続化済みのトレースを取得します。トレースが欠落または破損している場合は、評価の前に修復して検証します。フレームワークのスパンを重複して追加しないでください。
• 事前計算モード：渡されたinputsとoutputs、または既存のトレースを、predict_fnなしで評価します。エージェントを呼び出したり、保存済みレコードを変更したり、置き換え用のデータセットを作成したりしないでください。評価者のデータ要件を既存の証拠と照合します。最終出力を評価する評価者には、新たな計装は必要ありません。

手順 2：評価者を再利用して登録する

• 登録済みの評価者を一覧表示します：mlflow scorers list -x "$MLFLOW_EXPERIMENT_ID"。評価者のセット、モデル、定義を再利用し、合意済みの評価者のうち不足しているものだけを追加します。

• モデルの選択、登録、取得についてはscorers.mdを読みます。評価の前に新しい評価者を登録し、意図した実験で登録を確認します。

• インストール済みのrequired_columnsとトレースの要件を確認します。Correctnessには正解データが必要です。検索評価者にはTOOLスパンだけでなく、RETRIEVERスパンが必要です。

• ブール値、数値、または"yes"／"no"を集計します。保存済みの"pass"／"fail"スコアは、集計から除外される場合があります。

• カスタム評価者を作成する場合、またはスコアが欠落している場合は、scorers-constraints.mdを読みます。

手順 3：データを見つけて関連付ける

• データを作成する前に、インストール済みのデータセット検索APIを使用します。候補を確認し、適切なデータセット、または明示的に選択されたデータセットを再利用します。検索に失敗しても、データセットが存在しないことを意味するわけではありません。
• UCでは、意図した完全修飾テーブルと、バックエンドがサポートする検索方法を使用します。選択が曖昧な場合にのみ質問します。

レコードの作成、変換、合成を行う場合は、データセットの準備を読みます。実際のレコードキーと予測関数のシグネチャを確認します。

# MLflow calls predict_fn(**record["inputs"]). Nested values stay nested.
record = {"inputs": {"query": "Where is order 42?", "context": {"order_id": 42}}}
def predict(query, context):
    return agent(query=query, context=context)  # bind project config here as needed

• データセットにその入力キーがある場合に限り、inputsをラッパー引数として受け入れます。
• 正解データはexpectationsの下に格納します。例：expectations.expected_response。複数キーの入力とソースIDは保持します。
• データの規模はタスクと網羅範囲に合わせます。100問への拡張や合成の依存関係は必須ではありません。

コーパスの合成を依頼された場合は、RAGASのレシピを使用します。

ステップ 4：ドライラン：本評価の前に必須

本実行と同じモード、ラッパー、スコアラーを使い、代表的なレコードを 3 件、またはユーザーが明示したそれより少ない件数で評価します。パイロットは 1 回だけ実施し、個別にサニティチェックやドライランを行わないでください。すべての行を確認します。

• 予測処理は完了しましたか。必要なツールや検索は実行されましたか。利用可能な出力は保存されましたか。挨拶など、ツールを必要としないケースでは、ツールを実行する必要はありません。

• 該当するすべてのスコアラーが、エラーなしで有効な評価を返しましたか。行ごとの値や根拠、集計への反映の両方を確認します。トレースや実行のステータスが成功しただけでは不十分です。

• 0、False、"no" は有効な品質評価の失敗です。 疑わしいほど均一なスコアが付いている場合は、実際の応答や、既知の良い例・悪い例と照らして調査します。合格を捏造するために、非ゼロのスコアを要求したり、評価基準を変更したりしないでください。

• 認証／ツールの失敗、予測の失敗、再実行後の応答が空、またはスコアの欠落／エラーのみが発生した場合は、本実行を開始する前に停止します。 原因を特定し、作業範囲内で修正してから、パイロットを再実施してください。

• 事前計算された壊れた出力は、証拠として保持してください。スコアが付いた低評価と、スコアラー／インフラストラクチャの障害を区別します。

• 対応している場合は、パイロットの実行 ID を保持し、パイロットとしてラベルを付けてください。ユーザーから依頼されない限り、実行を削除しないでください。

• 修正できない場合は、ブロッカーを報告してください。資格情報を捏造したり、再試行のためにプロバイダーを切り替えたりしないでください。

ステップ 5：実行と確認

• 再実行：mlflow.genai.evaluate(data=selected_data, predict_fn=predict, scorers=registered_scorers)。事前計算済みの場合は、predict_fn を省略します。
• パイロットの処理速度から所要時間を見積もります。コストの高い実行では、throughput-guide.md を読み、リソース制限とホストでサポートされている実行方法を守ってください。
• 完了まで待ちます。終了ステータス、実行 ID／URL、経過時間、行レベルのアーティファクトのパスを保持してください。起動しただけでは成功ではありません。

検証

• 対象のエクスペリメントで新しい実行が行われ、選択したすべてのレコードと該当するすべてのスコアラーについて、行レベルの結果があることを確認します。

• 出力、トレース ID、値、根拠、評価エラーを保持します。

• 評価済み、失敗、欠落、スキップ、エラーの件数を報告します。合格率の分母から欠落行を除外してはいけません。メトリクスのみの実行や、空のスコアテーブルは成功ではありません。

• 評価基準ごとに個別に要約します。代表的な失敗は証拠にリンクし、サンプル数が少ない場合の制約も明記してください。任意でレポートの概要を使用できます。

• 要約を、型付きの生スコア／エラーと照合します。生成された評価や推奨事項だけでは、根本原因を特定できません。

• 要求された動作の修正：結果を mlflow-agent-improvement に引き継ぎます。

参考資料

• インフラストラクチャ、スキーマ、またはスコアラーの障害：troubleshooting.md。

• 本番トレースのキュレーション、バージョン比較、または継続的評価： advanced-evaluation.md。

• Databricks の本番スコアリング： databricks-online-monitoring.md。登録しただけでは監視は開始されません。

• 判定者間の不一致、ドメイン専門家のラベル、Review App、または MemAlign：mlflow-evaluation と、そのアラインメントの参考資料。

• 登録済みプロンプトの最適化／GEPA：prompt-optimization.md。

• API の詳細：評価のクイックスタートまたは参考資料内の該当トピックへの正確なリンクを参照してください。インストール済みバージョンとの互換性を確認してください。

• ページが見つからない、または移動している場合：llms.txt。

• ドキュメント／スキルを利用できない場合：ローカルの指示と、インストール済み API のイントロスペクションを使用してください。正確性に関する問題が解決されない場合は停止し、その旨を説明してください。レガシー API、バックエンド、プロバイダーに黙って置き換えないでください。