Halaman ini diterjemahkan oleh Cloud Translation API.

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

Setelah Anda men-deploy endpoint indeks Private Service Connect atau VPC Network Peering, kuerinya 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, dengan mengikuti petunjuk untuk mengajukan 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 Dokumentasi referensi Python 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 IndexEndpoints Private Service Connect 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 bisa mendapatkan 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 memenuhi syarat sepenuhnya.
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-nya akan menyertakan alamat IP internal yang akan digunakan saat membuat kueri IndexEndpoint.

Python

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 penyematan 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](#vpc-network-peering-setup).

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 token dan batasan 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.

Di bagian Vertex AI pada Konsol Google Cloud, buka bagian Deploy and Use. Pilih Cari Vektor
Buka Vector Search
Pilih indeks VPC yang ingin Anda buat kueri. Halaman Info indeks akan terbuka.
Scroll ke bawah ke bagian Indeks yang di-deploy, lalu pilih indeks yang di-deploy yang ingin Anda buat kuerinya. Halaman Info indeks yang di-deploy akan terbuka.
Dari bagian Indeks kueri, pilih parameter kueri Anda. Anda dapat memilih untuk membuat kueri berdasarkan vektor, atau titik data tertentu.
Jalankan kueri menggunakan alat open source grpc_cli, atau dengan menggunakan Vertex AI SDK untuk Python.

Di-deploy dengan Peering Jaringan VPC

Python

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 di 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 penyematan 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](#vpc-network-peering-setup).

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 token dan batasan 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.

Di bagian Vertex AI pada Konsol Google Cloud, buka bagian Deploy and Use. Pilih Cari Vektor
Buka Vector Search
Pilih indeks VPC yang ingin Anda buat kueri. Halaman Info indeks akan terbuka.
Scroll ke bawah ke bagian Indeks yang di-deploy, lalu pilih indeks yang di-deploy yang ingin Anda buat kuerinya. Halaman Info indeks yang di-deploy akan terbuka.
Dari bagian Indeks kueri, pilih parameter kueri Anda. Anda dapat memilih untuk membuat kueri berdasarkan vektor, atau titik data tertentu.
Jalankan kueri menggunakan alat open source grpc_cli, atau dengan menggunakan Vertex AI SDK untuk Python.

Setelan waktu kueri yang memengaruhi performa

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

Untuk definisi parameter, lihat Parameter konfigurasi indeks.

Parameter Tentang Dampak performa

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, 10 kali nilai tersebut direkomendasikan untuk `approximateNeighborsCount`. Untuk nilai `setNeighborsCount` yang lebih besar, pengganda yang lebih kecil dapat digunakan.	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 ingin ditampilkan oleh kueri.	Nilai kurang dari atau sama dengan 300 tetap berperforma baik dalam sebagian besar kasus penggunaan. Untuk nilai yang lebih besar, uji kasus penggunaan tertentu Anda.
`fractionLeafNodesToSearch`	Mengontrol persentase node daun yang akan dikunjungi saat menelusuri tetangga terdekat. Hal ini terkait dengan `leafNodeEmbeddingCount` karena semakin banyak penyematan per node daun, semakin banyak data yang diperiksa per daun.	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

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, 10 kali nilai tersebut direkomendasikan untuk approximateNeighborsCount. Untuk nilai setNeighborsCount yang lebih besar, pengganda yang lebih kecil dapat digunakan.

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 ingin ditampilkan oleh kueri.

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

fractionLeafNodesToSearch

Mengontrol persentase node daun yang akan dikunjungi saat menelusuri tetangga terdekat. Hal ini terkait dengan leafNodeEmbeddingCount karena semakin banyak penyematan per node daun, semakin banyak data yang diperiksa per daun.

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 selanjutnya

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