你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

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

注释

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

在 Azure AI 搜索中, 代理检索 是一个新的并行查询体系结构,它使用大型语言模型(LLM)进行查询规划。 它生成子查询,以扩大可搜索和相关的范围。 它将聊天历史记录纳入上下文中以提供背景。 LLM 研究查询并将其细分为更有针对性的查询,对子查询组合使用不同的短语和术语。

本文介绍如何使用调用知识代理和并行查询处理的 检索方法 。 本文还介绍了检索响应的三个组件:

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

检索请求可以包含指令,用于覆盖知识代理上的默认查询处理设置。

注释

响应中没有模型生成的“答案”。 相反,应将响应传递给 LLM,LLM 会根据内容给出答案。 有关包含此步骤的端到端示例,请参阅 生成代理到代理检索解决方案 Azure OpenAI 演示

先决条件

若要遵循本指南中的步骤,建议将 Visual Studio CodeREST 客户端 配合使用,以便将 REST API 调用发送到 Azure AI 搜索。 目前没有门户支持。

调用检索操作

调用知识代理器对象的检索动作以进行检索并返回响应。 使用 2025-05-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}}/agents/{{agent-name}}/retrieve?api-version=2025-05-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 don't 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?" }
                ]
            }
        ],
    "targetIndexParams" :  [
        { 
            "indexName" : "{{index-name}}",
            "filterAddOn" : "page_number eq '105'",
            "IncludeReferenceSourceData": true, 
            "rerankerThreshold" : 2.5,
            "maxDocsForReranker": 50
        } 
    ]
}

要点

  • messages 阐明发送到模型的消息。 消息格式类似于 Azure OpenAI API。

    • role 定义消息来自何处,例如 assistantuser。 使用的模型确定哪些角色有效。

    • content 是发送到 LLM 的消息。 它在此预览中必须是文本。

  • targetIndexParams 提供有关检索的说明。 目前在此预览版中,只能针对单个索引。

    • filterAddOn 允许为关键字或混合搜索设置 OData 筛选器表达式

    • IncludeReferenceSourceData 指示检索引擎在响应中返回源内容。 此值最初在知识代理定义中设置。 可以在检索操作中覆盖该设置,以便在响应的引用部分返回原始源内容。

    • rerankerThreshold 并且 maxDocsForReranker 最初在知识代理定义中设置为默认值。 可以在提取操作中覆盖它们,以配置语义重排器,并设置最小阈值及发送至重排器的最大输入数量。

      rerankerThreshold 是可接受的包含在响应中的最小语义重排序分数。 重排序器分数的范围从 1 到 4。 根据测试结果和内容需求,计划修改此值。

      maxDocsForReranker 指示要考虑的最终响应字符串的最大文档数。 语义重排序器最多接受 50 个文档。 如果最大值为 200,则会向查询计划添加 4 个子查询,以确保所有 200 个文档都按语义方式排名。 用于语义排名。 如果数字不能被 50 整除,则查询计划向上舍入到最接近的整数。

      响应的 content 部分由 200 个或更少的块组成,不包括任何未达到 2.5 重新排序分数最低阈值的结果。

查看提取的响应

提取的响应是单一的统一字符串,通常传递给将它用作基础数据的 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 是 JSON 数组。 给定查询和聊天历史输入,它是由搜索索引中找到的最相关的文档(或区块)组成的单一字符串。 此数组是聊天完成模型用来表述对用户问题的响应的基础数据。

  • “text”是type的唯一有效值,它包含区块的引用 ID(用于引文目的),以及目标索引的语义配置中所指定的任何字段。 在此示例中,应假定目标索引中的语义配置具有“title”字段、“terms”字段和“content”字段。

注释

maxOutputSize知识代理上的属性确定字符串的长度。 建议使用 5,000 个令牌。

查看活动数组

活动数组输出查询计划,并帮助您跟踪执行请求时执行的操作。 它提供操作的透明性,使你可以理解计费含义和资源调用的频率。

输出包括:

  • 用于输入的标记
  • 输出的令牌计数
  • 发送到检索管道的子查询
  • 每个子查询的结果计数
  • 子查询上的筛选器(如果适用)
  • 用于排名和提取的令牌计数

下面是活动数组的示例。

"activity": [
    {
      "type": "ModelQueryPlanning",
      "id": 0,
      "inputTokens": 1261,
      "outputTokens": 270
    },
    {
      "type": "AzureSearchQuery",
      "id": 1,
      "targetIndex": "earth_at_night",
      "query": {
        "search": "suburban belts December brightening urban cores comparison",
        "filter": null
      },
      "queryTime": "2025-05-30T21:23:25.944Z",
      "count": 0,
      "elapsedMs": 600
    },
    {
      "type": "AzureSearchQuery",
      "id": 2,
      "targetIndex": "earth_at_night",
      "query": {
        "search": "Phoenix nighttime street grid visibility from space",
        "filter": null
      },
      "queryTime": "2025-05-30T21:23:26.128Z",
      "count": 2,
      "elapsedMs": 161
    },
    {
      "type": "AzureSearchQuery",
      "id": 3,
      "targetIndex": "earth_at_night",
      "query": {
        "search": "interstate visibility from space midwestern cities",
        "filter": null
      },
      "queryTime": "2025-05-30T21:23:26.277Z",
      "count": 0,
      "elapsedMs": 147
    },
    {
      "type": "AzureSearchSemanticRanker",
      "id": 4,
      "inputTokens": 2622
    }
  ],

查看引用数组

references 数组是底层锚定数据的直接引用,包括用于生成响应的 sourceData。 它由搜索引擎找到并按语义方式排名的每个文档组成。 sourceData 中的字段包括 id 和语义字段:titletermscontent

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