Consultar índices de Acesso a serviços particulares (peering de rede VPC) ou do Private Service Connect

Depois de implantar um endpoint de índice do Private Service Connect ou do peering de rede VPC, a consulta dele será um pouco diferente, dependendo de como ele foi implantado:

Implantado com a automação do Private Service Connect

Para IndexEndpoints implantado com a automação do Private Service Connect, o SDK do Python vai mapear automaticamente a rede do Private Service Connect para o endpoint apropriado. Se você não estiver usando o SDK Python, será necessário se conectar diretamente ao endereço IP criado para o endpoint, seguindo as instruções para consultar uma implantação manual do Private Service Connect.

Python

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

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

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

Para o Private Service Connect IndexEndpoints implantado com uma conexão configurada manualmente, o endpoint é acessado usando o endereço IP do endereço de computação encaminhado para o anexo de serviço do Private Service Connect do endpoint.

Se ainda não souber, é possível acessar o endereço IP encaminhado para o URI de anexo de serviço usando os comandos gcloud ai index-endpoints describe e gcloud compute forwarding-rules list.

Faça as seguintes substituições:

  • INDEX_ENDPOINT_ID: ID do endpoint de índice totalmente qualificado.
  • REGION: a região em que o endpoint do índice é implantado.
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}"

A saída vai incluir o endereço IP interno a ser usado ao consultar o IndexEndpoint.

Python

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

Linha de comando

Para consultar um DeployedIndex, conecte-se ao TARGET_IP na porta 10000 e chame o método Match ou BatchMatch. Além disso, é possível consultar usando um ID de embedding específico.

Os exemplos a seguir usam a ferramenta de código aberto grpc_cli para enviar solicitações gRPC ao servidor de índice implantado.

No primeiro exemplo, você envia uma única consulta usando o 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, você combina duas consultas separadas na mesma solicitação 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,..]}]}]'

Faça chamadas para essas APIs a partir de um cliente em execução na mesma [VPC em que o serviço fez peering](#vpc-network-peering-setup).

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

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

Neste exemplo, você envia uma consulta usando restrições de número e 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"]}]'

Para saber mais, consulte Explicações sobre bibliotecas de cliente.

Console

Use estas instruções para consultar um índice de VPC no console.

  1. Na seção Vertex AI do console do Google Cloud, acesse a seção Implantar e usar. Selecione Pesquisa de vetor

    Acessar a Vector Search

  2. Selecione o índice de VPC que você quer consultar. A página Informações do índice é aberta.
  3. Role para baixo até a seção Índices implantados e selecione o índice implantado que você quer consultar. A página Informações do índice implantado é aberta.
  4. Na seção Índice de consulta, selecione os parâmetros de consulta. A consulta pode ser feita por um vetor ou por um ponto de dados específico.
  5. Execute a consulta usando a ferramenta de código aberto grpc_cli ou o SDK da Vertex AI para Python.

Implantado com o peering de rede VPC

Python

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

Observação:o SDK do Python procura automaticamente o endereço IP de um IndexEndpoint implantado 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 comando

Cada DeployedIndex tem um TARGET_IP, que pode ser recuperado na lista de IndexEndpoints.

Para consultar um DeployedIndex, conecte-se ao TARGET_IP na porta 10000 e chame o método Match ou BatchMatch. Além disso, é possível consultar usando um ID de embedding específico.

Os exemplos a seguir usam a ferramenta de código aberto grpc_cli para enviar solicitações gRPC ao servidor de índice implantado.

No primeiro exemplo, você envia uma única consulta usando o 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, você combina duas consultas separadas na mesma solicitação 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,..]}]}]'

Faça chamadas para essas APIs a partir de um cliente em execução na mesma [VPC em que o serviço fez peering](#vpc-network-peering-setup).

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

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

Neste exemplo, você envia uma consulta usando restrições de número e 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"]}]'

Para saber mais, consulte Explicações sobre bibliotecas de cliente.

Console

Use estas instruções para consultar um índice de VPC no console.

  1. Na seção Vertex AI do console do Google Cloud, acesse a seção Implantar e usar. Selecione Pesquisa de vetor

    Acessar a Vector Search

  2. Selecione o índice de VPC que você quer consultar. A página Informações do índice é aberta.
  3. Role para baixo até a seção Índices implantados e selecione o índice implantado que você quer consultar. A página Informações do índice implantado é aberta.
  4. Na seção Índice de consulta, selecione os parâmetros de consulta. A consulta pode ser feita por um vetor ou por um ponto de dados específico.
  5. Execute a consulta usando a ferramenta de código aberto grpc_cli ou o SDK da Vertex AI para Python.

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

Os parâmetros de tempo de consulta a seguir podem afetar a latência, a disponibilidade e o custo ao usar a pesquisa de vetor. Essa orientação se aplica à maioria dos casos. No entanto, sempre teste as configurações para garantir que elas funcionem com seu caso de uso.

Para definições de parâmetro, consulte Parâmetros de configuração de índice.

Parâmetro Sobre Impacto no desempenho
approximateNeighborsCount

Informa ao algoritmo o número de resultados aproximados a serem recuperados de cada fragmento.

O valor de approximateNeighborsCount precisa ser sempre maior que o valor de setNeighborsCount. Se o valor de setNeighborsCount for pequeno, o recomendado para approximateNeighborsCount é 10 vezes. Para valores setNeighborsCount maiores, é possível usar um multiplicador menor.

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

  • Recall: aumento
  • Latência: potencialmente aumentada
  • Disponibilidade: sem impacto
  • Custo: pode aumentar porque mais dados são processados durante uma pesquisa

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

  • Recall: diminuído
  • Latência: diminui potencialmente
  • Disponibilidade: sem impacto
  • Custo: pode diminuir o custo porque menos dados são processados durante uma pesquisa
setNeighborCount Especifica o número de resultados que a consulta deve retornar.

Valores inferiores ou iguais a 300 mantêm o desempenho na maioria dos casos de uso. Para valores maiores, teste cada caso de uso específico.

fractionLeafNodesToSearch Controla a porcentagem de nós de folha a serem visitados ao pesquisar vizinhos mais próximos. Isso está relacionado a leafNodeEmbeddingCount, porque quanto mais embeddings por nó de folha, mais dados examinados por folha.

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

  • Recall: aumento
  • Latência: aumentada
  • Disponibilidade: sem impacto
  • Custo: pode aumentar porque uma latência maior ocupa mais recursos da máquina

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

  • Recall: diminuído
  • Latência: diminuída
  • Disponibilidade: sem impacto
  • Custo: pode diminuir porque a menor latência ocupa menos recursos da máquina

A seguir