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

Depois de criar e implementar o índice, pode executar consultas para obter os vizinhos mais próximos.

Seguem-se alguns exemplos de uma consulta de correspondência para encontrar os principais vizinhos mais próximos através do algoritmo dos k-vizinhos mais próximos (k-NN).

Exemplos de consultas para o ponto final público

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_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 comandos

Pode encontrar o publicEndpointDomainName indicado abaixo em Implementar 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 fazer chamadas a partir de clientes http(s), embora o ponto final público suporte o 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 token e restrições numéricas.


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

Consola

Siga estas instruções para consultar um índice implementado num ponto final público 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 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 se quer consultar por um valor de incorporação denso, um valor de incorporação esparso, um valor de incorporação híbrido (incorporações densas e esparsas) ou um ponto de dados específico.
  5. Introduza os parâmetros de consulta para o tipo de consulta que selecionou. Por exemplo, se estiver a consultar por uma incorporação densa, introduza o vetor de incorporação para consultar.
  6. Execute a consulta através do comando curl fornecido ou executando-a com a Cloud Shell.
  7. Se estiver a usar o Cloud Shell, selecione Executar no Cloud Shell.
  8. Executar no Cloud Shell.
  9. Os resultados devolvem os vizinhos mais próximos.

Consultas híbridas

A pesquisa híbrida usa incorporações densas e esparsas para pesquisas baseadas na combinação de pesquisa de palavras-chave e pesquisa semântica.

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_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 crowdsourcing

A filtragem de correspondências de vetores permite restringir os resultados do vizinho mais próximo a categorias específicas. Os filtros também podem designar categorias a excluir dos resultados.

Os limites de vizinhos por aglomeração podem aumentar a diversidade dos resultados limitando o número de resultados devolvidos de qualquer etiqueta de aglomeração nos seus dados de índice.

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_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,
    )

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