Azure AI 検索でベクタークエリを作成する

Azure AI 検索に vector index がある場合、この記事では次の方法について説明します。

クエリベクターフィールド
一度に複数のベクターフィールドに対してクエリを実行する
ベクターの重みを設定する
統合ベクター化を使用したクエリ
しきい値を設定してスコアの低い結果を除外する (プレビュー)

この記事では、REST を使用して説明します。基本的なワークフローを理解したら、ベクタークエリを含むエンドツーエンドのソリューションを提供する azure-search-vector-samples リポジトリのAzure SDK コードサンプルに進みます。

Azure ポータルで Search Explorer を使用することもできます。

前提条件

任意のリージョンおよび任意のレベルのAzure AI 検索サービス。
ベクターインデックス。インデックス内の vectorSearch セクションを確認して、その存在を確認します。
必要に応じて、クエリ中に組み込みのテキストからベクターへの変換またはイメージからベクターへの変換のために、ベクター化をインデックスに追加します。
これらの例を独自に実行する場合は、REST クライアントとサンプルデータを使用してVisual Studio Codeします。 REST クライアントの使用を開始するには、「クイックスタート: REST を使用したフルテキスト検索」を参照してください。

クエリ文字列入力をベクターに変換する

ベクターフィールドに対してクエリを実行するには、クエリ自体がベクターである必要があります。

ユーザーのテキストクエリ文字列をベクター表現に変換する方法の 1 つは、アプリケーションコードで埋め込みライブラリまたは API を呼び出す方法です。ベストプラクティスとして、 ソースドキュメントに埋め込みを生成するために使用するのと同じ埋め込みモデルを常に使用します。埋め込みの生成方法を示すコードサンプルは、azure-search-vector-samples リポジトリにあります。

2 つ目の方法は、統合ベクター化を使用して、クエリのベクター化の入力と出力をAzure AI 検索処理できるように、一般提供されています。

Azure OpenAI 埋め込みモデルのデプロイに送信されるクエリ文字列の REST API の例を次に示します。

POST https://{{openai-service-name}}.openai.azure.com/openai/deployments/{{openai-deployment-name}}/embeddings?api-version={{openai-api-version}}
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "input": "what azure services support generative AI'"
}

デプロイされたモデルの呼び出しが成功した場合、予想される応答は 202 です。

応答の本文の embedding フィールドは、クエリ文字列 inputのベクター表現です。テストの目的で、次のいくつかのセクションで示す構文を使用して、 embedding 配列の値をクエリ要求の vectorQueries.vector にコピーします。

デプロイされたモデルに対するこの POST 呼び出しに対する実際の応答には、1,536 個の埋め込み機能が含まれています。読みやすくするために、この例では最初のいくつかのベクトルのみを示します。

{
    "object": "list",
    "data": [
        {
            "object": "embedding",
            "index": 0,
            "embedding": [
                -0.009171937,
                0.018715322,
                ...
                -0.0016804502
            ]
        }
    ],
    "model": "ada",
    "usage": {
        "prompt_tokens": 7,
        "total_tokens": 7
    }
}

このアプローチでは、アプリケーションコードは、モデルへの接続、埋め込みの生成、応答の処理を担当します。

ベクタークエリ要求

このセクションでは、ベクタークエリの基本的な構造について説明します。 Azure ポータル、REST API、またはAzure SDKを使用して、ベクタークエリを作成できます。

2023-07-01-Preview から移行する場合は、重大な変更があります。詳細については、「最新の REST API へのアップグレード」を参照してください。

安定バージョンでは、次の機能がサポートされます。

vectorQueries はベクター検索のコンストラクトです。
vectorQueries.kindをベクター配列の場合はvectorに設定し、入力が文字列の場合はtextを、かつベクトライザーを持っている場合は設定します。
vectorQueries.vector はクエリ (テキストまたは画像のベクター表現) です。
vectorQueries.exhaustive (省略可能) HNSW に対してフィールドのインデックスが作成されている場合でも、クエリ時に完全な KNN が呼び出されます。
vectorQueries.fields (省略可能) クエリ実行の特定のフィールドを対象とします (クエリあたり最大 10)。
vectorQueries.weight (省略可能) 検索操作に含まれる各ベクタークエリの相対的な重みを指定します。詳細については、「ベクターの重み付け」を参照してください。
vectorQueries.k は、返される一致の数です。

