評価用ハーネス

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

クイックリファレンス

パラメーター	Type	説明
`data`	MLflow EvaluationDataset、List[Dict]、Pandas DataFrame、Spark DataFrame	テストデータ
`predict_fn`	呼び出し	アプリ(Mode 1 のみ)
`scorers`	リスト[スコアラー]	Quality メトリクス
`model_id`	str	オプションのバージョン追跡

仕組み

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

前提条件

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

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

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

2つの評価モード

Mode 1: 直接評価 (推奨)

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

利点：

スコアラーは、オフライン評価と本番運用モニタリングの間で簡単に再利用できます
アプリの実行を自動的に並列化して評価を迅速化

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

evaluate とトレースの連携

ステップ 1: 評価を実行する

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()]
)

ステップ 2: UI で結果を表示する

評価結果

Mode 2:解答用紙の評価

生成AI アプリを直接実行できない場合に、コンピュート前の出力または既存のトレースを評価用に提供します。

ユースケース

外部システムからの出力のテスト
履歴トレースの評価
異なるプラットフォーム間での出力の比較

警告

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

Avaluateと解答用紙の連携

例(入力/出力あり):

ステップ 1: 評価を実行する

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()]
)

ステップ 2: 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()]
)

Key パラメーター

Python
def mlflow.genai.evaluate(
    data: Union[pd.DataFrame, List[Dict], mlflow.genai.datasets.EvaluationDataset],
    scorers: list[mlflow.genai.scorers.Scorer],
    predict_fn: Optional[Callable[..., Any]] = None,
    model_id: Optional[str] = None,
) -> mlflow.models.evaluation.base.EvaluationResult:

`data`

次のいずれかの形式の評価データセット:

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

data 引数が DataFrame またはディクショナリのリストとして指定されている場合は、次のスキーマに従う必要があります。これは、 EvaluationDataset で使用されるスキーマと一致しています。EvaluationDatasetを使用すると、スキーマの検証が強制され、各レコードのリネージも追跡されるため、使用することをお勧めします。

