在 Azure AI 搜索中创建用于代理检索的索引

注释

某些智能检索功能在2026-04-01 REST API版本中通过编程访问已普遍可用。

如果选择使用预览版 REST API 版本，则可以访问尚未正式提供的代理检索功能。预览版功能在没有服务级别协议的情况下提供，不建议用于生产工作负荷。

本文介绍代理检索所需的索引字段和配置。这些要求都不是新的。可以使用符合条件的现有索引，即使它是使用早期 API 版本创建的。

每个索引的知识源都依赖于基础索引。根据管道的设置方式，索引可以是以下项之一：

现有： 通过搜索索引知识源公开的独立索引。索引必须满足本文中的条件。
生成： 由索引知识源自动创建的索引。默认情况下，生成的索引满足所有条件。

智能体检索的条件

下表按要求级别组织影响代理检索的索引元素。

索引元素	要求	注释
`searchable` 和 `retrievable` 字符串字段	Required	用于查询执行和结果检索。
语义配置	Required	使用 `defaultSemanticConfiguration` 或替代知识源中的语义配置。
引用字段	推荐	用户定义字段，这些字段将响应属性为源内容，例如文档名称、页码或区块 ID。
矢量字段和向量器	推荐	在查询时启用文本到矢量转换。
评分配置	Optional	提高特定领域的相关性。将 `defaultScoringProfile` 设置为自动应用。
分析器	Optional	控制文本的标记方式，例如处理空格或特殊字符。
同义词映射	Optional	通过加入术语或行话来扩展查询。

示例索引定义

下面是一个可用于代理检索的示例索引。它满足所需元素的条件，并作为最佳做法包括矢量字段。

{
  "name": "earth_at_night",
  "description": "Contains images an descriptions of our planet in darkness as captured from space by Earth-observing satellites and astronauts on the International Space Station over the past 25 years.",
  "fields": [
    {
      "name": "id", "type": "Edm.String",
      "searchable": true, "retrievable": true, "filterable": true, "sortable": true, "facetable": true,
      "key": true,
      "stored": true,
      "synonymMaps": []
    },
    {
      "name": "page_chunk", "type": "Edm.String",
      "searchable": true, "retrievable": true, "filterable": false, "sortable": false, "facetable": false,
      "analyzer": "en.microsoft",
      "stored": true,
      "synonymMaps": []
    },
    {
      "name": "page_chunk_vector_text_3_large", "type": "Collection(Edm.Single)",
      "searchable": true, "retrievable": false, "filterable": false, "sortable": false, "facetable": false,
      "dimensions": 3072,
      "vectorSearchProfile": "hnsw_text_3_large",
      "stored": false,
      "synonymMaps": []
    },
    {
      "name": "page_number", "type": "Edm.Int32",
      "searchable": false, "retrievable": true, "filterable": true, "sortable": true, "facetable": true,
      "stored": true,
      "synonymMaps": []
    },
    {
      "name": "chapter_number", "type": "Edm.Int32",
      "searchable": false, "retrievable": true, "filterable": true, "sortable": true, "facetable": true,
      "stored": true,
      "synonymMaps": []
    }
  ],
  "semantic": {
    "defaultConfiguration": "semantic_config",
    "configurations": [
      {
        "name": "semantic_config",
        "flightingOptIn": false,
        "prioritizedFields": {
          "prioritizedContentFields": [
            {
              "fieldName": "page_chunk"
            }
          ],
          "prioritizedKeywordsFields": []
        }
      }
    ]
  },
  "vectorSearch": {
    "algorithms": [
      {
        "name": "alg",
        "kind": "hnsw",
        "hnswParameters": {
          "metric": "cosine",
          "m": 4,
          "efConstruction": 400,
          "efSearch": 500
        }
      }
    ],
    "compressions": []
  }
}

为生成式 AI 或检索增强生成（RAG）设计良好的索引具有以下组成部分：

LLM 或代理可以用来确定是否应使用或跳过索引的描述。
可作为输入令牌传递给 LLM 以生成答案的人类可读的文本块。
语义排名器配置，因为代理检索使用级别 2 （L2）语义排名来标识最相关的区块。
（可选）用于补充矢量搜索的人类可读文本区块的矢量等效版本。

