評価を実行して結果を表示する方法

プレビュー

この記事では、Mosaic AIエージェント評価を使用して評価を実行し、結果を表示する方法について説明します。

評価を実行するには、評価セットを指定する必要があります。評価セットは、ユーザーがエージェント・アプリケーションに対して行う一般的なリクエストのセットです。評価セットには、各入力要求に対して予想される出力を含めることもできます。評価セットの目的は、代表的な質問でエージェント・アプリケーションをテストすることにより、エージェント・アプリケーションのパフォーマンスを測定および予測できるようにすることです。

必要なスキーマなど、評価セットの詳細については、「評価セット」を参照してください。

評価を開始するには、MLflow API のmlflow.evaluate()メソッドを使用します。 mlflow.evaluate()評価セット内の各入力の品質、レイテンシ、コストのメトリクスと、すべての入力にわたる集計メトリクス。これらのメトリクスは評価結果とも呼ばれます。次のコードは、 mlflow.evaluate()を呼び出す例を示しています。

%pip install databricks-agents
dbutils.library.restartPython()

import mlflow
import pandas as pd

eval_df = pd.DataFrame(...)

# Puts the evaluation results in the current Run, alongside the logged model parameters
with mlflow.start_run():
        logged_model_info = mlflow.langchain.log_model(...)
        mlflow.evaluate(data=eval_df, model=logged_model_info.model_uri,
                       model_type="databricks-agent")

この例では、 mlflow.evaluate() 、他のコマンドによって記録された情報 (モデルパラメーターなど) とともに、その評価結果を MLflow 実行で記録します。 MLflow 実行の外部でmlflow.evaluate()を呼び出すと、新しい実行が開始され、その実行の評価結果がログに記録されます。実行で記録される評価結果の詳細など、mlflow.evaluate() の詳細については、 MLflowドキュメントを参照してください。

要件

パートナーが提供するAI 支援機能をワークスペースで有効にする必要があります。

評価実行に入力する方法

評価実行に意見を提供する方法は2つあります。

アプリケーションを入力引数として渡します。 mlflow.evaluate() 、評価セット内の各入力に対してアプリケーションを呼び出し、生成された出力に対してコンピュートメトリックを実行します。このオプションは、 MLflow トレースを有効にして MLflow を使用してアプリケーションがログに記録された場合、またはアプリケーションがノートブック内の Python 関数として実装されている場合に推奨されます。
以前に生成された出力を指定して、評価セットと比較します。 このオプションは、アプリケーションがDatabricksの外部で開発された場合、本番運用に既にデプロイされているアプリケーションからの出力を評価する場合、または評価構成間で評価結果を比較する場合に推奨されます。

次のコードサンプルは、各メソッドの最小限の例を示しています。評価セットスキーマの詳細については、「評価セットスキーマ」を参照してください。

mlflow.evaluate() 呼び出しで出力を生成するには、次のコードに示すように、関数呼び出しで評価セットとアプリケーションを指定します。より詳細な例については、「例: エージェント評価によるアプリケーションの実行」を参照してください。
```
evaluation_results = mlflow.evaluate(
    data=eval_set_df,  # pandas Dataframe containing just the evaluation set
    model=model,  # Reference to the MLflow model that represents the application
    model_type="databricks-agent",
)
```
以前に生成された出力を提供するには、次のコードに示すように評価セットのみを指定しますが、生成された出力が含まれていることを確認してください。より詳細な例については、「例：以前に生成された出力が提供される」を参照してください。
```
evaluation_results = mlflow.evaluate(
    data=eval_set_with_chain_outputs_df,  # pandas Dataframe with the evaluation set and application outputs
    model_type="databricks-agent",
)
```

評価結果

評価では、次の2種類の出力が生成されます。

評価セット内の各リクエストに関するデータ（以下を含む）。
- エージェント・アプリケーションに送信される入力。
- アプリケーションの出力 response
- アプリケーションによって生成されるすべての中間データ( retrieved_context、 traceなど)。
- Databricks 指定および顧客指定の各 LLM 審査員からの評価と根拠。評価は、正確性、接地性、検索精度など、アプリケーション出力のさまざまな品質側面を特徴付けます。
- アプリケーションのトレースを基にしたその他のメトリック（さまざまなステップのレイテンシやトークン数など）。
平均トークン数と合計トークン数、平均レイテンシなど、評価セット全体の集計されたメトリクス値。

