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

プレビュー

この機能はパブリックプレビュー段階です。

この記事では、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_contexttraceなど)。

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

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

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

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

1回の実行のメトリクスを確認する

このセクションでは、各評価実行で使用できるメトリックについて説明します。 実行間でメトリクスを比較するには、「実行間でメトリクスを比較する」を参照してください。

リクエストごとのメトリクス

リクエストごとのメトリックは、 databricks-agentsバージョン 0.3.0 以降で使用できます。

評価セット内の各リクエストの詳細なメトリックを表示するには、 MLflow実行ページの [評価結果] タブをクリックします。このページには、各評価実行の概要表が表示されます。 詳細については、実行の評価 IDをクリックしてください。

評価実行の詳細ページには次の内容が表示されます。

  • モデル出力: エージェントアプリから生成された応答とそのトレース(含まれている場合)。

  • 期待される出力: 各要求に対して予想される応答。

  • 詳細な評価:このデータに対する LLM 審査員の評価。 [ 詳細を表示 ] をクリックして、裁判官が提示した正当な理由を表示します。

リクエストごとにメトリックス

評価セット全体にわたる集計されたメトリクス

評価セット全体の集計されたメトリクス値を表示するには、 [概要]タブ (数値の場合) または[モデル メトリクス]タブ (グラフの場合) をクリックします。

評価メトリクス、評価値
評価メトリクス、チャート

メトリクスを比較する

エージェント アプリケーションが変更にどのように反応するかを確認するには、実行間で評価結果を比較することが重要です。 結果を比較すると、変更が品質にプラスの影響を与えているかどうかを把握したり、動作の変化のトラブルシューティングに役立てたりできます。

実行ごとにリクエストごとのメトリクスを比較する

実行全体で個々のリクエストのデータを比較するには、実験ページの「評価」タブをクリックします。 評価セットの各質問を表に示します。 ドロップダウンメニューを使用して、表示する列を選択します。

評価セット内の個々の質問

実行全体で集計されたメトリクスを比較する

エクスペリメント ページから同じ集計されたメトリクスにアクセスでき、異なる実行間でこれらのメトリクスを比較することもできます。 エクスペリメントページにアクセスするには、エクスペリメントアイコンをクリックしますエクスペリメントアイコンまたは、実行した ドイツ語 セルのセル結果に表示されるリンクをクリックします。 mlflow.evaluate()

エクスペリメントページで、チャートの表示アイコン 。 これにより、選択した実行の集計されたメトリックを視覚化し、過去の実行と比較することができます。

集計結果

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

制約

マルチターン会話の場合、評価出力は会話の最後のエントリのみを記録します。