查詢私人服務存取權 (VPC 網路對等互連) 或 Private Service Connect 索引

部署虛擬私有雲網路對等互連或 Private Service Connect 索引端點後,查詢方式會因部署方式而略有不同:

透過 Private Service Connect 自動化功能部署

如果是IndexEndpoints 透過 Private Service Connect 自動化功能部署,Python SDK 會自動將 Private Service Connect 網路對應至適當的端點。如果未使用 Python SDK,您必須直接連線至為端點建立的 IP 位址,並按照查詢 Private Service Connect 手動部署作業的操作說明進行。

Python

如要瞭解如何安裝或更新 Python 適用的 Vertex AI SDK,請參閱「安裝 Python 適用的 Vertex AI SDK」。 詳情請參閱 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

透過 Private Service Connect 手動設定部署

如果是透過手動設定的連線部署 Private Service Connect IndexEndpoints,系統會使用轉送至端點 Private Service Connect 服務連結的運算位址 IP 位址,存取您的端點。

如果不知道,可以使用 gcloud ai index-endpoints describegcloud compute forwarding-rules list 指令,取得轉送至服務附件 URI 的 IP 位址。

請將下列項目改為對應的值:

  • INDEX_ENDPOINT_ID:完整索引端點 ID。
  • REGION:部署索引端點的區域。
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}"

輸出內容會包含查詢 IndexEndpoint 時使用的內部 IP 位址。

Python

如要瞭解如何安裝或更新 Python 適用的 Vertex AI SDK,請參閱「安裝 Python 適用的 Vertex AI SDK」。 詳情請參閱 Python 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

指令列

如要查詢 DeployedIndex,請在連接埠 10000 連線至 TARGET_IP,然後呼叫 MatchBatchMatch 方法。此外,您也可以使用特定嵌入 ID 查詢。

下列範例使用開放原始碼工具 grpc_cli,將 gRPC 要求傳送至已部署的索引伺服器。

在第一個範例中,您使用 Match 方法傳送單一查詢。

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

在第二個範例中,您會將兩個獨立查詢合併到同一個 BatchMatch 要求中。

./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,..]}]}]'
  

您必須從與服務對等互連的虛擬私有雲中執行的用戶端呼叫這些 API。

如要使用 embedding_id 執行查詢,請參閱下列範例。

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

在本範例中,您會使用權杖和數字限制傳送查詢。

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

詳情請參閱「用戶端程式庫說明」。

控制台

請按照這些操作說明,從控制台查詢 VPC 索引。

  1. 在 Google Cloud 控制台的 Vertex AI 專區中,前往「Deploy and Use」(部署及使用) 專區。選取「Vector Search」

    前往 Vector Search

  2. 選取要查詢的 VPC 索引。「Index info」(索引資訊) 頁面隨即開啟。
  3. 向下捲動至「已部署的索引」部分,然後選取要查詢的已部署索引。「已部署的索引資訊」頁面隨即開啟。
  4. 在「查詢索引」部分中,選取查詢參數。您可以選擇依向量或特定資料點查詢。
  5. 使用開放原始碼工具 grpc_cli 或 Python 適用的 Vertex AI SDK 執行查詢。

透過虛擬私有雲網路對等互連部署

Python

如要瞭解如何安裝或更新 Python 適用的 Vertex AI SDK,請參閱「安裝 Python 適用的 Vertex AI SDK」。 詳情請參閱 Python API 參考說明文件

注意:Python SDK 會自動查閱透過虛擬私有雲網路對等互連部署的 IndexEndpoint IP 位址。

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

指令列

每個 DeployedIndex 都有 TARGET_IP,您可以在IndexEndpoints 清單中擷取。

如要查詢 DeployedIndex,請在連接埠 10000 連線至 TARGET_IP,然後呼叫 MatchBatchMatch 方法。此外,您也可以使用特定嵌入 ID 查詢。

下列範例使用開放原始碼工具 grpc_cli,將 gRPC 要求傳送至已部署的索引伺服器。

在第一個範例中,您使用 Match 方法傳送單一查詢。

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

在第二個範例中,您會將兩個獨立查詢合併到同一個 BatchMatch 要求中。

./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,..]}]}]'
  

您必須從與服務對等互連的虛擬私有雲中執行的用戶端呼叫這些 API。

如要使用 embedding_id 執行查詢,請參閱下列範例。

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

在本範例中,您會使用權杖和數字限制傳送查詢。

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

詳情請參閱「用戶端程式庫說明」。

控制台

請按照這些操作說明,從控制台查詢 VPC 索引。

  1. 在 Google Cloud 控制台的 Vertex AI 專區中,前往「Deploy and Use」(部署及使用) 專區。選取「Vector Search」

    前往 Vector Search

  2. 選取要查詢的 VPC 索引。「Index info」(索引資訊) 頁面隨即開啟。
  3. 向下捲動至「已部署的索引」部分,然後選取要查詢的已部署索引。「已部署的索引資訊」頁面隨即開啟。
  4. 在「查詢索引」部分中,選取查詢參數。您可以選擇依向量或特定資料點查詢。
  5. 使用開放原始碼工具 grpc_cli 或 Python 適用的 Vertex AI SDK 執行查詢。

影響成效的查詢時間設定

使用向量搜尋時,下列查詢時間參數可能會影響延遲時間、可用性和費用。這項指引適用於大多數情況。不過,請務必實驗各種設定,確保這些設定符合您的用途。

如需參數定義,請參閱「索引設定參數」。

參數 關於 效能影響
approximateNeighborsCount

告知演算法要從每個分片擷取的近似結果數量。

approximateNeighborsCount 的值一律應大於 setNeighborsCount 的值。如果 setNeighborsCount 的值很小,建議將 approximateNeighborsCount 設為該值的 10 倍。如果 setNeighborsCount 值較大,可以使用較小的乘數。

這個欄位對應的 REST API 名稱為 approximate_neighbor_count

增加 approximateNeighborsCount 的值可能會對效能造成以下影響:

  • 喚回度:提升
  • 延遲時間:可能增加
  • 可用性:沒有影響
  • 費用:可能會增加,因為搜尋期間處理的資料量較多

降低 approximateNeighborsCount 的值可能會對效能造成以下影響:

  • 喚回度:降低
  • 延遲:可能減少
  • 可用性:沒有影響
  • 成本:可減少搜尋期間處理的資料量,進而降低成本
setNeighborCount

指定查詢要傳回的結果數量。

這個欄位對應的 REST API 名稱為 neighbor_count

在大多數用途中,值小於或等於 300 仍可維持效能。 如為較大的值,請針對特定用途進行測試。

fractionLeafNodesToSearch 控管搜尋最近鄰時要造訪的分葉節點百分比。這與 leafNodeEmbeddingCount 相關,因為每個分葉節點的嵌入越多,每個分葉檢查的資料就越多。

這個欄位對應的 REST API 名稱為 fraction_leaf_nodes_to_search_override

增加 fractionLeafNodesToSearch 的值可能會對效能造成以下影響:

  • 喚回度:提升
  • 延遲時間:增加
  • 可用性:沒有影響
  • 費用:可能會增加,因為延遲時間越長,佔用的機器資源就越多

降低 fractionLeafNodesToSearch 的值可能會對效能造成以下影響:

  • 喚回度:降低
  • 延遲時間:縮短
  • 可用性:沒有影響
  • 費用:可降低,因為延遲時間越短,佔用的機器資源就越少

後續步驟