databricks-mlflow-evaluation

MLflow 3 GenAI 評価

アップストリームの mlflow/skills との適用範囲

OSS の mlflow/skills リポジトリには、汎用的な MLflow GenAI 評価ワークフロー（mlflow.genai.evaluate()、スコアラー／ジャッジ、データセット、トレーシングの設定、5 ステップの評価ループ）を扱う agent-evaluation と関連スキル（instrumenting-with-mlflow-tracing、analyze-mlflow-trace、retrieving-mlflow-traces、querying-mlflow-metrics）が含まれています。

このスキルは、そのワークフローを繰り返し説明するのではなく、その上に Databricks 固有のパターンを重ねます。以下のいずれかが必要な場合に、このスキルを使用してください。

• Unity Catalog のトレース取り込み — UC テーブルへの本番トレースの書き込み、ログベースのモニタリング（patterns-trace-ingestion.md）。
• UC SME ラベリングセッションを使用した MemAlign ジャッジの調整 — Databricks で収集したドメインエキスパートのフィードバックを基に、カスタムジャッジを調整します（patterns-judge-alignment.md）。
• optimize_prompts() GEPA ループ — UC データセット上で実行される Databricks の自動プロンプト最適化ドライバー（patterns-prompt-optimization.md）。
• Databricks 向けのスコアラー／データセットパターン — UC テーブルを基盤とするデータセット、Databricks UI でトレースにタグ付けして対象に含める方法（patterns-datasets.md、patterns-scorers.md）。

それ以外のすべてについて、つまり汎用的な mlflow.genai.evaluate() の呼び出し、スコアラーの作成パターン、Databricks 外でのデータセット作成、UC テーブルに紐付かない MLflow トレーシングの設定については、アップストリームの mlflow/skills/agent-evaluation スキルが正式な情報源であり、MLflow チームによって最新の状態に保たれています。

コードを書く前に

1. GOTCHAS.md を読む - 失敗の原因となるよくある間違いが 15 件以上記載されています
2. CRITICAL-interfaces.md を読む - 正確な API シグネチャとデータスキーマを確認します

エンドツーエンドのワークフロー

目標に応じて、以下のワークフローに従ってください。各ステップには、読むべきリファレンスファイルが示されています。

ワークフロー 1：初回評価のセットアップ

MLflow GenAI 評価が初めてのユーザー、または新しいエージェントの評価を設定するユーザー向けです。

ステップ	アクション	リファレンスファイル
1	評価対象を理解する	user-journeys.md（Journey 0: Strategy）
2	API パターンを学ぶ	GOTCHAS.md + CRITICAL-interfaces.md
3	初期データセットを作成する	patterns-datasets.md（Patterns 1-4）
4	スコアラーを選択／作成する	patterns-scorers.md + CRITICAL-interfaces.md（組み込み一覧）
5	評価を実行する	patterns-evaluation.md（Patterns 1-3）

ワークフロー 2：本番トレース → 評価データセット

本番トレースから評価データセットを構築するためのワークフローです。

ステップ	アクション	リファレンスファイル
1	トレースを検索してフィルタリングする	patterns-trace-analysis.md（MCP tools section）
2	トレースの品質を分析する	patterns-trace-analysis.md（Patterns 1-7）
3	対象に含めるトレースにタグを付ける	patterns-datasets.md（Patterns 16-17）
4	トレースからデータセットを構築する	patterns-datasets.md（Patterns 6-7）
5	期待値／正解データを追加する	patterns-datasets.md（Pattern 2）

ワークフロー 3：パフォーマンスの最適化

エージェントの実行が遅い、またはコストが高い場合のデバッグ向けです。

ステップ	アクション	リファレンスファイル
1	スパンごとのレイテンシをプロファイリングする	patterns-trace-analysis.md（Patterns 4-6）
2	トークン使用量を分析する	patterns-trace-analysis.md（Pattern 9）
3	コンテキストの問題を検出する	patterns-context-optimization.md（Section 5）
4	最適化を適用する	patterns-context-optimization.md（Sections 1-4, 6）
5	再評価して影響を測定する	patterns-evaluation.md（Pattern 6-7）

ワークフロー 4：回帰の検出

エージェントのバージョンを比較し、回帰を見つけるためのワークフローです。

ステップ	アクション	参照ファイル
1	ベースラインを確立する	patterns-evaluation.md（パターン 4：名前付き実行）
2	現在のバージョンを実行する	patterns-evaluation.md（パターン 1）
3	メトリクスを比較する	patterns-evaluation.md（パターン 6～7）
4	失敗したトレースを分析する	patterns-trace-analysis.md（パターン 7）
5	特定の失敗をデバッグする	patterns-trace-analysis.md（パターン 8～9）

ワークフロー 5：カスタムスコアラーの開発

プロジェクト固有の評価メトリクスを作成するためのワークフローです。

ステップ	アクション	参照ファイル
1	スコアラーのインターフェースを理解する	CRITICAL-interfaces.md（スコアラーのセクション）
2	スコアラーのパターンを選択する	patterns-scorers.md（パターン 4～11）
3	マルチエージェントのスコアラーの場合	patterns-scorers.md（パターン 13～16）
4	評価を使ってテストする	patterns-evaluation.md（パターン 1）

ワークフロー 6：Unity Catalog のトレース取り込みと本番環境のモニタリング

トレースを Unity Catalog に保存し、アプリケーションをインストルメント化して、本番環境の継続的なモニタリングを有効にするためのワークフローです。

