在 Azure AI 搜尋服務中升級至最新的 REST API

發行項
11/19/2024

使用本文將資料平面呼叫移轉至較新版本的搜尋 REST API。

2024-07-01 是最新的穩定版本。
2024-11-01-preview 是最新的預覽 API 版本。

升級指示著重於程式碼變更，讓您完成舊版的重大變更，使得現有的程式碼可如同之前般執行，但在較新的 API 版本上執行。一旦程式碼正常運作，您就可以決定是否採用較新的功能。若要深入了解新功能，請參閱向量程式碼範例和新功能。

建議您連續升級 API 版本，逐步升級每個版本，直到升級到最新的版本為止。

2023-07-01-preview 是用於向量支援的第一個 REST API。 請勿使用此 API 版本。它現在已被取代，而您應該立即移轉至穩定或較新的預覽版 REST API。

注意

REST API 參考文件現在已建立版本。對於特定版本的內容，請開啟參考頁面，然後使用位於目錄上方右側的選取器來挑選您的版本。

升級時機

Azure AI 搜尋服務會中斷回溯相容性作為最後手段。升級為必要的時機：

您的程式碼參考了一個已淘汰或不支援的 API 版本，且可能會受到一或多項重大變更的影響。如果您的程式碼是針對以下版本進行開發：2023-07-10-preview 用於向量、2020-06-01-preview 用於語意排名工具，以及 2019-05-06 用於過時的技能和因應措施，則必須解決重大變更的問題。
您的程式碼在 API 回應中傳回無法辨認的屬性時失敗。根據最佳做法，您的應用程式應該會略過不了解的屬性。
您的程式碼仍然存在 API 要求，並嘗試將它們重新傳送給新的 API 版本。例如，發生原因可能是您的應用程式持續保存搜尋服務 API 所傳回的接續 Token (如需詳細資訊，請在搜尋服務 API 參考) 中查找 @search.nextPageParameters。

如何升級

檢閱每個 API 版本的發行備註。
將要求標頭中指定的 api-version 參數更新為較新版本。

在直接呼叫 REST API 的應用程式程式碼中，搜尋現有版本的所有執行個體，然後將其取代為新版本。如需建構 REST 呼叫的詳細資訊，請參閱快速入門：使用 REST。

如果您使用的是 Azure SDK，這些套件會以 REST API 的特定版本為目標。套件更新可能會與 REST API 更新同時發生，但每個 SDK 都有自己的發行時間表，與 Azure AI 搜尋 REST API 版本無關。檢查 SDK 套件的變更記錄檔，以判斷套件版本是否以最新的 REST API 版本為目標。
檢閱本文所述的重大變更並實作因應措施。從您的程式碼所用的版本開始，解決每個較新 API 版本的任何重大變更，直到您到達最新的穩定或預覽版本為止。

讀取連線資訊的用戶端程式碼重大變更

自 2024 年 3 月 29 日起生效並適用於所有支援的 REST API：

GET Skillset、GET Index 和 GET Indexer 不再會於回應中傳回索引鍵或連接屬性。如果您有會從 GET 回應讀取金鑰或連線 (敏感性資料) 的下游程式碼，這是一項重大變更。
如果您需要擷取搜尋服務的管理員或查詢 API 金鑰，請使用管理 REST API。
如果您需要擷取另一個 Azure 資源 (例如 Azure 儲存體或 Azure Cosmos DB) 的連接字串，請使用該資源的 API 和已發佈的指導來取得資訊。

語意排名工具的中斷性變更

語意排名工具於 2023-11-01 正式推出。以下是舊版語意排名工具的中斷性變更：

在 2020-06-01-preview 之後的所有版本中：semanticConfiguration 取代了 searchFields 作為指定用於 L2 排名的欄位的機制。
對於所有 API 版本，2023 年 7 月 14 日對 Microsoft 裝載的語意模型的更新使語意排名工具與語言無關，有效地停用了 queryLanguage 屬性。程式碼中沒有「重大變更」，但該屬性被忽略。

請參閱從預覽版本移轉以將您的程式碼轉換為使用 semanticConfiguration。

升級至 2024-11-01-preview

