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 規格 | 加入複雜型別。 |
預覽版本
預覽版本已發行以測試新功能、收集意見反應，以及探索並修正問題。 預覽版 API 可在 Microsoft Azure Previews的補充使用規定下取得。
| API 版本 | 規範 | API 更新 |
|---|---|---|
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 規格 | 版本資訊 |
版本資訊
2024-11-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 剖析模式。 |
| 壓縮向量的 Rescoring 選項，用於重新記錄原始向量，而不是壓縮向量。 適用於 HNSW 和詳盡的 KNN 向量演算法，使用二進位和純量壓縮。 |
建立或更新索引，新的 rescoringOptions 屬性。 新的 enableRescoring 屬性對應至 2024-03-01-preview 中引進的 rerankWithOriginalVectors。 |
2024-09-01-preview
此預覽是以 2024-05-01-preview 升級至 2024-09-01-preview，不需要變更程序代碼。 如需詳細資訊，請參閱 升級 REST API。
| 更新 | 適用的 REST API |
|---|---|
| 在 Matryoshka 表示法學習 （MRL） 量化上重新定型的文字內嵌-3-small 和 text-embedding-3-large 模型的截斷維度。 | 建立或更新索引，新的 截斷Dimension 參數 |
| 解除封裝混合式搜尋結果的子分數或評分詳細數據，倒數排名融合 （RRF）。 | 搜尋檔、新的 偵錯 參數和查詢回應中的子核心定義。 |
| 混合式搜尋查詢的向量部分目標篩選。 | Search Documents、RawVectorQuery、VectorizableTextQuery、VectorizableImageUrlQueryVectorizableImageBinaryQuery中的 new 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 或 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
此預覽版本是以 2023-10-01-preview 為基礎，新增可改善向量儲存的預覽 API。 如需詳細資訊，請參閱 Azure AI 搜尋 的新功能。
| 更新 | 適用的 REST API |
|---|---|
| 如果您已內嵌支援向量字段的模型，或輸出較小向量的量化邏輯，則新的 縮小向量數據類型。 | 建立或更新索引 |
| 新的 向量量化屬性 搜尋索引中內建向量壓縮。 | 建立或更新索引 |
| 建立或更新索引 | |
| 自 2024 年 3 月 29 日生效：GET 回應不再傳回連接字串或密鑰。 如需詳細資訊，請參閱 讀取連線資訊 客戶端程式代碼的重大變更。 | 所有版本 |
2023-11-01
此版本提供正式運作的功能。 如需詳細資訊，請參閱 Azure AI 搜尋 的新功能。
| 更新 | 適用的 REST API |
|---|---|
| 搜尋張貼要求中的語意排名。 | 搜尋檔 |
| 索引向量欄位的向量搜尋組態 | 建立或更新索引 |
| 搜尋張貼要求中的向量查詢。 | 搜尋檔 |
| 自 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-PreviewalgorithmConfigurations屬性內的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是用於指定預先篩選的新參數（在 2023-10-01 之後建立的索引預設值）或查詢中的後續篩選（預設為先前索引）。
自 2024 年 3 月 29 日生效：GET 回應不再傳回連接字串或密鑰。 如需詳細資訊，請參閱 讀取連線資訊 客戶端程式代碼的重大變更。
2023-07-01-preview
重要
請勿使用此 API 版本。 已於 2024 年 4 月 15 日宣佈淘汰此預覽版本，並在 2024 年 7 月 8 日之後不再支援。 如需移轉的說明，請參閱在 Azure AI 搜尋服務中 升級 REST API。
此版本引進向量支援，並使用與較新的 API 版本不相容的向量組態。
- 已在包含單精度浮點數陣列的欄位上新增
Collection(Edm.Single)數據類型。 這是向量的數據型別，用來儲存每個檔欄位產生的內嵌。 搜尋索引也會指定向量組態屬性。 如需這些 API，請參閱 建立或更新索引。 - 已更新索引編製工作負載以接受向量數據。 請參閱 新增、更新或刪除檔。
- 已新增向量搜尋的查詢參數。 如需這些參數，請參閱 搜尋檔。
- 取得服務統計數據：傳回服務的向量索引配額和使用量。
- 取得索引統計數據：傳回搜尋索引的向量索引配額和使用方式。
- 自 2024 年 3 月 29 日生效：GET 回應不再傳回連接字串或密鑰。 如需詳細資訊，請參閱 讀取連線資訊 客戶端程式代碼的重大變更。
2021-04-30-preview
此預覽版本包含 2020-06-30-Preview 中引進的所有功能，以及下列 API 的新增功能：
- 索引別名 新增用於參考查詢和索引要求中索引的次要名稱。 別名作業包括建立、更新、刪除、取得和清單。
- 輸出連線的受控識別。 建立或更新數據源中連接字串的新值， 支援使用 Microsoft Entra ID 驗證和角色，而不是硬式編碼的資料庫認證或密鑰連線。
- 密鑰保存庫連線也支援受控識別支援，以 客戶管理的加密來補充預設加密的搜尋解決方案。
- 文字翻譯認知技能的更多語言。
- 在 搜尋檔 （預覽） 中，更多語意搜尋和拼字檢查的 queryLanguages。
- 在 搜尋檔 （預覽）中，選擇性地要求語意搜尋的 captions 參數。
- 語意組態 是在 建立或更新索引中指定。 語意組態會決定哪些字段應該用於語意排名、標題、醒目提示和答案。
- 搜尋檔 （預覽） 中語意查詢所需的 semanticConfiguration 參數，。
- 自 2024 年 3 月 29 日生效：GET 回應不再傳回連接字串或密鑰。 如需詳細資訊，請參閱 讀取連線資訊 客戶端程式代碼的重大變更。
2020-06-30
此版本提供正式推出的功能，包括：
- 數據平面作業的 Azure 角色型訪問控制
- 相關性評分 （BM25）
- 知識存放區
- Azure Data Lake Storage 的索引器數據源 （ADLS） Gen2
- 自定義實體查閱技能
- 透過 Microsoft Entra 識別碼，在系統或使用者受控識別下執行的索引器
- 自 2024 年 3 月 29 日生效：GET 回應不再傳回連接字串或密鑰。 如需詳細資訊，請參閱 讀取連線資訊 客戶端程式代碼的重大變更。
2020-06-30-preview
此預覽版本包含 2019-05-06-Preview 中引進的所有功能，以及下列新增功能：
- 語意搜尋，這是在標準層服務上執行的進階功能，其會叫用語意排名。
- Power Query 連接器的索引器數據源
- MySQL 的索引器數據源
- Cosmos DB Gremlin API 的索引器數據源
- SharePoint Online 的索引器數據源
- 文字正規化的 Normalizer 屬性、不區分大小寫的篩選、Facet 和排序
- 重設索引器索引編製的檔，以依標識元特別重新整理特定檔
- 實體連結認知技能 （v3）
- 實體辨識認知技能 （v3）
- 情感分析認知技能 （v3）
- 自 2024 年 3 月 29 日生效：GET 回應不再傳回連接字串或密鑰。 如需詳細資訊，請參閱 讀取連線資訊 客戶端程式代碼的重大變更。
2019-05-06-preview
- Cosmos DB MongoDB API 的索引器數據源支援
- Blob 記憶體中虛刪除的索引器數據源
- featuresMode 參數，會傳回相關性分數的詳細資訊
- Azure Machine Learning （AML） 認知技能
- 個人識別偵測認知技能
- 快取擴充檔以保留及重複使用影像處理（以及其他 AI 擴充）
- 自 2024 年 3 月 29 日生效：GET 回應不再傳回連接字串或密鑰。 如需詳細資訊，請參閱 讀取連線資訊 客戶端程式代碼的重大變更。