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

数据平面 REST API 版本(Azure AI 搜索)

本文列出了 Azure AI 搜索的搜索 REST API 的当前版本和过去版本。

版本控制 API 文档

REST API 文档现已进行版本控制。 打开 API 参考页时,版本选择器将显示在目录上方。 请确保 API 引用来自 引用>数据平面 文件夹。

版本选择器的屏幕截图。

稳定版本

API 版本 规范 API 更新
2024-07-01(最新) Swagger 规范 发行说明
2023-11-01 Swagger 规范 发行说明
2020-06-30 Swagger 规范 发行说明
2019-05-06 Swagger 规范 添加复杂类型。

预览版本

预览版已发布,用于测试新功能、收集反馈以及发现和修复问题。 Microsoft Azure 预览版补充使用条款下提供了预览版 API。

API 版本 规范 API 更新
2025-05-01-preview(最新) Swagger 规范 发行说明
2025-03-01-preview Swagger 规范 发行说明
2024-11-01-preview Swagger 规范 发行说明
2024-09-01-preview Swagger 规范 发行说明
2024-05-01-preview Swagger 规范 发行说明
2024-03-01-preview Swagger 规范 发行说明
2023-10-01-preview Swagger 规范 发行说明
2023-07-01-preview(已弃用) Swagger 规范 发行说明
2021-04-30-preview Swagger 规范 发行说明
2020-06-30-preview Swagger 规范 发行说明
2019-05-06-preview Swagger 规范 发行说明

发行说明

2025-05-01-preview

此预览版基于 并 2025-03-01-preview 包含 当前处于预览状态的所有功能

您只需对代码进行最少的更改,即可 将 REST API 版本从2025-03-01-preview 升级到 2025-05-01-preview

此预览版增加了对代理检索、多模式索引、文档级别权限继承的支持,以及与索引和查询工作负载中大型语言模型的更深入集成。

Azure AI 搜索中的新增功能 提供了详细信息。

功能 / 特点 更新 适用的 REST API
代理检索 使用对话语言模型添加查询扩展,以实现智能查询规划。 它还会生成一个复杂的响应,其中包括下游聊天应用程序的接地数据。 响应包括查询计划和基于源文档的引用数据。 知识代理知识检索
GenAI 提示技能 允许您指定提示和 LLM 以生成新的字段内容。 创建或更新技能集
文档布局技能 现在支持图像检测和上下文保留以进行多模态索引。 创建或更新技能集
Azure 逻辑应用集成 扩展了在工作流中运行的基于索引器的索引支持的数据源类型。 创建或更新数据源
文档级权限继承 支持每用户权限搜索结果。 创建或更新索引(权限筛选器)

创建或更新数据源(权限选项)

2025-03-01-preview

此预览版基于 并 2024-11-01-preview 包含 当前处于预览状态的所有功能。 可以通过最少的代码更改从 2024-11-01-preview 升级到 2025-03-01-preview。 有关详细信息,请参阅 升级 REST API

此预览版中只有少量数据平面 API 更新,但当您的代码调用此预览版 API 时,搜索服务上会提供更多功能。 有关详细信息,请参阅 Azure AI 搜索中的新增功能

更新 适用的 REST API
分面层次结构、聚合和筛选器,用于在分层、聚合和筛选的分面上生成分面导航结构。 搜索文档,请求中的新 facet 参数。
Semantic ranker opt-in for inflight models 创建或更新索引,在语义配置部分中新建 flightingOptIn 布尔属性。 如果您的搜索服务区域中提供了预发行版语义排名模型,则使用该模型而不是稳定版本进行二级排名。 此属性适用于希望在非生产代码上测试最新排名模型的开发人员。

2024-11-01-preview

此预览版基于 并 2024-09-01-preview 包含 当前处于预览状态的所有功能。 可以通过最少的代码更改从 2024-09-01-preview 升级到 2024-11-01-preview。 有关详细信息,请参阅 升级 REST API

