Membuat kueri indeks Akses Layanan Pribadi (Peering Jaringan VPC) atau Private Service Connect

Setelah Anda men-deploy endpoint indeks Private Service Connect atau Peering Jaringan VPC, kueri akan sedikit berbeda, bergantung pada cara deployment-nya:

• Otomatisasi Private Service Connect
• Konfigurasi manual Private Service Connect
• Peering Jaringan VPC

Di-deploy dengan otomatisasi Private Service Connect

Untuk IndexEndpoints yang di-deploy dengan otomatisasi Private Service Connect, Python SDK akan otomatis memetakan jaringan Private Service Connect ke endpoint yang sesuai. Jika tidak menggunakan Python SDK, Anda harus terhubung langsung ke alamat IP yang dibuat untuk endpoint Anda, dengan mengikuti petunjuk untuk membuat kueri deployment manual Private Service Connect.

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_match_psc_automation(
    project: str,
    location: str,
    index_endpoint_name: str,
    deployed_index_id: str,
    queries: List[List[float]],
    num_neighbors: int,
    psc_network: str,
) -> List[List[aiplatform.matching_engine.matching_engine_index_endpoint.MatchNeighbor]]:
    """Query the vector search index deployed with PSC automation.

    Args:
        project (str): Required. Project ID
        location (str): Required. The region name
        index_endpoint_name (str): Required. Index endpoint to run the query
        against. The endpoint must be a private endpoint.
        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.
        ip_address (str): Required. The IP address of the PSC endpoint. Obtained
        from the created compute address used in the fordwarding rule to the
        endpoint's service attachment.
        psc_network (str): The network the endpoint was deployed to via PSC
        automation configuration. The format is
        projects/{project_id}/global/networks/{network_name}.

    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 matches.
    resp = my_index_endpoint.match(
        deployed_index_id=deployed_index_id,
        queries=queries,
        num_neighbors=num_neighbors,
        psc_network=psc_network
    )
    return resp

Di-deploy dengan konfigurasi manual Private Service Connect

Untuk Private Service Connect IndexEndpoints yang di-deploy dengan koneksi yang dikonfigurasi secara manual, endpoint Anda diakses menggunakan alamat IP alamat komputasi yang diteruskan ke lampiran layanan Private Service Connect endpoint Anda.

Jika belum diketahui, Anda dapat memperoleh alamat IP yang diteruskan ke URI lampiran layanan menggunakan perintah gcloud ai index-endpoints describe dan gcloud compute forwarding-rules list.

Lakukan penggantian berikut:

• INDEX_ENDPOINT_ID: ID endpoint indeks yang sepenuhnya memenuhi syarat.
• REGION: Region tempat endpoint indeks Anda di-deploy.

SERVICE_ATTACHMENT_URI=`gcloud ai index-endpoints describe INDEX_ENDPOINT_ID \
  --region=REGION \
  --format="value(deployedIndexes.privateEndpoints.serviceAttachment)"`

gcloud compute forwarding-rules list --filter="TARGET:${SERVICE_ATTACHMENT_URI}"

Output akan menyertakan alamat IP internal yang akan digunakan saat membuat kueri IndexEndpoint.

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_match_psc_manual(
    project: str,
    location: str,
    index_endpoint_name: str,
    deployed_index_id: str,
    queries: List[List[float]],
    num_neighbors: int,
    ip_address: str,
) -> List[List[aiplatform.matching_engine.matching_engine_index_endpoint.MatchNeighbor]]:
    """Query the vector search index deployed with PSC manual configuration.

    Args:
        project (str): Required. Project ID
        location (str): Required. The region name
        index_endpoint_name (str): Required. Index endpoint to run the query
        against. The endpoint must be a private endpoint.
        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.
        ip_address (str): Required. The IP address of the PSC endpoint. Obtained
        from the created compute address used in the forwarding rule to the
        endpoint's service attachment.

    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
    )

    # Set the IP address of the PSC endpoint.
    my_index_endpoint.private_service_connect_ip_address = ip_address

    # Query the index endpoint for matches.
    resp = my_index_endpoint.match(
        deployed_index_id=deployed_index_id,
        queries=queries,
        num_neighbors=num_neighbors
    )
    return resp

Command-line

Untuk membuat kueri DeployedIndex, hubungkan ke TARGET_IP di port 10000 dan panggil metode Match atau BatchMatch. Selain itu, Anda dapat membuat kueri menggunakan ID embedding tertentu.

Contoh berikut menggunakan alat open source grpc_cli untuk mengirim permintaan gRPC ke server indeks yang di-deploy.

Pada contoh pertama, Anda mengirim satu kueri menggunakan metode Match.

./grpc_cli call ${TARGET_IP}:10000 google.cloud.aiplatform.container.v1.MatchService.Match 'deployed_index_id: "${DEPLOYED_INDEX_ID}", float_val: [-0.1,..]'
  

Pada contoh kedua, Anda menggabungkan dua kueri terpisah ke dalam permintaan BatchMatch yang sama.

./grpc_cli call ${TARGET_IP}:10000 google.cloud.aiplatform.container.v1.MatchService.BatchMatch 'requests: [{deployed_index_id: "${DEPLOYED_INDEX_ID}", requests: [{deployed_index_id: "${DEPLOYED_INDEX_ID}", float_val: [-0.1,..]}, {deployed_index_id: "${DEPLOYED_INDEX_ID}", float_val: [-0.2,..]}]}]'
  

