Esegui una query sull'indice pubblico per ottenere i vicini più vicini

Dopo aver creato e implementato l'indice, puoi eseguire query per ottenere i vicini più prossimi.

Ecco alcuni esempi di query di corrispondenza per trovare i primi vicini più prossimi utilizzando l'algoritmo k-Nearest Neighbors (k-NN).

Query di esempio per l'endpoint pubblico

Python

Per scoprire come installare o aggiornare l'SDK Vertex AI Python, consulta Installare l'SDK Vertex AI Python. Per saperne di più, consulta la documentazione di riferimento dell'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,
    )

Riga di comando

Il publicEndpointDomainName elencato di seguito è disponibile in Deploy ed è formattato come <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}]}'

Questo esempio di curl mostra come chiamare dai client http(s), anche se l'endpoint pubblico supporta il doppio protocollo per 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"]}'

Questo esempio di curl mostra come eseguire query con token e limiti numerici.


  $ 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

Segui queste istruzioni per eseguire query su un indice di cui è stato eseguito il deployment su un endpoint pubblico dalla console.

  1. Nella sezione Vertex AI della console Google Cloud , vai alla sezione Deployment e utilizzo. Seleziona Vector Search.

    Vai a Vector Search

  2. Seleziona l'indice su cui vuoi eseguire la query. Viene visualizzata la pagina Informazioni indice.
  3. Scorri verso il basso fino alla sezione Indici implementati e seleziona l'indice implementato per cui vuoi eseguire la query. Viene visualizzata la pagina Informazioni sull'indice di cui è stato eseguito il deployment.
  4. Nella sezione Indice query, seleziona se eseguire query in base a un valore di incorporamento denso, un valore di incorporamento sparso, un valore di incorporamento ibrido (incorporamenti densi e sparsi) o un punto dati specifico.
  5. Inserisci i parametri di ricerca per il tipo di query selezionato. Ad esempio, se esegui una query in base a un embedding denso, inserisci il vettore di embedding in base al quale eseguire la query.
  6. Esegui la query utilizzando il comando curl fornito o eseguendola con Cloud Shell.
  7. Se utilizzi Cloud Shell, seleziona Esegui in Cloud Shell.
  8. Esegui in Cloud Shell.
  9. I risultati restituiscono i vicini più prossimi.

Query ibride

La ricerca ibrida utilizza incorporamenti densi e sparsi per le ricerche basate su una combinazione di ricerca per parole chiave e ricerca semantica.

Python

Per scoprire come installare o aggiornare l'SDK Vertex AI Python, consulta Installare l'SDK Vertex AI Python. Per saperne di più, consulta la documentazione di riferimento dell'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,
    )

Query con filtri e affollamento

Il filtraggio delle corrispondenze vettoriali ti consente di limitare i risultati del vicino più prossimo a categorie specifiche. I filtri possono anche designare categorie da escludere dai risultati.

I limiti per vicino di crowding possono aumentare la diversità dei risultati limitando il numero di risultati restituiti da un singolo tag di crowding nei dati dell'indice.

Python

Per scoprire come installare o aggiornare l'SDK Vertex AI Python, consulta Installare l'SDK Vertex AI Python. Per saperne di più, consulta la documentazione di riferimento dell'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,
    )

Impostazioni in fase di query che influiscono sul rendimento

I seguenti parametri di query possono influire su latenza, disponibilità e costo quando utilizzi la ricerca vettoriale. Queste indicazioni si applicano alla maggior parte dei casi. Tuttavia, sperimenta sempre le tue configurazioni per assicurarti che funzionino per il tuo caso d'uso.

Per le definizioni dei parametri, vedi Parametri di configurazione dell'indice.

Parametro Informazioni Impatto sulle prestazioni
approximateNeighborsCount

Indica all'algoritmo il numero di risultati approssimativi da recuperare da ogni shard.

Il valore di approximateNeighborsCount deve essere sempre maggiore del valore di setNeighborsCount. Se il valore di setNeighborsCount è piccolo, per approximateNeighborsCount è consigliato un valore 10 volte superiore. Per valori di setNeighborsCount più grandi, è possibile utilizzare un moltiplicatore più piccolo.

Il nome dell'API REST corrispondente per questo campo è approximate_neighbor_count.

L'aumento del valore di approximateNeighborsCount può influire sulle prestazioni nei seguenti modi:

  • Richiamo: aumentato
  • Latenza: potenzialmente aumentata
  • Disponibilità: nessun impatto
  • Costo: può aumentare perché durante una ricerca vengono elaborati più dati

La riduzione del valore di approximateNeighborsCount può influire sul rendimento nei seguenti modi:

  • Richiamo: diminuito
  • Latenza: potenzialmente diminuisce
  • Disponibilità: nessun impatto
  • Costo: può diminuire perché durante una ricerca vengono elaborati meno dati
setNeighborCount

Specifica il numero di risultati che vuoi che la query restituisca.

Il nome dell'API REST corrispondente per questo campo è neighbor_count.

I valori inferiori o uguali a 300 rimangono efficienti nella maggior parte dei casi d'uso. Per valori più grandi, esegui il test per il tuo caso d'uso specifico.

fractionLeafNodesToSearch Controlla la percentuale di nodi foglia da visitare durante la ricerca dei vicini più prossimi. Questo è correlato a leafNodeEmbeddingCount in in quanto più incorporamenti per nodo foglia, più dati vengono esaminati per foglia.

Il nome dell'API REST corrispondente per questo campo è fraction_leaf_nodes_to_search_override.

Aumentare il valore di fractionLeafNodesToSearch può influire sul rendimento nei seguenti modi:

  • Richiamo: aumentato
  • Latenza: aumentata
  • Disponibilità: nessun impatto
  • Costo: può aumentare perché una latenza più elevata occupa più risorse della macchina

Diminuendo il valore di fractionLeafNodesToSearch, le prestazioni possono essere influenzate nei seguenti modi:

  • Richiamo: diminuito
  • Latenza: diminuita
  • Disponibilità: nessun impatto
  • Costo: può diminuire perché una latenza inferiore occupa meno risorse della macchina