データエージェントを評価する (プレビュー)

Fabric SDK を使用した評価では、Data Agent が自然言語の質問にどの程度反応するかをプログラムでテストできます。シンプルなPython インターフェイスを使用すると、ノートブック環境内で、地上の真実の例を定義し、評価を実行し、結果を分析できます。これにより、精度を検証し、エラーをデバッグし、エージェントを運用環境にデプロイする前に自信を持って改善することができます。

Von Bedeutung

この機能はプレビュー段階です。

[前提条件]

F2以上の有料Fabric容量、またはMicrosoft Fabricが有効なPower BI Premium per capacity（P1以上）容量。
Fabric データエージェントのテナント設定で説明されている要件に基づいて、AI用のクロスジオ処理およびクロスジオ格納を有効にします。
データを含む少なくとも 1 つのデータソース:ウェアハウス、レイクハウス、Power BI セマンティックモデル、KQL データベース、ミラー化されたデータベース、またはオントロジ。データソースへの読み取りアクセス権が必要です。

データエージェント SDK をインストールする

Fabric Data Agent のプログラムによる評価を開始するには、 Fabric Data Agent Python SDK をインストールする必要があります。この SDK には、データエージェントとの対話、評価の実行、結果のログ記録に必要なツールとメソッドが用意されています。ノートブックで次のコマンドを実行して、最新バージョンをインストールします。

%pip install -U fabric-data-agent-sdk

この手順により、SDK で最も up-to最新の機能と修正プログラムを利用できるようになります。

グラウンドトゥルースデータセットを読み込む

Fabric データエージェントを評価するには、一連のサンプル質問と予想される回答が必要です。これらの質問は、エージェントが実際のクエリにどの程度正確に応答するかを確認するために使用されます。

pandas DataFrame を使用して、コード内でこれらの質問を直接定義できます。

import pandas as pd

# Define a sample evaluation set with user questions and their expected answers.
# You can modify the question/answer pairs to match your scenario.
df = pd.DataFrame(
    columns=["question", "expected_answer"],
    data=[
        ["Show total sales for Canadian Dollar for January 2013", "46,117.30"],
        ["What is the product with the highest total sales for Canadian Dollar in 2013", "Mountain-200 Black, 42"],
        ["Total sales outside of the US", "19,968,887.95"],
        ["Which product category had the highest total sales for Canadian Dollar in 2013", "Bikes (Total Sales: 938,654.76)"]
    ]
)

または、既存の評価データセットがある場合は、列の質問とexpected_answerを含む CSV ファイルから読み込むことができます。

# Load questions and expected answers from a CSV file
input_file_path = "/lakehouse/default/Files/Data/Input/curated_2.csv"
df = pd.read_csv(input_file_path)

このデータセットは、データエージェントに対して自動評価を実行して精度とカバレッジを評価するための入力として機能します。

データエージェントの評価と査定

次の手順では、 evaluate_data_agent 関数を使用して評価を実行します。この関数は、エージェントの応答を予想される結果と比較し、評価メトリックを格納します。

from fabric.dataagent.evaluation import evaluate_data_agent

# Name of your Data Agent
data_agent_name = "AgentEvaluation"

# (Optional) Name of the workspace if the Data Agent is in a different workspace
workspace_name = None

# (Optional) Name of the output table to store evaluation results (default: "evaluation_output")
# Two tables will be created:
# - "<table_name>": contains summary results (e.g., accuracy)
# - "<table_name>_steps": contains detailed reasoning and step-by-step execution
table_name = "demo_evaluation_output"

# Specify the Data Agent stage: "production" (default) or "sandbox"
data_agent_stage = "production"

# Run the evaluation and get the evaluation ID
evaluation_id = evaluate_data_agent(
    df,
    data_agent_name,
    workspace_name=workspace_name,
    table_name=table_name,
    data_agent_stage=data_agent_stage
)

print(f"Unique ID for the current evaluation run: {evaluation_id}")

評価の概要を取得する

評価を実行した後、 get_evaluation_summary 関数を使用して結果の概要を取得できます。この関数は、予想される回答に一致した応答の数などのメトリックなど、データエージェント全体のパフォーマンスに関する分析情報を提供します。

from fabric.dataagent.evaluation import get_evaluation_summary

# Retrieve a summary of the evaluation results
df = get_evaluation_summary(table_name)

既定では、この関数は evaluation_output という名前のテーブルを検索します。評価時にカスタムテーブル名 ("demo_evaluation_output" など) を指定した場合は、その名前を table_name 引数として渡します。

返される DataFrame には、正しい応答、正しくない応答、不明な応答の数などの集計メトリックが含まれます。この結果は、エージェントの精度をすばやく評価し、改善のための領域を特定するのに役立ちます。