Anda harus melakukan panggilan ke API ini dari klien yang berjalan di VPC yang sama dengan yang di-peering dengan layanan.

Untuk menjalankan kueri menggunakan embedding_id, gunakan contoh berikut.

./grpc_cli call ${TARGET_IP}:10000  google.cloud.aiplatform.container.v1.MatchService.Match "deployed_index_id:'"test_index1"',embedding_id: '"606431"'"

Dalam contoh ini, Anda mengirim kueri menggunakan batasan token dan numerik.

./grpc_cli call ${TARGET_IP}:10000 google.cloud.aiplatform.container.v1.MatchService.Match 'deployed_index_id: "${DEPLOYED_INDEX_ID}", float_val: [1, 1], "sparse_embedding": {"values": [111.0,111.1,111.2], "dimensions": [10,20,30]}, numeric_restricts: [{name: "double-ns", value_double: 0.3, op: LESS_EQUAL}, {name: "double-ns", value_double: -1.2, op: GREATER}, {name: "double-ns", value_double: 0., op: NOT_EQUAL}], restricts: [{name: "color", allow_tokens: ["red"]}]'

Untuk mempelajari lebih lanjut, lihat Penjelasan library klien.

Konsol

Gunakan petunjuk ini untuk membuat kueri indeks VPC 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 VPC 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 parameter kueri Anda. Anda dapat memilih untuk membuat kueri berdasarkan vektor, atau titik data tertentu.
5. Jalankan kueri menggunakan alat open source grpc_cli, atau menggunakan Agent Platform SDK untuk Python.

Di-deploy dengan Peering Jaringan VPC

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.

Catatan: Python SDK otomatis mencari alamat IP untuk IndexEndpoint yang di-deploy dengan Peering Jaringan VPC.

def vector_search_match_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.

    Args:
        project (str): Required. Project ID
        location (str): Required. The region name
        index_endpoint_name (str): Required. Index endpoint to run the query
        against. The endpoint must be a private endpoint.
        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
    )

    # Example queries containing 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]
        ),
    ]

    # Query the index endpoint for matches.
    resp = my_index_endpoint.match(
        deployed_index_id=deployed_index_id,
        queries=hybrid_queries,
        num_neighbors=num_neighbors,
    )
    return resp

Command-line

Setiap DeployedIndex memiliki TARGET_IP, yang dapat Anda ambil dalam daftar IndexEndpoints.

Untuk membuat kueri DeployedIndex, hubungkan ke TARGET_IP di port 10000 dan panggil metode Match atau BatchMatch. Selain itu, Anda dapat membuat kueri menggunakan ID embedding tertentu.

Contoh berikut menggunakan alat open source grpc_cli untuk mengirim permintaan gRPC ke server indeks yang di-deploy.

Pada contoh pertama, Anda mengirim satu kueri menggunakan metode Match.

./grpc_cli call ${TARGET_IP}:10000 google.cloud.aiplatform.container.v1.MatchService.Match 'deployed_index_id: "${DEPLOYED_INDEX_ID}", float_val: [-0.1,..]'
  

Pada contoh kedua, Anda menggabungkan dua kueri terpisah ke dalam permintaan BatchMatch yang sama.

./grpc_cli call ${TARGET_IP}:10000 google.cloud.aiplatform.container.v1.MatchService.BatchMatch 'requests: [{deployed_index_id: "${DEPLOYED_INDEX_ID}", requests: [{deployed_index_id: "${DEPLOYED_INDEX_ID}", float_val: [-0.1,..]}, {deployed_index_id: "${DEPLOYED_INDEX_ID}", float_val: [-0.2,..]}]}]'
  

Anda harus melakukan panggilan ke API ini dari klien yang berjalan di VPC yang sama dengan yang di-peering dengan layanan.

Untuk menjalankan kueri menggunakan embedding_id, gunakan contoh berikut.

./grpc_cli call ${TARGET_IP}:10000  google.cloud.aiplatform.container.v1.MatchService.Match "deployed_index_id:'"test_index1"',embedding_id: '"606431"'"

Dalam contoh ini, Anda mengirim kueri menggunakan batasan token dan numerik.

./grpc_cli call ${TARGET_IP}:10000 google.cloud.aiplatform.container.v1.MatchService.Match 'deployed_index_id: "${DEPLOYED_INDEX_ID}", float_val: [1, 1], "sparse_embedding": {"values": [111.0,111.1,111.2], "dimensions": [10,20,30]}, numeric_restricts: [{name: "double-ns", value_double: 0.3, op: LESS_EQUAL}, {name: "double-ns", value_double: -1.2, op: GREATER}, {name: "double-ns", value_double: 0., op: NOT_EQUAL}], restricts: [{name: "color", allow_tokens: ["red"]}]'

Untuk mempelajari lebih lanjut, lihat Penjelasan library klien.

Konsol

Gunakan petunjuk ini untuk membuat kueri indeks VPC 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 VPC 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 parameter kueri Anda. Anda dapat memilih untuk membuat kueri berdasarkan vektor, atau titik data tertentu.
5. Jalankan kueri menggunakan alat open source grpc_cli, atau menggunakan Agent Platform SDK untuk Python.

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 definisi parameter, lihat Parameter konfigurasi indeks.

Parameter	Tentang	Dampak performa
approximateNeighborsCount	Memberi tahu algoritma jumlah hasil perkiraan 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 Anda.
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

Langkah berikutnya

• Pelajari cara Mengupdate dan membuat kembali indeks
• Pelajari cara Memfilter pencocokan vektor
• Pelajari cara Memantau indeks