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

升级到 Azure AI 搜索服务中最新的 REST API

2025-09-27

使用本文迁移到较新版本的搜索服务 REST API 以及搜索管理 REST API ，进行数据平面和控制平面操作。

下面是 REST API 的最新版本：

定向操作	REST API	状态
数据平面	`2025-09-01`	稳定
数据平面	`2025-08-01-preview`	预览
控制面板	`2025-05-01`	稳定
控制面板	`2025-02-01-preview`	预览

升级说明主要集中在代码更改上，这些更改帮助你应对以前版本的重大变更，从而确保现有代码依然可以像之前一样运行，但在较新的 API 版本上。代码按工作顺序运行后，你可以决定是否采用较新的功能。要了解有关新功能的详细信息，请参阅矢量代码示例和新增功能。

我们建议连续升级 API 版本，并处理每个版本，直到到达最新的版本。

2023-07-01-preview 是第一个用于矢量支持的 REST API。请勿使用此 API 版本。它现已弃用，应立即迁移到稳定或更新的预览版 REST API。

注意

REST API 参考文档现已进行版本控制。对于特定于版本的内容，请打开参考页，然后使用位于目录上方右侧的选择器选取版本。

何时升级

为了采取最终手段，Azure AI 搜索将会破坏后向兼容性。出现以下情况时，必须进行升级：

你的代码引用了已停用或不受支持的 API 版本，并且受到一项或多项中断性变更影响。如果代码面向 2025-05-01-preview（对于知识代理）、2023-07-10-preview（对于向量）、2020-06-01-preview（对于语义排序器）以及 2019-05-06（对于过时的技能和解决方法），则必须处理重大更改。
当 API 响应中返回无法识别的属性时，代码失效。最佳做法是，应用程序应忽略它无法理解的属性。
代码仍坚持 API 请求，并尝试将其重新发送到新 API 版本。例如，如果应用程序仍存留从搜索 API 返回的延续标记（有关详细信息，请查找@search.nextPageParameters中的）。

如何升级

如果要升级数据平面版本，请查看新 API 版本的发行说明。
将请求标头中指定的api-version参数更新为较新版本。

在直接调用 REST API 的应用程序代码中，搜索现有版本的所有实例，然后将其替换为新版本。有关构建 REST 调用的详细信息，请参阅快速入门：使用 REST 进行全文搜索。

如果使用 Azure SDK，则这些包面向特定版本的 REST API。包更新可能与 REST API 更新相吻合，但每个 SDK 都根据它自己的发布计划提供，它独立于 Azure AI 搜索 REST API 版本。检查 SDK 包的更改日志，以确定包版本是否面向最新的 REST API 版本。
如果要升级数据平面版本，请仔细查看本文档中记录的重大变更并实施解决方法。从您代码使用的版本开始，处理每个较新的 API 版本的所有破坏性更改，直至您达到最新的稳定或预览版本。

中断性变更

以下重大更改适用于数据操作。

知识代理的重大更改

知识代理是在 2025-05-01-preview 中引入的。重大更改适用于使用 targetIndexes 和 defaultMaxDocsForReranker 功能的代理，这两个功能已于 2025-08-01-preview 弃用。如需中断性变更方面的帮助，请参阅迁移智能体检索代码。

对读取连接信息的客户端代码的破坏性更改

自 2024 年 3 月 29 日起，适用于所有支持的 REST API：

GET Skillset、GET Index 和 GET Indexer 不再在响应中返回键或连接属性。如果下游代码从 GET 响应读取密钥或连接（敏感数据），则这是一项重大更改。
如果需要检索搜索服务的管理员或查询 API 密钥，请使用搜索管理 REST API。
如果需要检索另一个 Azure 资源的连接字符串（例如 Azure 存储或 Azure Cosmos DB），请使用该资源的 API 和发布的指南获取信息。

语义排序器的中断性变更

语义排名器已于 2023-11-01 正式发布。与早期版本相比，有一些重大更改：

在 2020-06-01-preview 之后的所有版本中：semanticConfiguration 取代 searchFields 作为指定使用哪些字段进行 L2 排名的机制。
对于所有 API 版本，2023 年 7 月 14 日对 Microsoft 托管语义模型的更新使语义排序器与语言无关，从而有效地停用了 queryLanguage 属性。代码中没有“中断性变更”，但该属性被忽略。

请参阅从预览版迁移，以将代码转换为使用 semanticConfiguration。

数据平面升级

