評価用ハーネス

評価ハーネスは、GenAI アプリケーションのテストフレームワークとして機能します。アプリを手動で実行して出力を 1 つずつ確認する代わりに、ハーネスはテストデータを入力し、アプリを実行して、結果を自動的にスコア付けする構造化された方法を提供します。これにより、バージョンの比較、改善の追跡、チーム間での結果の共有が容易になります。

MLflowを使用すると、評価ハーネスはオフラインテストを本番運用モニタリングに接続します。つまり、開発で使用するのと同じ評価ロジックを本番運用でも実行できるため、 AIライフサイクル全体にわたって一貫した品質のビューが得られます。

mlflow.genai.evaluate()関数は、テストデータ (評価データセットとスコアラーの適用) に対して GenAI アプリを実行することで、GenAI アプリの品質を体系的にテストします。

評価を初めて行う場合は、「チュートリアル: GenAI アプリケーションの評価と改善」から始めてください。

いつ使うか

キュレーションされた評価データセットに対するアプリの夜間または週次チェック
アプリのバージョン間でのプロンプトまたはモデルの変更の検証
リリースやPRの前に品質の低下を防ぐ

プロセスワークフロー

評価ハーネスは次のことを行います。

テスト入力でアプリを実行し、トレースをキャプチャします。
スコアラーを適用して品質を評価し、フィードバックを作成します。
評価実行の結果を保存します。

クイックリファレンス

API の詳細については、 mlflow.genai.evaluate()のパラメーターまたはMLflow ドキュメントを参照してください。

mlflow.genai.evaluate()関数は、指定されたスコアラーとオプションで予測関数またはモデル ID を使用して、評価データセットに対して GenAI アプリを実行し、 EvaluationResultを返します。

Python
def mlflow.genai.evaluate(
    data: Union[pd.DataFrame, List[Dict], mlflow.genai.datasets.EvaluationDataset],  # Test data.
    scorers: list[mlflow.genai.scorers.Scorer],  # Quality metrics, built-in or custom.
    predict_fn: Optional[Callable[..., Any]] = None,  # App wrapper. Used for direct evaluation only.
    model_id: Optional[str] = None,  # Optional version tracking.
) -> mlflow.models.evaluation.base.EvaluationResult:

前提条件

MLflow と必要なパッケージをインストールします。

Bash
pip install --upgrade "mlflow[databricks]>=3.1.0" openai "databricks-connect>=16.1"

MLflow エクスペリメントを作成するには、環境のセットアップに関するクイックスタートに従ってください。

（オプション）並列化を構成する

MLflow はデフォルトでバックグラウンドスレッドプールを使用して評価プロセスを高速化します。ワーカーの数を構成するには、環境変数MLFLOW_GENAI_EVAL_MAX_WORKERSを設定します。

Bash
export MLFLOW_GENAI_EVAL_MAX_WORKERS=10

評価モード

評価モードには、次の 2 つがあります。

直接評価（推奨）。MLflow はアプリを直接呼び出して、評価用のトレースを生成します。
解答用紙の評価。コンピュート前の出力または既存のトレースを評価用に提供します。

直接評価(推奨)

MLflow は GenAI アプリを直接呼び出して、トレースを生成および評価します。Python関数 ( predict_fn ) でラップされたアプリケーションのエントリポイントを渡すか、アプリがDatabricksモデルサービスエンドポイントとしてデプロイされている場合は、そのエンドポイントをto_predict_fnでラップして渡すことができます。

このモードでは、アプリを直接呼び出すことで、オフライン評価用に定義されたスコアラーを本番運用モニタリングで再利用できます。これは、結果のトレースが同一になるためです。

図に示すように、データ、アプリ、選択したスコアラーがmlflow.genai.evaluate()への入力として提供され、アプリとスコアラーが並行して実行され、出力がトレースとフィードバックとして記録されます。

評価とトレースの連携

直接評価のためのデータ形式

スキーマの詳細については、評価データセットリファレンスを参照してください。

