教程：使用 Azure AI 搜索生成端到端代理检索解决方案

注释

此功能目前处于公开预览状态。此预览版未随附服务级别协议，建议不要用于生产工作负载。某些功能可能不受支持或者受限。有关详细信息，请参阅适用于 Azure 预览版的补充使用条款。

本教程介绍如何构建集成 Azure AI 搜索和 Foundry 代理服务的解决方案，以便进行智能知识检索。

此解决方案使用模型上下文协议（MCP）在 Azure AI 搜索中的代理检索管道与 Foundry 代理服务中的代理之间建立标准化连接，该管道由引用知识库的知识源组成。可以将此体系结构用于需要对大型知识域进行复杂推理的对话应用程序，例如客户支持或技术故障排除。

下图显示了此代理检索解决方案的高级体系结构：

小窍门

想要立即开始？请参阅 agentic-retrieval-pipeline-example 源代码。
想要对代理检索进行更简单的介绍？请参阅快速入门：使用代理检索。

先决条件

在任意提供代理检索功能的区域中提供的 Azure AI 搜索服务。
Microsoft Foundry 项目和资源。创建项目时，会自动创建资源。
一个受支持的LLM，部署到你的项目中。我们建议最小令牌容量为 100,000。可以在 Foundry 门户中找到 LLM 的容量和速率限制。如果希望在查询时进行矢量化，还应部署文本嵌入模型。
搜索服务和项目的身份验证和权限。
预览软件包版本。有关此解决方案中使用的版本的完整列表，请参阅 requirements.txt 该文件。

身份验证和权限

在开始之前，请确保你有权访问内容和操作。我们建议使用 Microsoft Entra ID 进行身份验证，并通过基于角色的访问来进行授权。你必须是 所有者 或 用户访问管理员 才能分配角色。如果角色不可行，则可以改用基于密钥的身份验证。

若要配置此解决方案的访问权限，请选择以下两个选项卡。

Azure AI 搜索
Microsoft Foundry

启用基于角色的访问。
配置托管标识。
分配角色：
- 在 Azure AI 搜索中执行创建、加载和检索操作时，您必须具备 搜索服务参与者、搜索索引数据参与者 和 搜索索引数据读取者 角色。
- 对于集成操作，请确保使用检索管道的所有客户端都具有用于发送检索请求的 搜索索引数据读取者 角色。

了解解决方案

本部分将解决方案的每个组件与其相应的开发任务配对。有关更深入的指导，请参阅链接的操作指南文章。

Azure AI 搜索
Microsoft Foundry

Azure AI 搜索托管索引内容和代理检索管道。开发任务包括：

创建知识源。代理检索支持多种类型的知识源，但此解决方案会创建搜索索引知识源。
创建一个与您的 LLM 部署映射并使用提取数据输出模式的知识库。建议使用此输出模式与 Foundry 代理服务交互，因为它能够为代理提供未经过处理的逐字内容，以便进行信息基础和推理。

用户通过与调用代理的客户端应用（如聊天机器人）交互来启动查询处理。代理使用 MCP 工具协调对知识库的请求并合成响应。聊天机器人调用代理时，MCP 工具调用 Azure AI 搜索中的知识库，并将其发送回代理和聊天机器人。

生成解决方案

按照以下步骤创建端到端代理检索解决方案。

获取终结点

对于此解决方案，需要以下终结点：

Azure AI 搜索
Microsoft Foundry

可在 Azure 门户中的 “概述 ”页上找到的搜索服务的终结点。它应如下所示： https://{your-service-name}.search.azure.cn/

项目的父资源的 Azure OpenAI 终结点，可在 Azure 门户中的 “终结点 ”页上找到该终结点。它应如下所示： https://{your-resource-name}.openai.azure.com/
项目的终结点，可在 Azure 门户中的 “终结点 ”页上找到该终结点。它应如下所示： https://{your-resource-name}.services.ai.azure.com/api/projects/{your-project-name}
可在 Azure 门户中的 “属性” 页上找到的项目的资源 ID。它应如下所示： /subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/Microsoft.CognitiveServices/accounts/{account-name}/projects/{project-name}

创建代理检索对象

本部分省略在 Azure AI 搜索中创建知识源和知识库的代码片段，并直接讨论建立 Foundry Agent Service 的集成。有关省略的步骤的详细信息，请参阅 “了解解决方案 ”部分。

创建项目连接

在代理中使用 MCP 工具之前，必须在 Foundry 中创建一个项目连接，该连接指向您的知识库mcp_endpoint。此终结点允许代理访问知识库。

import requests
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

# Provide connection details
credential = DefaultAzureCredential()
project_resource_id = "{project_resource_id}" # e.g. /subscriptions/{subscription}/resourceGroups/{resource_group}/providers/Microsoft.MachineLearningServices/workspaces/{account_name}/projects/{project_name}
project_connection_name = "{project_connection_name}"
mcp_endpoint = "{search_service_endpoint}/knowledgebases/{knowledge_base_name}/mcp?api-version=2025-11-01-preview" # This endpoint enables the MCP connection between the agent and knowledge base

# Get bearer token for authentication
bearer_token_provider = get_bearer_token_provider(credential, "https://management.chinacloudapi.cn/.default")
headers = {
  "Authorization": f"Bearer {bearer_token_provider()}",
}

