如果语义排序代码是针对早期预览版 API 编写的，请参阅本文中有关迁移到较新 API 版本所需进行的代码更改的内容。 语义排序器的中断性变更仅限于最新 API 中的查询逻辑，但如果代码是针对初始预览版编写的，则可能还需要更改语义配置。
重大变化
不同版本的 REST API 的语义排序器有两项重大更改：
- 在 2021-04-30-preview 中，
searchFields被替换为semanticConfiguration -
queryLanguage自 2023-07-01-preview 起被忽略，但在 2024-11-01-preview 中针对查询重写功能恢复使用
版本特定的更新涉及到新功能，但不会破坏现有代码，因此不是破坏性变更。
如果你使用的是 Azure SDK，你会发现多个 API 已随着时间的推移而被重命名。 SDK 更改日志提供了详细信息。
提供语义排序的 API 版本
请检查代码中的 REST API 版本或 SDK 包版本，以确认哪一个提供语义排序。 以下 API 版本对语义排序提供一定程度的支持。
| 发布类型 | REST API 版本 | 语义排序器更新 |
|---|---|---|
| 初始 | 2020-06-30-preview | 将 queryType=semantic 添加到搜索文档中 |
| 预览 | 2021-04-30-preview | 添加了 semanticConfiguration 来创建或更新索引 |
| 预览 | 2023-07-01-preview | 更新 semanticConfiguration。 从 2023 年 7 月 14 日开始，对 Microsoft 托管语义模型的更新使语义排序器与语种无关，有效地停用了用于语义排序的 queryLanguage 属性。 代码中没有中断性变更，但该属性被忽略。 已建议客户从代码中移除此属性。 |
| 预览 | 2023-10-01-预览版 | 添加了 semanticQuery 来发送仅用于重新排序目的的查询。 |
| 稳定 | 2023-11-01 | 普遍可用。 已引入对 semanticConfiguration 所做的已推进到稳定版本的更改。 如果代码是针对此版本或更高版本的，则会与较新的 API 版本兼容，除非你采用新的预览功能。 |
| 预览 | 2024-05-01-预览版 | 无更改 |
| 稳定 | 2024-07-01 | 无更改 |
| 预览 | 2024-09-01-预览版 | 无更改 |
| 预览 | 2024-11-01-preview | 添加查询重写。 如果使用查询重写（预览版），现在需要 queryLanguage 属性。 |
Azure SDK 的更改日志
Azure SDK 具有独立的发布计划。 你应该检查更改日志，以确定哪些包提供语义功能以及是否有任何 API 已被重命名。
- 用于 .NET 的 Azure SDK 的更改日志
- 用于 Python 的 Azure SDK 的更改日志
- 用于 Java 的 Azure SDK 的更改日志
- 用于 JavaScript 的 Azure SDK 的更改日志
2024年11月01日-预览
2024-09-01-preview
与 2024-07-01 稳定版相比，语义排序语法没有变化。
2024年07月01日
与 2024-05-01-preview 版相比，语义排序语法没有变化。
请勿使用此 API 版本。 它可实现与任何较新的 API 版本不兼容的矢量查询语法。
2024-05-01-preview
与 2024-03-01-preview 版相比，语义排序语法没有变化。
2024-03-01-preview
与 2023-10-01-preview 版相比，语义排序语法没有变化，但引入了矢量查询。 语义排序现在适用于来自混合查询和矢量查询的响应。 你可以对响应中任何可人工读取的文本字段应用重新排序（假设这些字段在 prioritizedFields 中列出）。
2023年11月01日
- 排除了
SemanticDebug和semanticQuery，其余与 2023-10-01-preview 版相同。
2023-10-01-预览
- 添加
semanticQuery
2023-07-01-预览
- 添加了
semanticErrorHandling、semanticMaxWaitInMilliseconds。 - 为响应添加了许多与语义相关的字段，例如
SemanticDebug和SemanticErrorMode。 - 忽略了
queryLanguage，它不再用在语义排序中。
从 2023 年 7 月 14 日开始，语义排序器与语种无关。 在预览版中，语义排序会降低与字段分析器指定的 querylanguage 不同的结果的优先级。 不过，queryLanguage 属性仍然适用于拼写更正以及该功能支持的语言的简短列表。
2021-04-30-预览
- 语义支持通过搜索文档和创建或更新索引预览 API 调用来实现。
- 为搜索索引添加了
semanticConfiguration。 语义配置具有名称和优先字段列表。 - 添加 ``prioritizedFields`。
searchFields 属性不再用于确定字段的优先级。 在所有后续版本中，semanticConfiguration.prioritizedFields 取代 searchFields，成为指定使用哪些字段进行 L2 排序的机制。
2020-06-30-preview
- 语义支持通过搜索文档预览 API 调用来实现。
- 为查询请求添加了
queryType=semantic。 - 调整了
searchFields，这样就可以在查询类型是语义的情况下，可以通过searchFields属性确定语义排序器的字段输入的优先顺序。 - 为查询响应添加了
captions、answers和highlights。
后续步骤
通过运行语义查询来测试语义配置迁移。