更新 适用的 REST API
语义重排器中重写查询,用于优化发送到 L2 排名器的查询。 搜索文档,请求中的新 QueryRewritesType 属性。
用于分析文档结构的文档布局技能 创建或更新技能集、新的 DocumentIntelligenceLayoutSkill 技能。
用于 附加 Azure AI 多服务资源的托管标识 创建或更新 Skillset、新的 AIServicesAccountIdentity 属性。
Markdown 分析模式,用于为 Azure 存储中的 Markdown 文件编制索引。 创建或更新索引器、新的 markdown 分析模式。
压缩向量的重新记录选项,用于与原始向量(而不是压缩矢量)进行重新记录。 适用于使用二进制和标量压缩的 HNSW 和详尽 KNN 矢量算法。 创建或更新索引、新的 rescoringOptions 属性。 新的 enableRescoring 属性映射到 2024-03-01-preview 中引入的 rerankWithOriginalVectors

2024-09-01-preview

此预览版基于 并 2024-05-01-preview 包含 当前处于预览状态的所有功能。 可以从 2024-05-01-preview 升级到 2024-09-01-preview,无需更改代码。 有关详细信息,请参阅 升级 REST API

更新 适用的 REST API
截断维度,用于在 Matryoshka 表示法学习(MRL)量化上重新训练的文本嵌入-3 小模型和文本嵌入-3 大型模型。 创建或更新索引,新的 截断Dimension 参数
用于解压缩混合搜索结果的子分数或评分详细信息,这些搜索结果由 互惠排名融合(RRF)评分。 搜索文档,新的 在响应中调试 参数和查询子分数定义。
目标筛选到 混合搜索查询的向量部分。 搜索文档RawVectorQueryVectorizableTextQueryVectorizableImageUrlQueryVectorizableImageBinaryQuery中的新 filterOverride 参数。
文本拆分技能中的令牌分块,而不只是字符。 创建或更新 Skillset、新的 单元 参数和其他与令牌相关的属性。

2024-07-01

此版本为集成向量化(技能和矢量化)、标量量子化和二进制量子化提供正式版更新。 有关详细信息,请参阅 azure AI 搜索 中的 新增功能。

更新 适用的 REST API
正式发布 - 矢量数据类型 创建或更新索引
正式发布 - 矢量量化属性 搜索索引中的内置标量或二进制量子化。 创建或更新索引
正式发布 - 存储的属性向量字段,用于确定是否存储字段的额外副本。 额外的副本是该字段的可检索内容。 如果未存储该字段,则字段仍用于查询,但不能在搜索结果中返回。 可以将此属性设置为节省搜索服务的空间或搜索索引中的向量配额。 创建或更新索引
正式发布 - VectorizableTextQuery 参数进行相关性优化。 混合查询参数(MaxTextSizeRecall)仍处于预览状态。 搜索文档
正式发布 - AzureOpenAIEmbedding 技能,用于在编制索引期间支持更多的模型,而不仅仅是文本嵌入-ada-002。 将模型名称和维度属性设置为针对特定模型。 创建或更新技能集
正式发布 - Azure OpenAI 嵌入向量器,以便在查询期间实现集成向量化。 Vectorizer 属性支持更多模型。 创建或更新索引
自 2024 年 3 月 29 日起:GET 响应不再返回连接字符串或密钥。 有关详细信息,请参阅 读取连接信息的客户端代码中断性变更 所有版本

2024-05-01-preview

此预览版添加了对 OneLake 索引编制、相关性优化的支持,并在索引和查询期间与更多嵌入模型进行更深入的集成。 它基于 并 2024-03-01-preview 包含 当前处于预览状态的所有功能

若要从 2024-03-01-preview2023-10-01-preview升级,请更新 AzureOpenAIEmbedding 技能或向量器以包括模型名称和维度。 若要从 2023-07-01-preview 升级(已弃用)或分步说明,请参阅 升级 REST API

下面是此预览版中的更新。 我们还建议 Azure AI 搜索中的新增功能。