分块文本很重要，因为 LLM 使用并发出可读纯文本内容的标记化字符串。出于此原因，需要 searchable 提供纯文本字符串且 retrievable 位于响应中的字段。在Azure AI 搜索中，可以使用内置或第三方解决方案创建分块文本。

分块内容的内置假设是原始源文档具有大量详细内容。如果源内容是结构化数据（如产品数据库），索引应放弃分块，而是包括映射到原始数据源的字段，例如产品名称、类别或说明。 searchable 和 retrievable 的署名要求同样适用于结构化数据。 searchable 使内容进入查询范围，retrievable 则将其添加到搜索结果中（基础数据）。

矢量内容可能很有用，因为它增加了对信息检索的 相似性搜索 。在查询时，当索引中存在矢量字段时，代理检索引擎将并行执行向量查询与文本查询。由于矢量查询查找类似内容而不是匹配字词，因此矢量查询可以找到文本查询可能错过的高度相关结果。添加矢量可以增强和提高地面数据的质量，但并非严格要求。 Azure AI 搜索具有内置的方法来进行矢量化。

矢量字段仅用于Azure AI 搜索上的查询执行。你不需要结果中的向量，因为它不是人或 LLM 可读的。为了最大程度地减少空间要求，我们建议设置 retrievable 和 stored 设置为 false。有关详细信息，请参阅优化矢量存储和处理。

如果使用矢量，请在矢量搜索配置中定义向量化器至关重要。它确定您的矢量（向量）字段是否在查询执行期间使用。 vectorizer 在查询时将字符串子查询编码为矢量，以便对矢量进行相似性搜索。向量器必须是用于在索引中创建矢量的同一嵌入模型。

默认情况下，所有 searchable 字段都包含在查询执行中，所有 retrievable 字段都会在结果中返回。你可以选择要用于搜索索引知识源定义中每个操作的字段。

添加说明

索引 description 字段是用户定义的字符串，可用于在决定对查询使用特定索引时向 LLM 和模型上下文协议（MCP）服务器提供指导。当系统必须访问多个索引并根据说明做出决策时，此可读文本非常有用。

索引说明是架构更新，无需重新生成整个索引即可添加它。

字符串长度最大为 4,000 个字符。
在 Unicode 中，内容必须是人可读的。用例应确定要使用的语言（例如英语或其他语言）。

添加语义配置

索引必须至少有一个语义配置。语义配置必须具有：

命名配置。
prioritizedContentFields 设置为至少一个字符串字段，该字段同时为 searchable 和 retrievable。

可通过两种方法按名称指定语义配置。如果索引已 defaultSemanticConfiguration 设置为命名配置，则检索会使用它。或者，可以在搜索索引知识源内指定语义配置。

在配置中， prioritizedContentFields 是必需的。标题和关键字是可选的。对于分块内容，你可能两者都没有。但是，如果添加实体识别或关键短语提取，则可能具有一些与每个区块关联的关键字，这些关键字可用于搜索方案（也许在计分配置文件中）。

下面是可用于代理检索的语义配置的示例：

"semantic":{
   "defaultConfiguration":"semantic_config",
   "configurations":[
      {
         "name":"semantic_config",
         "flightingOptIn":false,
         "prioritizedFields":{
            "prioritizedFields":{
               "titleField":{
                  "fieldName":""
               },
               "prioritizedContentFields":[
                  {
                     "fieldName":"page_chunk"
                  }
               ],
               "prioritizedKeywordsFields":[
                  {
                     "fieldName":"Category"
                  },
                  {
                     "fieldName":"Tags"
                  },
                  {
                     "fieldName":"Location"
                  }
               ]
            }
         }
      }
   ]
}

注释

响应提供title、terms和content，这些映射到此配置中的优先字段。

添加向量器

如果索引包含向量字段，则查询计划包括这些字段（如果这些字段是 searchable 且具有 vectorizer 分配）。

向量器指定一个嵌入模型，该模型在查询时提供文本到向量转换。它必须指向用于在索引中对矢量内容进行编码的同一嵌入模型。可以使用Azure AI 搜索支持的任何嵌入模型。通过 矢量配置文件 为向量字段指定向量化器。