# Create project connection
response = requests.put(
  f"https://management.chinacloudapi.cn{project_resource_id}/connections/{project_connection_name}?api-version=2025-10-01-preview",
  headers = headers,
  json = {
    "name": "project_connection_name",
    "type": "Microsoft.MachineLearningServices/workspaces/connections",
    "properties": {
      "authType": "ProjectManagedIdentity",
      "category": "RemoteTool",
      "target": mcp_endpoint,
      "isSharedToAll": True,
      "audience": "https://search.azure.com/",
      "metadata": { "ApiType": "Azure" }
    }
  }
)

response.raise_for_status()
print(f"Connection '{project_connection_name}' created or updated successfully.")

设置 AI 项目客户端

使用 AIProjectClient 创建与 Foundry 项目的客户端连接。

from azure.ai.projects import AIProjectClient

project_client = AIProjectClient(endpoint=project_endpoint, credential=credential)

list(project_client.agents.list())

创建使用 MCP 工具的代理

下一步是创建使用 MCP 工具配置的代理。当代理收到用户查询时，它可以通过 MCP 工具调用知识库，以检索相关信息为响应提供依据。

代理定义包括指定其行为的说明和之前创建的项目连接。有关详细信息，请参阅快速入门：创建新的代理。

from azure.ai.projects.models import PromptAgentDefinition, MCPTool

# Define agent instructions
instructions = """
A Q&A agent that can answer questions based on the attached knowledge base.
Always provide references to the ID of the data source used to answer the question.
If you don't have the answer, respond with "I don't know".
"""

# Create MCP tool with knowledge base connection
mcp_kb_tool = MCPTool(
    server_label = "knowledge-base",
    server_url = mcp_endpoint,
    require_approval = "never",
    allowed_tools = ["knowledge_base_retrieve"],
    project_connection_id = project_connection_name
)

# Create agent with MCP tool
agent = project_client.agents.create_version(
    agent_name = agent_name,
    definition = PromptAgentDefinition(
        model = agent_model,
        instructions = instructions,
        tools = [mcp_kb_tool]
    )
)

print(f"Agent '{agent_name}' created or updated successfully.")

与代理聊天

客户端应用使用 Azure OpenAI 中的对话和响应 API 将用户输入发送到代理。客户端会创建一个聊天，并通过响应 API 将每个用户消息传递给代理，这类似于典型的聊天体验。

代理管理会话，确定何时通过 MCP 工具调用知识库，并将自然语言响应（引用检索的内容）返回到客户端应用。

# Get the OpenAI client for responses and conversations
openai_client = project_client.get_openai_client()

# Create conversation
conversation = openai_client.conversations.create()

# Send request to trigger the MCP tool
response = openai_client.responses.create(
    conversation = conversation.id,
    input = """
        Why do suburban belts display larger December brightening than urban cores even though absolute light levels are higher downtown?
        Why is the Phoenix nighttime street grid is so sharply visible from space, whereas large stretches of the interstate between midwestern cities remain comparatively dim?
    """,
    extra_body = {"agent": {"name": agent.name, "type": "agent_reference"}},
)

print(f"Response: {response.output_text}")

提高数据质量

默认情况下，知识库中的搜索结果合并到一个大型统一字符串中，可以传递给代理进行校验。 Azure AI 搜索提供以下索引和相关性优化功能，可帮助你生成高质量的结果。可以在搜索索引中实现这些功能，搜索相关性的改进在检索响应的质量中显而易见。

计分配置文件提供内置的加权标准。索引必须指定默认计分配置文件，当查询包含与该配置文件关联的字段时，检索引擎将使用该配置文件。
语义配置是必需的，但你可以确定哪些字段的优先级并用于排名。
对于纯文本内容，可以使用分析器控制索引期间的标记化。
对于多模式或图像内容，您可以在索引期间使用技能集将图像内容语言化以生成图像的 LLM 描述，或通过经典的 OCR 和图像分析来处理图像。

控制子查询数

为知识库提供支持的 LLM 根据以下因素确定子查询数：

用户查询
聊天历史记录
语义排名器输入约束

作为开发人员，可以通过设置检索推理工作来控制子查询的数量。推理工作确定查询规划的 LLM 处理级别，范围从最小（无 LLM 处理）到中等（更深入的搜索和后续迭代）。

控制发送到代理的上下文

响应 API 控制发送到代理和知识库的内容。若要优化性能和相关性，请在将聊天历史记录发送到 MCP 工具之前调整代理说明，以汇总或筛选聊天历史记录。

控制成本和限制运作

有关查询计划的见解，请查看知识库响应的活动数组中的输出令牌。

提高性能

若要优化性能和降低延迟，请考虑以下策略：

汇总消息会话。
使用 gpt-4.1-mini 或执行速度更快的较小模型。
设置maxOutputSize在检索操作上，以控制响应的大小或maxRuntimeInSeconds时间受限的处理。

清理资源

使用自己的订阅时，最好在项目结束时确定是否仍然需要所创建的资源。持续运行资源可能会产生费用。可以逐个删除资源，也可以删除资源组以删除整个资源集。

还可以删除单个对象：

# Delete the agent
project_client.agents.delete_version(agent.name, agent.version)
print(f"AI agent '{agent.name}' version '{agent.version}' deleted successfully")

# Delete the knowledge base
index_client.delete_knowledge_base(base_name)
print(f"Knowledge base '{base_name}' deleted successfully")

# Delete the knowledge source
index_client.delete_knowledge_source(knowledge_source=knowledge_source_name) # This is new feature in 2025-08-01-Preview api version
print(f"Knowledge source '{knowledge_source_name}' deleted successfully.")

# Delete the search index
index_client.delete_index(index)
print(f"Index '{index_name}' deleted successfully")

Last updated on 2025-12-01

Compartir a través de