验证端到端专用智能体检索

可易团队2026-11-01阅读约 11 分钟

第三部分教程说明如何在专用网络内创建知识来源与知识库、登记 MCP 连接，并用引用验收智能体检索。

#验证端到端专用智能体检索

重要

标记为（预览）的功能、能力或属性不受服务级别协议覆盖，不建议用于生产工作负载，并且在正式发布之前可能变更或受到限制。无论预览功能是独立的，还是作为正式发布功能的一部分，Azure AI Search 预览条款都适用于全部预览功能。

本文是三部分教程系列的第三部分。在本部分中，你创建知识来源和知识库，把 MCP 端点登记为项目连接，并通过智能体运行验证提示，以确认来自专用内容的、有依据且带引用的响应。至此，网络、身份和检索层汇入同一条运行时路径。

本文在两处使用预览 REST API 表面。知识库使用 outputMode（预览）和 retrievalReasoningEffort（预览）来显式指定抽取式输出和最小推理，尽管等价行为已正式发布。项目连接使用 RemoteTool（预览）和项目托管身份向 Azure AI Search 认证。

先决条件

已完成设置专用入站连接和设置专用出站连接。

在你向用户账户分配角色的范围内，具备 Owner、User Access Administrator 或 Role Based Access Control Administrator。

Foundry 模型部署包括 text-embedding-3-large 和一个 GPT-5 系列模型（例如 gpt-5-turbo）。第一部分使用的模板会部署一个 GPT-5 系列模型，但不会部署 text-embedding-3-large。先部署 text-embedding-3-large，再在继续之前验证两项部署。部署说明见在 Foundry 门户中部署 Microsoft Foundry 模型。

安装了 REST Client 扩展的 Visual Studio Code。

与第一部分相同的虚拟网络内客户端，例如跳板机、虚拟机、开发盒，或通过 Azure Bastion 连接的工作站。它必须连到部署中的专用网络路径，并能够到达你的专用端点。

Foundry 资源的 Allow Azure services on the trusted services list 设置保持启用。第二部分说明了为什么知识来源摄入仍然依赖这一旁路来完成嵌入调用。

验证模型部署

验证 Foundry 资源包含本文后面要用到的部署。

列出 Foundry 资源上的模型部署。

az cognitiveservices account deployment list \
      --name <foundry-resource-name> \
      --resource-group rg-private-retrieval \
      --query "[].{deployment:name,model:properties.model.name,status:properties.provisioningState}" \
      -o table

确认 text-embedding-3-large 和一个 GPT-5 系列模型都以 Succeeded 状态出现。

如果尚未部署 GPT-5 系列模型，请在本文后面创建智能体之前先部署一个。

为用户账户分配角色

教程第二部分向 Azure AI Search 授予运行时访问。在本节中，你向自己的用户账户授予上传示例内容、创建智能体检索对象、配置项目连接和运行智能体操作所需的权限。

提示

对于本文中适用的命令，把 <...-name> 占位符和 <subscription-id> 替换为你在第一部分记录的资源名称和订阅 ID。

向你的用户账户分配角色：

获取账户对象 ID，在下列命令中用作 <principal-object-id>。

az ad signed-in-user show --query id -o tsv

在 Azure Storage 账户范围内分配角色。

创建 Blob 容器并在下一节上传示例内容需要 Storage Blob Data Contributor。

az role assignment create \
      --assignee-object-id <principal-object-id> \
      --assignee-principal-type User \
      --role "Storage Blob Data Contributor" \
      --scope "/subscriptions/<subscription-id>/resourceGroups/rg-private-retrieval/providers/Microsoft.Storage/storageAccounts/<storage-account-name>"

在 Azure AI Search 服务范围内分配角色。

管理知识来源和知识库需要 Search Service Contributor。验证期间的知识库检索需要 Search Index Data Contributor。

