Membuat kueri indeks publik untuk mendapatkan tetangga terdekat

Setelah membuat dan men-deploy indeks, Anda dapat menjalankan kueri untuk mendapatkan tetangga terdekat.

Berikut adalah beberapa contoh kueri pencocokan untuk menemukan tetangga terdekat teratas menggunakan algoritma k-nearest neighbors (k-NN).

Contoh kueri untuk endpoint publik

Python

Untuk mempelajari cara menginstal atau mengupdate Vertex AI SDK untuk Python, lihat Menginstal Vertex AI SDK untuk Python. Untuk mengetahui informasi selengkapnya, lihat Python dokumentasi referensi API. 

def vector_search_find_neighbors(
    project: str,
    location: str,
    index_endpoint_name: str,
    deployed_index_id: str,
    queries: List[List[float]],
    num_neighbors: int,
) -> List[
    List[aiplatform.matching_engine.matching_engine_index_endpoint.MatchNeighbor]
]:
    """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.

    Returns:
        List[List[aiplatform.matching_engine.matching_engine_index_endpoint.MatchNeighbor]] - A list of nearest neighbors for each query.
    """
    # 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.
    return my_index_endpoint.find_neighbors(
        deployed_index_id=deployed_index_id,
        queries=queries,
        num_neighbors=num_neighbors,
    )

Command-line

Yang publicEndpointDomainName tercantum di bawah dapat ditemukan di Deploy dan diformat sebagai <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}]}'

Contoh curl ini menunjukkan cara melakukan panggilan dari http(s) klien, meskipun endpoint publik mendukung protokol ganda untuk aktivitas RESTful dan 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"]}'

Contoh curl ini menunjukkan cara membuat kueri dengan pembatasan token dan numerik.


  $ 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"]}]}}]}'

Konsol

Gunakan petunjuk ini untuk membuat kueri indeks yang di-deploy ke endpoint publik dari konsol.

  1. Di bagian Platform Agen pada Google Cloud konsol, buka bagian Deploy dan Gunakan. Pilih Vector Search.

    Buka Cari Vektor

  2. Pilih indeks yang ingin Anda kueri. Halaman Info indeks akan terbuka.
  3. Scroll ke bawah ke bagian Indeks yang di-deploy , lalu pilih indeks yang di-deploy yang ingin Anda kueri. Halaman Info indeks yang di-deploy akan terbuka.
  4. Dari bagian Kueri indeks, pilih apakah akan membuat kueri berdasarkan nilai embedding padat, nilai embedding jarang, nilai embedding hybrid (embedding padat dan jarang), atau titik data tertentu.
  5. Masukkan parameter kueri untuk jenis kueri yang Anda pilih. Misalnya, jika Anda membuat kueri berdasarkan embedding padat, masukkan vektor embedding untuk membuat kueri.
  6. Jalankan kueri menggunakan perintah curl yang disediakan, atau dengan menjalankan Cloud Shell.
  7. Jika menggunakan Cloud Shell, pilih Jalankan di Cloud Shell.
  8. Jalankan di Cloud Shell.
  9. Hasilnya akan menampilkan tetangga terdekat.

Kueri hybrid

Penelusuran hybrid menggunakan embedding padat dan jarang untuk penelusuran berdasarkan kombinasi penelusuran kata kunci dan penelusuran semantik.

Python

Untuk mempelajari cara menginstal atau mengupdate Vertex AI SDK untuk Python, lihat Menginstal Vertex AI SDK untuk Python. Untuk mengetahui informasi selengkapnya, lihat Python dokumentasi referensi API. 

def vector_search_find_neighbors_hybrid_queries(
    project: str,
    location: str,
    index_endpoint_name: str,
    deployed_index_id: str,
    num_neighbors: int,
) -> List[
    List[aiplatform.matching_engine.matching_engine_index_endpoint.MatchNeighbor]
]:
    """Query the vector search index using example hybrid queries.

    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.
        num_neighbors (int): Required. The number of neighbors to return.

    Returns:
        List[List[aiplatform.matching_engine.matching_engine_index_endpoint.MatchNeighbor]] - A list of nearest neighbors for each query.
    """
    # 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 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]
        ),
    ]

    return my_index_endpoint.find_neighbors(
        deployed_index_id=deployed_index_id,
        queries=hybrid_queries,
        num_neighbors=num_neighbors,
    )

Kueri dengan pemfilteran dan pengelompokan

Memfilter kecocokan vektor memungkinkan Anda membatasi hasil tetangga terdekat ke kategori tertentu. Filter juga dapat menetapkan kategori yang akan dikecualikan dari hasil Anda.

Batas tetangga per pengelompokan dapat meningkatkan keragaman hasil dengan membatasi jumlah hasil yang ditampilkan dari satu tag pengelompokan dalam data indeks Anda.

Python

Untuk mempelajari cara menginstal atau mengupdate Vertex AI SDK untuk Python, lihat Menginstal Vertex AI SDK untuk Python. Untuk mengetahui informasi selengkapnya, lihat Python dokumentasi referensi API. 

