使用知识库在 Azure AI 搜索中检索数据

注释

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

在代理检索管道中，检索操作从知识库调用并行查询处理。本文介绍如何调用检索操作并解释三方响应。

可以使用搜索服务 REST API 或提供等效功能的 Azure SDK 直接调用检索操作。每个知识库还公开一个模型上下文协议（MCP）终结点，供MCP兼容的代理使用。

先决条件

具有知识库的 Azure 人工智能搜索服务。
查询知识库的权限。为用户帐户分配搜索索引数据读取者角色（推荐）来配置无密钥身份验证，或者使用API 密钥。
如果知识库指定了 LLM，则搜索服务必须在 Microsoft Foundry 资源上具有管理的身份，并具有 Cognitive Services User 权限。
2025-11-01-preview REST API 或等效的 Azure SDK 预览包：.NETJavaJavaScriptPython。

调用检索操作

在知识库上指定检索操作。输入是自然语言的聊天对话历史记录，其中 messages 数组包含对话。仅当检索推理工作较低或中等时，代理检索引擎才支持消息。

下面是使用知识检索 - 检索（REST API）的示例：

@search-url=<YOUR SEARCH SERVICE URL>
@accessToken=<YOUR PERSONAL ID>

# Send grounding request
POST https://{{search-url}}/knowledgebases/{{knowledge-base-name}}/retrieve?api-version=2025-11-01-preview
    Content-Type: application/json
    Authorization: Bearer {{accessToken}}