az role assignment create \
      --assignee-object-id <principal-object-id> \
      --assignee-principal-type User \
      --role "Search Service Contributor" \
      --scope "/subscriptions/<subscription-id>/resourceGroups/rg-private-retrieval/providers/Microsoft.Search/searchServices/<search-service-name>"

az role assignment create \
      --assignee-object-id <principal-object-id> \
      --assignee-principal-type User \
      --role "Search Index Data Contributor" \
      --scope "/subscriptions/<subscription-id>/resourceGroups/rg-private-retrieval/providers/Microsoft.Search/searchServices/<search-service-name>"

在 Foundry 资源范围内分配角色。

创建项目连接需要 Foundry Project Manager。在 Foundry 项目中创建智能体并运行验证对话需要 Foundry User。

重要

Foundry RBAC 角色最近已更名。Foundry User、Foundry Owner、Foundry Account Owner 和 Foundry Project Manager 以前分别名为 Azure AI User、Azure AI Owner、Azure AI Account Owner 和 Azure AI Project Manager。更名推广期间，你仍可能在某些地方看到旧名称。角色 ID 和核心权限不因更名而改变。

az role assignment create \
      --assignee-object-id <principal-object-id> \
      --assignee-principal-type User \
      --role "Foundry Project Manager" \
      --scope "/subscriptions/<subscription-id>/resourceGroups/rg-private-retrieval/providers/Microsoft.CognitiveServices/accounts/<foundry-resource-name>"

az role assignment create \
      --assignee-object-id <principal-object-id> \
      --assignee-principal-type User \
      --role "Foundry User" \
      --scope "/subscriptions/<subscription-id>/resourceGroups/rg-private-retrieval/providers/Microsoft.CognitiveServices/accounts/<foundry-resource-name>"

验证角色分配。

az role assignment list \
      --assignee-object-id <principal-object-id> \
      --query "[].{role:roleDefinitionName,scope:scope}" \
      -o table

你应当在预期范围内看到 Search Service Contributor、Search Index Data Contributor、Foundry Project Manager、Foundry User 和 Storage Blob Data Contributor。

上传示例内容

把示例 JSON 文档上传到 Azure Blob Storage 中的一个容器。本文后面的验证提示以这些 Blob 内容为依据作答，因此知识来源摄入它们之前，文档必须就位。

重要

本文其余命令和 REST 调用都从你的虚拟网络内客户端运行。若干步骤会到达 Azure Blob Storage、Azure AI Search 和 Foundry 上的专用端点，包括本节的上传命令。因为第一部分禁用了这些服务的公共网络访问，这些步骤只有走专用网络路径才会成功。

上传示例内容：

把示例 JSON 文档下载到虚拟网络内客户端。

git clone --depth 1 https://github.com/Azure-Samples/azure-search-sample-data.git

创建 earth-at-night-json Blob 容器。

az storage container create \
      --name earth-at-night-json \
      --account-name <storage-account-name> \
      --auth-mode login

把示例文件拆成每条记录一个 Blob。

下载的示例把全部记录存在一个 documents.json 文件中。把该文件作为单个 Blob 上传可能延迟或卡住摄入，因此上传前先拆分。

mkdir -p earth-at-night-split
python - <<'PY'
import json
from pathlib import Path

source = Path("azure-search-sample-data/nasa-e-book/earth-at-night-json/documents.json")
target = Path("earth-at-night-split")
target.mkdir(exist_ok=True)

for doc in json.loads(source.read_text()):
       (target / f"{doc['id']}.json").write_text(json.dumps(doc))
PY

如果虚拟网络内客户端没有 Python，请在继续之前用另一种能处理 JSON 的工具，按每条记录创建一个 Blob。

把拆分后的示例文档上传到容器。

az storage blob upload-batch \
      --destination earth-at-night-json \
      --source earth-at-night-split \
      --account-name <storage-account-name> \
      --auth-mode login

验证文档已成功上传。