フィールド	データ型	説明	アプリが `predict_fn` (モード1) に渡される場合は必須ですか？	解答用紙(モード2)を提出する場合は必要ですか?
`inputs`	`dict[Any, Any]`	`**kwargs`を使用して`predict_fn`に渡される`dict`。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`のいずれかが必要です。両方をパスすることはできません。

`predict_fn`

生成AI アプリのエントリポイント (Mode 1 のみ)。べし：

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

`scorers`

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

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

`model_id`

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

データ形式

直接評価用 (Mode 1)

フィールド	必須	説明
`inputs`	✅	辞書があなたに渡されます `predict_fn`
`expectations`	オプション	スコアラーのためのオプションのグラウンドトゥルース

答案用紙評価用(Mode 2)

オプション A - 入力と出力を提供します。

フィールド	必須	説明
`inputs`	✅	生成AI アプリへの元の入力
`outputs`	✅	アプリからのプレコンピュート出力
`expectations`	オプション	スコアラーのためのオプションのグラウンドトゥルース

オプション B - 既存のトレースを提供します。

フィールド	必須	説明
`trace`	✅	MLflow Trace オブジェクトと入力/出力
`expectations`	オプション	スコアラーのためのオプションのグラウンドトゥルース

一般的なデータ入力パターン

MLflow 評価データセットを使用して評価する (推奨)

MLflow Evaluation データセットは、本番運用に対応した評価のためのバージョン管理、リネージ追跡、および Unity Catalog 統合を提供します。

Python
import mlflow
from mlflow.genai.scorers import Correctness, Safety
from my_app import agent  # Your GenAI app with tracing

# Load versioned evaluation dataset
dataset = mlflow.genai.datasets.get_dataset("catalog.schema.eval_dataset_name")

# Run evaluation
results = mlflow.genai.evaluate(
    data=dataset,
    predict_fn=agent,
    scorers=[Correctness(), Safety()],
)

用途:

バージョン管理とリネージ追跡を備えた評価データが必要
トレースを評価レコードに簡単に変換

トレースまたはスクラッチからデータセットを作成するには、「評価データセットの構築」を参照してください。

辞書のリストで評価する

ディクショナリの単純なリストを使用して、正式な評価データセットを作成せずに迅速なプロトタイプ作成を行います。

Python
import mlflow
from mlflow.genai.scorers import Correctness, RelevanceToQuery
from my_app import agent  # Your GenAI app with tracing

# Define test data as a list of dictionaries
eval_data = [
    {
        "inputs": {"question": "What is MLflow?"},
        "expectations": {"expected_facts": ["open-source platform", "ML lifecycle management"]}
    },
    {
        "inputs": {"question": "How do I track experiments?"},
        "expectations": {"expected_facts": ["mlflow.start_run()", "log metrics", "log parameters"]}
    },
    {
        "inputs": {"question": "What are MLflow's main components?"},
        "expectations": {"expected_facts": ["Tracking", "Projects", "Models", "Registry"]}
    }
]

# Run evaluation
results = mlflow.genai.evaluate(
    data=eval_data,
    predict_fn=agent,
    scorers=[Correctness(), RelevanceToQuery()],
)

用途:

迅速なプロトタイピング
小さなデータセット(< 100 例)
アドホック開発テスト

本番運用の場合は、 MLflow Evaluation データセットに変換します。

Pandas DataFrame で評価する

PandasDataFramesCSVファイルまたは既存のデータサイエンスワークフローを操作する場合は、評価にを使用します。

Python
import mlflow
import pandas as pd
from mlflow.genai.scorers import Correctness, Safety
from my_app import agent  # Your GenAI app with tracing

# Create evaluation data as a Pandas DataFrame
eval_df = pd.DataFrame([
    {
        "inputs": {"question": "What is MLflow?"},
        "expectations": {"expected_response": "MLflow is an open-source platform for ML lifecycle management"}
    },
    {
        "inputs": {"question": "How do I log metrics?"},
        "expectations": {"expected_response": "Use mlflow.log_metric() to log metrics"}
    }
])

# Run evaluation
results = mlflow.genai.evaluate(
    data=eval_df,
    predict_fn=agent,
    scorers=[Correctness(), Safety()],
)

用途:

迅速なプロトタイピング
小さなデータセット(< 100 例)
アドホック開発テスト

Spark DataFrame を使用して評価する

Spark DataFrames は、大規模な評価や、データが既に Delta Lake/Unity Catalog にある場合に使用します。

Python
import mlflow
from mlflow.genai.scorers import Safety, RelevanceToQuery
from my_app import agent  # Your GenAI app with tracing

# Load evaluation data from a Delta table in Unity Catalog
eval_df = spark.table("catalog.schema.evaluation_data")

# Or load from any Spark-compatible source
# eval_df = spark.read.parquet("path/to/evaluation/data")

# Run evaluation
results = mlflow.genai.evaluate(
    data=eval_df,
    predict_fn=agent,
    scorers=[Safety(), RelevanceToQuery()],
)

用途:

データは Delta Lake または Unity Catalog に既に存在します
評価を実行する前に MLflow 評価データセット内のレコードをフィルター処理する必要がある場合

手記： DataFrame は、評価データセットスキーマに準拠している必要があります。

一般的な `predict_fn` パターン

アプリを直接呼び出す

パラメーター名が評価データセットのキーと一致する場合は、 predict_fn としてアプリを直接渡します。

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

# Your GenAI app that accepts 'question' as a parameter
@mlflow.trace
def my_chatbot_app(question: str) -> dict:
    # Your app logic here
    response = f"I can help you with: {question}"
    return {"response": response}

# Evaluation data with 'question' key matching the function parameter
eval_data = [
    {"inputs": {"question": "What is MLflow?"}},
    {"inputs": {"question": "How do I track experiments?"}}
]

# Pass your app directly since parameter names match
results = mlflow.genai.evaluate(
    data=eval_data,
    predict_fn=my_chatbot_app,  # Direct reference, no wrapper needed
    scorers=[RelevanceToQuery(), Safety()]
)

用途:

評価データセットの inputs

アプリを callable でラップする

評価データセットの inputsとは異なるパラメーター名やデータ構造が想定される場合は、アプリをラップします。

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

# Your existing GenAI app with different parameter names
@mlflow.trace
def customer_support_bot(user_message: str, chat_history: list = None) -> dict:
    # Your app logic here
    context = f"History: {chat_history}" if chat_history else "New conversation"
    return {
        "bot_response": f"Helping with: {user_message}. {context}",
        "confidence": 0.95
    }

# Wrapper function to translate evaluation data to your app's interface
def evaluate_support_bot(question: str, history: str = None) -> dict:
    # Convert evaluation dataset format to your app's expected format
    chat_history = history.split("|") if history else []

    # Call your app with the translated parameters
    result = customer_support_bot(
        user_message=question,
        chat_history=chat_history
    )

    # Translate output to standard format if needed
    return {
        "response": result["bot_response"],
        "confidence_score": result["confidence"]
    }

# Evaluation data with different key names
eval_data = [
    {"inputs": {"question": "Reset password", "history": "logged in|forgot email"}},
    {"inputs": {"question": "Track my order"}}
]

# Use the wrapper function for evaluation
results = mlflow.genai.evaluate(
    data=eval_data,
    predict_fn=evaluate_support_bot,  # Wrapper handles translation
    scorers=[RelevanceToQuery(), Safety()]
)

用途:

アプリのパラメーターと評価データセットの input キーの間でパラメーター名が一致しません (例: user_input と question)
データ形式の変換(文字列からリストへの変換、JSONの解析)

デプロイされたエンドポイントの評価

Databricks Agent Framework またはモデルサービングエンドポイントの場合は、to_predict_fn を使用して互換性のある予測関数を作成します。

Python
import mlflow
from mlflow.genai.scorers import RelevanceToQuery

# Create predict function for your endpoint
predict_fn = mlflow.genai.to_predict_fn("endpoints:/my-chatbot-endpoint")

# Evaluate
results = mlflow.genai.evaluate(
    data=[{"inputs": {"question": "How does MLflow work?"}}],
    predict_fn=predict_fn,
    scorers=[RelevanceToQuery()]
)

益：トレースが有効なエンドポイントからトレースを自動的に抽出し、完全な可観測性を実現します。

記録済みモデルの評価

ログに記録された MLflow モデルをラップして、評価の名前付きパラメーターとモデルの単一パラメーターインターフェイスの間で変換します。

ほとんどの記録済みモデル (PyFunc や LangChainのようなロギングフレーバーを使用するモデルなど) は 1 つの入力パラメーター (PyFunc の場合は model_inputs など) を受け入れますが、 predict_fn は評価データセットのキーに対応する名前付きパラメーターを期待します。

Python
import mlflow
from mlflow.genai.scorers import Safety

# Make sure to load your logged model outside of the predict_fn so MLflow only loads it once!
model = mlflow.pyfunc.load_model("models:/chatbot/staging")

def evaluate_model(question: str) -> dict:
    return model.predict({"question": question})

results = mlflow.genai.evaluate(
    data=[{"inputs": {"question": "Tell me about MLflow"}}],
    predict_fn=evaluate_model,
    scorers=[Safety()]
)

次のステップ

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

クイックリファレンス​

仕組み​

前提 条件​

2つの評価モード​

Mode 1: 直接評価 (推奨)​

ステップ 1: 評価を実行する​

ステップ 2: UI で結果を表示する​

Mode 2:解答用紙の評価​

ステップ 1: 評価を実行する​

ステップ 2: UI で結果を表示する​

Key パラメーター​

data​

predict_fn​

scorers​

model_id​

データ形式​

直接評価用 (Mode 1)​

答案用紙評価用(Mode 2)​

一般的なデータ入力パターン​

MLflow 評価データセットを使用して評価する (推奨)​

辞書のリストで評価する​

Pandas DataFrame で評価する​

Spark DataFrame を使用して評価する​

一般的な predict_fn パターン​

アプリを直接呼び出す​

アプリを callable でラップする​

デプロイされたエンドポイントの評価​

記録済みモデルの評価​

次のステップ​

クイックリファレンス

仕組み

前提条件

2つの評価モード

Mode 1: 直接評価 (推奨)

ステップ 1: 評価を実行する

ステップ 2: UI で結果を表示する

Mode 2:解答用紙の評価

ステップ 1: 評価を実行する

ステップ 2: UI で結果を表示する

Key パラメーター

`data`

`predict_fn`

`scorers`

`model_id`

データ形式

直接評価用 (Mode 1)

答案用紙評価用(Mode 2)

一般的なデータ入力パターン

MLflow 評価データセットを使用して評価する (推奨)

辞書のリストで評価する

Pandas DataFrame で評価する

Spark DataFrame を使用して評価する

一般的な `predict_fn` パターン

アプリを直接呼び出す

アプリを callable でラップする

デプロイされたエンドポイントの評価

記録済みモデルの評価

次のステップ