パブリック インデックスをクエリして最近傍を取得する

インデックスを作成してデプロイしたら、クエリを実行して最近傍を取得できます。

以下に、k 最近傍探索アルゴリズム(k-NN)を使用して上位の最近傍を見つける一致クエリの例を示します。

パブリック エンドポイントのクエリ例

Python

Python

def vector_search_find_neighbors(
    project: str,
    location: str,
    index_endpoint_name: str,
    deployed_index_id: str,
    queries: List[List[float]],
    num_neighbors: int,
) -> None:
    """Query the vector search index.

    Args:
        project (str): Required. Project ID
        location (str): Required. The region name
        index_endpoint_name (str): Required. Index endpoint to run the query
        against.
        deployed_index_id (str): Required. The ID of the DeployedIndex to run
        the queries against.
        queries (List[List[float]]): Required. A list of queries. Each query is
        a list of floats, representing a single embedding.
        num_neighbors (int): Required. The number of neighbors to return.
    """
    # Initialize the Vertex AI client
    aiplatform.init(project=project, location=location)

    # Create the index endpoint instance from an existing endpoint.
    my_index_endpoint = aiplatform.MatchingEngineIndexEndpoint(
        index_endpoint_name=index_endpoint_name
    )

    # Query the index endpoint for the nearest neighbors.
    resp = my_index_endpoint.find_neighbors(
        deployed_index_id=deployed_index_id,
        queries=queries,
        num_neighbors=num_neighbors,
    )
    print(resp)

    # Query hybrid datapoints, sparse-only datapoints, and dense-only datapoints.
    hybrid_queries = [
        aiplatform.matching_engine.matching_engine_index_endpoint.HybridQuery(
            dense_embedding=[1, 2, 3],
            sparse_embedding_dimensions=[10, 20, 30],
            sparse_embedding_values=[1.0, 1.0, 1.0],
            rrf_ranking_alpha=0.5,
        ),
        aiplatform.matching_engine.matching_engine_index_endpoint.HybridQuery(
            dense_embedding=[1, 2, 3],
            sparse_embedding_dimensions=[10, 20, 30],
            sparse_embedding_values=[0.1, 0.2, 0.3],
        ),
        aiplatform.matching_engine.matching_engine_index_endpoint.HybridQuery(
            sparse_embedding_dimensions=[10, 20, 30],
            sparse_embedding_values=[0.1, 0.2, 0.3],
        ),
        aiplatform.matching_engine.matching_engine_index_endpoint.HybridQuery(
            dense_embedding=[1, 2, 3]
        ),
    ]

    hybrid_resp = my_index_endpoint.find_neighbors(
            deployed_index_id=deployed_index_id,
            queries=hybrid_queries,
            num_neighbors=num_neighbors,)
    print(hybrid_resp)

Curl

下記の publicEndpointDomainName は、デプロイにあります。形式は <number>.<region>-<number>.vdb.vertexai.goog です。


  $ curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer `gcloud auth print-access-token`" https://1957880287.us-central1-181224308459.vdb.vertexai.goog/v1/projects/181224308459/locations/us-central1/indexEndpoints/3370566089086861312:findNeighbors -d '{deployed_index_id: "test_index_public1", queries: [{datapoint: {datapoint_id: "0", feature_vector: [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]}, neighbor_count: 5}]}'
  

この curl の例は、http(s) クライアントから呼び出す方法を示していますが、パブリック エンドポイントは RESTful と grpc_cli のデュアル プロトコルをサポートしています。


  $ curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer `gcloud auth print-access-token`" https://1957880287.us-central1-181224308459.vdb.vertexai.goog/v1/projects/${PROJECT_ID}/locations/us-central1/indexEndpoints/${INDEX_ENDPOINT_ID}:readIndexDatapoints -d '{deployed_index_id:"test_index_public1", ids: ["606431", "896688"]}'
  

この curl の例は、トークンと数値の制限を使用してクエリを実行する方法を示しています。


  $ curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer `gcloud auth print-access-token`"  https://${PUBLIC_ENDPOINT_DOMAIN}/v1/projects/${PROJECT_ID}/locations/${LOCATION}/indexEndpoints/${INDEX_ENDPOINT_ID}:findNeighbors -d '{deployed_index_id:"${DEPLOYED_INDEX_ID}", queries: [{datapoint: {datapoint_id:"x", feature_vector: [1, 1], "sparse_embedding": {"values": [111.0,111.1,111.2], "dimensions": [10,20,30]}, numeric_restricts: [{namespace: "int-ns", value_int: -2, op: "GREATER"}, {namespace: "int-ns", value_int: 4, op: "LESS_EQUAL"}, {namespace: "int-ns", value_int: 0, op: "NOT_EQUAL"}], restricts: [{namespace: "color", allow_list: ["red"]}]}}]}'
  