升级指南假定从最新版本升级。如果代码基于旧 API 版本，我们建议通过每个后续版本进行升级，以获取最新版本。

升级到 2025年09月01日

2025-09-01 是最新的稳定 REST API 版本，增加了一般可用性，如 OneLake 索引器、文档布局技能以及其他 API。

如果您从 2024-07-01 升级并且没有使用任何预览功能，则不会有任何破坏性更改。要使用新的稳定版本，请更改 API 版本并测试代码。

升级到 2025-08-01-preview

2025-08-01-preview 对使用 2025-05-01-preview 创建的知识代理引入了以下重大更改：

将 targetIndexes 替换为 knowledgeSources。
无需更换即可删除 defaultMaxDocsForReranker。

否则，现有 API 的行为不会发生任何变化。可以在新的 API 版本中交换，代码运行方式与之前相同。

升级到 2025-05-01-preview

2025-05-01-preview 提供新功能，但现有 API 上没有行为更改。可以在新的 API 版本中交换，代码运行方式与之前相同。

升级到 2025-03-01-preview

2025-03-01-preview 提供新功能，但现有 API 上没有行为更改。可以在新的 API 版本中交换，代码运行方式与之前相同。

升级到 2024-11-01-preview

2024-11-01-preview 查询重写、文档布局技能、技能处理无密钥计费、Markdown 分析模式以及压缩矢量的重新评分选项。

如果要从 2024-09-01-preview中升级，可以在新的 API 版本中交换代码，代码运行方式与之前相同。

但是，新版本引入了对 vectorSearch.compressions 的语法更改：

将 rerankWithOriginalVectors 替换为 enableRescoring
将 defaultOversampling 移动到新的 rescoringOptions 属性对象

由于内部 API 映射，保留了向后兼容性，但如果采用新的预览版本，建议更改语法。有关语法的比较，请参阅使用标量或二进制量化压缩矢量。

升级到 2024-09-01-preview

2024-09-01-preview 添加了适合 text-embedding-3 模型的俄罗斯套娃表征学习 (MRL) 压缩、用于混合查询的目标矢量筛选、应用于调试的矢量子分数细节，以及适用于文本拆分技能的标记分块。

如果要从 2024-05-01-preview中升级，可以在新的 API 版本中交换代码，代码运行方式与之前相同。

升级到 2024-07-01

2024-07-01是正式版本。以前的预览功能现已正式发布：集成分块和矢量化（文本拆分技能、AzureOpenAIEmbedding 技能）、基于 AzureOpenAIEmbedding 的查询向量器、矢量压缩（标量量子化、二进制量子化、存储属性、窄数据类型）。

如果从2024-05-01-preview升级到稳定版本，则不会发生重大变化。要使用新的稳定版本，请更改 API 版本并测试代码。

如果直接从2023-11-01升级，则会出现破坏性变更。按照每个较新的预览版概述的步骤从2023-11-01迁移到2024-07-01。

升级到 2024-05-01-preview

2024-05-01-preview 为 Microsoft OneLake、二进制向量和其他嵌入模型添加索引器。

如果是从 2024-03-01-preview 升级，AzureOpenAIEmbedding 技能现在需要模型名称和维度属性。

在代码库中搜索 AzureOpenAIEmbedding 引用。
将 modelName 设置为“text-embedding-ada-002”，并将 dimensions 设置为“1536”。

升级到 2024-03-01-preview

2024-03-01-preview 添加了窄数据类型、标量量化和矢量存储选项。

如果您从 2023-10-01-preview 升级，则没有重大变更。但存在一个行为差异：对于 2023-11-01 及更新的预览版，vectorFilterMode的默认值从后筛选更改为预筛选。

在代码库中搜索 vectorFilterMode 引用。
如果显式设置了该属性，则无需执行任何操作。如果依赖于默认值，则新的默认行为是在查询执行之前进行筛选。如果想要进行查询后筛选，请将 vectorFilterMode 显式设置为后筛选以保留旧行为。

升级到 2023年11月1日版本

2023-11-01是正式版本。以前的预览功能现已正式发布：语义排名器和矢量支持。

从2023-10-01-preview升级没有中断性变更，但从2023-07-01-preview到2023-11-01有多个中断性变更。有关详细信息，请参阅从 2023-07-01-preview 升级。

要使用新的稳定版本，请更改 API 版本并测试代码。

升级到 2023-10-01 预览版