def vector_search_find_neighbors_filtering_crowding(
    project: str,
    location: str,
    index_endpoint_name: str,
    deployed_index_id: str,
    queries: List[List[float]],
    num_neighbors: int,
    filter: List[aiplatform.matching_engine.matching_engine_index_endpoint.Namespace],
    numeric_filter: List[
        aiplatform.matching_engine.matching_engine_index_endpoint.NumericNamespace
    ],
    per_crowding_attribute_neighbor_count: int,
) -> List[
    List[aiplatform.matching_engine.matching_engine_index_endpoint.MatchNeighbor]
]:
    """Query the vector search index with filtering and crowding.

    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.
        filter (List[Namespace]): Required. A list of Namespaces for filtering
        the matching results. For example,
        [Namespace("color", ["red"], []), Namespace("shape", [], ["square"])]
        will match datapoints that satisfy "red color" but not include
        datapoints with "square shape".
        numeric_filter (List[NumericNamespace]): Required. A list of
        NumericNamespaces for filtering the matching results. For example,
        [NumericNamespace(name="cost", value_int=5, op="GREATER")] will limit
        the matching results to datapoints with cost greater than 5.
        per_crowding_attribute_neighbor_count (int): Required. The maximum
        number of returned matches with the same crowding tag.

    Returns:
        List[List[aiplatform.matching_engine.matching_engine_index_endpoint.MatchNeighbor]] - A list of nearest neighbors for each query.
    """
    # 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.
    return my_index_endpoint.find_neighbors(
        deployed_index_id=deployed_index_id,
        queries=queries,
        num_neighbors=num_neighbors,
        filter=filter,
        numeric_filter=numeric_filter,
        per_crowding_attribute_neighbor_count=per_crowding_attribute_neighbor_count,
    )

Command-line

Yang PUBLIC_ENDPOINT_DOMAIN tercantum di bawah dapat ditemukan di indeks yang di-deploy dan diformat sebagai <number>.<region>-<number>.vdb.vertexai.goog.

Contoh curl ini menunjukkan cara membuat kueri dengan pembatasan token dan numerik.


  $ 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"]}]}}]}'

Setelan waktu kueri yang memengaruhi performa

Parameter waktu kueri berikut dapat memengaruhi latensi, ketersediaan, dan biaya saat menggunakan Vector Search. Panduan ini berlaku untuk sebagian besar kasus. Namun, selalu lakukan eksperimen dengan konfigurasi Anda untuk memastikan konfigurasi tersebut berfungsi untuk kasus penggunaan Anda.

Untuk mengetahui definisi parameter, lihat Parameter konfigurasi indeks.

Parameter Tentang Dampak performa
approximateNeighborsCount

Memberi tahu algoritma jumlah perkiraan hasil yang akan diambil dari setiap shard.

Nilai approximateNeighborsCount harus selalu lebih besar dari nilai setNeighborsCount. Jika nilai setNeighborsCount kecil, sebaiknya gunakan 10 kali nilai tersebut untuk approximateNeighborsCount. Untuk nilai setNeighborsCount yang lebih besar, pengganda yang lebih kecil dapat digunakan.

Nama REST API yang sesuai untuk kolom ini adalah approximate_neighbor_count.

Meningkatkan nilai approximateNeighborsCount dapat memengaruhi performa dengan cara berikut:

  • Recall: Meningkat
  • Latensi: Berpotensi meningkat
  • Ketersediaan: Tidak ada dampak
  • Biaya: Dapat meningkat karena lebih banyak data yang diproses selama penelusuran

Menurunkan nilai approximateNeighborsCount dapat memengaruhi performa dengan cara berikut:

  • Recall: Menurun
  • Latensi: Berpotensi menurun
  • Ketersediaan: Tidak ada dampak
  • Biaya: Dapat mengurangi biaya karena lebih sedikit data yang diproses selama penelusuran
setNeighborCount

Menentukan jumlah hasil yang Anda inginkan untuk ditampilkan oleh kueri.

Nama REST API yang sesuai untuk kolom ini adalah neighbor_count.

Nilai yang kurang dari atau sama dengan 300 tetap berperforma baik di sebagian besar kasus penggunaan. Untuk nilai yang lebih besar, uji untuk kasus penggunaan tertentu.

fractionLeafNodesToSearch Mengontrol persentase node daun yang akan dikunjungi saat menelusuri tetangga terdekat. Hal ini terkait dengan leafNodeEmbeddingCount di bahwa semakin banyak embedding per node daun, semakin banyak data yang diperiksa per daun.

Nama REST API yang sesuai untuk kolom ini adalah fraction_leaf_nodes_to_search_override.

Meningkatkan nilai fractionLeafNodesToSearch dapat memengaruhi performa dengan cara berikut:

  • Recall: Meningkat
  • Latensi: Meningkat
  • Ketersediaan: Tidak ada dampak
  • Biaya: Dapat meningkat karena latensi yang lebih tinggi menggunakan lebih banyak resource mesin

Menurunkan nilai fractionLeafNodesToSearch dapat memengaruhi performa dengan cara berikut:

  • Recall: Menurun
  • Latensi: Menurun
  • Ketersediaan: Tidak ada dampak
  • Biaya: Dapat menurun karena latensi yang lebih rendah menggunakan lebih sedikit resource mesin