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

项目
08/12/2024

根据本文将数据平面调用迁移到较新版本的搜索 REST API。

2024-07-01 是最新的稳定版本。
2024-05-01-preview 是最新的预览版 API 版本。

升级说明侧重于代码更改，这些更改可让你完成以前版本的中断性变更，以便现有代码像之前那样运行，只是针对较新的 API 版本。代码按工作顺序运行后，你可以决定是否采用较新的功能。要了解有关新功能的详细信息，请参阅矢量代码示例和新增功能。

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

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

注意

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

何时升级

Azure AI 搜索将后向兼容性作为最后的手段。出现以下情况时，必须进行升级：

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

如何升级

参数 api-version 在请求标头中指定。在直接调用 REST API 的应用程序代码中，搜索现有版本的所有实例，然后将其替换为新版本。有关构建 REST 调用的详细信息，请参阅“快速入门：使用 REST”。

如果使用 Azure SDK，则这些包面向特定版本的 REST API。包更新可能与 REST API 更新相吻合，但每个 SDK 都根据它自己的发布计划提供，它独立于 Azure AI 搜索 REST API 版本。检查 SDK 包的更改日志，以确定包版本是否面向最新的 REST API 版本。

读取连接信息的客户端代码的重大更改

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

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

从 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 门户中管理使用旧的“平面”格式创建的索引。请尽早将索引的“平面”表示形式升级到“树形”表示形式。

后续步骤

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

搜索服务 REST API 参考

通过

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

何时升级

如何升级

读取连接信息的客户端代码的重大更改

从 2023-07-01-preview 升级

矢量索引的门户升级

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

升级到 2020-06-30

中断性变更

行为更改

升级到 2019-05-06

中断性变更

升级复杂类型

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

后续步骤

其他资源