更新 适用的 REST API
OneLake 文件和快捷方式的索引器数据源。 创建或更新数据源
Collection(Edm.Byte),用于嵌入支持的模型的二进制数据类型。 矢量字段定义支持此数据类型。 创建或更新索引
多个矢量和混合查询参数用于相关性优化。 设置阈值以排除低评分结果。 权重向量查询。 对于混合查询,请设置在混合查询的文本部分中检索的最大文档。 搜索文档
新的 Azure AI 视觉技能,用于在编制索引期间实现多模式集成矢量化。 此技能调用 Azure AI 视觉的多模式 API。 创建或更新技能集
适用于多模式查询的新 Azure AI 视觉向量器。 向量器在索引定义中指定,但在查询执行期间使用。 创建或更新索引
更新了 AzureOpenAIEmbedding 技能,以支持多个模型,而不仅仅是文本嵌入-ada-002,以便在编制索引期间实现集成矢量化。 将模型名称和维度属性设置为针对特定模型。 创建或更新技能集
更新了 Azure OpenAI 嵌入向量器,以便在查询期间集成矢量化。 Vectorizer 属性支持更多模型。 创建或更新索引
自 2024 年 3 月 29 日起:GET 响应不再返回连接字符串或密钥。 有关详细信息,请参阅 读取连接信息的客户端代码中断性变更 所有版本

2024-03-01-preview

此预览版本通过添加改进矢量存储的预览 API 来构建 2023-10-01-preview。 有关详细信息,请参阅 azure AI 搜索 中的 新增功能。

更新 适用的 REST API
如果嵌入了支持这些字段的模型或输出较小向量的量化逻辑,则新 缩小矢量的数据类型 创建或更新索引
新的 矢量量化属性 搜索索引中的内置矢量压缩。 创建或更新索引
向量字段 上新的布尔 存储属性,用于确定是否存储字段的额外副本。 额外的副本是该字段的可检索内容。 如果未存储该字段,则字段仍用于查询,但不能在搜索结果中返回。 可以将此属性设置为节省搜索服务的空间或搜索索引中的向量配额。 创建或更新索引
自 2024 年 3 月 29 日起:GET 响应不再返回连接字符串或密钥。 有关详细信息,请参阅 读取连接信息的客户端代码中断性变更 所有版本

2023-11-01

此版本提供正式版功能。 有关详细信息,请参阅 azure AI 搜索 中的 新增功能。

更新 适用的 REST API
搜索帖子请求中的语义排名。 搜索文档
索引向量字段的矢量搜索配置 创建或更新索引
搜索 Post 请求中的矢量查询。 搜索文档
自 2024 年 3 月 29 日起:GET 响应不再返回连接字符串或密钥。 有关详细信息,请参阅 读取连接信息的客户端代码中断性变更 所有版本

2023-10-01-preview

此版本包括以前预览版中引入的所有功能,以及向量搜索 API 的添加和修改。 矢量搜索 API 的更新是 2023-07-01-Preview 的重大更改。 请参阅 添加矢量字段创建矢量查询 以获取迁移帮助。

如果您计划使用新的预筛选功能,则必须使用在 2023-10-01.

创建或更新索引

  • vectorSearch 具有 algorithmsprofilesvectorizers的定义:

    • algorithms 继续支持 hnsw,现在还支持 eknn,以引用分层导航小型世界(HNSW)和详尽的K近邻(eKNN)。 在算法部分中,可以定义 HNSW 和 eKNN 参数的多个命名组合。 这将替换 2023-07-01-Preview 中 algorithmConfigurations 属性中的 vectorSearch

    • profiles 是一个新定义,用于指定算法配置。 例如,假设你有名为 HNSW-1、HSNW-2、eKNN-1 的算法配置。 配置文件可以指定 HNSW-1。

    • vectorizers 在索引中定义,但在查询时用于嵌入文本查询字符串。 向量器引用嵌入模型。 搜索服务调用嵌入模型来向量化文本查询字符串,然后将结果传递给矢量查询的搜索引擎。

  • 在向量字段上,vectorSearchProfile 替换 vectorSearchConfigurationvectorSearchProfile 属性指定要在字段上使用的向量搜索配置文件。

  • 在此 API 版本之前创建的索引上,在请求中调用 2023-10-01-Preview API 时,必须更改字段以指定 vectorSearchProfile,前提是配置文件指定之前在 vectorSearchConfiguration中指定的完全相同的算法。 例如,如果现有字段定义指定 "vectorSearchConfiguration": "myHnsw",则必须将其替换为 "vectorSearchProfile": "your profile name",并且必须定义配置文件才能引用相同的 "algorithm": "myHnsw"

