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

注释

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

在代理检索多查询管道中，通过检索操作在知识库上执行查询，以调用并行查询处理。新的 2025-11-01-preview 更新了此请求结构，该结构引入了以前的预览版的重大更改。如需中断性变更方面的帮助，请参阅迁移智能体检索代码。

本文介绍如何设置检索操作。它还介绍了检索响应的三个组件：

LLM 的已提取响应
引用的结果
查询活动

检索请求可以包含用于替代知识库上设置的默认指令的查询处理指令。检索操作包含适用于任何请求的核心参数，以及特定于知识源的参数。

还可以使用可选答案合成将 LLM 答案表述引入查询管道，将简洁或格式化的答案返回给代理或应用。

先决条件

支持的知识源，用于封装可搜索的索引或指向外部源以进行本地数据检索。
表示一个或多个知识库的知识库。如果需要智能查询规划和答案表述，请包含聊天完成模型。
提供代理检索功能的任何区域内的 Azure AI 搜索。
Azure AI 搜索的权限。用于检索内容的角色包括用于运行查询的 搜索索引数据读取器 。若要支持从搜索服务到聊天完成模型的出站呼叫，必须为搜索服务配置托管标识，并且它必须具有对 Azure OpenAI 资源的 认知服务用户 权限。有关本地测试和获取访问令牌的详细信息，请参阅快速入门：在没有密钥的情况下连接。
API 版本要求。若要创建或使用知识库，请使用 2025-11-01-preview 数据平面 REST API。或者，使用提供知识库 API 的 Azure SDK 的预览包： Python、 .NET、 Java。

若要遵循本指南中的步骤，建议将 Visual Studio Code 与 REST 客户端配合使用，以便将 REST API 调用发送到 Azure AI 搜索。

设置检索操作

指定知识库上的检索操作。知识库具有一个或多个知识来源。检索可以返回来自知识源的自然语言或原始基础区块的合成答案。

查看知识库定义，了解哪些知识源在范围内。
查看知识源以了解其参数和配置。
使用 2025-11-01-preview 数据平面 REST API 或 Azure SDK 预览包调用检索。

对于具有默认检索说明的知识源，可以替代检索请求中的默认值。

从搜索索引中检索信息

对于面向搜索索引的知识源，所有 searchable 字段都在查询执行范围内。如果索引包含向量字段，则索引应具有有效的向量器定义，以便代理检索引擎可以向量查询输入。否则，将忽略向量字段。隐式查询类型为 semantic，没有搜索模式。

检索路由的输入是自然语言的聊天对话历史记录，其中 messages 数组包含聊天。仅当检索推理工作为低或中时，代理检索引擎才支持消息。

@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"
    }
  ]
}

Responses

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

检索参数

Name	Description	类型	可编辑	必选
`messages`	阐明发送到聊天完成模型的消息。消息格式类似于 Azure OpenAI API。	物体	是的	否
`role`	定义消息来自何处，例如 `assistant` 或 `user`。使用的模型确定哪些角色有效。	String	是的	否
`content`	发送到 LLM 的消息或提示符。它在此预览中必须是文本。	String	是的	否
`knowledgeSourceParams`	如果要在查询时自定义查询或响应，请为每个知识源指定参数。	物体	是的	否

例子

检索请求因知识源以及是否要重写默认配置而异。下面是几个演示一系列请求的示例。

示例：覆盖默认推理设定并设置请求限制

此示例指定答案公式，因此 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
}

示例：设置每个知识源的引用

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

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
        }
    ]
}

注释

如果要从 OneLake 或索引 SharePoint 知识源检索内容，请将 includeReferenceSourceData 设置为 true 以在引文中包含源文档的 URL。

示例：最小推理工作量

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

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

查看提取的响应

提取的响应是通常传递给 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`支持的其他知识源。
自主推理努力	对于每个检索操作，您可以指定 LLM 的支持程度。使用最小设置以绕过 LLM，使用低设置以进行受限的 LLM 处理，使用中设置以进行完整的 LLM 处理。
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
    }
  ]

查看引用数组

该 references 数组直接来自基础地面数据。它包括用于生成响应的 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
    }
  ]

注释

如果要从 OneLake 或索引的 SharePoint 知识源检索内容，请在检索请求中将includeReferenceSourceData设置为true，以获取引文中源文档的 URL。

Last updated on 2026-01-29

通过