2024-11-01-preview 查詢重寫、檔版面配置技能、技能處理的無索引計費、Markdown 剖析模式，以及壓縮向量的重新記錄選項。

如果您要從 2024-09-01-preview升級，您可以使用新的預覽 API，而不需要變更現有的程式代碼。

不過，新版本引進的語法變更為 vectorSearch.compressions：

rerankWithOriginalVectors以取代enableRescoring
移至 defaultOversampling 新的 rescoringOptions 屬性物件

回溯相容性會因為內部 API 對應而保留，但如果您採用新的預覽版本，建議您變更語法。如需語法的比較，請參閱使用純量或二進位量化壓縮向量。

升級至 2024-09-01-preview

2024-09-01-preview新增適用於文字內嵌-3 模型的 Matryoshka 表示法學習（MRL）壓縮、混合式查詢的目標向量篩選、用於偵錯的向量子核心詳細數據，以及文字分割技能的令牌區塊化。

如果您要從 2024-05-01-preview升級，您可以使用新的預覽 API，而不需要變更現有的程式代碼。

升級至 2024-07-01

2024-07-01 是一般版本。先前的預覽功能現已正式推出：整合式區塊化和向量化 (文字分割技能、AzureOpenAIEmbedding 技能)、根據 AzureOpenAIEmbedding、向量壓縮 (純量量化、二進位量化、預存屬性、窄資料類型) 查詢向量化工具。

如果您從 2024-05-01-preview 升級為穩定，則不會有任何重大變更。若要使用新的穩定版本，請變更 API 版本並測試您的程式碼。

如果您直接從 2023-11-01 升級，就會出現重大變更。遵循每個較新預覽版所述的步驟，從 2023-11-01 移轉至 2024-07-01。

升級至 2024-05-01-preview

2024-05-01-preview 新增了 OneLake 索引、對二進位向量的支援，以及對更多內嵌模型的支援。

如果您從 2024-03-01-preview 升級，AzureOpenAIEmbedding 技能現在需要模型名稱和維度屬性。

在您的程式碼基底中搜尋 AzureOpenAIEmbedding 參考。
將 modelName 設為 "text-embedding-ada-002" 並將 dimensions 設為 "1536"。

升級至 2024-03-01-preview

2024-03-01-preview 新增了窄資料類型、純量量化和向量儲存選項。

如果您從 2023-10-01-preview 升級，則不會有任何重大變更。不過，有一個行為差異：對於 2023-11-01 及更新的預覽版，filter 運算式中的 vectorFilterMode 預設值已從 postfilter 變更為 prefilter。

在您的程式碼基底中搜尋 vectorFilterMode 參考。
如果明確設定該屬性，則無需執行任何動作。如果您使用預設值，請注意新的預設行為是在查詢執行之前進行篩選。如果您想要進行後查詢篩選，請明確將 vectorFilterMode 設為 postfilter 以保留舊的行為。

升級至 2023-11-01

2023-11-01 是一般版本。先前的預覽功能現已正式推出：語意排名工具、向量索引和查詢支援。

2023-10-01-preview 沒有任何重大變更，但是從 2023-07-01-preview 到 2023-11-01 有多項重大變更。如需詳細資訊，請參閱從 2023-07-01-preview 升級。

若要使用新的穩定版本，請變更 API 版本並測試您的程式碼。

升級至 2023-10-01-preview

2023-10-01-preview 是第一個新增「索引編製期間的內建資料區塊化和向量化」和「內建查詢向量化」的預覽版本。它也支援先前版本的向量索引編製和查詢。

如果您從先前的版本升級，下一節會提供相關的步驟。

從 2023-07-01-preview 升級

請勿使用此 API 版本。它實作了與任何較新的 API 版本都不相容的向量查詢語法。

2023-07-01-preview 現在已被取代，因此您不應在此版本上建立新程式碼，在任何情況下也不應升級到此版本。本節說明從 2023-07-01-preview 到任何較新 API 版本的移轉路徑。

向量索引的入口網站升級

Azure 入口網站支援 2023-07-01-preview 索引的一鍵升級路徑。它會偵測向量欄位並提供一個 [移轉] 按鈕。