次の例では、ベクトルはこの文字列の表現です: "what Azure services support full text search"。クエリは contentVector フィールドを対象とし、結果 k 返します。実際のベクターには 1,536 個の埋め込みがあり、この例では読みやすくするためにトリミングされています。

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}}
{
    "count": true,
    "select": "title, content, category",
    "vectorQueries": [
        {
            "kind": "vector",
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "exhaustive": true,
            "fields": "contentVector",
            "weight": 0.5,
            "k": 5
        }
    ]
}

2025-11-01-preview は、検索 - POST の最新プレビュー API バージョンです。 2025-09-01 と同じベクタークエリ構文がサポートされていますが、ハイブリッド検索用の追加のパラメーターと、弱い結果を除外するための最小しきい値があります。

このプレビューでは、次の機能がサポートされます。

threshold 低スコアの結果を除外する場合。
hybridSearch.MaxTextRecallSize ハイブリッドクエリへの入力をより詳細に制御できます。

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2025-11-01-preview
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "count": true,
    "select": "title, content, category",
    "hybridSearch": {
        "maxTextRecallSize": 100,
        "countAndFacetMode": "countAllResults"
        }
    "vectorQueries": [
        {
            "kind": "vector",
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "fields": "contentVector",
            "k": 5,
            "exhaustive": true,
            "weight": 2,
            "threshold": {
                "kind": "vectorSimilarity",
                "value": 0.8
            },

        }
    ]
}

ベクタークエリ応答

Azure AI 検索では、クエリ応答は既定ですべての retrievable フィールドで構成されます。ただし、検索結果をretrievableステートメントに一覧表示することで、検索結果をselectフィールドのサブセットに限定するのが一般的です。

ベクタークエリでは、応答内のフィールドをベクターにする必要があるかどうかを慎重に検討します。ベクターフィールドは人間が判読できないため、Web ページに応答をプッシュする場合は、結果を表す非ベクトルフィールドを選択する必要があります。たとえば、クエリが contentVectorに対して実行される場合は、代わりに content を返します。

結果にベクターフィールドが必要な場合は、応答構造の例を次に示します。 contentVector は埋め込みの文字列配列であり、この例では読みやすくするためにトリミングされています。検索スコアは関連性を示します。コンテキストには、その他の非ベクトルフィールドが含まれています。

{
    "@odata.count": 3,
    "value": [
        {
            "@search.score": 0.80025613,
            "title": "Azure Search",
            "category": "AI + Machine Learning",
            "contentVector": [
                -0.0018343845,
                0.017952163,
                0.0025753193,
                ...
            ]
        },
        {
            "@search.score": 0.78856903,
            "title": "Azure Application Insights",
            "category": "Management + Governance",
            "contentVector": [
                -0.016821077,
                0.0037742127,
                0.016136652,
                ...
            ]
        },
        {
            "@search.score": 0.78650564,
            "title": "Azure Media Services",
            "category": "Media",
            "contentVector": [
                -0.025449317,
                0.0038463024,
                -0.02488436,
                ...
            ]
        }
    ]
}

重要なポイント:

k は、返される最も近い近隣の結果の数 (この場合は 3) を決定します。一部のドキュメントの類似性が低い場合でも、少なくともkドキュメントが存在すると仮定すると、ベクタークエリは常にk結果を返します。これは、アルゴリズムがクエリベクターに最も近い k を検出するためです。
ベクター検索アルゴリズムによって、@search.scoreが決定されます。
検索結果のフィールドは、すべてretrievableフィールドかselect句内のフィールドです。ベクタークエリの実行中に、ベクターデータに対して一致が行われます。ただし、応答には、インデックスに任意の retrievable フィールドを含めることができます。ベクターフィールドの結果をデコードする機能がないため、非ベクトルテキストフィールドを含めることは、人間が判読できる値に役立ちます。

複数のベクターフィールド

vectorQueries.fields プロパティを複数のベクターフィールドに設定できます。ベクタークエリは、 fields リストに指定した各ベクターフィールドに対して実行されます。最大 10 個のフィールドを指定できます。

