次の方法で共有

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

  • [アーティクル]

データ プレーン呼び出しを新しいバージョンの Search REST 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 を参照してください)。

アップグレードする方法

  1. 各 API バージョンのリリース ノートを確認します。

  2. 要求ヘッダーで指定されている api-version パラメーターを、新しいバージョンに更新します。

    REST API を直接呼び出すアプリケーション コードで、既存のバージョンのすべてのインスタンスを検索し、新しいバージョンに置き換えます。 REST 呼び出しの構成の詳細については、「クイック スタート: RESTの使用」を参照してください。

    Azure SDK を使用している場合、これらのパッケージは特定のバージョンの REST API をターゲットにします。 パッケージの更新は REST API の更新と同時に行われる場合もありますが、各 SDK には独自のリリース スケジュールがあり、Azure AI Search REST API のバージョンとは関係なく出荷されます。 SDK パッケージの変更ログをチェックして、パッケージ リリースが最新の REST API バージョンをターゲットにしているかどうかを確認します。

  3. この記事に記載されている破壊的変更を確認し、回避策を実装します。 自分のコードで使われているバージョンから始めて、最新の安定版またはプレビュー リリースに達するまで、新しい各 API バージョンの破壊的変更を解決します。

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

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-09-01-preview にアップグレードする

2024-09-01-preview では、text-embedding-3 モデル用のマトリョーシカ表現学習 (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 スキルにモデル名とディメンション プロパティが必要になりました。

  1. コードベースで AzureOpenAIEmbedding 参照を検索します。

  2. modelName を "text-embedding-ada-002" に設定し、dimensions を "1536" に設定します。

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

2024-03-01-preview は、狭いデータ型、スカラー量子化、ベクトル ストレージ オプションを追加します。

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

  1. コードベースで vectorFilterMode 参照を検索します。

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

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

2023-11-01 は一般向けリリースです。 前のプレビュー機能 (セマンティック ランカー、ベクトル インデックス、クエリのサポート) は一般提供になっています。

2023-10-01-preview からの場合は破壊的変更はありませんが、2023-07-01-preview から 2023-11-01 の場合は複数の破壊的変更があります。 詳しくは、「2023-07-01 プレビューからのアップグレード」をご覧ください。

新しい安定版リリースを使うには、API のバージョンを変更して、コードをテストします。

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 からベクトル フィールド、構成、クエリを移行してください。

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

  2. ベクトル検索構成を変更します。 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"
      }
    ]
  }

  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 を追加し、それを 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 以降では動作しません。

  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-Preview 以降のデータ ソース 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-Preview で導入されました。 この新しい形式では、それぞれの複合フィールドに、サブフィールドが定義されたフィールド コレクションがあります。 API バージョン 2019-05-06 の場合、この新しい形式は、排他的に使用されます。古い形式を使用してインデックスを作成または更新しようとすると失敗します。 古い形式を使って作成されたインデックスがある場合は、API バージョン 2017-11-11-Preview を使って新しい形式に更新してから、API バージョン 2019-05-06 を使って管理する必要があります。

API バージョン 2017-11-11-Preview を使って次の手順のようにすると、フラットなインデックスを新しい形式に更新できます。

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

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

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

Note

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

次のステップ

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

Search Service REST API リファレンス