移轉路徑是從 2023-07-01-preview 到 2024-05-01-preview。
更新僅限於向量欄位定義和向量搜尋演算法設定。
更新是單向。您無法反轉升級。升級索引之後，您必須使用 2024-05-01-preview 或更新版本來查詢索引。

沒有用於升級向量查詢語法的入口網站移轉。請參閱程式碼升級以取得查詢語法變更。

選取 [移轉] 之前，請先選取 [編輯 JSON] 以檢閱更新的架構。您應該會找到符合程式碼升級一節所述變更的結構描述。入口網站移轉只會使用一個向量搜尋演算法設定來處理索引。它會建立對應至 2023-07-01-preview 向量搜尋演算法的預設設定檔。具有多個向量搜尋設定的索引需要手動移轉。

向量索引和查詢的程式碼升級

在建立或更新索引 (2023-07-01-preview) 中引進向量搜尋支援。

從 2023-07-01-preview 升級至任何較新的穩定或預覽版本需要：

重新命名和重建索引中的向量設定
重寫向量查詢

使用本節中的指示，從 2023-07-01-preview 移轉向量欄位、設定和查詢。

呼叫 Get Index 以擷取現有的定義。

修改向量搜尋組態。 2023-11-01 和更新版本引進了將向量相關設定組合在一個名稱下的向量設定檔概念。較新版本也會將 algorithmConfigurations 重新命名為 algorithms。

將 algorithmConfigurations 重新命名為 algorithms。這只是陣列的重新命名。內容回溯相容性。這表示您可以使用現有的 HNSW 組態參數。
新增 profiles，並為每個項目提供一個名稱與演算法組態。

移轉前 (2023-07-01-preview)：

  "vectorSearch": {
    "algorithmConfigurations": [
        {
            "name": "myHnswConfig",
            "kind": "hnsw",
            "hnswParameters": {
                "m": 4,
                "efConstruction": 400,
                "efSearch": 500,
                "metric": "cosine"
            }
        }
    ]}

移轉之後 (2023-11-01)：

  "vectorSearch": {
    "algorithms": [
      {
        "name": "myHnswConfig",
        "kind": "hnsw",
        "hnswParameters": {
          "m": 4,
          "efConstruction": 400,
          "efSearch": 500,
          "metric": "cosine"
        }
      }
    ],
    "profiles": [
      {
        "name": "myHnswProfile",
        "algorithm": "myHnswConfig"
      }
    ]
  }

變更向量欄位定義，以 vectorSearchProfile 取代 vectorSearchConfiguration。請確定設定檔名稱解析為新的向量設定檔定義，而不是演算法組態名稱。其他向量欄位屬性保持不變。例如，它們無法篩選、排序或多面向化，也無法使用分析器或正規化程式或同義字對應。

之前 (2023-07-01-preview)：

  {
      "name": "contentVector",
      "type": "Collection(Edm.Single)",
      "key": false,
      "searchable": true,
      "retrievable": true,
      "filterable": false,  
      "sortable": false,  
      "facetable": false,
      "analyzer": "",
      "searchAnalyzer": "",
      "indexAnalyzer": "",
      "normalizer": "",
      "synonymMaps": "", 
      "dimensions": 1536,
      "vectorSearchConfiguration": "myHnswConfig"
  }

之後 (2023-11-01)：

  {
    "name": "contentVector",
    "type": "Collection(Edm.Single)",
    "searchable": true,
    "retrievable": true,
    "filterable": false,  
    "sortable": false,  
    "facetable": false,
    "analyzer": "",
    "searchAnalyzer": "",
    "indexAnalyzer": "",
    "normalizer": "",
    "synonymMaps": "", 
    "dimensions": 1536,
    "vectorSearchProfile": "myHnswProfile"
  }

呼叫建立或更新索引來張貼變更。

修改搜尋 POST 以變更查詢語法。此 API 變更可支援多型向量查詢類型。

將 vectors 重新命名為 vectorQueries。
針對每個向量查詢，新增 kind，並將其設定為 vector。
針對每個向量查詢，請重新命名 value 為 vector。
或者，如果您使用篩選表示式，請新增 vectorFilterMode。預設值是 2023-10-01 之後所建立之索引的預先篩選器 (prefilter)。不論您如何設定篩選模式，在該日期前建立的索引都僅支援後置篩選。