フィールド	データ型	必須	説明
`inputs`	`dict[Any, Any]`	はい	辞書があなたに渡されます `predict_fn`
`expectations`	`dict[str, Any]`	No	スコアラーのためのオプションのグラウンドトゥルース

直接評価を使用した例

次のコードは、評価を実行する方法の例を示しています。

Python
import mlflow
from mlflow.genai.scorers import RelevanceToQuery, Safety

# Your GenAI app with MLflow tracing
@mlflow.trace
def my_chatbot_app(question: str) -> dict:
    # Your app logic here
    if "MLflow" in question:
        response = "MLflow is an open-source platform for managing ML and GenAI workflows."
    else:
        response = "I can help you with MLflow questions."

    return {"response": response}

# Evaluate your app
results = mlflow.genai.evaluate(
    data=[
        {"inputs": {"question": "What is MLflow?"}},
        {"inputs": {"question": "How do I get started?"}}
    ],
    predict_fn=my_chatbot_app,
    scorers=[RelevanceToQuery(), Safety()]
)

その後、UI で結果を表示できます。

評価結果

解答用紙の評価

評価中に GenAI アプリを直接実行できない、または実行したくない場合は、このモードを使用します。たとえば、すでに出力 (外部システム、履歴トレース、バッチジョブなど) があり、それらにスコアを付けたいとします。入力と出力、およびハーネス実行スコアラーを提供し、評価実行をログに記録します。

important

本番運用環境と異なるトレースを持つ解答用紙を使用している場合、本番運用モニタリングに利用するためには、スコアラー関数の書き換えが必要になることがあります。

図に示すように、評価データと選択したスコアラーをmlflow.genai.evaluate()への入力として提供します。評価データは、既存のトレース、または入力とコンピュート前の出力で構成されます。入力と事前コンピュート出力が指定されている場合、 mlflow.genai.evaluate()入力と出力からトレースを構築します。どちらの入力オプションでも、 mlflow.genai.evaluate()トレース上でスコアラーを実行し、スコアラーからのフィードバックを出力します。

評価と解答用紙の連携

解答用紙評価のためのデータ形式

スキーマの詳細については、評価データセットリファレンスを参照してください。

入力と出力が提供されている場合

フィールド	データ型	必須	説明
`inputs`	`dict[Any, Any]`	はい	生成AI アプリへの元の入力
`outputs`	`dict[Any, Any]`	はい	アプリからのプレコンピュート出力
`expectations`	`dict[str, Any]`	No	スコアラーのためのオプションのグラウンドトゥルース

既存のトレースが提供されている場合

フィールド	データ型	必須	説明
`trace`	`mlflow.entities.Trace`	はい	MLflow Trace オブジェクトと入力/出力
`expectations`	`dict[str, Any]`	No	スコアラーのためのオプションのグラウンドトゥルース

入力と出力の使用例

次のコードは、評価を実行する方法の例を示しています。

Python
import mlflow
from mlflow.genai.scorers import Safety, RelevanceToQuery

# Pre-computed results from your GenAI app
results_data = [
    {
        "inputs": {"question": "What is MLflow?"},
        "outputs": {"response": "MLflow is an open-source platform for managing machine learning workflows, including tracking experiments, packaging code, and deploying models."},
    },
    {
        "inputs": {"question": "How do I get started?"},
        "outputs": {"response": "To get started with MLflow, install it using 'pip install mlflow' and then run 'mlflow ui' to launch the web interface."},
    }
]

# Evaluate pre-computed outputs
evaluation = mlflow.genai.evaluate(
    data=results_data,
    scorers=[Safety(), RelevanceToQuery()]
)

その後、UI で結果を表示できます。

評価結果

既存のトレースの使用例

次のコードは、既存のトレースを使用して評価を実行する方法を示しています。

Python
import mlflow

# Retrieve traces from production
traces = mlflow.search_traces(
    filter_string="trace.status = 'OK'",
)

# Evaluate problematic traces
evaluation = mlflow.genai.evaluate(
    data=traces,
    scorers=[Safety(), RelevanceToQuery()]
)

