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

發行項
05/03/2024

使用本文將數據平面呼叫遷移至較新版本的搜尋 REST API。

2023-11-01 是最新的穩定版本。這個版本已正式推出索引和查詢向量的語意排名和支援。
2023-10-01-preview 是最新的預覽版本。預覽功能包括內建查詢向量化、內建數據區塊化和編製索引期間向量化（使用文字分割技能與 Azure OpenAI 內嵌技能）。如需新功能的說明，請參閱程式碼範例和逐步解說。
2023-07-01-preview 是第一個用於向量支援的 REST API。現在已淘汰，您應該立即移轉至 2023-11-01 或 2023-10-01-preview 。

注意

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

升級的時機

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

您的程式代碼會參考已淘汰或已淘汰的 API 版本，並受限於一或多個重大變更。屬於此類別的 API 版本包括向量 2023-07-10-preview 和 2019-05-06。
在 API 回應中傳回無法辨識的屬性時，您的程式代碼會失敗。最佳做法是，您的應用程式應該忽略它不瞭解的屬性。
您的程式代碼會保存 API 要求，並嘗試將它們重新傳送至新的 API 版本。例如，如果您的應用程式保存從搜尋 API 傳回的接續令牌，就會發生這種情況（如需詳細資訊，請在搜尋 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-10-01-preview

此版本與 2023-11-01 相同，但在公開預覽中具有額外的功能：內建查詢向量化程式和向量預先篩選模式。如果您想要使用這些功能，您應該升級至最新的預覽版本。

搜尋索引內的向量搜尋演算法組態與 2023-11-01 相同。若要修正 2023-07-01-preview 的重大變更，請遵循下一節中的指示。

升級至 2023-11-01

此版本對於語意排名和向量搜尋支援具有重大變更和行為差異。

語意排名已正式推出，且不再使用 queryLanguage 屬性。它也需要 semanticConfiguration 定義。

若要從 2020-06-30-preview 升級，請建立 semanticConfiguration 以取代 searchFields。如需步驟，請參閱從預覽版本移轉。
在建立或更新索引中引進向量搜尋支援（2023-07-01-preview）。

若要從 2023-07-01-preview 升級，請重新命名及重新建構索引中的向量組態，並使用本節中的指示重寫向量查詢語法。

若要從 2023-10-01-preview 升級，沒有任何重大變更，但有一種行為差異：vectorFilterMode預設已從後篩選變更為篩選表達式的預篩選。如果您的 2023-10-01-preview 程式代碼未明確設定 vectorFilterMode ，請確定您瞭解新的行為，或將模式設定為後置篩選，以保留舊的行為。

提示

Azure 入口網站支援 2023-07-01-preview 索引的單鍵升級路徑。入口網站會偵測 2023-07-01-preview 索引，並提供 [移轉] 按鈕。選取 [ 移轉] 之前，請先選取 [編輯 JSON ] 以檢閱更新的架構。您應該會找到符合本節所述變更的架構。入口網站移轉只會處理具有一個向量搜尋演算法組態的索引，並建立對應至演算法的預設配置檔。具有多個設定的索引需要手動移轉。

以下是從 2023-07-01-preview 移轉的步驟：

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

修改向量搜尋組態。此 API 引進了向量配置檔的概念 ，這些配置檔 會將向量相關組態組合在一個名稱之下。它也會重新命名 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": {
    "profiles": [
      {
        "name": "myHnswProfile",
        "algorithm": "myHnswConfig"
      }
    ],
    "algorithms": [
      {
        "name": "myHnswConfig",
        "kind": "hnsw",
        "hnswParameters": {
          "m": 4,
          "efConstruction": 400,
          "efSearch": 500,
          "metric": "cosine"
        }
      }
    ]
  }

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

之前（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 版本的移轉。

升級至 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 值的排序方式，請注意這項變更。

升級至 2019-05-06

此 API 版本正式推出的功能包括：

自動完成是一種類型功能，可完成部分指定的字詞輸入。
複雜類型提供搜尋索引中結構化對象數據的原生支援。
JsonLines 剖析模式是 Azure Blob 索引編製的一部分，會為每個 JSON 實體建立一份搜尋檔，並以換行符分隔。
AI 擴充提供使用 Azure AI 服務 AI 擴充引擎的索引。

重大變更

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

Azure Cosmos DB 的 Type 屬性。針對以適用於 NoSQL API 資料來源的 Azure Cosmos DB 為目標的索引器，請將變更"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 版本建立超過這些限制的索引，任何使用 API 2019-05-06 版更新或重新建立索引都會失敗。如果您發現自己在這種情況下，您需要重新設計架構以符合新的限制，然後重建您的索引。
從 api-version 2019-05-06 開始，每個文件的複雜集合元素數目會有新的限制。如果您使用預覽 API 版本建立超過這些限制的檔索引，則任何使用 api-version 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 將其更新為新的格式，才能使用 API 版本 2019-05-06 來管理這些索引。

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

執行 GET 要求以擷取您的索引。如果它已經是新的格式，您就會完成。
將索引從「flat」格式轉譯為新的格式。您必須為此工作撰寫程式代碼，因為本文撰寫時沒有可用的範例程序代碼。
執行 PUT 要求，將索引更新為新的格式。請避免變更索引的任何其他詳細數據，例如欄位的可搜尋性/篩選性，因為更新索引 API 不允許影響現有索引之實體表達式的變更。

注意

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

下一步

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

搜尋服務 REST API 參考

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

升級的時機

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

升級至 2023-10-01-preview

升級至 2023-11-01

升級至 2020-06-30

重大變更

行為變更

升級至 2019-05-06

重大變更

升級複雜類型

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

下一步

其他資源