使用 Fabric 数据代理（预览版）

2025-05-19

Microsoft Fabric 中的数据代理将企业数据转换为聊天式 Q&A 系统。它使用户能够通过聊天与其数据交互，以发现可作的见解。使用 Fabric 数据代理的一种方法是通过 Azure AI 代理服务（Azure AI Foundry 的核心组件）。通过将 Fabric 数据代理与 Azure AI Foundry 集成，Azure AI 代理可以直接利用 Microsoft Fabric OneLake 中提供的丰富、结构化的语义数据。此集成提供对高质量企业数据的即时访问，并使 Azure AI 代理能够生成可行的见解并简化分析工作流。然后，组织可以使用 Fabric 数据代理作为其 Azure AI 环境中的强大知识源来增强数据驱动的决策。

重要

此功能以预览版提供。应使用 Azure AI 代理 Python SDK 的最新 beta/预览版。

先决条件

付费 F2 或更高版本的 Fabric 容量资源
Fabric 数据代理租户设置已启用。
Copilot 租户切换已启用。
启用了 AI 的跨地理位置处理。
已启用适用于 AI 的跨地理位置存储。
至少有一个以下资源：一个仓库、一个 lakehouse、一个或多个 Power BI 语义模型，或者一个包含数据的 KQL 数据库。
已为 Power BI 语义模型数据源启用通过 XMLA 终结点的 Power BI 语义模型租户切换。
在 Azure AI Foundry 中，开发人员和最终用户必须至少具有 AI Developer 基于角色的访问控制 (RBAC) 角色。

工作原理

代理设置：在 Azure AI 代理服务中，创建新的代理，并将 Fabric 数据代理添加为其知识源之一。若要建立此连接，需要 Fabric 数据代理具有工作区 ID 和项目 ID。安装程序使 Azure AI 代理能够在收到查询时评估可用的源，以确保它调用正确的工具来处理请求。目前，只能将一个 Fabric 数据代理作为知识源添加到 Azure AI 代理。

注释

在 Azure AI 代理设置中选择的模型仅用于 Azure AI 代理业务流程和响应生成。它不会影响 Fabric 数据代理使用的模型。

查询处理：当用户从 Foundry工具台发送查询时，Azure AI 代理服务确定 Fabric 数据代理是否为执行该任务的最佳工具。如果是，则 Azure AI 代理会：

使用最终用户的标识对用户有权从 Fabric 数据代理中访问的数据源生成安全查询。
调用 Fabric 来提取和处理数据，确保流畅的自动化体验。
将 Fabric 数据代理的结果与其自己的逻辑组合在一起，以生成全面的响应。标识直通（代理）授权会保护此流，以确保跨企业数据的可靠安全性和适当的访问控制。

注释

Fabric 数据代理和 Azure AI Foundry 资源应位于同一租户上，Microsoft Fabric 和 Azure AI Foundry 应使用相同的帐户登录。

将 Fabric 数据代理添加到 Azure AI 代理

可以通过编程方式或使用用户界面（UI）将 Fabric 数据代理添加到 Azure AI 代理。可以在 Azure AI 代理集成文档中找到详细的代码示例和进一步说明。

通过 UI 添加 Fabric 数据代理：

导航到左侧窗格。在“ 生成和自定义”下，选择 “代理”，如以下屏幕截图所示：

此时会显示现有 Azure AI 代理的列表。可以将 Fabric 添加到其中一个代理，也可以选择 “新建代理 ”以创建新代理。新建代理会生成唯一的代理 ID 和默认名称。可随时更改该名称。有关详细信息，请访问 Azure AI Foundry 门户中什么是 Azure OpenAI。

启动添加知识源：选择 “添加 ”按钮，如以下屏幕截图所示：

这将打开受支持的知识源类型的菜单。

选择Microsoft Fabric 作为源：从列表中选择 Microsoft Fabric，如以下屏幕截图所示：

使用此选项，代理可以访问 Fabric 数据代理。