之前 (2023-07-01-preview)：

{
    "search": (this parameter is ignored in vector search),
    "vectors": [
      {
        "value": [
            0.103,
            0.0712,
            0.0852,
            0.1547,
            0.1183
        ],
        "fields": "contentVector",
        "k": 5
      }
    ],
    "select": "title, content, category"
}

之後 (2023-11-01)：

{
  "search": "(this parameter is ignored in vector search)",
  "vectorQueries": [
    {
      "kind": "vector",
      "vector": [
        0.103,
        0.0712,
        0.0852,
        0.1547,
        0.1183
      ],
      "fields": "contentVector",
      "k": 5
    }
  ],
  "vectorFilterMode": "preFilter",
  "select": "title, content, category"
}

這些步驟會完成移轉至 2023-11-01 穩定 API 版本或較新的預覽 API 版本。

升級至 2020-06-30

在此版本中，有一項重大變更和數種行為差異。正式推出的功能包括：

知識存放區、透過技能集建立的擴充內容持續性儲存區、為下游分析所建立和透過其他應用程式進行處理。知識存放區是透過 Azure AI 搜尋服務 REST API 建立，但位於 Azure 儲存體中。

重大變更

針對舊版 API 版本撰寫的程式碼若包含下列功能，則會在 2020-06-30 和更新版本上中斷：

篩選運算式中的任何 Edm.Date 常值 (由年月日期組成的日期，例如 2020-12-12)，都必須遵循 Edm.DateTimeOffset 格式：2020-12-12T00:00:00Z。這是必要變更，以處理因時區差異而造成的錯誤或非預期的查詢結果。

行為變更

BM25 排名演算法會以較新的技術取代先前的排名演算法。 2019 年之後建立的服務會自動使用此演算法。針對較舊的服務，您必須設定參數以使用新的演算法。
此版本中已變更 Null 值的已排序結果，如果排序為 asc，則會先顯示 Null 值，如果排序為 desc ，則會最後顯示 Null 值。如果您編寫程式碼來處理 Null 值的排序方式，請注意這項變更。

升級至 2019-05-06

此 API 版本已正式推出許多功能，包括：

自動完成是一種自動提示功能，可完成部分指定字詞輸入。
複雜類型可提供搜尋索引中結構化物件資料的原生支援。
JsonLines 剖析模式是 Azure Blob 索引的一部分，會為每個 JSON 實體建立一個搜尋文件，並以新行字元分隔。
AI 擴充提供使用 Azure AI 服務 AI 擴充引擎的索引。

重大變更

針對舊版 API 版本撰寫的程式碼若包含下列功能，則會在 2019-05-06 和更新版本上中斷：

Azure Cosmos DB 的 Type 屬性。針對以 Azure Cosmos DB for NoSQL API 資料來源為目標的索引子，請將 "type": "documentdb" 變更為 "type": "cosmosdb"。
如果您的索引子錯誤處理包含 status 屬性的參考，您應該將其移除。我們已從錯誤回應中移除狀態，因為它未提供實用的資訊。
回應中不再會傳回資料來源連接字串。自 API 版本 2019-05-06 和 2019-05-06-Preview 起，資料來源 API 已不再於任何 REST 作業的回應中傳回連接字串。在舊版 API 中，針對使用 POST 建立的資料來源，Azure AI 搜尋服務會傳回 201，後面接著包含純文字連接字串的 OData 回應。
具名實體辨識認知技能已淘汰。如果您在程式碼中呼叫具名實體辨識技能，呼叫會失敗。取代功能是實體辨識技能 (V3)。請遵循淘汰的技能中之建議，以移轉至支援的技能。

升級複雜類型

API 版本 2019-05-06 已針對複雜類型新增正式支援。如果您的程式碼在 2017-11-11-Preview 或 2016-09-01-Preview 中實作的是複雜類型對應的先前建議，則從 2019-05-06 版本開始將有一些新的和變更的限制需要注意：

