Azure AI 検索でベクトルクエリを作成する

2025-06-23

この記事では、Azure AI 検索でベクトルインデックスがある場合の、次の方法について説明します。

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

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

Azure portal で Search エクスプローラーを使うこともできます。

前提条件

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

クエリ文字列入力をベクトルに変換する

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

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

2 つ目のアプローチは、一般公開された統合ベクター化を使用して、Azure AI Search でクエリベクター化の入力と出力を処理できるようにすることです。

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 portal、REST API、または Azure SDK を使用して、ベクトルクエリを作成できます。

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

2024-07-01 は、安定した REST API バージョンの Search POST です。このバージョンでは次の内容がサポートされます。

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=2024-07-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
        }
    ]
}

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

このプレビューでは、以下が追加されました。

threshold 低スコアの結果を除外する場合。
Hybridsearch.MaxTextRecallSizeへの入力をより細かく制御するための。

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2024-05-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=2024-07-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
        }
    ]
}

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

垂直統合を使用したクエリ

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

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

Azure Portal
REST API

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

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

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

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

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

POST https://{{search-service}}.search.windows.net/indexes/{{index}}/docs/search?api-version=2024-07-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=2024-07-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 に合致する結果をブーストします。

注

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

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

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

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

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

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

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

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

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

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

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

類似性メトリック

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

Azure OpenAI 埋め込みモデルではコサイン類似性が使用されるため、Azure OpenAI 埋め込みモデルを使用している場合は、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=2024-07-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 クエリパラメーターを追加します。フィルター処理は、複数のリコールセットの結果を融合する前に発生します。

このパラメーターはプレビュー段階です。 2024-05-01-preview REST API バージョンをお勧めします。

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

POST https://[service-name].search.windows.net/indexes/[index-name]/docs/search?api-version=2024-05-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 
          } 
        }
      ]
    }

ハイブリッド検索用の MaxTextSizeRecall (プレビュー)

ベクトルクエリは、非ベクトルフィールドを含むハイブリッドコンストラクトでよく使用されます。ハイブリッドクエリの結果における BM25 ランクの結果の出現が多すぎる、または少なすぎる場合、maxTextRecallSize を設定して、ハイブリッドランク付けに対して提供された BM25 ランクの結果を増減させることができます。

このプロパティは、 search コンポーネントと vectorQueries コンポーネントの両方を含むハイブリッド要求でのみ設定できます。

このパラメーターはプレビュー段階です。 2024-05-01-preview REST API バージョンをお勧めします。

詳細については、maxTextRecallSize の設定 - ハイブリッドクエリの作成に関する記事を参照してください。

次のステップ

次の手順として、Python、C#、JavaScript のベクトルクエリコードの例を確認してください。

次の方法で共有

Azure AI 検索でベクトル クエリを作成する

前提条件

クエリ文字列入力をベクトルに変換する

ベクトル クエリ要求

ベクトル クエリ応答

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

複数のベクトル クエリ