az storage blob list \
      --container-name earth-at-night-json \
      --account-name <storage-account-name> \
      --auth-mode login \
      --query "[].name" -o tsv

输出列出 Earth at Night 示例集中的 JSON 文件。这些按记录拆分的 Blob 成为下一节知识来源所摄入的专用内容。

创建知识来源和知识库

在 Azure AI Search 中，智能体检索涉及两个对象：知识来源和知识库。本节创建一个 Blob 知识来源，它会生成一条摄入流水线：对专用 Blob 内容分块，用你已部署的 text-embedding-3-large 模型做向量化，并把增强后的内容存入搜索索引。知识库随后编排来自知识来源的检索，并通过 MCP 端点暴露结果。该端点成为后面章节中智能体调用的目标。

创建知识来源和知识库：

获取 Azure AI Search 持有者令牌，在下列请求中用作 <search-access-token>。

az account get-access-token --scope https://search.azure.com/.default --query accessToken -o tsv

打开 Visual Studio Code，创建名为 private-agentic-retrieval.rest 的文件。

创建 Blob 知识来源。

PUT https://<search-service-name>.search.windows.net/knowledgesources/ks-private-retrieval?api-version=2026-08-01-preview
Authorization: Bearer <search-access-token>
Content-Type: application/json

{
     "name": "ks-private-retrieval",
      "kind": "azureBlob",
      "description": "Private blob-backed knowledge source for tutorial content.",
      "azureBlobParameters": {
         "connectionString": "ResourceId=/subscriptions/<subscription-id>/resourceGroups/rg-private-retrieval/providers/Microsoft.Storage/storageAccounts/<storage-account-name>;",
         "containerName": "earth-at-night-json",
         "isADLSGen2": false,
         "ingestionParameters": {
            "embeddingModel": {
               "kind": "azureOpenAI",
               "azureOpenAIParameters": {
                  "resourceUri": "https://<foundry-resource-name>.openai.azure.com/",
                  "deploymentId": "text-embedding-3-large",
                  "modelName": "text-embedding-3-large"
               }
            },
            "contentExtractionMode": "minimal",
            "disableImageVerbalization": true
         }
      }
}

创建引用该知识来源的知识库。

PUT https://<search-service-name>.search.windows.net/knowledgebases/kb-private-retrieval?api-version=2026-08-01-preview
Authorization: Bearer <search-access-token>
Content-Type: application/json

{
     "name": "kb-private-retrieval",
      "description": "Knowledge base grounded in private blob tutorial content.",
      "knowledgeSources": [
         {
            "name": "ks-private-retrieval"
         }
      ],
      "outputMode": "extractiveData",
      "retrievalReasoningEffort": {
         "kind": "minimal"
      }
}

确认知识来源已成功创建。

GET https://<search-service-name>.search.windows.net/knowledgesources/ks-private-retrieval?api-version=2026-08-01-preview
Authorization: Bearer <search-access-token>

此请求应返回 HTTP 200。响应负载应包含 "name": "ks-private-retrieval"。

确认知识库已成功创建。

GET https://<search-service-name>.search.windows.net/knowledgebases/kb-private-retrieval?api-version=2026-08-01-preview
Authorization: Bearer <search-access-token>

此请求应返回 HTTP 200。响应负载应包含 "name": "kb-private-retrieval"，并在 knowledgeSources 下列出 "name": "ks-private-retrieval"。

说明

创建知识来源会启动对 Blob 内容的异步摄入。首次摄入可能需要数分钟才能完成。在创建智能体之前，重新运行本节中知识来源和知识库的 GET 请求，并确认它们仍返回 HTTP 200。如果过早运行验证提示，响应可能在引用出现之前失败。等待 30 到 60 秒，然后重试。如果摄入停滞，请验证你上传的是按记录拆分的 Blob，而不是单个大型 documents.json 文件，并确认第二部分所述的 Foundry 受信任服务旁路仍然启用。

创建项目连接