搜索文档

  • vectorQueries 在 2023-07-01-Preview 中替换 vectors
  • vectorQueries.vectors 在 2023-07-01-Preview 中替换 vectors.values
  • 矢量查询现在是多态结构。 必须指定 kind 以表示所请求的矢量查询的类型。 "kind": "vector" 意味着查询是矢量,因此调用方应已将搜索查询字符串矢量化为矢量嵌入。
  • "exhaustive": "true" 是一个新属性,指定是否对矢量索引中的所有向量执行详尽的(暴力破解)k-最接近的邻居搜索。
  • vectorFilterMode 是一个新参数,用于在查询中指定 prefiltering(对于 after.com 2023-10-01创建的索引的默认值)或 postfiltering(对先前的索引的默认值)。

自 2024 年 3 月 29 日起:GET 响应不再返回连接字符串或密钥。 有关详细信息,请参阅 读取连接信息的客户端代码中断性变更

2023-07-01-preview

重要

请勿使用此 API 版本。 弃用此预览版已于 2024 年 4 月 15 日发布,2024 年 7 月 8 日之后不再受支持。 有关迁移的帮助,请参阅 Azure AI 搜索中的 升级 REST API。

此版本引入了向量支持,并使用与较新的 API 版本不兼容的向量配置。

2021-04-30-preview

此预览版包括 2020-06-30-Preview 中引入的所有功能,以及以下 API 的新增功能:

2020-06-30

此版本提供正式版功能,包括:

  • 用于数据平面操作的 Azure 基于角色的访问控制
  • 相关性评分 (BM25)
  • 知识存储
  • Azure Data Lake Storage (ADLS) Gen2 的索引器数据源
  • 自定义实体查找技能
  • 通过 Microsoft Entra ID 在系统或用户托管标识下运行的索引器
  • 自 2024 年 3 月 29 日起:GET 响应不再返回连接字符串或密钥。 有关详细信息,请参阅 读取连接信息的客户端代码中断性变更

2020-06-30-preview

此预览版包括 2019-05-06-Preview 中引入的所有功能,以及以下新增功能:

  • 语义搜索是一项高级功能,可在标准层服务上运行,并调用语义排名。
  • Power Query 连接器的索引器数据源
  • MySQL 的索引器数据源
  • Cosmos DB Gremlin API 的索引器数据源
  • SharePoint Online 的索引器数据源
  • 文本规范化的 Normalizer 属性、不区分大小写的筛选、分面和排序
  • 重置基于索引器索引的文档,以按 ID 专门刷新特定文档
  • 实体链接认知技能 (v3)
  • 实体识别认知技能 (v3)
  • 情绪分析认知技能 (v3)
  • 自 2024 年 3 月 29 日起:GET 响应不再返回连接字符串或密钥。 有关详细信息,请参阅 读取连接信息的客户端代码中断性变更

2019-05-06-preview

  • Cosmos DB MongoDB API 的索引器数据源支持
  • Blob 存储中软删除的索引器数据源
  • featuresMode 参数,该参数返回有关相关性分数的详细信息
  • Azure 机器学习 (AML) 认知技能
  • 个人识别检测认知技能
  • 缓存扩充文档以保留和重用图像处理(以及其他 AI 扩充)
  • 自 2024 年 3 月 29 日起:GET 响应不再返回连接字符串或密钥。 有关详细信息,请参阅 读取连接信息的客户端代码中断性变更

另请参阅