Azure AI Search でハイブリッドクエリを作成する

ハイブリッド検索は、単一の検索要求内でテキスト (キーワード) クエリとベクトルクエリを組み合わせたものです。どちらのクエリも並列で実行されます。結果は Reciprocal Rank Fusion (RRF) を使ってマージされ、新しい検索スコアによって並べ替えられて、統合された結果セットが返されます。多くの場合、ベンチマークテストに従い、セマンティックランク付けを使用したハイブリッドクエリからは最も関連性の高い結果が返されます。

この記事では、次のことについて説明します:

基本的なハイブリッド要求を設定する
パラメーターとフィルターを追加する
セマンティックのランク付けまたはベクトルの重みを使用して関連性を向上させる
入力を制御してクエリの動作を最適化する (maxTextRecallSize)

前提条件

searchable ベクトルと非ベクトルフィールドを含む検索インデックス。インデックスをすばやく作成するには、 データのインポート (新しい) ウィザードをお勧めします。それ以外の場合は、インデックスの作成に関するページと、検索インデックスへのベクトルフィールドの追加に関するページを参照してください。
(省略可能) セマンティックランカーが必要な場合、検索サービスは Basic レベル以上で、セマンティックランカーが有効になっている必要があります。
(省略可能) クエリ文字列のテキストからベクトルへの組み込み変換を行いたい場合は、ベクトル化を作成して検索インデックス内のベクトルフィールドに割り当てます。

API またはツールを選択する

Azure portal の Search Explorer (安定版とプレビュー版の両方の API 検索構文をサポート) には、ハイブリッド要求を貼り付けることができる JSON ビューがあります。
Azure SDK の新しい安定したパッケージまたはプレビューパッケージ (SDK 機能サポートの変更ログを参照)。
maxTextRecallSize や countAndFacetMode(preview)などのプレビュー機能を使用している場合は、安定した REST API または最新のプレビュー API バージョン。

読みやすくするため、REST の例を使用して、API のしくみを説明します。 Visual Studio Code などの REST クライアントと REST 拡張機能を使用して、ハイブリッドクエリを作成できます。 Azure SDK を使用することもできます。詳細については、「クイックスタート: ベクター検索」を参照してください。

ハイブリッドクエリを設定する

このセクションでは、ハイブリッドクエリの基本的な構造と、Search Explorer または REST クライアントで実行するクエリを設定する方法について説明します。

結果は、retrievable とマークされたフィールドのベクトルを含む、プレーンテキストで返されます。数値ベクトルは検索結果では役に立たないため、インデックス内の他のフィールドをベクトル一致のプロキシとして選択します。たとえば、インデックスに "descriptionVector" フィールドと "descriptionText" フィールドがある場合、クエリは "descriptionVector" で一致しますが、検索結果には "descriptionText" と表示されます。この select パラメータを使用して、結果に人間が判読できるフィールドのみを指定します。

Azure Portal
レスト

Azure portal にサインインし、ご利用の検索サービスを探します。
[ 検索の管理>インデックス] で、ベクトルと非ベクターコンテンツを含むインデックスを選択します。検索エクスプローラーが最初のタブです。
[ ビュー] で JSON ビュー に切り替えて、ベクタークエリに貼り付けることができます。
既定のクエリテンプレートをハイブリッドクエリに置き換えます。基本的なハイブリッドクエリには、 searchで指定されたテキストクエリと、 vectorQueries.vectorで指定されたベクタークエリがあります。テキストクエリとベクトルクエリは同等の場合も異なる場合もありますが、通常は同じ意図を共有します。

この例は、ベクターコンテンツと非ベクトルコンテンツを含むベクタークイックスタートと、いくつかのクエリ例です。簡潔にするために、この記事ではベクトルは切り詰められています。
```
{
    "search": "historic hotel walk to restaurants and shopping",
    "vectorQueries": [
        {
            "vector": [0.01944167, 0.0040178085, -0.007816401 ... <remaining values omitted> ], 
            "k": 7,
            "fields": "DescriptionVector",
            "kind": "vector",
            "exhaustive": true
        }
    ]
}
```
[Search] を選択します。

ヒント

ベクトルを非表示にすると、検索結果が読みやすくなります。 [クエリオプション] で、検索結果のベクトル値の非表示の設定を有効にします。