2023-10-01-preview 是第一个添加了内置数据分块和矢量化（索引期间）和内置查询矢量化的预览版本。它还支持上一版本中的矢量索引和查询。

如果从上一版本升级，请参阅下一部分，其中介绍了相关步骤。

从 2023-07-01-preview 升级

请勿使用此 API 版本。它可实现与任何较新的 API 版本不兼容的矢量查询语法。

2023-07-01-preview 现已弃用，因此不应基于此版本编写新代码，也不应在任何情况下升级到此版本。本部分介绍从 2023-07-01-preview 到任何较新的 API 版本的迁移路径。

矢量索引的门户升级

Azure 门户支持 2023-07-01-preview 索引的一键式升级路径。它检测矢量字段，并提供迁移按钮。

迁移路径从 2023-07-01-preview 到 2024-05-01-preview。
更新仅限于矢量字段定义和矢量搜索算法配置。
更新是单向的。升级将无法逆转。升级索引后，必须使用 2024-05-01-preview 或更高版本来查询索引。

无法通过门户迁移来升级矢量查询语法。有关查询语法更改，请参阅代码升级。

在选择“迁移”之前，请选择“编辑 JSON”以首先查看更新的架构。你应该会发现一个符合代码升级部分所述更改的模式。门户迁移仅处理具有一个矢量搜索算法配置的索引。它创建映射到 2023-07-01-preview 矢量搜索算法的默认配置文件。具有多个矢量搜索配置的索引需要手动迁移。

矢量索引和查询的代码升级

创建或更新索引（2023-07-01-preview）中引入了矢量搜索支持。

从 2023-07-01-preview 升级到任何较新的稳定版本或预览版需要：

重命名和重组索引中的矢量配置
重写矢量查询

使用本部分中的说明从 2023-07-01-preview 迁移矢量字段、配置和查询。

调用获取索引以检索现有定义。

修改矢量搜索配置。 2023-11-01 及更高版本引入了矢量配置文件的概念，将矢量相关的配置捆绑在一个名称下。较新版本还将 algorithmConfigurations 重命名为 algorithms。

将 algorithmConfigurations 重命名为 algorithms。这只是数组的重命名。内容向后兼容。这意味着可以使用现有的 HNSW 配置参数。
添加 profiles，为每个配置提供名称和算法配置。

迁移 (2023-07-01-preview) 前：

  "vectorSearch": {
    "algorithmConfigurations": [
        {
            "name": "myHnswConfig",
            "kind": "hnsw",
            "hnswParameters": {
                "m": 4,
                "efConstruction": 400,
                "efSearch": 500,
                "metric": "cosine"
            }
        }
    ]}

迁移 (2023-11-01) 后：

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

修改矢量字段定义，将 vectorSearchConfiguration 替换为 vectorSearchProfile。请确保配置文件名称解析为新的矢量配置文件定义，而不是算法配置名称。其他矢量字段属性保持不变。例如，它们应该不可筛选、不可排序或不可分面，也不能使用分析器、规范化器或同义词映射。

(2023-07-01-preview) 之前：

  {
      "name": "contentVector",
      "type": "Collection(Edm.Single)",
      "key": false,
      "searchable": true,
      "retrievable": true,
      "filterable": false,  
      "sortable": false,  
      "facetable": false,
      "analyzer": "",
      "searchAnalyzer": "",
      "indexAnalyzer": "",
      "normalizer": "",
      "synonymMaps": "", 
      "dimensions": 1536,
      "vectorSearchConfiguration": "myHnswConfig"
  }

(2023-11-01) 后:

  {
    "name": "contentVector",
    "type": "Collection(Edm.Single)",
    "searchable": true,
    "retrievable": true,
    "filterable": false,  
    "sortable": false,  
    "facetable": false,
    "analyzer": "",
    "searchAnalyzer": "",
    "indexAnalyzer": "",
    "normalizer": "",
    "synonymMaps": "", 
    "dimensions": 1536,
    "vectorSearchProfile": "myHnswProfile"
  }

调用创建或更新索引来发布更改。

修改搜索 POST 以更改查询语法。此 API 更改支持多态矢量查询类型。

将 vectors 重命名为 vectorQueries。
对于每个矢量查询，请添加 kind，将其设置为 vector。
对于每个矢量查询，请将 value 重命名为 vector。
（可选）如果使用vectorFilterMode，请添加。对于在 2023-10-01后创建的索引，默认值为预筛选。在该日期之前创建的索引仅支持后筛选，而不考虑筛选模式是如何设置的。