複数のベクターフィールドに対してクエリを実行する場合は、各フィールドに同じ埋め込みモデルの埋め込み値が含まれていることを確認します。クエリも同じ埋め込みモデルから生成する必要があります。

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}}
{
    "count": true,
    "select": "title, content, category",
    "vectorQueries": [
        {
            "kind": "vector",
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "exhaustive": true,
            "fields": "contentVector, titleVector",
            "k": 5
        }
    ]
}

複数のベクタークエリ

マルチクエリベクター検索では、検索インデックス内の複数のベクターフィールドに対して複数のクエリが送信されます。この種類のクエリは、同じモデルでテキストと画像の両方をベクター化できるマルチモーダル検索用の CLIP などのモデルでよく使用されます。

次のクエリ例では、 myImageVector と myTextVector の両方で類似性を検索しますが、それぞれ並列で実行される 2 つのクエリ埋め込みを送信します。このクエリの結果は、逆ランク融合 (RRF) を使用してスコア付けされます。

vectorQueries はベクタークエリの配列を提供します。
vector には、検索インデックス内の画像ベクトルとテキストベクトルが含まれています。各インスタンスは個別のクエリです。
fields は、ターゲットにするベクターフィールドを指定します。
k は、結果に含める最も近い近隣の一致の数です。

{
    "count": true,
    "select": "title, content, category",
    "vectorQueries": [
        {
            "kind": "vector",
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "fields": "myimagevector",
            "k": 5
        },
        {
            "kind": "vector"
            "vector": [
                -0.002222222,
                0.018708462,
                -0.013770515,
            . . .
            ],
            "fields": "mytextvector",
            "k": 5
        }
    ]
}

検索インデックスでは画像を格納できません。インデックスに画像ファイルのフィールドが含まれていると仮定すると、検索結果にはテキストと画像の組み合わせが含まれます。

統合ベクター化を使用したクエリ

このセクションでは、統合ベクター化を呼び出してテキストまたは画像のクエリをベクターに変換するベクタークエリを示します。この機能には、安定した 2025-09-01 REST API、Search Explorer、またはそれ以降のAzure SDK パッケージをお勧めします。

前提条件は、 vectorizer が構成され、ベクターフィールドに割り当てられている検索インデックスです。ベクターライザーは、クエリ時に使用される埋め込みモデルへの接続情報を提供します。

Azure portal
REST API

Search Explorer では、クエリ時の統合ベクター化がサポートされます。インデックスにベクターフィールドが含まれており、ベクター化がある場合は、組み込みのテキストからベクターへの変換を使用できます。

Azure ポータルで検索サービスに移動します。
左側のメニューから、[検索の管理] >[インデックス] を選択し、インデックスを選択します。
ベクター化があることを確認するには、[Vector profiles]\( ベクトルプロファイル \) タブを選択します。
[検索エクスプローラー] タブを選択します。既定のクエリビューを使用すると、検索バーにテキスト文字列を入力できます。組み込みのベクターライザーは、文字列をベクターに変換し、検索を実行し、結果を返します。

または、 ビュー>JSON ビュー を選択して、クエリを表示または変更することもできます。ベクターが存在する場合、Search Explorer はベクタークエリを自動的に設定します。 JSON ビューを使用すると、検索と応答で使用するフィールドの選択、フィルターの追加、ハイブリッドクエリなどのより高度なクエリの構築を行うことができます。 JSON の例を表示するには、このセクションの [REST API] タブを選択します。

Index - GET を使用してインデックス定義を返し、ベクター化構成が存在することを確認します。インデックス定義で vectorizers を探します。デプロイされた埋め込みモデルを指定する必要があります。
クエリ要求に検索 - POST を使用します。
- kind を textに設定する必要があります。
- text にはテキスト文字列が必要です。これは、ベクターフィールドに割り当てられたベクターライザーに渡されます。
- fields は検索するベクターフィールドです。
- k は、返されるベクター一致の数です。

クエリ時にベクター化されるクエリの簡単な例を次に示します。テキスト文字列はベクター化され、 descriptionVector フィールドのクエリに使用されます。

