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

Fabric SDKを評価に使うことで、データエージェントが自然言語の質問にどれだけ応答するかプログラム的にテストできます。 シンプルなPythonインターフェースを使えば、グラウンドトゥルースの例を定義し、評価を実行し、結果を分析するなど、すべてノートブック環境内で行えます。 このプロセスにより、正確性の検証、エラーのデバッグ、そして本番環境へのデプロイ前にエージェントの改善を自信を持って行えます。

[前提条件]

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

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

Fabricデータエージェントをプログラム的に評価し始めるには、Fabricデータエージェントの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)"]
    ]
)

あるいは、既存の評価データセットがある場合は、 question と 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
try:
    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}")
except Exception as e:
    print(f"Evaluation failed: {e}")

ラン終了後、以下のテキストのような出力が表示されます。

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
summary_df = get_evaluation_summary(table_name)

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

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

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

データエージェントが各質問にどのように応答したかを詳しく知りたい場合は、 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
)

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

デフォルトでは、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 サポートと連携したり、予期しない挙動をトラブルシューティングする際にこの機能を活用してください。 ダウンロードしたファイルを確認することで、データエージェントがどのようにあなたのリクエストを処理したか、どの設定が適用されたか、そして潜在的な問題が発生した箇所を正確に確認できます。 このレベルの透明性により、デバッグやデータエージェントのパフォーマンス最適化が容易になります。

Troubleshooting

次のステップ

• Fabric データ エージェントを作成する
• Fabric データ エージェント SDK を使用する
• データ エージェント SDK の使用方法に関するサンプル ノートブックにアクセスする