评估数据代理（预览版）

2025-05-09

使用 Fabric SDK 进行评估可以编程方式测试数据代理对自然语言问题的响应程度。使用简单的 Python 接口，可以定义基本事实示例、运行评估和分析结果-全部在笔记本环境中。这有助于在将代理部署到生产环境之前验证准确性、调试错误并自信地改进代理。

先决条件

付费 F2 或更高版本的 Fabric 容量资源
Fabric 数据代理租户设置已启用。
Copilot 租户切换已启用。
启用了 AI 的跨地理位置处理。
已启用适用于 AI 的跨地理位置存储。
至少有一个以下数据源：一个仓库、一个 lakehouse、一个或多个 Power BI 语义模型，或者一个包含数据的 KQL 数据库。

安装数据代理 SDK

若要以编程方式开始评估 Fabric 数据代理，需要安装 Fabric 数据代理 Python SDK。此 SDK 提供了与数据代理交互、运行评估和日志结果所需的工具和方法。通过在笔记本中运行以下命令安装最新版本：

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

此步骤确保 SDK 中提供最新的功能和修补程序。

加载基本事实数据集

若要评估 Fabric 数据代理，需要一组示例问题以及预期答案。这些问题用于验证代理对真实查询的响应程度。

可以使用 pandas 数据帧直接在代码中定义这些问题：

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

或者，如果你有现成的评估数据集，可以从一个包含“问题”和“期望答案”列的 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 参数传递。

返回的数据帧包括聚合指标，例如正确、不正确或不清楚的响应数。此结果可帮助你快速评估代理的准确性，并确定改进方面。

获取评估摘要

返回一个数据帧，其中包含已完成评估的高级概要指标，例如正确、不正确和不确定响应的数量。

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

输入参数：

table_name（str，可选） - 包含评估摘要结果的表的名称。默认值为“evaluation_output”。
verbose（bool，可选） - 如果设置为 True，则向控制台输出评估指标的摘要。默认为 False。

返回：

DataFrame – 包含评估摘要统计信息的 pandas 数据帧，例如：
- 评估的问题总数
- 正确、错误和不清楚的结果计数
- 准确性

检查详细的评估结果

若要深入了解数据代理如何响应每个单独问题，请使用函数 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

返回一个数据帧，其中包含特定评估运行的详细结果，包括问题、预期答案、代理响应、评估状态和诊断元数据。

输入参数：

evaluation_id（str） - 必需。供评估运行检索详细信息的唯一标识符。
table_name（str，可选） - 包含评估结果的表的名称。默认为 evaluation_output。
get_all_rows（bool，可选） - 是返回评估（True）中的所有行，还是仅返回代理响应不正确或不清楚的行（False）。默认为 False。
verbose（bool，可选） - 如果设置为 True，请将评估指标的摘要输出到控制台。默认为 False。

返回：

DataFrame – 包含行级评估结果的 pandas 数据帧，包括：
- 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)

此功能在以下情况下特别有用：

你想要申请更宽松或更严格的标准来确定计为匹配项的条件。
预期答案和实际答案的格式可能有所不同，但仍在语义上等效。
你需要捕捉领域特定的细微差别，以便正确评估答案。

通过

评估数据代理（预览版）

先决条件

安装数据代理 SDK

加载基本事实数据集

评估数据代理

获取评估摘要

获取评估摘要

检查详细的评估结果

get_evaluation_details

自定义评估提示

后续步骤

反馈

其他资源