如果您的語意排名程式碼是針對早期預覽 API 撰寫，本文會識別移轉至較新版本 API 所需的程式碼變更。 語意排名工具的重大變更僅限於最近 API 中的查詢邏輯，但如果您的程式碼是針對初始預覽版本製作的，您可能也需要變更語意設定。
重大變更
在 REST API 版本中，語意排名工具有兩項重大變更：
-
searchFields已在 2021-04-30-preview 中由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-preview | 新增 semanticQuery 以傳送僅用於重新排名用途的查詢。 |
| stable | 2023-11-01 | 正式推出。 對 semanticConfiguration 推出變更，推展至穩定版本。 如果您的程式碼以此版本或更新版本為目標，除非您採用新的預覽功能，否則它與較新的 API 版本相容。 |
| 預覽 | 2024-05-01-preview | 沒有變更 |
| stable | 2024-07-01 | 沒有變更 |
| 預覽 | 2024-09-01-preview | 沒有變更 |
| 預覽 | 2024-11-01-preview | 新增查詢重寫。 如果您使用queryLanguage，現在需要 屬性。 |
| 預覽 | 2025-03-01-preview | 將加入新增至語意模型的發行前版本。 |
| 預覽 | 2025-05-01-preview | 此預覽版中沒有 API 更新，但語意排名現在與 評分配置檔有較佳的整合。 |
| 預覽 | 2025-08-01-preview | 沒有變更 |
| 預覽 | 2025-11-01-preview | 於免費層級提供。 |
Azure SDK 的變更記錄
要判斷特定 Azure SDK 套件中有哪些語意特性可用，以及是否有 API 被重新命名，請參閱 SDK 的變更日誌：
- Azure SDK for .NET 變更記錄
- Azure SDK for Python 變更記錄
- Azure SDK for Java 變更記錄
- Azure SDK for JavaScript 變更記錄
2024-11-01-preview
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-preview
- 新增
semanticErrorHandling、semanticMaxWaitInMilliseconds。 - 將許多語意相關欄位新增至回應，例如
SemanticDebug和SemanticErrorMode。 - 忽略
queryLanguage，語意排名中不再使用。
從 2023 年 7 月 14 日開始，語意排名工具不受限於語言。 在預覽版本中，針對與欄位分析器所指定 querylanguage 不同的結果，語意排名會降低其優先順序。 不過，queryLanguage 屬性仍然適用於拼字校正和該功能所支援的語言簡短清單。
2021-04-30-preview
- 語意支援是透過搜尋文件和建立或更新索引預覽 API 呼叫。
- 將
semanticConfiguration新增至搜尋索引。 語意設定具有名稱和優先順序欄位清單。 - 新增 ``prioritizedFields`。
searchFields 屬性不再用來設定欄位的優先順序。 在之後的所有版本中，semanticConfiguration.prioritizedFields 會取代 searchFields 作為指定用於 L2 排名的欄位的機制。
2020-06-30-preview
- 語意支援是透過搜尋文件預覽 API 呼叫。
- 將
queryType=semantic新增至查詢要求。 - 調整
searchFields讓查詢類型為語意，searchFields屬性會決定欄位輸入對語意排名工具的優先順序。 - 將
captions、answers和highlights新增至查詢回應。
後續步驟
透過執行語意查詢，測試您的語意設定移轉。