(2023-07-01-preview) 之前：

{
    "search": (this parameter is ignored in vector search),
    "vectors": [
      {
        "value": [
            0.103,
            0.0712,
            0.0852,
            0.1547,
            0.1183
        ],
        "fields": "contentVector",
        "k": 5
      }
    ],
    "select": "title, content, category"
}

(2023-11-01) 后:

{
  "search": "(this parameter is ignored in vector search)",
  "vectorQueries": [
    {
      "kind": "vector",
      "vector": [
        0.103,
        0.0712,
        0.0852,
        0.1547,
        0.1183
      ],
      "fields": "contentVector",
      "k": 5
    }
  ],
  "vectorFilterMode": "preFilter",
  "select": "title, content, category"
}

这些步骤完成 2023-11-01 稳定 API 版本或更新预览版 API 版本的迁移。

升级到 2020-06-30

在此版本中，有一个中断性变更和几个行为差异。正式版功能包括：

知识存储，通过技能组创建的扩充内容的持久存储，创建的目的是通过其他应用程序进行下游分析和处理。知识存储是通过 Azure AI 搜索 REST API 创建的，但它驻留在 Azure 存储中。

中断性变更

如果针对早期 API 版本编写的代码包含以下功能，那么该代码在 2020-06-30 及更高版本上会中断：

筛选器表达式中的任何 Edm.Date 文本（由年、月、日组成的日期，例如 2020-12-12）必须遵循 Edm.DateTimeOffset 格式：2020-12-12T00:00:00Z。由于时区不同，需要进行此更改才能处理错误的或意外的查询结果。

行为更改

BM25 排名算法将以前的排名算法替换为更新的技术。 2019 年之后创建的服务会自动使用此算法。对于更早的服务，必须将参数设置为使用新算法。
在此版本中，NULL 值的排序结果发生了变化，如果排序是 asc，则 NULL 值首先出现；如果排序是 desc，则 NULL 值最后出现。如果你编写代码来处理 NULL 值的排序方式，请注意此更改。

升级到 2019-05-06

此 API 版本中正式可用的功能包括：

自动完成是一项自动提示功能，可以完成部分指定的字词输入。
复杂类型原生支持搜索索引中的结构化对象数据。
JsonLines 分析模式（Azure Blob 编制索引的一部分）可为每个 JSON 实体创建以换行符分隔的搜索文档。
AI 扩充将提供可以使用 Azure AI 服务的 AI 扩充引擎的索引编制功能。

中断性变更

如果针对早期 API 版本编写的代码包含以下功能，那么该代码在 2019-05-06 及更高版本上会中断：

Azure Cosmos DB 的 Type 属性。对于面向 Azure Cosmos DB for NoSQL API 数据源的索引器，请将 "type": "documentdb" 更改为 "type": "cosmosdb"。
如果索引器错误处理包括对 status 属性的引用，则应将其删除。我们从错误响应中删除了状态，因为它没有提供有用的信息。
响应中不再返回数据源连接字符串。从 API 版本 2019-05-06 和 2019-05-06-Preview 开始，数据源 API 不再在任何 REST 操作的响应中返回连接字符串。在以前的 API 版本中，对于使用 POST 创建的数据源，Azure AI 搜索会返回 201，后跟 OData 响应，该响应包含纯文本格式的连接字符串。
命名实体识别认知技能已停用。如果在代码中调用命名实体识别技能，调用会失败。替代的功能是实体识别技能 (V3)。按照已弃用的技能中的建议，迁移到支持的技能。

升级复杂类型

API 版本 2019-05-06 添加了对复杂类型的正式支持。如果你的代码在 2017-11-11-Preview 或 2016-09-01-Preview 中实现了以前关于复杂类型等效性的建议，那么从 2019-05-06 版本开始，你需要注意一些新的和更改的限制：

每个索引的子字段深度和复杂集合数目限制已降低。如果使用预览版 API 创建了超出这些限制的索引，尝试使用 API 版本 2019-05-06 更新或重新创建这些索引将会失败。如果发现自己处于这种情况，则需要重新设计架构，使其不会超出新的限制，然后重新生成索引。
从 API 版本 2019-05-06 开始，对每个文档的复杂集合元素数目施加了新的限制。如果使用预览版 API 创建了文档超出这些限制的索引，尝试使用 API 版本 2019-05-06 重建该数据的索引将会失败。如果遇发现自己处于这种情况，需要在重建数据的索引之前，减少每个文档的复杂集合元素数目。

