Consultar o índice público para encontrar os vizinhos mais próximos

Depois de criar e implantar o índice, é possível executar consultas para encontrar os vizinhos mais próximos.

Veja alguns exemplos de uma consulta de correspondência para encontrar os próximos vizinhos mais próximos usando o algoritmo de vizinhos k-mais próximo (k-NN).

Exemplos de consultas para o endpoint público

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_find_neighbors(
    project: str,
    location: str,
    index_endpoint_name: str,
    deployed_index_id: str,
    queries: List[List[float]],
    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.
        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.

    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 the nearest neighbors.
    return my_index_endpoint.find_neighbors(
        deployed_index_id=deployed_index_id,
        queries=queries,
        num_neighbors=num_neighbors,
    )

Linha de comando

O publicEndpointDomainName listado abaixo pode ser encontrado em Implantar e está formatado como <number>.<region>-<number>.vdb.vertexai.goog. 


  $ curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer `gcloud auth print-access-token`" https://1957880287.us-central1-181224308459.vdb.vertexai.goog/v1/projects/181224308459/locations/us-central1/indexEndpoints/3370566089086861312:findNeighbors -d '{deployed_index_id: "test_index_public1", queries: [{datapoint: {datapoint_id: "0", feature_vector: [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]}, neighbor_count: 5}]}'

Este exemplo de curl demonstra como realizar chamadas de clientes http(s), embora o endpoint público dê suporte ao protocolo duplo para RESTful e grpc_cli. 


  $ curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer `gcloud auth print-access-token`" https://1957880287.us-central1-181224308459.vdb.vertexai.goog/v1/projects/${PROJECT_ID}/locations/us-central1/indexEndpoints/${INDEX_ENDPOINT_ID}:readIndexDatapoints -d '{deployed_index_id:"test_index_public1", ids: ["606431", "896688"]}'

Este exemplo de curl demonstra como consultar com restrições de número e token.


  $ curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer `gcloud auth print-access-token`"  https://${PUBLIC_ENDPOINT_DOMAIN}/v1/projects/${PROJECT_ID}/locations/${LOCATION}/indexEndpoints/${INDEX_ENDPOINT_ID}:findNeighbors -d '{deployed_index_id:"${DEPLOYED_INDEX_ID}", queries: [{datapoint: {datapoint_id:"x", feature_vector: [1, 1], "sparse_embedding": {"values": [111.0,111.1,111.2], "dimensions": [10,20,30]}, numeric_restricts: [{namespace: "int-ns", value_int: -2, op: "GREATER"}, {namespace: "int-ns", value_int: 4, op: "LESS_EQUAL"}, {namespace: "int-ns", value_int: 0, op: "NOT_EQUAL"}], restricts: [{namespace: "color", allow_list: ["red"]}]}}]}'

Console

Use estas instruções para consultar um índice implantado em um endpoint público pelo console.

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

    Acessar a Vector Search

  2. Selecione o índice 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 se você quer consultar por um valor de incorporação densa, esparsa, híbrida (incorporações densas e esparsas) ou um ponto de dados específico.
  5. Insira os parâmetros de consulta para o tipo de consulta selecionado. Por exemplo, se você estiver consultando por um embedding denso, insira o vetor de embedding para consultar.
  6. Execute a consulta com o comando curl fornecido ou com o Cloud Shell.
  7. Se for usar o Cloud Shell, selecione Executar no Cloud Shell.
  8. Executar no Cloud Shell
  9. Os resultados retornam os vizinhos mais próximos.

Consultas híbridas

A pesquisa híbrida usa embeddings densos e esparsos para pesquisas baseadas em uma combinação de pesquisa por palavra-chave e pesquisa semântica.

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_find_neighbors_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 using example hybrid queries.

    Args:
        project (str): Required. Project ID
        location (str): Required. The region name
        index_endpoint_name (str): Required. Index endpoint to run the query
        against.
        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
    )

    # Query 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]
        ),
    ]

    return my_index_endpoint.find_neighbors(
        deployed_index_id=deployed_index_id,
        queries=hybrid_queries,
        num_neighbors=num_neighbors,
    )

Consultas com filtragem e recolhimento

Com a filtragem de correspondências de vetores, é possível restringir os resultados de vizinho mais próximo a categorias específicas. Os filtros também podem designar categorias a serem excluídas dos resultados.

Limites de vizinhos por recolhimento podem aumentar a diversidade de resultados ao limitar o número de resultados retornados de qualquer tag de recolhimento nos dados do índice.

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_find_neighbors_filtering_crowding(
    project: str,
    location: str,
    index_endpoint_name: str,
    deployed_index_id: str,
    queries: List[List[float]],
    num_neighbors: int,
    filter: List[aiplatform.matching_engine.matching_engine_index_endpoint.Namespace],
    numeric_filter: List[
        aiplatform.matching_engine.matching_engine_index_endpoint.NumericNamespace
    ],
    per_crowding_attribute_neighbor_count: int,
) -> List[
    List[aiplatform.matching_engine.matching_engine_index_endpoint.MatchNeighbor]
]:
    """Query the vector search index with filtering and crowding.

    Args:
        project (str): Required. Project ID
        location (str): Required. The region name
        index_endpoint_name (str): Required. Index endpoint to run the query
        against.
        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.
        filter (List[Namespace]): Required. A list of Namespaces for filtering
        the matching results. For example,
        [Namespace("color", ["red"], []), Namespace("shape", [], ["square"])]
        will match datapoints that satisfy "red color" but not include
        datapoints with "square shape".
        numeric_filter (List[NumericNamespace]): Required. A list of
        NumericNamespaces for filtering the matching results. For example,
        [NumericNamespace(name="cost", value_int=5, op="GREATER")] will limit
        the matching results to datapoints with cost greater than 5.
        per_crowding_attribute_neighbor_count (int): Required. The maximum
        number of returned matches with the same crowding tag.

    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 the nearest neighbors.
    return my_index_endpoint.find_neighbors(
        deployed_index_id=deployed_index_id,
        queries=queries,
        num_neighbors=num_neighbors,
        filter=filter,
        numeric_filter=numeric_filter,
        per_crowding_attribute_neighbor_count=per_crowding_attribute_neighbor_count,
    )

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.

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

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.

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

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.

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

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