创建连接：如果以前已建立与 Fabric 数据代理的连接，则可以为新的 Azure AI 代理重复使用该连接。否则，请选择 “新建连接 ”以创建连接，如以下屏幕截图所示：

此时将打开 “新建Microsoft Fabric 连接 窗口，如以下屏幕截图所示：

设置连接时，请提供 Fabric 数据代理 workspace-id 和 artifact-id 值作为自定义键。可以在已发布的 Fabric 数据代理终结点中找到 workspace-id 和 artifact-id 值。 Fabric 数据代理终结点采用以下格式：

https://fabric.microsoft.com/groups/ < workspace_id>/aiskills/<artifact-id>，然后选择 “是机密 ”复选框

最后，将名称分配给连接，并选择是将其提供给 Azure AI Foundry 中的所有项目，还是将其限制为当前项目。

选择 “连接”后，Microsoft Fabric 数据代理将添加为知识资源，如以下屏幕截图所示：

还必须向 Azure AI 代理提供有关使用 Fabric 数据代理何时、作方式和条件的说明。从 Azure AI 代理的角度来看，Fabric 数据代理被视为 Fabric 工具，因此可以在说明中引用它。

还可以根据用例要求调整部署模型、添加作或更改模型设置。完全配置 Azure AI 代理后，选择 “试用演练 ”以测试其性能。

以编程方式添加 Fabric 数据代理：以下步骤介绍如何在 Python 中以编程方式将 Fabric 数据代理添加到 Azure AI 代理。对于其他语言（C#、JavaScript），可以引用此资源。

步骤 1：创建项目客户端

创建包含连接到 AI 项目和其他资源的连接字符串的客户端对象。

import os
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from azure.ai.agents.models import FabricTool, ListSortOrder

步骤 2：创建启用了 Microsoft Fabric 工具的代理

若要使 Fabric 数据代理工具可供 Azure AI 代理使用，请使用连接来初始化该工具并将其附加到代理。可以在 Azure AI Foundry 门户中你的项目的“连接的资源”部分中找到连接。

# The Fabric connection ID can be found in the Azure AI Foundry project as a property of the Fabric tool
# Your connection ID is in the format /subscriptions/<your-subscription-id>/resourceGroups/<your-resource-group>/providers/Microsoft.CognitiveServices/accounts/<ai-foundry-resource-name>/projects/<your-project-name>/connections/<your-fabric-connection-name>
conn_id = "your-connection-id"

# Initialize the AI project client
project_client = AIProjectClient(
    endpoint=os.environ["PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)

# Initialize agent Fabric tool and add the connection ID
fabric = FabricTool(connection_id=conn_id)

# Create agent with the Fabric tool and process assistant run
with project_client:
    agent = project_client.agents.create_agent(
        model="gpt-4o",
        name="my-assistant",
        instructions="You are a helpful assistant",
        tools=fabric.definitions,
        headers={"x-ms-enable-preview": "true"},
    )
    print(f"Created agent, ID: {agent.id}")

步骤 3：创建线程

# Create thread for communication
thread = project_client.agents.create_thread()
print(f"Created thread, ID: {thread.id}")

# Create message to thread
# Remember to update the message with your data
message = project_client.agents.create_message(
    thread_id=thread.id,
    role="user",
    content="what is top sold product in Contoso last month?",
)
print(f"Created message, ID: {message.id}")

步骤 4：创建运行并检查输出

创建一个运行实例，并观察模型使用了 Fabric 数据代理工具来提供用户问题的响应。

# Create and process agent run in thread with tools
run = project_client.agents.create_and_process_run(thread_id=thread.id, assistant_id=agent.id)
print(f"Run finished with status: {run.status}")

if run.status == "failed":
    print(f"Run failed: {run.last_error}")

# Delete the assistant when done
project_client.agents.delete_agent(agent.id)
print("Deleted agent")

# Fetch and log all messages
messages = project_client.agents.list_messages(thread_id=thread.id)
print(f"Messages: {messages}")