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

發行項
05/21/2024

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

2023-11-01 是最新的穩定版本。此版本中正式推出向量索引編製和查詢的語意排名和支援。

如果您是從 2023-10-10-01-preview 升級至 2023-11-01，則沒有任何重大變更，但有一項行為差異：vectorFilterMode 預設已針對篩選運算式從後置篩選變更為預先篩選。如果您的 2023-10-01-preview 程式碼未明確設定 vectorFilterMode，請確定您了解新的預設行為，或將 vectorFilterMode 明確設定為後置篩選以保留舊行為。
2024-05-01-preview 是最新的預覽 API 版本。它新增用於向量欄位的二進位資料類型、可獲得更佳搜尋結果的相關性屬性、OneLake 檔案索引子、更多向量化工具，以及更多內嵌技能。 AzureOpenAIEmbedding 技能已更新為包含 dimensions 和 modelName 屬性。此預覽與前兩個預覽之間的唯一回溯相容性問題為，modelName 現在是必要的。
2024-03-01-preview 新增用於壓縮的新資料類型和屬性，但與其他 2023-10-01-preview 完全相容。沒有使用此預覽版的升級指示。
2023-10-01-preview 是新增內建查詢向量化、編製索引期間的內建資料區塊化和向量化的第一個預覽版本 (使用文字分割技能和 Azure OpenAI 內嵌技能)。它在索引和向量查詢中引進向量設定的重大變更。
2023-07-01-preview 是用於向量支援的第一個 REST API。現在已取代，而您應該立即移轉至 2023-11-01 或任何較新的預覽版 REST API。

注意

REST API 參考文件現在已建立版本。若要取得正確的內容，請開啟參考頁面，然後依版本進行篩選，使用位於目錄上方的選取器。

升級時機

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

您的程式碼會參考已淘汰或已取代的 API 版本，並受限於一或多個重大變更。屬於此類別的 API 版本包括針對向量的 2023-07-10-preview，以及針對淘汰技能和因應措施的 2019-05-06。
您的程式碼在 API 回應中傳回無法辨認的屬性時失敗。根據最佳做法，您的應用程式應該會略過不了解的屬性。
您的程式碼仍然存在 API 要求，並嘗試將它們重新傳送給新的 API 版本。例如，發生原因可能是您的應用程式持續保存搜尋服務 API 所傳回的接續 Token (如需詳細資訊，請在搜尋服務 API 參考) 中查找 @search.nextPageParameters。

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

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

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

語意排名的重大變更

語意排名於 2023-11-01 中正式推出。相較於先前的 REST API 版本，它不再使用 queryLanguage 屬性。它也需要 semanticConfiguration 定義，以取代舊版中的 searchFields。請參閱從預覽版本移轉，以將程式碼轉換為正式推出版本或至較新的預覽版本。

從 2023-07-01-preview 升級

本節說明從 2023-07-01-preview 到任何較新 API 版本的移轉路徑。從 2023-07-01-preview 到任何較新版本有數個重大變更，但後續較新的 API 版本之間只有次要相容性問題。

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

向量索引的入口網站升級

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

移轉路徑是從 2023-07-01-preview 到 2023-10-01-preview。
更新僅限於向量欄位定義和向量搜尋演算法設定。
更新是單向。您無法反轉升級。升級索引之後，您必須使用 2023-10-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 後所建立之索引的預先篩選器。不論您如何設定篩選模式，在該日期前建立的索引都僅支援後置篩選。

之前 (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 參考

Share via

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

升級時機

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

語意排名的重大變更

從 2023-07-01-preview 升級

向量索引的入口網站升級

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

升級至 2020-06-30

重大變更

行為變更

升級至 2019-05-06

重大變更

升級複雜類型

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

下一步

其他資源