クエリの別のバージョンを次に示します。これにより、検出された一致の数の count 、特定のフィールドを選択するための select パラメーター、上位 7 つの結果を返す top パラメーターが追加されます。

 {
     "count": true,
     "search": "historic hotel walk to restaurants and shopping",
     "select": "HotelId, HotelName, Category, Tags, Description",
     "top": 7,
     "vectorQueries": [
         {
             "vector": [0.01944167, 0.0040178085, -0.007816401 ... <remaining values omitted> ], 
             "k": 7,
             "fields": "DescriptionVector",
             "kind": "vector",
             "exhaustive": true
         }
     ]
 }

次の例は、REST API を使用したハイブリッドクエリ要求を示しています。

この例は、ベクターコンテンツと非ベクトルコンテンツを含むベクタークイックスタートと、いくつかのクエリ例です。簡潔にするために、この記事ではベクトルは切り詰められています。

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2025-09-01
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "vectorQueries": [
        {
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "fields": "DescriptionVector",
            "kind": "vector",
            "exhaustive": true,
            "k": 10
        },
        {
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "fields": "DescriptionVector",
            "kind": "vector",
            "exhaustive": true,
            "k": 10
        }
    ],
    "search": "historic hotel walk to restaurants and shopping",
    "select": "HotelName, Description, Address/City",
    "top": 10
}

重要なポイント:

ベクトルクエリ文字列は、vectorQueries.vector プロパティを使用して指定されます。クエリは "DescriptionVector" フィールドに対して実行されます。クエリの種類を示すには、kind を "vector" に設定します。必要に応じて、exhaustive を true に設定し、ベクトルフィールドのすべての内容に対してクエリを実行します。
キーワード検索は、search プロパティを使用して指定されます。ベクトルクエリと並行して実行されます。
k は、ベクトルクエリから返され、RRF ランカーに提供される最も近い近隣の一致の数を決定します。
top は、応答全体で返される一致の数を決定します。この例では、マージされた結果に少なくとも 10 個の一致があると仮定して、応答に 10 個の結果が含まれています。

maxTextRecallSize と countAndFacetMode を設定する

注

現在、この機能はパブリックプレビュー段階にあります。このプレビュー版はサービスレベルアグリーメントなしで提供されています。運用環境のワークロードに使用することはお勧めできません。特定の機能はサポート対象ではなく、機能が制限されることがあります。詳しくは、Microsoft Azure プレビューの追加使用条件に関するページをご覧ください。

ハイブリッドクエリを調整して、各サブクエリが結合された結果にどの程度寄与するかを制御できます。 maxTextRecallSize設定では、ハイブリッドランク付けモデルに渡される BM25 ランク付け結果の数を指定します。

maxTextRecallSizeを使用する場合は、CountAndFacetModeを設定することもできます。このパラメーターは、 count と facets に、検索クエリに一致するすべてのドキュメントを含めるか、 maxTextRecallSize ウィンドウ内で取得したドキュメントのみを含めるかを決定します。既定値は "countAllResults" です。

これらのオプションを設定するには、最新のプレビュー REST API をお勧めします。

ヒント

ハイブリッドクエリチューニングのもう 1 つの方法は、要求内のベクタークエリの重要度を高めるために使用されるベクター重み付けです。

プレビューパラメーターを指定するには、検索 - POST (プレビュー) または検索 - GET (プレビュー) を使用します。
ハイブリッドクエリの BM25 ランク付け結果によって呼び戻されるドキュメントの最大数を設定するには、hybridSearch クエリパラメーターオブジェクトを追加します。 2 つのプロパティがあります。
- maxTextRecallSize は、ハイブリッドクエリで使われる Reciprocal Rank Fusion (RRF) ランカーに提供する BM25 ランク付け結果の数を指定します。既定値は 1,000 です。最大値は 10,000 です。
- countAndFacetMode は、BM25 ランク付け結果 (およびファセットを使用している場合はファセット) の数を報告します。既定値は、クエリに一致するすべてのドキュメントです。必要に応じて、"カウント" のスコープを maxTextRecallSize に設定できます。
maxTextRecallSizeを設定します。
- ベクター類似性検索が一般にハイブリッドクエリのテキスト側を上回る場合は、 maxTextRecallSize を減らします。
- インデックスが大きく、既定値で十分な数の結果がキャプチャされていない場合は、 maxTextRecallSize を増やします。 BM25 ランク付け結果セットが大きいときは、top、skip、next を設定して、それらの結果の一部を取得することもできます。

次の REST の例では、maxTextRecallSize の設定に関する 2 つのユースケースを示します。

最初の例では、maxTextRecallSize を 100 に減らして、ハイブリッドクエリのテキスト側を 100 ドキュメントのみに制限しています。また、countAndFacetMode からの結果のみを含むように、maxTextRecallSize を設定しています。