これら2種類の出力はmlflow.evaluate()から返され、MLflow実行時にも記録されます。ノートブック内または対応するMLflow実行のページから出力を検査できます。

ノートブックの出力を確認する

次のコードは、ノートブックから実行された評価の結果を確認する方法の例を示しています。

%pip install databricks-agents pandas
dbutils.library.restartPython()

import mlflow
import pandas as pd

###
# Run evaluation
###
evaluation_results = mlflow.evaluate(..., model_type="databricks-agent")

###
# Access aggregated metric values across the entire evaluation set
###
metrics_as_dict = evaluation_results.metrics
metrics_as_pd_df = pd.DataFrame([evaluation_results.metrics])

# Sample usage
print(f"The percentage of generated responses that are grounded: {metrics_as_dict['response/llm_judged/groundedness/percentage']}")


###
# Access data about each question in the evaluation set
###

per_question_results_df = evaluation_results.tables['eval_results']

# Show information about responses that are not grounded
per_question_results_df[per_question_results_df["response/llm_judged/groundedness/rating"] == "no"].display()

リクエストごとのデータフレームには、入力スキーマ内のすべての列と、各リクエストに固有のすべてのコンピュートメトリックが含まれます。報告された各メトリクスの詳細については、「エージェントメトリクスとLLM審査員を使用してアプリのパフォーマンスを評価する」を参照してください。

MLflow UIを使用して出力を確認する

評価の結果は、MLflow UIでも確認できます。MLflow UIにアクセスするには、ノートブックの右サイドバーにあるエクスペリメントアイコンをクリックするか、mlflow.evaluate()を実行したノートブックセルのセル結果に表示されるリンクをクリックします。

評価セット全体にわたる集計メトリクス（MLflow UI）

評価セット全体の集計メトリクス値を確認するには、エクスペリメントページをクリックしてください。これにより、選択した実行のメトリクスを視覚化し、過去の実行と比較することができます。

また、「概要」タブ（数値用）または「モデルメトリクス」タブ（グラフ用）を使用して、実行ページから集計されたメトリクス値を確認することもできます。

概要タブの集計メトリクス

モデルメトリクスタブの集計メトリクス

評価セット内の各リクエストに関するデータ（MLflow UI）

評価セットに含まれる個別のリクエストのデータを表示するには、エクスペリメントページの「評価」タブをクリックします。表には、評価セットの各質問が示されています。ドロップダウンメニューを使用して、表示する列を選択します。

また、実行ページから結果を確認することもできます。「アーティファクト」タブをクリックし、eval_results.json アーティファクトを選択します。

`mlflow.evaluate()`呼び出しの例

このセクションには、 mlflow.evaluate() 呼び出しのコードサンプルが含まれており、アプリケーションと評価セットを呼び出しに渡すためのオプションを示します。

例: エージェント評価がアプリケーションを実行する

%pip install databricks-agents pandas
dbutils.library.restartPython()

import mlflow
import pandas as pd

###
# mlflow.evaluate() call
###
evaluation_results = mlflow.evaluate(
    data=eval_set_df,  # pandas DataFrame with just the evaluation set
    model=model,  # Reference to the application
    model_type="databricks-agent",
)

###
# There are 4 options for passing an application in the `model` argument.
####

#### Option 1. Reference to a Unity Catalog registered model
model = "models:/catalog.schema.model_name/1"  # 1 is the version number

#### Option 2. Reference to a MLflow logged model in the current MLflow Experiment
model = "runs:/6b69501828264f9s9a64eff825371711/chain"
# `6b69501828264f9s9a64eff825371711` is the run_id, `chain` is the artifact_path that was
# passed when calling mlflow.xxx.log_model(...).
# If you called model_info = mlflow.langchain.log_model() or mlflow.pyfunc.log_model(), you can access this value using `model_info.model_uri`.

#### Option 3. A PyFunc model that is loaded in the notebook
model = mlflow.pyfunc.load_model(...)