コンソール

パブリック エンドポイントにデプロイされたインデックスをコンソールからクエリするには、次の手順を実施します。

  1. Google Cloud コンソールの [Vertex AI] セクションで、[デプロイと使用] セクションに移動します。[ベクトル検索] を選択します。

    [ベクトル検索] に移動

  2. クエリを実行するインデックスを選択します。[インデックスの情報] ページが開きます。
  3. [デプロイされたインデックス] セクションまで下にスクロールし、クエリを実行するデプロイされたインデックスを選択します。[デプロイされるインデックスの情報] ページが開きます。
  4. [インデックスのクエリ] セクションで、密エンベディング値、スパース エンベディング値、ハイブリッド エンベディング値(密エンベディングとスパース エンベディング)、または特定のデータポイントでクエリを実行するかどうかを選択します。
  5. 選択したクエリの種類に合わせてクエリ パラメータを入力します。たとえば、密エンベディングでクエリを実行する場合は、クエリするエンベディング ベクトルを入力します。
  6. 指定された curl コマンドを使用して、または Cloud Shell を使用して実行し、クエリを実行します。
  7. Cloud Shell を使用する場合は、[Cloud Shell で実行] を選択します。
  8. Cloud Shell で実行します。
  9. 結果として最近傍が返されます。

インデックスの作成方法、パブリック エンドポイントへのデプロイ方法、クエリの方法に関するエンドツーエンドの例については、公式ノートブックのStackOverflow 質問のテキストにベクトル検索と Vertex AI エンベディングを使用するをご覧ください。

パフォーマンスに影響するクエリ時間の設定

ベクトル検索を使用する場合、クエリ時のパラメータはレイテンシ、可用性、コストに影響する可能性があります。このガイダンスはほとんどのケースに適用されます。 ただし、必ず構成をテストして、ユースケースに適していることを確認してください。

パラメータの定義については、インデックス構成パラメータをご覧ください。

パラメータ 概要 パフォーマンスへの影響
approximateNeighborsCount

各シャードから取得するおおよその結果数をアルゴリズムに指定します。

approximateNeighborsCount の値は常に setNeighborsCount の値より大きくする必要があります。setNeighborsCount の値が小さい場合は、approximateNeighborsCount の値を 10 倍にすることをおすすめします。setNeighborsCount 値が大きい場合は、小さい乗数を使用できます。

approximateNeighborsCount の値を大きくすると、次のようにパフォーマンスに影響する可能性があります。

  • 再現率: 増加
  • レイテンシ: 増加する可能性がある
  • 可用性: 影響なし
  • 費用: 検索時に処理されるデータが増えるため、費用が増加する可能性がある

approximateNeighborsCount の値を小さくすると、次のようにパフォーマンスに影響する可能性があります。

  • 再現率: 減少
  • レイテンシ: 低下する可能性がある
  • 可用性: 影響なし
  • 費用: 検索時に処理されるデータが少ないため、費用が削減される
setNeighborCount クエリで返す結果の数を指定します。

300 以下の値は、ほとんどのユースケースでパフォーマンスを維持できます。値が大きい場合は、特定のユースケースでテストします。

fractionLeafNodesToSearch 最近傍を検索する際に参照するリーフノードの割合を制御します。これは、リーフノードあたりのエンベディングが多いほど、リーフあたりのデータが多く検査される leafNodeEmbeddingCount に関連しています。

fractionLeafNodesToSearch の値を大きくすると、次のようにパフォーマンスに影響する可能性があります。

  • 再現率: 増加
  • レイテンシ: 増加
  • 可用性: 影響なし
  • 費用: レイテンシが長くなると、マシンリソースの占有量が増えるため、費用が増加する可能性がある

fractionLeafNodesToSearch の値を小さくすると、次のようにパフォーマンスに影響する可能性があります。

  • 再現率: 減少
  • レイテンシ: 短縮
  • 可用性: 影響なし
  • 費用: レイテンシが短いほどマシンリソースを占有しなくなるため、費用が削減される

次のステップ