POST https://[service-name].search.windows.net/indexes/[index-name]/docs/search?api-version=2024-05-01-Preview 

    { 
      "vectorQueries": [ 
        { 
          "kind": "vector", 
          "vector": [1.0, 2.0, 3.0], 
          "fields": "my_vector_field", 
          "k": 10 
        } 
      ], 
      "search": "hello world", 
      "hybridSearch": { 
        "maxTextRecallSize": 100, 
        "countAndFacetMode": "countRetrievableResults" 
      } 
    }

2 番目の例では、maxTextRecallSize を 5,000 に増やしています。また、top、skip、next を使って、大きな結果セットから結果をプルしています。この場合の要求では、RRF 複合結果セットへのテキストクエリの寄与として、位置 1,500 から始まって 2,000 までの BM25 ランク付け結果がプルされます。

POST https://[service-name].search.windows.net/indexes/[index-name]/docs/search?api-version=2024-05-01-Preview 

    { 
      "vectorQueries": [ 
        { 
          "kind": "vector", 
          "vector": [1.0, 2.0, 3.0], 
          "fields": "my_vector_field", 
          "k": 10 
        } 
      ], 
      "search": "hello world",
      "top": 500,
      "skip": 1500,
      "next": 500,
      "hybridSearch": { 
        "maxTextRecallSize": 5000, 
        "countAndFacetMode": "countRetrievableResults" 
      } 
    }

ハイブリッドクエリの例

このセクションには、ハイブリッドクエリパターンを示す複数のクエリ例があります。

例: フィルターを使用したハイブリッド検索

この例では、検索インデックスの非ベクトルフィールド filterable に適用されるフィルターを追加します。

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2025-09-01
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "vectorQueries": [
        {
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "fields": "DescriptionVector",
            "kind": "vector",
            "k": 10
        }
    ],
    "search": "historic hotel walk to restaurants and shopping",
    "vectorFilterMode": "preFilter",
    "filter": "ParkingIncluded",
    "top": "10"
}

重要なポイント:

フィルターは、フィルター可能なフィールドの内容に適用されます。この例では、ParkingIncluded フィールドはブール値であり、インデックススキーマで filterable としてマークされています。
ハイブリッドクエリでは、クエリの実行前にフィルターを適用して、クエリの表面を減らしたり、クエリの実行後に結果をトリミングしたりできます。 "preFilter" は既定値です。 postFilterまたはstrictPostFilter (プレビュー) を使用するには、この例に示すようにフィルター処理モードを設定します。
クエリ結果を事後フィルター処理すると、結果の数が上位 N 未満になる可能性があります。

例: ベクターサブクエリを対象とするフィルターを使用したハイブリッド検索 (プレビュー)

最新のプレビュー REST API を使用すると、ハイブリッド要求のベクターサブクエリのみを対象とするセカンダリフィルターを適用することで、検索要求のグローバルフィルターをオーバーライドできます。

この機能は、フィルターがベクトル検索結果にのみ影響を与え、キーワードベースの検索結果には影響を与えないようにすることで、細かな制御を実現します。

ターゲットフィルターは、セキュリティによるトリミングや地理空間の検索に使用されるフィルターなど、グローバルフィルターを完全にオーバーライドします。セキュリティによるトリミングなどのグローバルフィルターが必要な場合は、これらのフィルターを、最上位レベルのフィルターと各ベクトルレベルのフィルターの両方に明示的に含め、セキュリティやその他の制約が一貫して適用されるようにする必要があります。

対象となるベクトルフィルターを適用するには:

最新のプレビュー Search Documents REST API または機能を提供する Azure SDK ベータパッケージを使用します。
クエリ要求を変更し、新しい vectorQueries.filterOverride パラメーターセットを OData フィルター式に追加します。

フィルターのオーバーライドを追加するハイブリッドクエリの例を次に示します。グローバルフィルター "Rating gt 3" は、実行時に filterOverrideに置き換えられます。

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2025-08-01-preview

{
    "vectorQueries": [
        {
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "fields": "DescriptionVector",
            "kind": "vector",
            "exhaustive": true,
            "filterOverride": "Address/City eq 'Seattle'",
            "k": 10
        }
    ],
    "search": "historic hotel walk to restaurants and shopping",
    "select": "HotelName, Description, Address/City, Rating",
    "filter": "Rating gt 3"
    "debug": "vector",
    "top": 10
}

例: セマンティックハイブリッド検索