#### Option 4. A local function in the notebook
def model_fn(model_input):
  # code that implements the application
  response = 'the answer!'
  return response

model = model_fn

###
# `data` is a pandas DataFrame with your evaluation set.
# These are simple examples. See the input schema for details.
####

# You do not have to start from a dictionary - you can use any existing pandas or
# Spark DataFrame with this schema.

# Minimal evaluation set
bare_minimum_eval_set_schema = [
    {
        "request": "What is the difference between reduceByKey and groupByKey in Spark?",
    }]

# Complete evaluation set
complete_eval_set_schema = [
    {
        "request_id": "your-request-id",
        "request": "What is the difference between reduceByKey and groupByKey in Spark?",
        "expected_retrieved_context": [
            {
                # In `expected_retrieved_context`, `content` is optional, and does not provide any additional functionality.
                "content": "Answer segment 1 related to What is the difference between reduceByKey and groupByKey in Spark?",
                "doc_uri": "doc_uri_2_1",
            },
            {
                "content": "Answer segment 2 related to What is the difference between reduceByKey and groupByKey in Spark?",
                "doc_uri": "doc_uri_2_2",
            },
        ],
        "expected_response": "There's no significant difference.",
    }]

#### Convert dictionary to a pandas DataFrame
eval_set_df = pd.DataFrame(bare_minimum_eval_set_schema)

#### Use a Spark DataFrame
import numpy as np
spark_df = spark.table("catalog.schema.table") # or any other way to get a Spark DataFrame
eval_set_df = spark_df.toPandas()

例：以前に生成された出力が提供された場合

必要な評価セットスキーマについては、評価セットを参照してください。

%pip install databricks-agents pandas
dbutils.library.restartPython()

import mlflow
import pandas as pd

###
# mlflow.evaluate() call
###
evaluation_results = mlflow.evaluate(
    data=eval_set_with_app_outputs_df,  # pandas Dataframe with the evaluation set and application outputs
    model_type="databricks-agent",
)

###
# `data` is a pandas DataFrame with your evaluation set and outputs generated by the application.
# These are simple examples. See the input schema for details.
####

# You do not have to start from a dictionary - you can use any existing pandas or
# Spark DataFrame with this schema.

# Bare minimum data
bare_minimum_input_schema = [
    {
        "request": "What is the difference between reduceByKey and groupByKey in Spark?",
        "response": "reduceByKey aggregates data before shuffling, whereas groupByKey shuffles all data, making reduceByKey more efficient.",
    }]

complete_input_schema  = [
    {
        "request_id": "your-request-id",
        "request": "What is the difference between reduceByKey and groupByKey in Spark?",
        "expected_retrieved_context": [
            {
                # In `expected_retrieved_context`, `content` is optional, and does not provide any additional functionality.
                "content": "Answer segment 1 related to What is the difference between reduceByKey and groupByKey in Spark?",
                "doc_uri": "doc_uri_2_1",
            },
            {
                "content": "Answer segment 2 related to What is the difference between reduceByKey and groupByKey in Spark?",
                "doc_uri": "doc_uri_2_2",
            },
        ],
        "expected_response": "There's no significant difference.",
        "response": "reduceByKey aggregates data before shuffling, whereas groupByKey shuffles all data, making reduceByKey more efficient.",
        "retrieved_context": [
            {
                # In `retrieved_context`, `content` is optional. If provided, the Databricks Context Relevance LLM Judge is executed to check the `content`'s relevance to the `request`.
                "content": "reduceByKey reduces the amount of data shuffled by merging values before shuffling.",
                "doc_uri": "doc_uri_2_1",
            },
            {
                "content": "groupByKey may lead to inefficient data shuffling due to sending all values across the network.",
                "doc_uri": "doc_uri_6_extra",
            },
        ],
    }]

#### Convert dictionary to a pandas DataFrame
eval_set_with_app_outputs_df = pd.DataFrame(bare_minimum_input_schema)

#### Use a Spark DataFrame
import numpy as np
spark_df = spark.table("catalog.schema.table") # or any other way to get a Spark DataFrame
eval_set_with_app_outputs_df = spark_df.toPandas()