把知识库 MCP 端点登记为 Foundry 中的 RemoteTool 项目连接（预览）。该连接让智能体使用项目托管身份调用 MCP 端点，而不是嵌入机密。完成本节后，你会得到一个可供智能体定义引用的可复用连接名称。

创建项目连接：

获取 Azure 资源管理器令牌，在下列请求中用作 <management-access-token>。

az account get-access-token --scope https://management.azure.com/.default --query accessToken -o tsv

获取项目资源 ID，在下列请求中用作 <project-resource-id>。

az rest --method get \
     --url "https://management.azure.com/subscriptions/<subscription-id>/resourceGroups/rg-private-retrieval/providers/Microsoft.CognitiveServices/accounts/<foundry-resource-name>/projects?api-version=2025-10-01-preview" \
     --query "value[0].id" -o tsv

使用 Azure 资源管理器创建项目连接。

PUT https://management.azure.com/<project-resource-id>/connections/conn-kb-private-retrieval?api-version=2025-10-01-preview
Authorization: Bearer <management-access-token>
Content-Type: application/json

{
     "name": "conn-kb-private-retrieval",
      "type": "Microsoft.MachineLearningServices/workspaces/connections",
      "properties": {
         "authType": "ProjectManagedIdentity",
         "category": "RemoteTool",
         "target": "https://<search-service-name>.search.windows.net/knowledgebases/kb-private-retrieval/mcp?api-version=2026-08-01-preview",
         "isSharedToAll": true,
         "audience": "https://search.azure.com/",
         "metadata": {
            "ApiType": "Azure"
         }
      }
}

确认连接已创建。

GET https://management.azure.com/<project-resource-id>/connections/conn-kb-private-retrieval?api-version=2025-10-01-preview
Authorization: Bearer <management-access-token>

此请求返回 HTTP 200。验证 authType 为 ProjectManagedIdentity，target 与你的知识库 MCP URL 匹配，且 name 为 conn-kb-private-retrieval。你必须向 Azure AI Search 服务授予 ProjectManagedIdentity 授权，方法是分配 Search Index Data Reader 角色；如果需要写访问，还要分配 Search Index Data Contributor 角色。帮助见创建项目连接。

创建智能体并验证引用

警告

MCP 实现容易受到攻击、级联故障和失去人工监督等风险影响。你可以通过审查 MCP 服务器的安全性和可靠性、遵循 Microsoft 推荐做法和行业最佳实践，并实施审批机制和监控级联行为，来缓解这些风险。

创建一个使用项目连接来调用知识库 MCP 工具的智能体，然后通过对话运行验证提示。目标是确认端到端检索行为：智能体依据专用内容作答，并返回有依据的引用，而不是依赖模型的一般知识。

创建智能体并验证引用：

获取 Foundry 访问令牌，在下列请求中用作 <foundry-access-token>。

az account get-access-token --scope https://ai.azure.com/.default --query accessToken -o tsv

获取项目端点，在下列请求中用作 <project-endpoint>。

az rest --method get \
     --url "https://management.azure.com/subscriptions/<subscription-id>/resourceGroups/rg-private-retrieval/providers/Microsoft.CognitiveServices/accounts/<foundry-resource-name>/projects?api-version=2025-10-01-preview" \
     --query "value[0].properties.endpoints.* | [0]" -o tsv

创建使用你的 MCP 连接的提示智能体。

POST <project-endpoint>/agents?api-version=v1
Authorization: Bearer <foundry-access-token>
Content-Type: application/json

{
     "name": "agent-private-retrieval",
      "definition": {
         "model": "<gpt-5-model-deployment-name>",
         "instructions": "Use the knowledge base for every answer. Return grounded citations. If the answer is not in the knowledge base, say that you do not know.",
         "tools": [
            {
               "type": "mcp",
               "server_label": "knowledge-base",
               "server_url": "https://<search-service-name>.search.windows.net/knowledgebases/kb-private-retrieval/mcp?api-version=2026-08-01-preview",
               "project_connection_id": "conn-kb-private-retrieval",
               "require_approval": "never",
               "allowed_tools": ["knowledge_base_retrieve"]
            }
         ],
         "kind": "prompt"
      }
}