子欄位深度和每個索引的複雜集合數目限制已降低。如果您使用預覽 api-version 建立的索引超過這些限制數目，則任何使用 API 2019-05-06 版本更新或重新建立的索引都會失敗。如果您發現這種情況，您必須重新設計結構描述，以符合新的限制，然後再重建您的索引。
從 api-version 2019-05-06 開始，每個文件的複雜集合元素數目將有新的限制。如果您使用預覽 api-version 建立的文件索引超出了這些限制，則任何使用 api 版本 2019-05-06 對該資料重新編製索引的嘗試都會失敗。如果您發現這種情況，則必須在重新編製資料索引之前，減少每個文件的複雜集合元素數目。

如需詳細資訊，請參閱 Azure AI 搜尋服務的服務限制。

如何升級舊的複雜類型結構

如果您的程式碼使用複雜類型搭配其中一個較舊的預覽 API 版本，您可以使用如下所示的索引定義格式：

{
  "name": "hotels",  
  "fields": [
    { "name": "HotelId", "type": "Edm.String", "key": true, "filterable": true },
    { "name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false },
    { "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
    { "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
    { "name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true, "analyzer": "tagsAnalyzer" },
    { "name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true },
    { "name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true },
    { "name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address", "type": "Edm.ComplexType" },
    { "name": "Address/StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true },
    { "name": "Address/City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/Country", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Location", "type": "Edm.GeographyPoint", "filterable": true, "sortable": true },
    { "name": "Rooms", "type": "Collection(Edm.ComplexType)" }, 
    { "name": "Rooms/Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene" },
    { "name": "Rooms/Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.lucene" },
    { "name": "Rooms/Type", "type": "Edm.String", "searchable": true },
    { "name": "Rooms/BaseRate", "type": "Edm.Double", "filterable": true, "facetable": true },
    { "name": "Rooms/BedOptions", "type": "Edm.String", "searchable": true },
    { "name": "Rooms/SleepsCount", "type": "Edm.Int32", "filterable": true, "facetable": true },
    { "name": "Rooms/SmokingAllowed", "type": "Edm.Boolean", "filterable": true, "facetable": true },
    { "name": "Rooms/Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "facetable": true, "analyzer": "tagsAnalyzer" }
  ]
}

API 版本 2017-11-11-Preview 中引進了定義索引欄位的較新樹狀結構格式。在新的格式中，每個複雜欄位都有一個欄位集合，其中會定義其子欄位。在 API 版本 2019-05-06 中，此新格式是採用獨佔方式使用，而且若嘗試使用舊格式建立或更新索引將會失敗。如果您有使用舊格式建立的索引，您必須使用 API 版本 2017-11-11-Preview 將其更新為新的格式，才能使用 2019-05-06 API 版本進行管理。

您可以使用 API 版本 2017-11-11-Preview，將一般索引更新為新的格式：

執行 GET 要求以擷取您的索引。如果已是新的格式，則代表擷取已完成。
將索引從一般格式轉譯為新的格式。您必須為此工作撰寫程式碼，因為在撰寫時沒有可用的範例程式碼。
執行 PUT 要求，將索引更新為新的格式。避免變更索引的任何其他詳細資料，例如欄位的可搜尋性/可篩選性，因為更新索引 API 不允許進行會影響現有索引實體運算式的變更。

注意

您無法從 Azure 入口網站管理使用舊版「一般」格式建立的索引。請稍早將索引從「一般」標記法升級為「樹狀結構」表示法。

下一步

檢閱搜尋 REST API 參考文件。如果您遇到問題，請在 Stack Overflow 上尋求協助，或連絡支援人員。

搜尋服務 REST API 參考

共用方式為

在 Azure AI 搜尋服務中升級至最新的 REST API

升級時機

如何升級

讀取連線資訊的用戶端程式碼重大變更

語意排名工具的中斷性變更

升級至 2024-11-01-preview

升級至 2024-09-01-preview

升級至 2024-07-01

升級至 2024-05-01-preview

升級至 2024-03-01-preview

升級至 2023-11-01

升級至 2023-10-01-preview

從 2023-07-01-preview 升級

向量索引的入口網站升級

向量索引和查詢的程式碼升級

升級至 2020-06-30

重大變更

行為變更

升級至 2019-05-06

重大變更

升級複雜類型

如何升級舊的複雜類型結構

下一步

意見反應

其他資源