Azure AI Search で最新の REST API にアップグレードする

[アーティクル]
06/24/2024

データプレーン呼び出しを新しいバージョンの Search REST API に移行するには、この記事を参照してください。

2023-11-01 が最新の安定版です。
2024-05-01-preview が最新のプレビュー API バージョンです。

アップグレード手順では、以前のバージョンからの破壊的変更に対応するためのコードの変更に焦点を当てます。そうすると、既存のコードが以前と同じように、新しい API バージョンで実行されるようになります。コードが正常に動作したら、新しい機能を採用するかどうかを決定できます。プレビュー機能の詳細については、ベクターコードサンプルと新機能を参照してください。

API バージョンを連続してアップグレードし、最新のバージョンに到達するまで各バージョンを処理することをお勧めします。

2023-07-01-preview は、ベクトルサポート用の最初の REST API でした。この API バージョンは使用しないでください。現在は非推奨のため、安定した、または新しいプレビュー REST API のいずれかにすぐに移行してください。

Note

REST API リファレンスドキュメントがバージョン管理されるようになりました。バージョン固有のコンテンツについては、リファレンスページを開き、目次の上の右側にあるセレクターを使用して、バージョンを選択してください。

アップグレードするタイミング

Azure AI Search は、最後の手段として下位互換性を破ります。アップグレードは、次の場合に必要です。

コードは、廃止またはサポート対象外となった API バージョンを参照しており、1 つ以上の破壊的変更の影響を受けています。コードがベクトルに対して 2023-07-10-preview、セマンティックランク付けに対して 2020-06-01-preview、廃止されたスキルと回避策に対して 2019-05-06 を対象とする場合は、破壊的変更に対処する必要があります。
API 応答で認識できないプロパティが返されるとコードが失敗する。ベストプラクティスとして、アプリケーションは、認識できないプロパティを無視する必要があります。
コードが API 要求を保持し、新しい API バージョンへの再送信を試行する。たとえば、この状況は、アプリケーションが Search API から返される継続トークンを保持する場合に発生する可能性があります (詳細については、Search API リファレンスのページの @search.nextPageParameters を参照してください)。

接続情報を読み取るクライアントコードの破壊的変更

2024 年 3 月 29 日より、すべてのサポートされている REST API に適用されます。

GET Skillset、GET Index、GET Indexer からは、応答でキーも接続プロパティも返されなくなります。 GET 応答からキーや接続 (機密データ) を読み取るダウンストリームコードがある場合、これは破壊的変更となります。
検索サービスのために管理者を取得したり、API キーを問い合わせたりする必要がある場合、管理 REST API を使用します。
Azure Storage や Azure Cosmos DB など、別の Azure リソースの接続文字列を取得する必要がある場合、そのリソースの API と公開されているガイダンスを使用して情報を取得します。

セマンティックランク付けの破壊的変更

セマンティックランク付けは、2023-11-01 で一般提供になります。以前のリリースからのセマンティックランク付けの破壊的変更を次に示します。

2020-06-01-preview より後のすべてのバージョン: semanticConfiguration は L2 ランク付けに使用するフィールドを指定するためのメカニズムとして searchFields を置き換えます。
すべての API バージョンについて、Microsoft がホストするセマンティックモデルに対する 2023 年 7 月 14 日の更新により、セマンティックランク付け言語に依存しなくなり、queryLanguage プロパティが実質的に使用停止になりました。コードに "破壊的変更" はありませんが、プロパティは無視されます。

semanticConfiguration を使用するようにコードを移行するには、「プレビューバージョンからの移行」を参照してください。

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 からアップグレードする場合、破壊的変更はありません。ただし、次の 1 点だけ動作の違いがあります: 2023-11-01 およびそれより新しいプレビューの場合、vectorFilterMode の既定値がフィルター式の事後フィルターから事前フィルターに変更されました。

コードベースで vectorFilterMode 参照を検索します。
プロパティが明示的に設定されている場合、アクションは必要ありません。既定値を使用した場合、新しい既定の動作ではクエリの実行前にフィルター処理されます。クエリ後のフィルター処理を行う場合は、vectorFilterMode を明示的に postfilter に設定して、以前の動作を保持します。

2023-10-01-preview にアップグレードする

2023-10-01-preview は、インデックス作成時の組み込みのデータのチャンク化とベクトル化および組み込みのクエリのベクトル化を追加する最初のプレビューバージョンです。以前のバージョンのベクトルインデックス作成とクエリもサポートされています。