セマンティックランカーがあり、インデックス定義にセマンティック構成が含まれていると仮定すると、マージされた結果セットに対するセマンティックランク付けを使用して、ベクター検索とキーワード検索を含むクエリを作成できます。必要に応じて、キャプションと回答を追加できます。

ベクトルでセマンティックランク付けを使用するときは常に、k が 50 に設定されていることを確認します。セマンティックランカーでは、入力として最大 50 個の一致が使用されます。 50 未満を指定すると、セマンティックランク付けモデルに必要な入力が与えられなくなります。

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2025-09-01
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "vectorQueries": [
        {
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "fields": "DescriptionVector",
            "kind": "vector",
            "k": 50
        }
    ],
    "search": "historic hotel walk to restaurants and shopping",
    "select": "HotelName, Description, Tags",
    "queryType": "semantic",
    "semanticConfiguration": "my-semantic-config",
    "captions": "extractive",
    "answers": "extractive",
    "top": "50"
}

重要なポイント:

セマンティックランカーでは、マージされた応答から最大 50 個の結果が受け入れられます。
"queryType" と "semanticConfiguration" は必須です。
"captions" と "answers" は省略可能です。値は、結果内の逐語的なテキストから抽出されます。回答は、クエリに対する回答の特性を持つ内容が結果に含まれている場合にのみ返されます。

例: フィルターを使用したセマンティックハイブリッド検索

ここでは、コレクションでの最後のクエリを示します。これは、前の例と同じセマンティックハイブリッドクエリですが、フィルターを使用します。

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2025-09-01
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "vectorQueries": [
        {
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "fields": "DescriptionVector",
            "kind": "vector",
            "k": 50
        }
    ],
    "search": "historic hotel walk to restaurants and shopping",
    "select": "HotelName, Description, Tags",
    "queryType": "semantic",
    "semanticConfiguration": "my-semantic-config",
    "captions": "extractive",
    "answers": "extractive",
    "filter": "ParkingIsIncluded'",
    "vectorFilterMode": "preFilter",
    "top": "50"
}

重要なポイント:

フィルターモードは、セマンティックリランカーで使用できる結果の数に影響を与える可能性があります。ベストプラクティスとして、セマンティックランカーにドキュメントの最大数 (50) を指定するのが賢明です。事前フィルターまたは事後フィルターの選択性が高すぎる場合、操作するドキュメントを 50 未満にすることでセマンティックランカーを過小評価している可能性があります。
preFilter はクエリの実行前に適用されます。プレフィルターによって検索領域が 100 個のドキュメントに縮小された場合、ベクタークエリは、これらの 100 個のドキュメントに対して DescriptionVector フィールドに対して実行され、k= 50 の最適な一致が返されます。その後、これらの一致する 50 ドキュメントが RRF に渡されてマージされた結果が得られ、セマンティックランカーに渡されます。
postFilter は、クエリの実行後に適用されます。 k=50 がベクトルクエリ側で 50 件の一致を返し、その後に 50 件の一致にポストフィルターを適用すると、結果はフィルター条件を満たすドキュメントの数だけ減少します。これにより、セマンティックランカーに渡されるドキュメントは 50 未満になります。セマンティックランク付けを使用する場合は、この点に留意してください。セマンティックランカーは、入力として 50 個のドキュメントがある場合に最適に動作します。
strictPostFilter (プレビュー) は、クエリの実行後にフィルター処理されていない上位k 結果に適用されます。常に、 k ドキュメント以下を返します。フィルター処理されていない k=50 が 50 個のフィルター処理されていない結果を返し、フィルターが 30 個のドキュメントと一致する場合、インデックスにフィルターに一致するドキュメントが 30 個を超える場合でも、結果セットには 30 個のドキュメントのみが返されます。このモードでは再現率が最も低いため、セマンティックランカーで使用することはお勧めしません。

クエリ応答を構成する

ハイブリッドクエリを設定するときは、応答構造について考えてください。検索エンジンは、一致するドキュメントをランク付けし、最も関連性の高い結果を返します。応答はフラット化行セットです。クエリのパラメータによって、各行に含まれるフィールドと、応答内の行数が決まります。

応答のフィールド

検索結果は、検索インデックスの retrievable フィールドで構成されます。結果は次のいずれかになります:

すべての retrievable フィールド (REST API の既定値)。
クエリの select パラメーターに明示的に一覧表示されているフィールド。

この記事の例では、 select ステートメントを使用して、応答のテキスト (非ベクトル) フィールドを指定しました。

注

