Interroger un index public pour obtenir les voisins les plus proches

Une fois que vous avez créé et déployé l'index, vous pouvez exécuter des requêtes pour obtenir les voisins les plus proches.

Voici des exemples de requête de correspondance visant à identifier les voisins les plus proches à l'aide de l'algorithme des k plus proches voisins (k-NN).

Exemples de requêtes pour un point de terminaison public

Python

Pour savoir comment installer ou mettre à jour le SDK Vertex AI pour Python, consultez la section Installer le SDK Vertex AI pour Python. Pour en savoir plus, consultez la documentation de référence de l'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,
    )

Ligne de commande

Le publicEndpointDomainName listé ci-dessous est disponible dans Déployer et est au format <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}]}'
  

Cet exemple curl montre comment appeler à partir de clients http(s), bien que le point de terminaison public soit compatible avec le double protocole pour RESTful et 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"]}'
  

Cet exemple curl montre comment effectuer des requêtes avec restrictions de jeton et restrictions numériques.


  $ 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

Suivez ces instructions pour interroger un index déployé sur un point de terminaison public depuis la console.

  1. Dans la section "Vertex AI" de la console Google Cloud , accédez à la section Déployer et utiliser. Sélectionnez Recherche vectorielle.

    Accéder à "Recherche vectorielle"

  2. Sélectionnez l'index que vous souhaitez interroger. La page Informations sur l'index s'ouvre.
  3. Faites défiler la page jusqu'à la section Index déployés et sélectionnez celui que vous souhaitez interroger. La page Informations sur l'index déployé s'ouvre.
  4. Dans la section Interroger l'index, sélectionnez si vous souhaitez effectuer une requête avec une valeur d'embedding dense, une valeur d'embedding creux, une valeur d'embedding hybride (dense et creux) ou un point de données spécifique.
  5. Saisissez les paramètres correspondant au type de requête que vous avez sélectionné. Par exemple, si vous effectuez une requête avec un embedding dense, saisissez le vecteur d'embedding à utiliser.
  6. Exécutez la requête à l'aide de la commande curl fournie ou de Cloud Shell.
  7. Si vous utilisez Cloud Shell, sélectionnez Exécuter dans Cloud Shell.
  8. Exécutez la requête dans Cloud Shell.
  9. Les résultats renvoient les voisins les plus proches.

Requêtes hybrides

La recherche hybride utilise des embeddings denses et creux pour les combinaisons de recherche sémantique et par mot clé.

Python

Pour savoir comment installer ou mettre à jour le SDK Vertex AI pour Python, consultez la section Installer le SDK Vertex AI pour Python. Pour en savoir plus, consultez la documentation de référence de l'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,
    )

Requêtes avec filtrage et regroupement

Le filtrage des correspondances vectorielles vous permet de limiter les résultats sur les voisins les plus proches à des catégories spécifiques. Les filtres peuvent également désigner des catégories à exclure de vos résultats.

Les limites de voisins par regroupement peuvent augmenter la diversité des résultats en limitant le nombre de résultats renvoyés à partir d'un seul tag de regroupement dans vos données d'index.

Python

Pour savoir comment installer ou mettre à jour le SDK Vertex AI pour Python, consultez la section Installer le SDK Vertex AI pour Python. Pour en savoir plus, consultez la documentation de référence de l'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,
    )

Paramètres de requête ayant un impact sur les performances

Les paramètres de requête suivants peuvent avoir un impact sur la latence, la disponibilité et les coûts lors de l'utilisation de la recherche vectorielle. Ces conseils s'appliquent à la plupart des cas. Toutefois, testez toujours vos configurations pour vous assurer qu'elles fonctionnent bien pour votre cas d'utilisation.

Pour les définitions de paramètres, consultez Paramètres de configuration d'index.

Paramètre À propos Impact sur les performances
approximateNeighborsCount

Indique à l'algorithme le nombre de résultats approximatifs à récupérer à partir de chaque segment.

La valeur de approximateNeighborsCount doit toujours être supérieure à la valeur de setNeighborsCount. Si la valeur de setNeighborsCount est faible, nous vous recommandons de la multiplier par 10 pour approximateNeighborsCount. Pour les valeurs de setNeighborsCount plus élevées, vous pouvez utiliser un multiplicateur plus petit.

Le nom de l'API REST correspondant à ce champ est approximate_neighbor_count.

Augmenter la valeur de approximateNeighborsCount peut affecter les performances de différentes manières :

  • Rappel : augmentation
  • Latence : augmentation potentielle
  • Disponibilité : aucun impact
  • Coût : augmentation potentielle, car davantage de données sont traitées lors d'une recherche

Diminuer la valeur de approximateNeighborsCount peut affecter les performances de différentes manières :

  • Rappel : diminution
  • Latence : diminution potentielle
  • Disponibilité : aucun impact
  • Coût : diminution potentielle, car moins de données sont traitées lors d'une recherche
setNeighborCount

Spécifie le nombre de résultats que la requête doit renvoyer.

Le nom de l'API REST correspondant à ce champ est neighbor_count.

Les valeurs inférieures ou égales à 300 restent performantes dans la plupart des cas d'utilisation. Pour les valeurs plus élevées, testez votre cas d'utilisation spécifique.

fractionLeafNodesToSearch Contrôle le pourcentage de nœuds feuilles à consulter lors de la recherche de voisins les plus proches. Ce paramètre est lié à leafNodeEmbeddingCount, dans le sens où plus il y a d'embeddings par nœud feuille, plus la quantité de données examinées par feuille est importante.

Le nom de l'API REST correspondant à ce champ est fraction_leaf_nodes_to_search_override.

Augmenter la valeur de fractionLeafNodesToSearch peut affecter les performances de différentes manières :

  • Rappel : augmentation
  • Latence : augmentation
  • Disponibilité : aucun impact
  • Coût : augmentation potentielle, car une latence plus élevée occupe plus de ressources machine

Diminuer la valeur de fractionLeafNodesToSearch peut affecter les performances de différentes manières :

  • Rappel : diminution
  • Latence : diminution
  • Disponibilité : aucun impact
  • Coût : diminution potentielle, car une latence plus faible occupe moins de ressources machine