查询专用服务访问通道 (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 describe 和 gcloud 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，并调用 Match 或 BatchMatch 方法。此外，您还可以使用特定的嵌入 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，并调用 Match 或 BatchMatch 方法。此外，您还可以使用特定的嵌入 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 的值会对性能产生以下影响：

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

后续步骤