{
    "messages" : [
            {
                "role" : "assistant",
                "content" : [
                  { "type" : "text", "text" : "You can answer questions about the Earth at night.
                    Sources have a JSON format with a ref_id that must be cited in the answer.
                    If you do not have the answer, respond with 'I do not know'." }
                ]
            },
            {
                "role" : "user",
                "content" : [
                  { "type" : "text", "text" : "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?" }
                ]
            }
        ],
  "knowledgeSourceParams": [
    {
      "filterAddOn": null,
      "knowledgeSourceName": "earth-at-night-blob-ks",
      "kind": "searchIndex"
    }
  ]
}

请求参数

传递以下参数以调用检索操作。

Name	Description	类型	可编辑	必选
`messages`	阐明发送到 LLM 的消息。消息格式类似于 Azure OpenAI API。	物体	是的	否
`messages.role`	定义消息来自何处，例如 `assistant` 或 `user`。使用的模型确定哪些角色有效。	String	是的	否
`messages.content`	发送到 LLM 的消息或提示符。在此预览版中，它必须是文本。	String	是的	否
`knowledgeSourceParams`	覆盖每个知识源的默认检索设置。可用于在查询时自定义查询或响应。	物体	是的	否

从搜索索引中检索信息

对于面向搜索索引的知识源，所有 searchable 字段都在查询执行范围内。隐式查询类型为 semantic，没有搜索模式。

如果索引包含矢量字段，则需要有效的向量器定义，以便代理检索引擎可以向量化查询输入。否则，将忽略向量字段。

调用 MCP 端点

MCP 是一种开放协议，用于标准化 AI 应用程序如何连接到外部数据源和工具。

在 Azure AI Search 中，每个知识库都是一个独立的 MCP 服务器，用于公开knowledge_base_retrieve 工具。任何 MCP 兼容的客户端，包括 Foundry Agent Service、GitHub Copilot、Claude 和 Cursor，都可以调用此工具来查询知识库。

MCP 终结点格式

每个knowledge base都有一个位于以下 URL 的 MCP 终结点：

https://<your-service-name>.search.azure.cn/knowledgebases/<your-knowledge-base-name>/mcp?api-version=2025-11-01-preview

在 MCP 终端进行身份验证

MCP 终结点需要通过自定义标头进行身份验证。可以使用两个选项：

（推荐） 在 Authorization 标头中传递持有者令牌。令牌背后的标识必须在搜索服务上分配Search Index Data Reader角色。此方法可避免将密钥存储在配置文件中。有关详细信息，请参阅使用标识将应用程序连接到Azure AI Search。
在 api-key 标头内输入查询密钥或管理密钥。建议为只读访问提供查询密钥，这足以进行检索，并且是一个更安全的选择。管理密钥提供对搜索服务的完整读写访问权限。有关更多信息，请参阅使用 API 密钥连接到 Azure AI Search。

查看响应

成功检索会返回200 OK状态代码。如果knowledge base无法从一个或多个知识源中检索，206 Partial Content状态代码将返回。响应仅包括成功源的结果。有关部分响应的详细信息会作为错误项显示在活动数组中。

检索操作返回三个主要组件：

提取的响应或合成答案（具体取决于输出模式）
活动数组
引用数组

提取的响应

提取的响应是通常传递给 LLM 的单个统一字符串。 LLM 将其用作基础数据，并利用它生成回复。对 LLM 的 API 调用包括模型的统一字符串和说明，例如是否专门使用基础信息还是作为补充。

响应正文也以聊天消息样式格式进行结构化。在此预览版中，内容将序列化为 JSON。

"response": [
    {
        "role": "assistant",
        "content": [
            {
                "type": "text",
                "text": "[{\"ref_id\":0,\"title\":\"Urban Structure\",\"terms\":\"Location of Phoenix, Grid of City Blocks, Phoenix Metropolitan Area at Night\",\"content\":\"<content chunk redacted>\"}]"
            }
        ]
    }
]

要点：

content.text 是 JSON 数组。给定查询和聊天历史输入，它是由搜索索引中找到的最相关的文档（或区块）组成的单一字符串。此数组是聊天完成模型用来表述对用户问题的响应的基础数据。

响应的这一部分包含 200 个区块或更少区块，不包括未能满足 2.5 重新评分的最低阈值的任何结果。

该字符串以区块的引用 ID（用于引文目的）开头，后续包含目标索引的语义配置中指定的所有字段。在此示例中，假定目标索引中的语义配置具有“title”字段、“terms”字段和“content”字段。
在此预览版中，content.type有一个有效值： text
知识库上的maxOutputSize属性确定字符串的长度。

活动数组

活动数组输出的查询计划为操作透明度提供了跟踪操作、计费影响和资源调用。它还包括发送到检索管道的子查询，以及由于无法访问的知识源等原因导致的任何检索失败错误。

输出包括以下组件：

Section	Description
modelQueryPlanning	对于使用 LLM 进行查询规划的知识库，本部分报告用于输入的令牌计数，以及子查询的令牌计数。
特定于源的活动	对于查询中包含的每个知识源，本节将报告已用的时间以及查询中使用的参数，包括语义排名器。知识源类型包括 `searchIndex`、 `azureBlob`支持的其他知识源。
主体性推理	本部分报告检索期间代理推理的令牌消耗情况，具体取决于指定的检索推理工作。
modelAnswerSynthesis	对于使用答案合成的知识库，本部分将报告用于制定答案的令牌计数，以及答案输出的令牌计数。

下面是活动数组的示例：

  "activity": [
    {
      "type": "modelQueryPlanning",
      "id": 0,
      "inputTokens": 2302,
      "outputTokens": 109,
      "elapsedMs": 2396
    },
    {
      "type": "searchIndex",
      "id": 1,
      "knowledgeSourceName": "demo-financials-ks",
      "queryTime": "2025-11-04T19:25:23.683Z",
      "count": 26,
      "elapsedMs": 1137,
      "searchIndexArguments": {
        "search": "List of companies in the financial sector according to SEC GICS classification",
        "filter": null,
        "sourceDataFields": [ ],
        "searchFields": [ ],
        "semanticConfigurationName": "en-semantic-config"
      }
    },
    {
      "type": "searchIndex",
      "id": 2,
      "knowledgeSourceName": "demo-healthcare-ks",
      "queryTime": "2025-11-04T19:25:24.186Z",
      "count": 17,
      "elapsedMs": 494,
      "searchIndexArguments": {
        "search": "List of companies in the financial sector according to SEC GICS classification",
        "filter": null,
        "sourceDataFields": [ ],
        "searchFields": [ ],
        "semanticConfigurationName": "en-semantic-config"
      }
    },
    {
      "type": "agenticReasoning",
      "id": 3,
      "retrievalReasoningEffort": {
        "kind": "low"
      },
      "reasoningTokens": 103368
    },
    {
      "type": "modelAnswerSynthesis",
      "id": 4,
      "inputTokens": 5821,
      "outputTokens": 344,
      "elapsedMs": 3837
    }
  ]

引用数组

引用数组直接来自基础地面数据。它包括用于生成响应的 sourceData。它由代理检索引擎查找的每个文档组成，并在语义上排名。 sourceData 包含 id 及语义字段：title、terms 和 content。

id 用于作为具体响应中某个项目的引用 ID。它不是搜索索引中的文档标识符。使用它来提供引文。

此数组的目的是提供聊天消息样式结构，以便轻松集成。例如，如果要将结果序列化为不同的结构，或者需要对数据进行一些编程作，然后再将其返回给用户。

还可以从引用数组中的源数据对象中获取结构化数据，以对其进行操作，使之符合你的需求。

下面是引用数组的示例：

  "references": [
    {
      "type": "AzureSearchDoc",
      "id": "0",
      "activitySource": 2,
      "docKey": "earth_at_night_508_page_104_verbalized",
      "sourceData": null
    },
    {
      "type": "AzureSearchDoc",
      "id": "1",
      "activitySource": 2,
      "docKey": "earth_at_night_508_page_105_verbalized",
      "sourceData": null
    }
  ]

例子

以下示例演示了调用检索操作的不同方法：

替代默认推理工作并设置请求限制
为每个知识源设置引用
使用最少的推理工作量

替代默认推理工作并设置请求限制

此示例指定答案合成，因此 retrievalReasoningEffort 必须为“low”或“medium”。

POST {{url}}/knowledgebases/kb-override/retrieve?api-version={{api-version}}
api-key: {{key}}
Content-Type: application/json

{
    "messages": [
        {
            "role": "user",
            "content": [
                { "type": "text", "text": "What companies are in the financial sector?" }
            ]
        }
    ],
    "retrievalReasoningEffort": { "kind": "low" },
    "outputMode": "answerSynthesis",
    "maxRuntimeInSeconds": 30,
    "maxOutputSize": 6000
}

为每个知识源设置引用

此示例使用knowledge base中指定的默认推理工作。此示例的重点是规范响应中要包含的信息量。

POST {{url}}/knowledgebases/kb-medium-example/retrieve?api-version={{api-version}}
api-key: {{key}}
Content-Type: application/json

{
    "messages": [
        {
            "role": "user",
            "content": [
                { "type": "text", "text": "What companies are in the financial sector?" }
            ]
        }
    ],
    "includeActivity": true,
    "knowledgeSourceParams": [
        {
            "knowledgeSourceName": "demo-financials-ks",
            "kind": "searchIndex",
            "includeReferences": true,
            "includeReferenceSourceData": true
        },
        {
            "knowledgeSourceName": "demo-communicationservices-ks",
            "kind": "searchIndex",
            "includeReferences": false,
            "includeReferenceSourceData": false
        },
        {
            "knowledgeSourceName": "demo-healthcare-ks",
            "kind": "searchIndex",
            "includeReferences": true,
            "includeReferenceSourceData": false,
            "alwaysQuerySource": true
        }
    ]
}

使用最少的推理工作量

在此示例中，没有用于智能查询规划或答案合成的 LLM。查询字符串将转到关键字搜索或混合搜索的代理检索引擎。

POST {{url}}/knowledgebases/kb-minimal/retrieve?api-version={{api-version}}
api-key: {{key}}
Content-Type: application/json

{
    "intents": [
        {
            "type": "semantic",
            "search": "what is a brokerage"
        }
    ]
}

Last updated on 2026-03-10

通过