索引示例中的 向量字段定义 显示了键字段属性： dimensions这是模型生成的嵌入次数，以及 vectorSearchProfile。

  {
    "name": "page_chunk_text_3_large", "type": "Collection(Edm.Single)",
    "searchable": true, "retrievable": false, "filterable": false, "sortable": false, "facetable": false,
    "dimensions": 3072,
    "vectorSearchProfile": "hnsw_text_3_large",
    "stored": false,
    "synonymMaps": []
  }

矢量概要是矢量化器、算法和压缩技术的配置。每个向量字段只能使用一个配置文件，但如果希望每个向量字段具有唯一的配置文件，您的索引可以包含多个配置文件。

查询向量和调用向量器会增加整个请求的延迟，但如果想要相似性搜索，它可能值得权衡。

下面是一个用于代理检索的向量器示例，如 vectorSearch 配置中所示。矢量化定义中没有任何内容需要更改才能使用代理检索。

"vectorSearch": {
  "algorithms": [
    {
      "name": "alg",
      "kind": "hnsw",
      "hnswParameters": {
        "metric": "cosine",
        "m": 4,
        "efConstruction": 400,
        "efSearch": 500
      }
    }
  ],
  "profiles": [
    {
      "name": "hnsw_text_3_large",
      "algorithm": "alg",
    }
  ],
  "compressions": []
}

添加计分概要文件

计分概要文件是相关性提升的条件。它们应用于非矢量字段（文本和数字），并在查询执行期间进行评估，尽管精确行为取决于用于创建索引的 API 版本。

如果索引基于结构化数据，评分配置文件更可能提升解决方案的价值。结构化数据被索引到多个离散字段，这意味着计分配置文件可以有针对特定字段的内容或特征的条件。

如果使用 2025-05-01-preview 或更高版本创建索引，计分概要文件将最后执行。如果索引是使用早期 API 版本创建的，则计分概要文件将在语义重新排序之前进行评估。语义排名结果的实际顺序由索引中的 rankOrder 属性确定，该属性设置为 boostedRerankerScore （已应用评分配置文件）或 rerankerScore （无评分配置文件）。

可以使用对你的索引有意义的任何计分概要文件。下面是一个示例，当特定字段中找到匹配项时，该示例可提升匹配项的搜索分数。字段通过提升乘数来加权。例如，如果在“类别”字段中找到匹配项，则提升分数乘以 5。

"scoringProfiles": [
    {
      "name": "boostSearchTerms",
      "text": {
        "weights": {
          "Location": 2,
          "Category": 5 
        }
      }
    }
]

添加分析器

分析器适用于文本字段，可以是语言分析器或自定义分析器，用于控制索引中的标记化，例如保留特殊字符或空格。

分析器在搜索索引中定义，并分配给字段。字段集合示例包含文本区块上的分析器引用。在此示例中，默认分析器（标准 Lucene）替换为Azure语言分析器。

{
  "name": "page_chunk", "type": "Edm.String",
  "searchable": true, "retrievable": true, "filterable": false, "sortable": false, "facetable": false,
  "analyzer": "en.microsoft",
  "stored": true,
  "synonymMaps": []
}

添加同义词映射

同义词映射通过为命名术语添加同义词来扩展查询。例如，常见术语可能对应于科学或医学术语。

同义词映射被定义为搜索索引上的顶级资源，并被分配到字段。字段集合示例不包括同义词映射，但如果在同义词映射中对区域名称进行了变体拼写，则以下示例在分配给假设的“locations”字段时可能如下所示。

{
    "name":"locations",
    "type":"Edm.String",
    "searchable":true,
    "synonymMaps":[ "region-synonyms" ]
}

将索引添加到知识源

如果你有一个已存在且不是由知识源生成的独立索引，请创建以下对象：

用于封装索引内容的搜索索引知识源。
表示一个或多个知识源的知识库，以及用于代理检索的其他说明。

Azure AI 搜索中的 Agentic 检索

Last updated on 2026-06-30

在 Azure AI 搜索 中创建用于代理检索的索引