有关详细信息，请参阅 Azure AI 搜索的服务限制。

如何升级旧的复杂类型结构

如果代码使用在早期 API 预览版中创建的复杂类型，则你可能正在使用如下所示的索引定义格式：

{
  "name": "hotels",  
  "fields": [
    { "name": "HotelId", "type": "Edm.String", "key": true, "filterable": true },
    { "name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false },
    { "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
    { "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
    { "name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true, "analyzer": "tagsAnalyzer" },
    { "name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true },
    { "name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true },
    { "name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address", "type": "Edm.ComplexType" },
    { "name": "Address/StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true },
    { "name": "Address/City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/Country", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Location", "type": "Edm.GeographyPoint", "filterable": true, "sortable": true },
    { "name": "Rooms", "type": "Collection(Edm.ComplexType)" }, 
    { "name": "Rooms/Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene" },
    { "name": "Rooms/Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.lucene" },
    { "name": "Rooms/Type", "type": "Edm.String", "searchable": true },
    { "name": "Rooms/BaseRate", "type": "Edm.Double", "filterable": true, "facetable": true },
    { "name": "Rooms/BedOptions", "type": "Edm.String", "searchable": true },
    { "name": "Rooms/SleepsCount", "type": "Edm.Int32", "filterable": true, "facetable": true },
    { "name": "Rooms/SmokingAllowed", "type": "Edm.Boolean", "filterable": true, "facetable": true },
    { "name": "Rooms/Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "facetable": true, "analyzer": "tagsAnalyzer" }
  ]
}

API 版本 2017-11-11-Preview 中引入了一种更新的用于定义索引字段的树形格式。在新格式中，每个复杂字段提供一个字段集合，可在该集合中定义该字段的子字段。在 API 版本 2019-05-06 中，此新格式是以独占方式使用的，使用旧格式尝试创建或更新索引将会失败。如果索引是使用旧格式创建的，则你需要使用 API 版本 2017-11-11-Preview 将其更新到新格式，然后才能使用 API 版本 2019-05-06 来管理它们。

要更新“平面”索引为新格式，可以使用 API 版本 2017-11-11-Preview 执行以下步骤：

执行 GET 请求以检索索引。如果该索引已采用新格式，则无需执行后续操作。
将索引从“平面”格式转换为新格式。必须为此任务编写代码，因为在撰写本文时尚未有示例代码可用。
执行 PUT 请求，将索引更新为新格式。避免更改索引的任何其他详细信息（例如字段的可搜索性/可筛选性），因为更新索引 API 不允许那些影响现有索引的物理表达式的更改。

注意

无法从 Azure 门户管理使用旧“平面”格式创建的索引。尽早将索引从“平面”表示形式升级到“树”表示形式。

控制平面升级

适用于：2014-07-31-Preview、 2015-02-28和 2015-08-19

listQueryKeys旧版搜索管理 API 版本的 GET 请求现已弃用。建议迁移到最新的稳定控制平面 API 版本，以使用 listQueryKeys POST 请求。

在现有代码中，将 api-version 参数更改为最新版本（2025-05-01）。

将请求从GET更改为POST。

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Search/searchServices/{searchServiceName}/listQueryKeys?api-version=2025-05-01
Authorization: Bearer {{token}}

如果使用 Azure SDK，建议升级到最新版本。

后续步骤

查看搜索 REST API 参考文档。如果遇到问题，请通过 Stack Overflow 向我们寻求帮助，或联系支持人员。

搜索服务 REST API 参考

反馈

此页面是否有帮助？

通过

升级到 Azure AI 搜索服务中最新的 REST API

何时升级

如何升级

中断性变更

知识代理的重大更改

对读取连接信息的客户端代码的破坏性更改

语义排序器的中断性变更

数据平面升级

升级到 2025年09月01日

升级到 2025-08-01-preview

升级到 2025-05-01-preview

升级到 2025-03-01-preview

升级到 2024-11-01-preview

升级到 2024-09-01-preview

升级到 2024-07-01

升级到 2024-05-01-preview

升级到 2024-03-01-preview

升级到 2023年11月1日版本

升级到 2023-10-01 预览版

从 2023-07-01-preview 升级

矢量索引的门户升级

矢量索引和查询的代码升级

升级到 2020-06-30

中断性变更

行为更改

升级到 2019-05-06

中断性变更

升级复杂类型

如何升级旧的复杂类型结构

控制平面升级

后续步骤

反馈

其他资源