Consultar índices de acesso a serviços privados (intercâmbio da rede da VPC) ou do Private Service Connect

Depois de implementar um peering de rede VPC ou um ponto final do índice do Private Service Connect, a consulta difere ligeiramente consoante a forma como foi implementado:

Implementado com a automatização do Private Service Connect

Para IndexEndpoints implementações com a automatização do Private Service Connect, o SDK Python mapeia automaticamente a rede do Private Service Connect para o ponto final adequado. Se não usar o SDK Python, tem de se ligar diretamente ao endereço IP criado para o seu ponto final, seguindo as instruções para consultar uma implementação manual do Private Service Connect.

Python

Para saber como instalar ou atualizar o SDK Vertex AI para Python, consulte o artigo Instale o SDK Vertex AI para Python. Para mais informações, consulte a Python documentação de referência da 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

Implementado com a configuração manual do Private Service Connect

Para o Private Service Connect IndexEndpoints implementado com uma ligação configurada manualmente, o seu ponto final é acedido através do endereço IP do endereço de computação encaminhado para a associação do serviço do Private Service Connect do seu ponto final.

Se ainda não souber, pode obter o endereço IP encaminhado para o URI do anexo do serviço através dos comandos gcloud ai index-endpoints describe e gcloud compute forwarding-rules list.

Faça as seguintes substituições:

  • INDEX_ENDPOINT_ID: ID do ponto final do índice totalmente qualificado.
  • REGION: a região onde o seu ponto final do índice está implementado.
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}"

O resultado inclui o endereço IP interno a usar quando consultar o IndexEndpoint.

Python

Para saber como instalar ou atualizar o SDK Vertex AI para Python, consulte o artigo Instale o SDK Vertex AI para Python. Para mais informações, consulte a Python documentação de referência da 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

Linha de comandos

Para consultar um DeployedIndex, estabeleça ligação ao respetivo TARGET_IP na porta 10000 e chame o método Match ou BatchMatch. Além disso, pode fazer consultas com um ID de incorporação específico.

Os exemplos seguintes usam a ferramenta de código aberto grpc_cli para enviar pedidos gRPC para o servidor de índice implementado.

No primeiro exemplo, envia uma única consulta através do método Match. 

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

No segundo exemplo, combina duas consultas separadas no mesmo pedido 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,..]}]}]'

Tem de fazer chamadas para estas APIs a partir de um cliente em execução na mesma VPC com a qual o serviço foi intercâmbio.

Para executar uma consulta com um embedding_id, use o exemplo seguinte.

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

Neste exemplo, envia uma consulta com restrições numéricas e de tokens.

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

Para saber mais, consulte o artigo Explicação das bibliotecas de cliente.

Consola

Siga estas instruções para consultar um índice de VPC a partir da consola.

  1. Na secção do Vertex AI da Google Cloud consola, aceda à secção Implementar e usar. Selecione Vector Search

    Aceda a Vector Search

  2. Selecione o índice de VPC que quer consultar. É apresentada a página Informações do índice.
  3. Desloque a página para baixo até à secção Índices implementados e selecione o índice implementado que quer consultar. É apresentada a página Informações do índice implementado.
  4. Na secção Índice de consultas, selecione os parâmetros de consulta. Pode optar por consultar por um vetor ou um ponto de dados específico.
  5. Execute a consulta através da ferramenta de código aberto grpc_cli ou do SDK Vertex AI para Python.

Implementado com o intercâmbio da rede da VPC

Python

Para saber como instalar ou atualizar o SDK Vertex AI para Python, consulte o artigo Instale o SDK Vertex AI para Python. Para mais informações, consulte a Python documentação de referência da API.

Nota: o SDK Python procura automaticamente o endereço IP de um IndexEndpoint implementado com o peering de rede 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

Linha de comandos

Cada DeployedIndex tem um TARGET_IP, que pode obter na sua lista de IndexEndpoints.

Para consultar um DeployedIndex, estabeleça ligação ao respetivo TARGET_IP na porta 10000 e chame o método Match ou BatchMatch. Além disso, pode fazer consultas com um ID de incorporação específico.