のための争点 `mlflow.genai.evaluate()`

このセクションでは、 mlflow.genai.evaluate()で使用される各問題について説明します。

Python
def mlflow.genai.evaluate(
    data: Union[pd.DataFrame, List[Dict], mlflow.genai.datasets.EvaluationDataset],  # Test data.
    scorers: list[mlflow.genai.scorers.Scorer],  # Quality metrics, built-in or custom.
    predict_fn: Optional[Callable[..., Any]] = None,  # App wrapper. Used for direct evaluation only.
    model_id: Optional[str] = None,  # Optional version tracking.
) -> mlflow.models.evaluation.base.EvaluationResult:

`data`

評価データセットは、次のいずれかの形式である必要があります。

EvaluationDataset (推奨)。
ディクショナリ、Pandas DataFrame、または Spark DataFrame のリスト。

データ引数が DataFrame または辞書のリストとして提供される場合は、次のスキーマに従う必要があります。これは、 EvaluationDataset で使用されるスキーマと一致しています。Databricks では、各レコードのリネージを追跡することに加えて、スキーマの検証を強制する EvaluationDataset を使用することをお勧めします。

フィールド	データ型	説明	直接評価で使用	解答用紙と併用
`inputs`	`dict[Any, Any]`	を使用して`predict_fn`に渡される`dict` `**kwargs`。JSON シリアル化可能である必要があります。各キーは、 `predict_fn`の名前付き引数に対応する必要があります。	必須	`inputs`+`outputs`または`trace`のいずれかが必要です。両方をパスすることはできません。指定されていない場合は `trace` から派生します。
`outputs`	`dict[Any, Any]`	対応する`input`の生成AI アプリの出力を含む`dict`。JSON シリアル化可能である必要があります。	トレースから MLflow によって生成された、指定しないでください。	`inputs`+`outputs`または`trace`のいずれかが必要です。両方をパスすることはできません。指定されていない場合は `trace` から派生します。
`expectations`	`dict[str, Any]`	に対応するグラウンドトゥルースラベルを持つ `dict` `input`。`scorers`が品質をチェックするために使用されます。JSON シリアル化可能であり、各キーは `str`である必要があります。	オプション	オプション
`trace`	`mlflow.entities.Trace`	要求のトレースオブジェクト。`trace`が指定されている場合、`expectations`は、個別の列としてではなく、`trace`上の`Assessments`として提供できます。	トレースから MLflow によって生成された、指定しないでください。	`inputs`+`outputs`または`trace`のいずれかが必要です。両方をパスすることはできません。

`scorers`

適用する品質メトリクスの一覧です。次のものを提供できます。

詳細はスコアラーをご覧ください。

`predict_fn`

生成 AI アプリのエントリポイント。このパラメータは、直接評価でのみ使用されます。 predict_fn 次の要件を満たす必要があります。

data の inputs ディクショナリのキーをキーワード引数として受け入れます。
JSON シリアル化可能なディクショナリを返します。
MLflow Tracingで計測可能にされています。
呼び出しごとに 1 つのトレースを出力します。

`model_id`

結果をアプリのバージョンにリンクするためのオプションのモデル識別子(例: "models:/my-app/1")。詳細については、バージョン追跡を参照してください。

次のステップ

アプリを評価する - 最初の評価を実行するためのステップバイステップガイド。
評価データセットの構築 - 本番運用ログまたはスクラッチから構造化テストデータを作成します。
カスタムスコアラーの定義 - ビルドメトリクス特定のユースケースに合わせたもの。

いつ使うか​

プロセスワークフロー​

クイックリファレンス​

前提 条件​

（オプション）並列化を構成する​

評価モード​

直接評価(推奨)​

直接評価のためのデータ形式​

直接評価を使用した例​

解答用紙の評価​

解答用紙評価のためのデータ形式​

入力と出力の使用例​

既存のトレースの使用例​

のための争点 mlflow.genai.evaluate()​

data​

scorers​

predict_fn​

model_id​

次のステップ​