POST https://{{search-service}}.search.windows.net/indexes/{{index}}/docs/search?api-version=2025-09-01
{
    "select": "title, genre, description",
    "vectorQueries": [
        {
            "kind": "text",
            "text": "mystery novel set in London",
            "fields": "descriptionVector",
            "k": 5
        }
    ]
}

テキストクエリに統合ベクター化を使用するハイブリッドクエリを次に示します。このクエリには、複数のクエリベクターフィールド、複数の非ベクトルフィールド、フィルター、セマンティックランク付けが含まれます。ここでも、違いは、ベクタークエリのkindと、textではなくvector文字列です。

この例では、検索エンジンは、インデックス内の descriptionVector、 synopsisVector、および authorBioVector に割り当てられたベクター化を 3 回呼び出します。結果のベクターは、それぞれのフィールドに対してドキュメントを取得するために使用されます。検索エンジンは、 search クエリに対してキーワード検索も実行します。これは "mystery novel set in London"です。

POST https://{{search-service}}.search.windows.net/indexes/{{index}}/docs/search?api-version=2025-09-01
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "search":"mystery novel set in London", 
    "searchFields":"description, synopsis", 
    "semanticConfiguration":"my-semantic-config", 
    "queryType":"semantic",
    "select": "title, author, synopsis",
    "filter": "genre eq 'mystery'",
    "vectorFilterMode": "postFilter",
    "vectorQueries": [
        {
            "kind": "text",
            "text": "mystery novel set in London",
            "fields": "descriptionVector, synopsisVector",
            "k": 50
        },
        {
            "kind": "text"
            "text": "living english author",
            "fields": "authorBioVector",
            "k": 50
        }
    ]
}

ベクトルでセマンティックランク付けを使用する場合は常に、 k を 50 に設定します。セマンティックランカーでは、入力として最大 50 個の一致が使用されます。 50 未満を指定すると、必要な入力のセマンティックランク付けモデルが奪われます。

4 つのクエリすべてからのスコア付けされた結果は、 RRF ランク付けを使用して融合されます。セカンダリセマンティックランク付けは、searchFields のみで融合された検索結果に対して呼び出され、意味的に整合する"search":"mystery novel set in London"に合わせた結果を強調します。

メモ

ベクター化は、インデックス作成とクエリ中に発生します。インデックスにデータチャンクとベクター化が必要ない場合は、インデクサー、スキルセット、データソースの作成などの手順をスキップできます。このワークフローでは、ベクター化は、テキスト文字列または画像を埋め込み形式に変換するために、クエリ時にのみ使用されます。このステップの検索インデックスでベクターライザーを定義できます。

ベクタークエリ応答のランク付けされた結果の数

ベクタークエリは、結果で返される一致の数を決定する k パラメーターを指定します。検索エンジンは常に一致の件数kを返します。 kがインデックス内のドキュメントの数より大きい場合、ドキュメントの数によって返される内容の上限が決まります。

フルテキスト検索に慣れている場合は、インデックスに用語または語句が含まれていない場合は、結果が 0 になると予想されます。ただし、ベクター検索では、最も近い近傍が特定され、最も近い近隣ノードが類似していない場合でも、常に k 結果が返されます。特にプロンプトを使用して境界を設定していない場合は、無意味なクエリまたはトピック外のクエリの結果を取得できます。関連性の低い結果は類似度スコアが悪くなりますが、近いものがない場合でも"最も近い"ベクトルです。そのため、意味のある結果を含まない応答でも k 結果を返すことができますが、各結果の類似性スコアは低くなります。

フルテキスト検索を含むハイブリッドアプローチでは、この問題を軽減できます。もう 1 つの解決策は、クエリが純粋な単一ベクトルクエリである場合にのみ、検索スコアに最小しきい値を設定することです。 RRF 範囲ははるかに小さく、揮発性が高いため、ハイブリッドクエリは最小しきい値に役立たない。

結果数に影響するクエリパラメーターは次のとおりです。

"k": n ベクターのみのクエリの結果。
"top": n search パラメーターを含むハイブリッドクエリの結果。

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

ベクタークエリで使用されるランク付けアルゴリズム

結果のランク付けは、次のいずれかによって計算されます。

類似性メトリック。
検索結果のセットが複数ある場合は RRF。

類似性メトリック