以前のバージョンからアップグレードする場合は、次のセクションに手順があります。

2023-07-01 プレビューからのアップグレード

この API バージョンは使用しないでください。これは、新しい API バージョンと互換性のないベクトルクエリ構文を実装しています。

2023-07-01-preview は現在非推奨になっているため、このバージョンに基づいて新しいコードを作成したり、いかなる状況でもこのバージョンにアップグレードしたりしないでください。このセクションでは、2023-07-01-preview から、それよりも新しい API バージョンへの移行パスについて説明します。

ベクトルインデックスに関するポータルのアップグレード

Azure portal は、2023-07-01-preview インデックスのワンクリックアップグレードパスをサポートします。ベクトルフィールドを検出して [移行] ボタンを表示します。

移行パスは 2023-07-01-preview から 2024-05-01-preview です。
更新は、ベクトルフィールドの定義とベクトル検索アルゴリズムの構成だけです。
更新は一方向です。アップグレードを元に戻すことはできません。インデックスをアップグレードしたら、2024-05-01-preview 以降を使ってインデックスのクエリを実行する必要があります。

ベクトルクエリ構文のアップグレードに関してポータルの移行はありません。クエリ構文の変更については、コードのアップグレードを参照してください。

[移行] を選択する前に [JSON の編集] を選択して、更新されたスキーマを確認してください。コードのアップグレードセクションには、説明する変更に準拠したスキーマがあります。ポータルの移行では、ベクトル検索アルゴリズムの構成が 1 つのインデックスのみが処理されます。 2023-07-01-preview ベクトル検索アルゴリズムにマップする既定のプロファイルが作成されます。複数のベクトル検索構成を持つインデックスは、手動で移行する必要があります。

ベクターインデックスとクエリのコードアップグレード

[インデックスを作成または更新] (2023-07-01-preview) で [ベクトル検索] サポートが導入されました。

2023-07-01-preview から新しい安定またはプレビューバージョンにアップグレードするには、次のものが必要です。

インデックス内のベクター構成の名前変更と再構築
ベクタークエリの書き換え

このセクションの手順を使って、2023-07-01-preview からベクトルフィールド、構成、クエリを移行してください。

[インデックスの取得] を呼び出し、既存の定義を取得します。
ベクトル検索構成を変更します。 2023-11-01 以降のバージョンでは、"ベクトルプロファイル" という概念を導入し、ベクトル関連の構成を 1 つの名前にまとめています。また、新しいバージョンでは、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"
      }
    ]
  }
