你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
本文列出了 Azure AI 搜索的搜索 REST API 的当前版本和过去版本。
版本控制 API 文档
REST API 文档现已进行版本控制。 打开 API 参考页时，版本选择器将显示在目录上方。 当您从“参考数据平面”>文件夹中选择页面时，选择器将变为可用。
稳定版本
| API 版本 | 规范 | API 更新 |
|---|---|---|
2025-09-01（最新） |
Swagger 规范 | 发行说明 |
2024-07-01 |
Swagger 规范 | 发行说明 |
2023-11-01 |
Swagger 规范 | 发行说明 |
2020-06-30 |
Swagger 规范 | 发行说明 |
2019-05-06 |
Swagger 规范 | 添加复杂类型。 |
预览版本
在过渡到稳定版本之前，所有新功能都在预览 API 中引入。 Microsoft Azure 预览版
| API 版本 | 规范 | API 更新 |
|---|---|---|
2025-08-01-preview（最新） |
Swagger 规范 | 发行说明 |
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-09-01
此 API 版本是适用于 Azure AI 搜索的最新稳定 REST API。 它基于以前的稳定版本 （2024-07-01） 构建，并添加了下表中列出的 API 更新。
其他一些正式发布的功能（如 逻辑应用集成 和 语义评分配置文件支持）不会影响 API 协定，也不会反映在表中。 有关公告的完整列表，请参阅 Azure AI 搜索中的新增功能 。
| 功能 / 特点 | 更新 | 适用的 REST API |
|---|---|---|
| OneLake 索引器 | 自动从 Microsoft OneLake 湖屋检索和索引数据。 | 创建或更新数据源 |
| 文档布局技能 | 根据文档结构对文本进行分块。 | 创建或更新技能集 |
| 规范化器属性 | 支持不区分大小写的筛选、分面和排序。 | 创建或更新索引 |
| 索引描述属性 | 描述一个索引，该索引有助于 RAG 工作负载中的提示工程。 | 创建或更新索引 |
| 压缩载体的重新评分选项 | 使用原始向量而不是压缩向量重新评分向量搜索结果。 适用于使用二进制和标量压缩的 HNSW 和详尽 KNN 矢量算法。 | 创建或更新索引 |
| 截断尺寸 | 适用于文本嵌入 3-small 和文本嵌入 3-large 模型，在俄罗斯套娃表示学习 （MRL） 量化上重新训练。 | 创建或更新索引 |
| 调试参数和查询子分数 | 将 混合搜索结果分数 解压缩为其组成部分。 | 搜索文档 |
2025-08-01-preview
此预览版基于 并 2025-05-01-preview 包含 当前处于预览状态的所有功能。
如果您使用 创建 2025-05-01-preview 知识代理，则此预览版将引入重大更改。 有关迁移的帮助，请参阅 将代理检索代码迁移到最新版本。
有关这些更新的详细信息，请参阅 Azure AI 搜索中的新增功能。
| 功能 / 特点 | 更新 | 适用的 REST API |
|---|---|---|
| 知识代理 | 对知识代理定义的体系结构更改，现在需要一个或多个knowledgeSourcestargetIndexes而不是 和弃用 defaultMaxDocsForReranker。添加多个属性以更好地控制查询规划和执行，包括 |
知识代理 - 创建或更新 |
| 知识来源 | 用于创建和管理知识源的新 REST API，支持 searchIndex （一个或多个索引）和 azureBlob 类型。 |
知识来源 |
| 对矢量查询进行严格的后筛选 |
strictPostFilter的新值vectorFilterMode，在识别全局顶k向量结果后应用过滤器。 |
文件 - 搜索帖子 |
| 增加矢量场的最大尺寸 | 每个向量场的最大值 dimensions 现在 4096为 。 此更新适用于支持向量且不会引入重大更改的所有稳定版和预览版 REST API 版本。 |
索引 - 创建或更新 |
| 改进的索引器运行时跟踪信息 | “获取服务统计信息” 现在返回整个搜索服务的累积索引器处理信息。 获取状态 - 索引器 为各个索引器提供相同的信息。 | 获取服务统计信息 并 获取状态 - 索引器 |
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 包含 当前处于预览状态的所有功能。 您只需对代码进行最少的更改，即可 将 REST API 版本从2024-11-01-preview 升级到 2025-03-01-preview 。
此预览版中只有少量数据平面 API 更新，但当您的代码调用此预览版 API 时，搜索服务上会提供更多功能。 有关详细信息，请参阅 Azure AI 搜索中的新增功能。
| 更新 | 适用的 REST API |
|---|---|
| 分面层次结构、聚合和筛选器，用于在分层、聚合和筛选的分面上生成分面导航结构。 | 搜索文档，请求中的新 facet 参数。 |
| 机中模型的语义排名器选择加入 | 创建或更新索引，在语义配置部分中新建 flightingOptIn 布尔属性。 如果您的搜索服务区域中提供了预发行版语义排名模型，则使用该模型而不是稳定版本进行二级排名。 此属性适用于希望在非生产代码上测试最新排名模型的开发人员。 |
2024-11-01-preview
此预览版基于 并 2024-09-01-preview 包含 当前处于预览状态的所有功能。 您只需对代码进行最少的更改，即可 将 REST API 版本从2024-09-01-preview 升级到 2024-11-01-preview 。
| 更新 | 适用的 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）评分。 | 搜索文档，新的 在响应中调试 参数和查询子分数定义。 |
| 目标筛选到 混合搜索查询的向量部分。 | 搜索文档、RawVectorQuery、VectorizableTextQuery、VectorizableImageUrlQuery、VectorizableImageBinaryQuery中的新 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-preview 或 2023-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具有algorithms、profiles和vectorizers的定义：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替换vectorSearchConfiguration。vectorSearchProfile属性指定要在字段上使用的向量搜索配置文件。在此 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.com2023-10-01创建的索引的默认值）或 postfiltering（对先前的索引的默认值）。
自 2024 年 3 月 29 日起：GET 响应不再返回连接字符串或密钥。 有关详细信息，请参阅 读取连接信息的客户端代码中断性变更。
2023-07-01-preview
重要
请勿使用此 API 版本。 弃用此预览版已于 2024 年 4 月 15 日发布，2024 年 7 月 8 日之后不再受支持。 有关迁移的帮助，请参阅 Azure AI 搜索中的
此版本引入了向量支持，并使用与较新的 API 版本不兼容的向量配置。
- 在包含单精度浮点数数组的字段上添加了
Collection(Edm.Single)数据类型。 这是矢量的数据类型，用于存储每个文档字段生成的嵌入。 搜索索引还指定矢量配置属性。 - 更新了索引工作负载以接受矢量数据。
- 添加了矢量搜索的查询参数。 有关这些参数，请参阅搜索文档。
- 获取服务统计信息：返回服务的向量索引配额和使用情况。
- 获取索引统计信息：返回搜索索引的向量索引配额和使用情况。
- 自 2024 年 3 月 29 日起：GET 响应不再返回连接字符串或密钥。 有关详细信息，请参阅 读取连接信息的客户端代码中断性变更。
2021-04-30-preview
此预览版包括 2020-06-30-Preview 中引入的所有功能，以及以下 API 的新增功能：
- 索引别名添加一个辅助名称，用于在查询和索引请求中引用索引。 别名操作包括创建、更新、删除、获取和列表。
- 出站连接的托管标识。 “创建或更新数据源”中连接字符串的新值支持使用 Microsoft Entra ID 身份验证和角色（而不是硬编码的数据库凭据或密钥）进行连接。
- 密钥保管库连接也支持托管标识支持，对于使用 客户管理的加密补充默认加密的搜索解决方案。
- 文本翻译认知技能的更多语言。
- 搜索文档中用于语义搜索和拼写检查器的更多查询语言。
- captions 参数，用于选择从“搜索文档”中的语义搜索请求标题。
- 语义配置在 创建或更新索引中指定。 语义配置确定应用于语义排名、标题、突出显示和答案的字段。
- 搜索文档中的语义查询所需的 semanticConfiguration 参数。
- 自 2024 年 3 月 29 日起：GET 响应不再返回连接字符串或密钥。 有关详细信息，请参阅 读取连接信息的客户端代码中断性变更。
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 响应不再返回连接字符串或密钥。 有关详细信息，请参阅 读取连接信息的客户端代码中断性变更。
另请参阅
- 创建搜索服务
- 快速入门：使用 REST API 创建 Azure AI 搜索索引