Os exemplos seguintes usam a ferramenta de código aberto grpc_cli para enviar pedidos gRPC para o servidor de índice implementado.

No primeiro exemplo, envia uma única consulta através do método Match. 

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

No segundo exemplo, combina duas consultas separadas no mesmo pedido 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,..]}]}]'

Tem de fazer chamadas para estas APIs a partir de um cliente em execução na mesma VPC com a qual o serviço foi intercâmbio.

Para executar uma consulta com um embedding_id, use o exemplo seguinte.

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

Neste exemplo, envia uma consulta com restrições numéricas e de tokens.

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

Para saber mais, consulte o artigo Explicação das bibliotecas de cliente.

Consola

Siga estas instruções para consultar um índice de VPC a partir da consola.

  1. Na secção do Vertex AI da Google Cloud consola, aceda à secção Implementar e usar. Selecione Vector Search

    Aceda a Vector Search

  2. Selecione o índice de VPC que quer consultar. É apresentada a página Informações do índice.
  3. Desloque a página para baixo até à secção Índices implementados e selecione o índice implementado que quer consultar. É apresentada a página Informações do índice implementado.
  4. Na secção Índice de consultas, selecione os parâmetros de consulta. Pode optar por consultar por um vetor ou um ponto de dados específico.
  5. Execute a consulta através da ferramenta de código aberto grpc_cli ou do SDK Vertex AI para Python.

Definições de tempo de consulta que afetam o desempenho

Os seguintes parâmetros de tempo de consulta podem afetar a latência, a disponibilidade e o custo quando usa a pesquisa vetorial. Estas orientações aplicam-se à maioria dos casos. No entanto, experimente sempre as suas configurações para se certificar de que funcionam para o seu exemplo de utilização.

Para ver as definições dos parâmetros, consulte os parâmetros de configuração do índice.

Parâmetro Acerca de Impacto no desempenho
approximateNeighborsCount

Indica ao algoritmo o número de resultados aproximados a obter de cada fragmento.

O valor de approximateNeighborsCount deve ser sempre superior ao valor de setNeighborsCount. Se o valor de setNeighborsCount for pequeno, recomenda-se que approximateNeighborsCount seja 10 vezes esse valor. Para valores de setNeighborsCount maiores, pode usar um multiplicador mais pequeno.

O nome da API REST correspondente para este campo é approximate_neighbor_count.

Aumentar o valor de approximateNeighborsCount pode afetar o desempenho das seguintes formas:

  • Recordação: aumentada
  • Latência: potencialmente aumentada
  • Disponibilidade: nenhum impacto
  • Custo: pode aumentar porque são processados mais dados durante uma pesquisa

Diminuir o valor de approximateNeighborsCount pode afetar o desempenho das seguintes formas:

  • Recordação: diminuída
  • Latência: potencialmente diminui
  • Disponibilidade: nenhum impacto
  • Custo: pode diminuir o custo porque são processados menos dados durante uma pesquisa
setNeighborCount

Especifica o número de resultados que quer que a consulta devolva.

O nome da API REST correspondente para este campo é neighbor_count.

Os valores inferiores ou iguais a 300 mantêm o desempenho na maioria dos exemplos de utilização. Para valores maiores, teste o seu exemplo de utilização específico.

fractionLeafNodesToSearch Controla a percentagem de nós folha a visitar quando se procura os vizinhos mais próximos. Isto está relacionado com o leafNodeEmbeddingCount, uma vez que quanto mais incorporações por nó folha, mais dados são examinados por folha.

O nome da API REST correspondente para este campo é fraction_leaf_nodes_to_search_override.

Aumentar o valor de fractionLeafNodesToSearch pode afetar o desempenho das seguintes formas:

  • Recordação: aumentada
  • Latência: aumentada
  • Disponibilidade: nenhum impacto
  • Custo: pode aumentar porque a latência mais elevada ocupa mais recursos da máquina

Diminuir o valor de fractionLeafNodesToSearch pode afetar o desempenho das seguintes formas:

  • Recordação: diminuída
  • Latência: diminuída
  • Disponibilidade: nenhum impacto
  • Custo: pode diminuir porque a latência mais baixa ocupa menos recursos da máquina

O que se segue?