ベクトルのみのクエリのインデックス vectorSearch セクションで指定された類似性メトリック。有効な値は、 cosine、 euclidean、および dotProductです。

OpenAI 埋め込みモデルAzureはコサインの類似性を使用するため、OpenAI 埋め込みモデルAzure使用している場合は、cosine が推奨されるメトリックです。その他のサポートされているランク付けメトリックには、 euclidean と dotProductがあります。

RRF

クエリが複数のベクターフィールドを対象とする場合、複数のベクタークエリを並列で実行する場合、またはセマンティックランク付けの有無にかかわらず、ベクターとフルテキスト検索のハイブリッドである場合は、複数のセットが作成されます。

クエリの実行中、ベクタークエリは 1 つの内部ベクターインデックスのみを対象にすることができます。複数のベクターフィールドと複数のベクタークエリの場合、検索エンジンは、各フィールドのそれぞれのベクターインデックスを対象とする複数のクエリを生成します。出力は、RRF を使用して融合された各クエリのランク付けされた結果のセットです。詳細については、「逆ランク融合を使用した関連性スコアリング」を参照してください。

ベクターの重み付け

weight クエリパラメーターを追加して、検索操作に含まれる各ベクタークエリの相対的な重みを指定します。この値は、同じ要求内の 2 つ以上のベクタークエリによって生成された複数のランク付けリストの結果を結合する場合、またはハイブリッドクエリのベクター部分から結合する場合に使用されます。

既定値は 1.0 で、値は 0 より大きい正の数値である必要があります。

重みは、各ドキュメントの RRF スコアを計算するときに使用されます。計算は、それぞれの結果セット内のドキュメントのランクスコアに対する weight 値の乗数です。

次の例は、2 つのベクタークエリ文字列と 1 つのテキスト文字列を含むハイブリッドクエリです。重みはベクタークエリに割り当てられます。最初のクエリは 0.5 または半分の重みであり、要求での重要度が低下します。 2 番目のベクタークエリは 2 倍重要です。

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

    { 
      "vectorQueries": [ 
        { 
          "kind": "vector", 
          "vector": [1.0, 2.0, 3.0], 
          "fields": "my_first_vector_field", 
          "k": 10, 
          "weight": 0.5 
        },
        { 
          "kind": "vector", 
          "vector": [4.0, 5.0, 6.0], 
          "fields": "my_second_vector_field", 
          "k": 10, 
          "weight": 2.0
        } 
      ], 
      "search": "hello world" 
    }

ベクターの重み付けはベクターにのみ適用されます。この例のテキストクエリ "hello world"、暗黙的なニュートラルウェイトは 1.0 です。ただし、ハイブリッドクエリでは、 maxTextRecallSize を設定することで、テキストフィールドの重要度を増減できます。

しきい値を設定してスコアの低い結果を除外する (プレビュー)

最も近い近隣検索では常に要求された k 近隣が返されるため、検索結果における k 数の要件を満たすために、複数の低スコアのマッチを取得できます。スコアの低い検索結果を除外するには、最小スコアに基づいて結果を除外する threshold クエリパラメーターを追加します。フィルター処理は、異なるリコールセットの結果を融合する前に発生します。

このパラメーターはプレビュー段階です。最新のプレビューバージョンの Documents - Search Post (REST API) をお勧めします。

この例では、結果の数が kを下回った場合でも、0.8 未満のスコアのすべての一致がベクター検索結果から除外されます。

POST https://[service-name].search.windows.net/indexes/[index-name]/docs/search?api-version=2025-11-01-preview 
    Content-Type: application/json 
    api-key: [admin key] 

    { 
      "vectorQueries": [ 
        { 
          "kind": "vector", 
          "vector": [1.0, 2.0, 3.0], 
          "fields": "my-cosine-field", 
          "threshold": { 
            "kind": "vectorSimilarity", 
            "value": 0.8 
          } 
        }
      ]
    }

次の手順

次の手順として、Python、C#、または JavaScript のベクタークエリコードの例を確認します。

フィードバック

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

Last updated on 2026-04-30

Azure AI 検索でベクター クエリを作成する

前提 条件

クエリ文字列入力をベクターに変換する

ベクター クエリ要求

ベクター クエリ応答

複数のベクター フィールド

複数のベクター クエリ