get_evaluation_summary

正しい応答、正しくない応答、不明な応答の数など、完了した評価実行の概要メトリックを含む DataFrame を返します。

get_evaluation_summary(table_name='evaluation_output', verbose=False)

入力パラメーター:

table_name (str、省略可能) – 評価の概要結果を含むテーブルの名前。既定値は 'evaluation_output' です。
verbose (ブール値、省略可能) – Trueに設定されている場合は、評価メトリックの概要をコンソールに出力します。既定値は False です。

戻り値:

DataFrame – 評価の概要統計を含む Pandas DataFrame。例として次のようなものが含まれます。
- 評価された質問の合計数
- 真、偽、不明確な結果数
- 精度

詳細な評価結果を検査する

個々の質問に対して Data Agent がどのように応答したかを詳しく調べるには、 get_evaluation_details 関数を使用します。この関数は、実際のエージェント応答、予想される回答と一致したかどうか、評価スレッドへのリンク (評価を実行したユーザーにのみ表示される) など、評価実行の詳細な内訳を返します。

from fabric.dataagent.evaluation import get_evaluation_details

# Table name used during evaluation
table_name = "demo_evaluation_output"

# Whether to return all evaluation rows (True) or only failures (False)
get_all_rows = False

# Whether to print a summary of the results
verbose = True

# Retrieve evaluation details for a specific run
eval_details = get_evaluation_details(
    evaluation_id,
    table_name,
    get_all_rows=get_all_rows,
    verbose=verbose
)

get_evaluation_details

質問、予想される回答、エージェントの応答、評価状態、診断メタデータなど、特定の評価実行の詳細な結果を含む DataFrame を返します。

入力パラメーター:

evaluation_id (str) – 必須。詳細を取得するための評価実行の一意識別子。
table_name (str、省略可能) – 評価結果を含むテーブルの名前。既定値は evaluation_output です。
get_all_rows (ブール値、省略可能) – 評価からすべての行を返すか (True) か、エージェントの応答が正しくないか不明な行のみを返すか (False)。既定値は False です。
verbose (ブール値、省略可能) – True に設定すると、評価メトリックの概要がコンソールに出力されます。既定値は False です。

戻り値:

DataFrame – 行レベルの評価結果を含む pandas DataFrame（以下を含む）。
- question
- expected_answer
- actual_answer
- evaluation_result (true、 false、 unclear)
- thread_url (評価を実行したユーザーのみがアクセスできます)

評価のプロンプトをカスタマイズする

既定では、Fabric SDK は組み込みのプロンプトを使用して、データエージェントの実際の回答が予想される回答と一致するかどうかを評価します。ただし、 critic_prompt パラメーターを使用して、より微妙な評価やドメイン固有の評価を求める独自のプロンプトを指定できます。

カスタムプロンプトには、プレースホルダー {query}、 {expected_answer}、 {actual_answer}が含まれている必要があります。これらのプレースホルダーは、評価中に各質問に動的に置き換えます。

from fabric.dataagent.evaluation import evaluate_data_agent

# Define a custom prompt for evaluating agent responses
critic_prompt = """
    Given the following query, expected answer, and actual answer, please determine if the actual answer is equivalent to expected answer. If they are equivalent, respond with 'yes'.

    Query: {query}

    Expected Answer:
    {expected_answer}

    Actual Answer:
    {actual_answer}

    Is the actual answer equivalent to the expected answer?
"""

# Name of the Data Agent
data_agent_name = "AgentEvaluation"

# Run evaluation using the custom critic prompt
evaluation_id = evaluate_data_agent(df, data_agent_name, critic_prompt=critic_prompt)

この機能は、次の場合に特に便利です。

一致としてカウントされる条件を、より緩やかまたは厳密に適用する必要があります。
予想される回答と実際の回答の形式は異なる場合がありますが、意味的には同等です。
回答の判断方法について、ドメイン固有の微妙な違いを把握する必要があります。

[診断] ボタン

[ 診断 ] ボタンを使用すると、 データエージェントの構成と実行手順の完全なスナップショットをダウンロードできます。このエクスポートには、データソースの設定、適用された手順、使用されるクエリの例、データエージェントが応答を生成するために実行した基になる手順などの詳細が含まれます。

この機能は、Microsoft サポートを操作する場合や、予期しない動作のトラブルシューティングを行う場合に使用します。ダウンロードしたファイルを確認すると、Data Agent が要求をどのように処理したか、どの構成が適用されたか、潜在的な問題が発生した可能性がある場所を正確に確認できます。このレベルの透明性により、データエージェントのパフォーマンスのデバッグと最適化が容易になります。

次のステップ

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-04-22