```

ベクトルフィールドの定義を変更し、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 バージョン以降のプレビュー API バージョンへの移行が完了します。

2020-06-30 へのアップグレード

このバージョンでは、1 つの重大な変更と複数の動作の違いがあります。一般提供の機能には、次のようなものがあります。

ナレッジストアは、スキルセットを通して作成される充実したコンテンツから成る永続的ストレージで、ダウンストリーム分析や他のアプリケーションを通した処理のために作成されます。ナレッジストアは Azure AI Search REST API を使用して作成されますが、Azure Storage にあります。

互換性に影響する変更点

以前の API バージョンに対して記述されたコードは、コードに次の機能が含まれる場合、2020-06-30 以降では動作しません。

フィルター式のすべての Edm.Date リテラル (2020-12-12 のような年月日で構成される日付) は、Edm.DateTimeOffset 形式 2020-12-12T00:00:00Z に従う必要があります。タイムゾーンの違いによる間違ったクエリ結果や予期しないクエリ結果を処理するために、この変更が必要でした。

動作の変更

BM25 ランク付けアルゴリズムでは、前のランク付けアルゴリズムがより新しいテクノロジに置き換えられます。 2019 年以降に作成されたサービスは、このアルゴリズムを自動的に使用します。以前のサービスについては、新しいアルゴリズムを使用するようにパラメーターを設定する必要があります。
このバージョンでは、順序付けされた null 値の結果が変更されていて、null 値は、並べ替えが asc の場合は最初に、並べ替えが desc の場合は最後に表示されます。 null 値を並べ替える方法を扱うコードを記述した場合は、この変更に注意してください。

2019-05-06 へのアップグレード

この API バージョンで一般公開された機能には、以下が含まれます。

オートコンプリート。用語の一部を入力するだけでその用語全体が表示される先行入力機能です。
複合型。検索インデックス内で構造化オブジェクトデータがネイティブでサポートされます。
JsonLines 解析モード。Azure BLOB インデックスの一部で、JSON エンティティごとに 1 つの検索ドキュメントが新規行として作成されます。
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 Search で 201 と、プレーンテキストの接続文字列を含む OData 応答が返されました。
固有表現認識コグニティブスキルは廃止されました。コード内で名前付きエンティティの認識スキルを呼び出した場合、その呼び出しは失敗します。これに代わる機能は、エンティティ認識スキル (V3) です。「非推奨のスキル」に記載されている推奨事項に従い、サポートされているスキルに移行してください。

複合型のアップグレード

API バージョン 2019-05-06 では、複合型の正式なサポートが追加されました。 2017-11-11-Preview または 2016-09-01-Preview での複合型の等価性に関する以前の推奨事項をコードで実装した場合、バージョン 2019-05-06 以降では新しい制限と変更された制限がいくつかあり、注意する必要があります。

サブフィールドの深さとインデックスあたりの複合コレクションの数に関する制限が低くなりました。プレビュー API バージョンを使ってこれらの制限を超えるインデックスを作成した場合、API バージョン 2019-05-06 を使ってそれらを更新または再作成しようとすると失敗します。この状況に当てはまる場合は、新しい制限内に収まるようにスキーマを再設計してから、インデックスをリビルドする必要があります。
API バージョン 2019-05-06 以降では、ドキュメントあたりの複合コレクションの要素数について、新しい制限があります。プレビュー API バージョンを使って、これらの制限を超えるインデックスをドキュメントで作成した場合、API バージョン 2019-05-06 を使ってそのデータのインデックスを再作成しようとすると失敗します。この状況に当てはまる場合は、データのインデックスを再作成する前に、ドキュメントあたりの複合コレクション要素の数を減らす必要があります。

詳細については、「Service limits for Azure AI Search (Azure Search サービスの制限)」を参照してください。

以前の複合型の構造をアップグレードする方法

以前のいずれかのプレビュー版の 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 要求を実行してインデックスを取得します。既に新しい形式になっている場合は、作業完了です。
インデックスをフラット形式から新しい形式に変換します。この記事の執筆時点では、サンプルコードが用意されていないため、このタスクのコードは自分で作成する必要があります。
PUT 要求を実行し、インデックスを新しい形式に更新します。インデックスの更新 API では既存のインデックスの物理的な式に影響する変更は許可されないため、インデックスのその他の詳細 (フィールドの検索可能性やフィルター処理など) は変更しないでください。

Note

古い "フラット" 形式で作成されたインデックスを Azure portal から管理することはできません。なるべく早く、インデックスを "フラット" 表現から "ツリー" 表現にアップグレードしてください。

次のステップ

Search REST API リファレンスドキュメントを確認します。問題が発生する場合は、Stack Overflow で助けを求めるか、サポートに問い合わせてください。

Search Service REST API リファレンス

次の方法で共有

Azure AI Search で最新の REST API にアップグレードする

アップグレードするタイミング

接続情報を読み取るクライアントコードの破壊的変更

セマンティックランク付けの破壊的変更

2024-05-01-preview にアップグレードする

2024-03-01-preview にアップグレードする

2023-10-01-preview にアップグレードする

2023-07-01 プレビューからのアップグレード

ベクトルインデックスに関するポータルのアップグレード

ベクターインデックスとクエリのコードアップグレード

2020-06-30 へのアップグレード

互換性に影響する変更点

動作の変更

2019-05-06 へのアップグレード

重大な変更

複合型のアップグレード

以前の複合型の構造をアップグレードする方法

次のステップ

フィードバック

フィードバック

その他のリソース

次の方法で共有

Azure AI Search で最新の REST API にアップグレードする

アップグレードするタイミング

接続情報を読み取るクライアント コードの破壊的変更

セマンティック ランク付けの破壊的変更

2024-05-01-preview にアップグレードする

2024-03-01-preview にアップグレードする

2023-10-01-preview にアップグレードする

2023-07-01 プレビューからのアップグレード

ベクトル インデックスに関するポータルのアップグレード

ベクター インデックスとクエリのコード アップグレード

2020-06-30 へのアップグレード

互換性に影響する変更点

動作の変更

2019-05-06 へのアップグレード

重大な変更

複合型のアップグレード

以前の複合型の構造をアップグレードする方法

次のステップ

フィードバック

フィードバック

その他のリソース

接続情報を読み取るクライアントコードの破壊的変更

セマンティックランク付けの破壊的変更

ベクトルインデックスに関するポータルのアップグレード

ベクターインデックスとクエリのコードアップグレード