ベクトルは人間が判読できるテキストにリバースエンジニアリングされないため、応答で返されないようにします。代わりに、検索ドキュメントを代表する非ベクトルフィールドを選択します。たとえば、クエリが "DescriptionVector" フィールドを対象とする場合、応答に 1 つの ("Description") がある場合は、同等のテキストフィールドを返します。

結果の件数

検索条件が弱い場合は、クエリが任意の数のドキュメントと一致する場合があります (たとえば、null クエリの場合は "search=*")。無制限の結果を返すことが実用的であることは滅多にないので、"応答全体" の最大値を指定する必要があります:

"top": n キーワードのみのクエリの結果 (ベクターなし)
ベクトルのみのクエリの結果として "k": n
"top": n "search" パラメーターを含むハイブリッドクエリ (セマンティックあり、または、なし) の結果

k と top はどちらも省略可能です。指定しない場合、応答の結果の既定の数は 50 です。 topとskipをページに設定して、より多くの結果を表示したり、既定値を変更したりできます。

注

2024-05-01-preview API でハイブリッド検索を使用する場合は、maxTextRecallSize を使用してキーワードクエリから返される結果の数を制御できます。これを k の設定と組み合わせて、各検索サブシステム (キーワードとベクター) の表現を制御します。

セマンティックランカーの結果

注

セマンティックランカーでは最大 50 件の結果を受け取ることができます。

2024-05-01-preview 以降でセマンティックランカーを使用している場合は、 k と maxTextRecallSize を合計 50 以上に設定することをお勧めします。その後、 top パラメーターを使用して、ユーザーに返される結果を制限できます。

前の API でセマンティックランカーを使用する場合は、次の操作を行います。

キーワードのみの検索 (ベクトルなし) top 50 に設定する場合
ハイブリッド検索 k 50 に設定されている場合は、セマンティックランカーが少なくとも 50 件の結果を取得するようにします。

ランク付け

オプションのセマンティック再ランク付けの有無にかかわらず、ハイブリッドクエリでは複数のセットが作成されます。結果のランク付けは、Reciprocal Rank Fusion (RRF) によって計算されます。

このセクションでは、単一ベクトル検索と単純ハイブリッド検索の応答を比較して、上位の結果を確認します。異なるランク付けアルゴリズムである HNSW の類似性メトリックと RRF の場合では、異なる大きさのスコアが生成されます。この動作は仕様によるものです。 RRF スコアは、類似性の一致が高い場合でも、非常に低くなる場合があります。スコアの低さは、RRF アルゴリズムの特性です。 RRF を使用するハイブリッドクエリの場合、純粋なベクトル検索とは対照的に、RRF でランク付けされたドキュメントのスコアは比較的小さいため、ランク付けされたドキュメントの逆数がより多く結果に含まれます。

単一ベクトル検索: コサイン類似度で並べ替えられた結果の @search.score (既定のベクトル類似距離関数)。

{
    "@search.score": 0.8399121,
    "HotelId": "49",
    "HotelName": "Swirling Currents Hotel",
    "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center.",
    "Category": "Luxury",
    "Address": {
    "City": "Arlington"
    }
}

ハイブリッド検索: Reciprocal Rank Fusion を使用してランク付けされたハイブリッド結果の @search.score。

{
    "@search.score": 0.032786883413791656,
    "HotelId": "49",
    "HotelName": "Swirling Currents Hotel",
    "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center.",
    "Category": "Luxury",
    "Address": {
    "City": "Arlington"
    }
}

次のステップ

Python、C#、または JavaScript のベクターデモコードを確認することをお勧めします。

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-08-28

次の方法で共有

Azure AI Search でハイブリッド クエリを作成する

前提条件

API またはツールを選択する

ハイブリッド クエリを設定する

maxTextRecallSize と countAndFacetMode を設定する

ハイブリッド クエリの例

例: フィルターを使用したハイブリッド検索

例: ベクター サブクエリを対象とするフィルターを使用したハイブリッド検索 (プレビュー)

例: セマンティック ハイブリッド検索

例: フィルターを使用したセマンティック ハイブリッド検索

クエリ応答を構成する

応答のフィールド

結果の件数

セマンティック ランカーの結果

ランク付け

次のステップ

フィードバック

その他のリソース

Azure AI Search でハイブリッドクエリを作成する

ハイブリッドクエリを設定する

ハイブリッドクエリの例

例: ベクターサブクエリを対象とするフィルターを使用したハイブリッド検索 (プレビュー)

例: セマンティックハイブリッド検索

例: フィルターを使用したセマンティックハイブリッド検索

セマンティックランカーの結果