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

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

• 2023-11-01 が最新の安定版です。 このバージョンでは、セマンティックの順位付けと、インデックス作成ベクトルとクエリ実行ベクトルのサポートが一般提供されています。

• 2023-10-01-preview が最新のプレビュー バージョンです。 プレビュー機能には、組み込みのクエリ ベクトル化、インデックス作成時の組み込みのデータ チャンキングとベクトル化 (テキスト分割スキルと Azure OpenAI 埋め込みスキルを使用) が含まれます。 新機能のヘルプについては、コード サンプルとチュートリアル ページを参照してください。

• 2023-07-01-preview は、ベクトル サポート用の最初の REST API でした。 現在は非推奨となったため、2023-11-01 または 2023-10-01-preview にすぐに移行する必要があります。

Note

API リファレンス ドキュメントがバージョン管理されるようになりました。 適切なコンテンツを入手するには、リファレンス ページを開き、目次の上にあるセレクターを使用して、バージョンでフィルターしてください。

アップグレードする方法

Azure AI Search は、最後の手段として下位互換性を破ります。 このセクションでは、新しいバージョンでは実行されない既存のコードを変更する手順について説明します。 アップグレードは、次の場合に必要です。

• 廃止または非推奨になった API バージョンをコードで参照していて、1 つ以上の破壊的変更の対象となっている。 このカテゴリに分類される API バージョンには、ベクトル用の 2023-07-10-preview と、2019-05-06 があります。

• API 応答で認識できないプロパティが返されるとコードが失敗する。 ベスト プラクティスとして、アプリケーションは、認識できないプロパティを無視する必要があります。

• コードが API 要求を保持し、新しい API バージョンへの再送信を試行する。 たとえば、この状況は、アプリケーションが Search API から返される継続トークンを保持する場合に発生する可能性があります (詳細については、Search API リファレンスのページの @search.nextPageParameters を参照してください)。

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

このバージョンは 2023-11-01 と同じですが、パブリック プレビュー段階の追加機能があります: 組み込みのクエリ ベクトル化とベクトル事前フィルター モード。 これらの機能を使用するには、最新のプレビュー バージョンにアップグレードする必要があります。

検索インデックス内のベクトル検索アルゴリズムの構成は、2023-11-01 と同じです。 2023-07-01-preview の破壊的変更を修正するには、次のセクションの手順に従います。

2023-11-01 へのアップグレード

このバージョンでは、セマンティック ランク付けとベクトル検索のサポートに関する重大な変更と動作の違いがあります。

• セマンティックの順位付けは一般提供されており、queryLanguage プロパティを使用しなくなりました。 また、semanticConfiguration 定義も必要です。

  2020-06-30-preview からアップグレードするには、searchFields を置き換える semanticConfiguration を作成します。 手順については、「プレビュー バージョンからの移行」を参照してください。

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

  2023-07-01-preview からアップグレードするには、インデックスのベクトル構成の名前を変更して再構築し、このセクションの手順に従ってベクトル クエリ構文を書き直します。

  2023-10-01-preview からアップグレードするには、重大な変更はありませんが、次の 1 点だけ動作の違いがあります: vectorFilterMode の既定値がフィルター式の事後フィルターから事前フィルターに変更されました。 2023-10-01-preview コードで vectorFilterMode が明示的に設定されていない場合は、新しい動作を理解しているか、モードを postfilter に設定して古い動作を保持する必要があります。

ヒント

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

2023-07-01-preview からの移行手順を次に示します。

1. [インデックスの取得] を呼び出し、既存の定義を取得します。

2. ベクトル検索構成を変更します。 この API は、"ベクトル プロファイル" という概念を導入し、ベクトル関連の構成を 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": {
       "profiles": [
         {
           "name": "myHnswProfile",
           "algorithm": "myHnswConfig"
         }
       ],
       "algorithms": [
         {
           "name": "myHnswConfig",
           "kind": "hnsw",
           "hnswParameters": {
             "m": 4,
             "efConstruction": 400,
             "efSearch": 500,
             "metric": "cosine"
           }
         }
       ]
     }
   

3. ベクトル フィールドの定義を変更し、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"
     }
   

4. インデックスの作成または更新を呼び出して変更を投稿します。

5. [POST の検索] を変更して、クエリ構文を変更します。 この API の変更により、ポリモーフィック ベクトル クエリ型をサポートできるようになります。

   • vectors の名前を vectorQueries に変更します。
   • 各ベクトル クエリに対して kind を追加し、"ベクトル" に設定します。
   • 各ベクトル クエリについて、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 へのアップグレード

このバージョンでは、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 以降では使用できません。

1. Azure Cosmos DB の Type プロパティ。 Azure Cosmos DB for NoSQL API データ ソースを対象とするインデクサーの場合は、"type": "documentdb" を "type": "cosmosdb" に変更します。

2. インデクサー エラー処理に status プロパティへの参照が含まれる場合は、それを削除する必要があります。 有用な情報を提供していなかったため、エラー応答から状態を削除しました。

3. データ ソース接続文字列が、応答で返されなくなりました。 API バージョン 2019-05-06 および 2019-05-06 プレビュー以降、データ ソース API では、REST 操作の応答として、接続文字列が返されなくなりました。 これまでの API バージョンで、データ ソースの作成に POST が使用されていた場合は、Azure AI Search で 201 と、プレーンテキストの接続文字列を含む OData 応答が返されました。

4. 固有表現認識コグニティブ スキルは廃止されました。 コード内で名前付きエンティティの認識スキルを呼び出した場合、その呼び出しは失敗します。 これに代わる機能は、エンティティ認識スキル (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 プレビューで導入されました。 この新しい形式では、それぞれの複合フィールドに、サブフィールドが定義されたフィールド コレクションがあります。 API バージョン 2019-05-06 の場合、この新しい形式は、排他的に使用されます。古い形式を使用してインデックスを作成または更新しようとすると失敗します。 古い形式を使用してインデックスを作成した場合は、API バージョン 2017-11-11 プレビューを使用してインデックスを新しい形式に更新してから、API バージョン 2019-05-06 を使用してインデックスを管理する必要があります。

"フラット" インデックスを新しい形式に更新するには、API バージョン 2017-11-11 プレビューを使用して、次の手順を実行します。

1. GET 要求を実行してインデックスを取得します。 既に新しい形式になっている場合は、作業完了です。

2. インデックスを "フラット" 形式から新しい形式に変換します。 この記事の執筆時点では、サンプル コードが用意されていないため、このタスクのコードは自分で作成する必要があります。

3. PUT 要求を実行し、インデックスを新しい形式に更新します。 インデックスの更新 API では既存のインデックスの物理的な式に影響する変更は許可されないため、インデックスのその他の詳細 (フィールドの検索可能性やフィルター処理など) は変更しないでください。

Note

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

次のステップ

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

Search Service REST API リファレンス