Eseguire query sull'indice pubblico per ottenere i vicini più prossimi

Dopo aver creato e sottoposto a deployment 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 Neighbor (k-NN).

Esempi di query 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 Esegui il deployment e ha il formato <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 i 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 restrizioni di token e numeriche.


  $ 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

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

  1. Nella sezione Piattaforma agente della Google Cloud console, vai a la sezione Esegui il deployment e utilizza. Seleziona Ricerca vettoriale.

    Vai a Ricerca vettoriale

  2. Seleziona l'indice su cui vuoi eseguire query. Viene visualizzata la pagina Informazioni sull'indice.
  3. Scorri verso il basso fino alla sezione Indici di cui è stato eseguito il deployment e seleziona l'indice di cui è stato eseguito il deployment su cui vuoi eseguire query. Viene visualizzata la pagina Informazioni sull'indice di cui è stato eseguito il deployment.
  4. Nella sezione Esegui query sull'indice , seleziona se eseguire query in base a un valore di embedding denso, un valore di embedding sparso, un valore di embedding ibrido (embedding densi e sparsi) o un punto dati specifico.
  5. Inserisci i parametri di ricerca per il tipo di query selezionato. Ad esempio, se esegui query in base a un embedding denso, inserisci il vettore di embedding su cui eseguire 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 embedding densi e sparsi per le ricerche basate sulla 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 dei vicini più prossimi a categorie specifiche. I filtri possono anche designare le categorie da escludere dai risultati.

I limiti dei vicini per affollamento possono aumentare la diversità dei risultati limitando il numero di risultati restituiti da un singolo tag di affollamento 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,
    )

Riga di comando

Il PUBLIC_ENDPOINT_DOMAIN elencato di seguito è disponibile nell' indice di cui è stato eseguito il deployment e ha il formato <number>.<region>-<number>.vdb.vertexai.goog.

Questo esempio di curl mostra come eseguire query con restrizioni di token e numeriche.


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

Impostazioni di query che influiscono sulle prestazioni

I seguenti parametri di query possono influire su latenza, disponibilità e costi quando si utilizza Vector Search. 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, consulta 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 di il valore di setNeighborsCount. Se il valore di setNeighborsCount è piccolo, per approximateNeighborsCount è consigliato un valore 10 volte superiore. Per valori 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 sulle prestazioni nei seguenti modi:

  • Richiamo: diminuito
  • Latenza: potenzialmente diminuita
  • 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 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 che più embedding per nodo foglia, più dati esaminati per foglia.

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

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

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

La riduzione del valore di fractionLeafNodesToSearch può influire sulle prestazioni nei seguenti modi:

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