ステップ	アクション	参照ファイル
1	UC スキーマを実験にリンクする	patterns-trace-ingestion.md（パターン 1～2）
2	トレースの保存先を設定する	patterns-trace-ingestion.md（パターン 3～4）
3	アプリケーションをインストルメント化する	patterns-trace-ingestion.md（パターン 5～8）
4	トレースソース（Apps/Serving/OTEL）を設定する	patterns-trace-ingestion.md（パターン 9～11）
5	本番環境のモニタリングを有効にする	patterns-trace-ingestion.md（パターン 12～13）
6	UC トレースをクエリして分析する	patterns-trace-ingestion.md（パターン 14）

ワークフロー 7：MemAlign によるジャッジの調整

LLM ジャッジをドメイン専門家の好みに合わせて調整するためのワークフローです。適切に調整されたジャッジは、評価の精度、本番環境のモニタリングシグナル、プロンプト最適化の品質など、以降のすべての用途を向上させます。このワークフローは、プロンプト最適化とは独立して、単独でも有用です。

ステップ	アクション	参照ファイル
1	make_judge を使って基本ジャッジを設計する（任意のフィードバックタイプ）	patterns-judge-alignment.md（パターン 1）
2	evaluate() を実行し、成功したトレースにタグを付ける	patterns-judge-alignment.md（パターン 2）
3	UC データセットを構築し、SME ラベリングセッションを作成する	patterns-judge-alignment.md（パターン 3）
4	ラベリングの完了後、MemAlign でジャッジを調整する	patterns-judge-alignment.md（パターン 4）
5	調整済みのジャッジを実験に登録する	patterns-judge-alignment.md（パターン 5）
6	調整済みのジャッジで再評価する（ベースライン）	patterns-judge-alignment.md（パターン 6）

ワークフロー 8：GEPA によるプロンプトの自動最適化

optimize_prompts() を使って、登録済みのシステムプロンプトを自動的に改善するためのワークフローです。任意のスコアラーと併用できますが、調整済みのジャッジ（ワークフロー 7）と組み合わせると、ドメインに最も即したシグナルが得られます。調整と最適化を組み合わせたエンドツーエンドの全体的なループについては、user-journeys.md のジャーニー 10 を参照してください。

ステップ	アクション	参照ファイル
1	最適化データセットを構築する（入力＋期待値）	patterns-prompt-optimization.md（パターン 1）
2	GEPA ＋スコアラーで optimize_prompts() を実行する	patterns-prompt-optimization.md（パターン 2）
3	新しいバージョンを登録し、条件付きで昇格させる	patterns-prompt-optimization.md（パターン 3）

リファレンスファイルのクイック参照

リファレンス	目的	読むタイミング
GOTCHAS.md	よくある間違い	コードを書く前に必ず最初に読む
CRITICAL-interfaces.md	API シグネチャ、スキーマ	評価コードを書くとき
patterns-evaluation.md	評価の実行、比較	評価を実行するとき
patterns-scorers.md	カスタムスコアラーの作成	組み込みスコアラーでは不十分なとき
patterns-datasets.md	データセットの構築	評価データを準備するとき
patterns-trace-analysis.md	トレースのデバッグ	エージェントの動作を分析するとき
patterns-context-optimization.md	トークン数／レイテンシの改善	エージェントの動作が遅い、またはコストが高いとき
patterns-trace-ingestion.md	UC トレースのセットアップ、モニタリング	トレースストレージや本番環境のモニタリングを設定するとき
patterns-judge-alignment.md	MemAlign によるジャッジの調整、ラベリングセッション、SME フィードバック	ジャッジをドメインエキスパートの好みに合わせるとき
patterns-prompt-optimization.md	GEPA による最適化：データセットの構築、optimize_prompts()、昇格	プロンプトの自動改善を実行するとき
user-journeys.md	高レベルのワークフロー、ドメインエキスパートによる最適化の全サイクル	新しい評価プロジェクトを開始するとき、または調整と最適化の全サイクルを実行するとき

重要な API 情報

• 使用するもの： mlflow.genai.evaluate()（mlflow.evaluate()ではありません）
• データ形式： {"inputs": {"query": "..."}}（ネストされた構造が必要です）
• predict_fn： **展開された kwargsを受け取ります（辞書ではありません）
• MemAlign： スコアラーに依存しません（あらゆるfeedback_value_type — float、bool、categorical — で動作します）。埋め込みモデルのトークン消費量が多いため、embedding_modelを明示的に設定してください
• ラベルスキーマ名の一致： ラベリングセッションのラベルスキーマnameは、align()がスコアを対応付けられるよう、evaluate()で使用するジャッジのnameと一致する必要があります
• 調整済みジャッジのスコア： 調整前のジャッジのスコアより低くなることがあります。これは想定どおりの動作であり、ジャッジの精度が向上したことを意味します。エージェントの性能が低下したわけではありません
• GEPA 最適化データセット： 各レコードにinputsとexpectationsの両方が必要です（評価データセットとは異なります）
• エピソード記憶： 遅延読み込みされます。ジャッジが初めて使用されるまでは、get_scorer()の結果を表示してもエピソード記憶は表示されません
• optimize_prompts： MLflow >= 3.5.0 が必要です
• UC モデルサービングのジャッジモデル： databricks:/system.ai.<model>のジャッジ／スコアラー URI には最低バージョン要件があり、404（古いクライアント）または403（レガシーエンドポイント名）が発生する場合があります。バージョン、正確なエラーメッセージ、修正方法については、GOTCHAS.md -> 「Custom Judge Model Format」を参照してください

一覧についてはGOTCHAS.mdを参照してください。

関連スキル

• databricks-docs - Databricks ドキュメント全般のリファレンス
• databricks-model-serving - モデルとエージェントのサービングエンドポイントへのデプロイ
• databricks-agent-bricks - このスキルで評価できるエージェントの構築
• databricks-python-sdk - MLflow API と併用する SDK のパターン
• databricks-unity-catalog - 管理対象の評価データセット用 Unity Catalog テーブル