创建对话，然后从响应中复制 id 值，在下一步用作 <conversation-id>。

POST <project-endpoint>/openai/v1/conversations
Authorization: Bearer <foundry-access-token>
Content-Type: application/json

{}

通过智能体运行验证提示。

POST <project-endpoint>/openai/v1/responses
Authorization: Bearer <foundry-access-token>
Content-Type: application/json

{
      "conversation": "<conversation-id>",
      "input": "Summarize the key findings from the Earth at Night sample documents and cite the source content.",
      "agent_reference": {
         "type": "agent_reference",
         "name": "agent-private-retrieval"
      }
}

预期结果：

智能体返回依据你所上传 Blob 内容的答案。
响应包含引用 Earth at Night 来源内容的引用。
请求从你的专用网络客户端成功，使用的是第一部分和第二部分配置的同一条专用路径。

故障排除

用下表隔离检索验证流程中的失败。

检查或症状	可能问题	下一步做什么
创建知识来源或知识库时出现 `403`	Azure AI Search 授权（调用方或依赖资源）	验证调用方在搜索服务范围内具有 `Search Service Contributor`。然后验证 Azure AI Search 能通过专用链接到达 Azure Blob Storage 和 Foundry 端点，并验证第二部分中的托管身份角色分配。
`401`，并伴有 `Failed to create or update Knowledge Source` 和 `Unable to retrieve blob container ... using your managed identity`	第二部分的 Azure AI Search 运行时依赖不完整	验证两条共享专用链接都显示 `Approved`，并验证 Azure AI Search 托管身份在存储账户上具有 `Storage Blob Data Reader`，在 Foundry 资源上具有 `Cognitive Services User`。
创建知识来源或知识库时出现 `400`	嵌入模型配置无效	验证 `text-embedding-3-large` 嵌入模型的 `resourceUri`、`deploymentId` 和 `modelName`。
摄入期间出现 `403 Public access is disabled`	Foundry 受信任服务旁路被禁用	在 Foundry 资源上重新启用 Allow Azure services on the trusted services list，然后重试摄入。`openai_account` 共享专用链接目前不能替代这一摄入时依赖。
MCP 端点 URL 上出现 `404`	知识库端点不正确	验证 MCP 目标为 `https://<search-service-name>.search.windows.net/knowledgebases/kb-private-retrieval/mcp?api-version=2026-08-01-preview`。
创建项目连接时出现 `401` 或 `403`	Azure 资源管理器授权或令牌范围	验证调用方身份可以在 `<project-resource-id>` 上管理项目连接。同时验证你用 `--scope https://management.azure.com/.default` 请求了令牌。
智能体调用 MCP 工具时出现 `401` 或 `403`	项目托管身份没有所需的 Search 数据平面访问，或角色分配尚未传播	验证该连接的项目托管身份在 Azure AI Search 服务上具有所需的数据平面角色，然后稍等角色传播，再重试验证提示。
智能体返回答案但没有引用	智能体工具接线、指令或检索数据可用性	验证智能体包含 MCP 工具，`allowed_tools` 包含 `knowledge_base_retrieve`，且指令要求有依据的引用。同时验证知识库包含来自 `earth-at-night-json` 的可检索内容。

清理资源

在你自己的订阅中工作时，项目结束时移除不再需要的资源是好做法。继续运行的资源会产生费用。

本教程使用名为 rg-private-retrieval 的专用资源组。如果不再需要该资源组，删除它：

az group delete \
   --name rg-private-retrieval \
   --yes \
   --no-wait

PRIMARY_SOURCE: https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/foundry-iq-tutorial-private-retrieval

#Foundry IQ
#专用网络
#知识库
#MCP
#验收