查询专用服务访问通道 (VPC 网络对等互连) 或 Private Service Connect 索引

部署 VPC 网络对等互连或 Private Service Connect 索引端点后,查询该端点的方式会因其部署方式而略有不同:

使用 Private Service Connect 自动化功能部署

对于使用 Private Service Connect 自动化功能部署的 IndexEndpoints,Python SDK 会自动将 Private Service Connect 网络映射到相应的端点。如果不使用 Python SDK,您必须按照查询 Private Service Connect 手动部署中的说明,直接连接到为端点创建的 IP 地址。

Python 版 Vertex AI SDK

如需了解如何安装或更新 Vertex AI SDK for Python,请参阅安装 Vertex AI SDK for Python。 如需了解详情,请参阅 Python 版 Vertex AI SDK 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 地址来访问您的端点。

如果您还不知道该 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 版 Vertex AI SDK

如需了解如何安装或更新 Vertex AI SDK for Python,请参阅安装 Vertex AI SDK for Python。 如需了解详情,请参阅 Python 版 Vertex AI SDK 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,..]}]}]'
  

必须从运行在与服务对等的同一 VPC 中的客户端调用这些 API。

如需使用 embedding_id 运行查询,请使用以下示例。

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

在此示例中,您使用 token 和数值限制发送查询。

./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 部分中,前往部署和使用部分。选择 Vector Search

    前往 Vector Search

  2. 选择要查询的 VPC 索引。此时会打开索引信息页面。
  3. 向下滚动到已部署的索引部分,然后选择要查询的已部署索引。此时会打开已部署的索引信息页面。
  4. 查询索引部分中,选择查询参数。您可以选择按向量或特定数据点进行查询。
  5. 使用开源工具 grpc_cli 或使用 Vertex AI SDK for Python 执行查询。

使用 VPC 网络对等互连部署

Python 版 Vertex AI SDK

如需了解如何安装或更新 Vertex AI SDK for Python,请参阅安装 Vertex AI SDK for Python。 如需了解详情,请参阅 Python 版 Vertex AI SDK API 参考文档

注意:Python SDK 会自动查找通过 VPC 网络对等互连部署的 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 列表中检索该 TARGET_IP

如需查询 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,..]}]}]'
  

必须从运行在与服务对等的同一 VPC 中的客户端调用这些 API。

如需使用 embedding_id 运行查询,请使用以下示例。

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

在此示例中,您使用 token 和数值限制发送查询。

./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 部分中,前往部署和使用部分。选择 Vector Search

    前往 Vector Search

  2. 选择要查询的 VPC 索引。此时会打开索引信息页面。
  3. 向下滚动到已部署的索引部分,然后选择要查询的已部署索引。此时会打开已部署的索引信息页面。
  4. 查询索引部分中,选择查询参数。您可以选择按向量或特定数据点进行查询。
  5. 使用开源工具 grpc_cli 或使用 Vertex AI SDK for Python 执行查询。

影响性能的查询时间设置

使用向量搜索时,以下查询时间参数可能会影响延迟时间、可用性和费用。本指南适用于大多数情况。但是,请始终对您的配置进行实验,以确保它们适用于您的应用场景。

如需了解参数定义,请参阅索引配置参数

参数 简介 性能影响
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 的值会对性能产生以下影响:

  • 召回率:降低
  • 延迟时间:缩短
  • 可用性:无影响
  • 费用:可能会降低,因为延迟时间较短会占用较少的机器资源

后续步骤