Interroger les index d'accès aux services privés (appairage de réseaux VPC) ou de Private Service Connect

Une fois que vous avez déployé un point de terminaison d'index d'appairage de réseau VPC ou Private Service Connect, la façon de l'interroger diffère légèrement selon le mode de déploiement :

Déploiement avec l'automatisation Private Service Connect

Lorsque des IndexEndpoints sont déployés avec l'automatisation Private Service Connect, le SDK Python mappe automatiquement le réseau Private Service Connect au point de terminaison approprié. Si vous n'utilisez pas le SDK Python, vous devez vous connecter directement à l'adresse IP créée pour votre point de terminaison en suivant les instructions concernant l'interrogation d'un déploiement manuel Private Service Connect.

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_match_psc_automation(
    project: str,
    location: str,
    index_endpoint_name: str,
    deployed_index_id: str,
    queries: List[List[float]],
    num_neighbors: int,
    psc_network: str,
) -> List[List[aiplatform.matching_engine.matching_engine_index_endpoint.MatchNeighbor]]:
    """Query the vector search index deployed with PSC automation.

    Args:
        project (str): Required. Project ID
        location (str): Required. The region name
        index_endpoint_name (str): Required. Index endpoint to run the query
        against. The endpoint must be a private endpoint.
        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.
        ip_address (str): Required. The IP address of the PSC endpoint. Obtained
        from the created compute address used in the fordwarding rule to the
        endpoint's service attachment.
        psc_network (str): The network the endpoint was deployed to via PSC
        automation configuration. The format is
        projects/{project_id}/global/networks/{network_name}.

    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 matches.
    resp = my_index_endpoint.match(
        deployed_index_id=deployed_index_id,
        queries=queries,
        num_neighbors=num_neighbors,
        psc_network=psc_network
    )
    return resp

Déploiement avec la configuration manuelle de Private Service Connect

Lorsque des IndexEndpoints Private Service Connect sont déployés avec une connexion configurée manuellement, votre point de terminaison est accessible à l'aide de l'adresse IP de l'adresse de calcul transférée au rattachement de service Private Service Connect de votre point de terminaison.

Si vous ne la connaissez pas déjà, vous pouvez obtenir l'adresse IP transmise à l'URI du rattachement de service à l'aide des commandes gcloud ai index-endpoints describe et gcloud compute forwarding-rules list.

Effectuez les remplacements suivants :

  • INDEX_ENDPOINT_ID : ID complet du point de terminaison de l'index
  • REGION : région dans laquelle votre point de terminaison d'index est déployé
SERVICE_ATTACHMENT_URI=`gcloud ai index-endpoints describe INDEX_ENDPOINT_ID \
  --region=REGION \
  --format="value(deployedIndexes.privateEndpoints.serviceAttachment)"`

gcloud compute forwarding-rules list --filter="TARGET:${SERVICE_ATTACHMENT_URI}"

Le résultat inclut l'adresse IP interne à utiliser pour interroger IndexEndpoint.

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_match_psc_manual(
    project: str,
    location: str,
    index_endpoint_name: str,
    deployed_index_id: str,
    queries: List[List[float]],
    num_neighbors: int,
    ip_address: str,
) -> List[List[aiplatform.matching_engine.matching_engine_index_endpoint.MatchNeighbor]]:
    """Query the vector search index deployed with PSC manual configuration.

    Args:
        project (str): Required. Project ID
        location (str): Required. The region name
        index_endpoint_name (str): Required. Index endpoint to run the query
        against. The endpoint must be a private endpoint.
        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.
        ip_address (str): Required. The IP address of the PSC endpoint. Obtained
        from the created compute address used in the forwarding rule to the
        endpoint's service attachment.

    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
    )

    # Set the IP address of the PSC endpoint.
    my_index_endpoint.private_service_connect_ip_address = ip_address

    # Query the index endpoint for matches.
    resp = my_index_endpoint.match(
        deployed_index_id=deployed_index_id,
        queries=queries,
        num_neighbors=num_neighbors
    )
    return resp

Ligne de commande

Pour interroger un DeployedIndex, connectez-vous à son TARGET_IP sur le port 10000, puis appelez la méthode Match ou BatchMatch. Vous pouvez également effectuer des requêtes à l'aide d'un ID d'embedding spécifique.

Les exemples suivants utilisent l'outil Open Source grpc_cli pour envoyer des requêtes gRPC au serveur d'index déployé.

Dans le premier exemple, vous envoyez une seule requête à l'aide de la méthode Match. 

./grpc_cli call ${TARGET_IP}:10000 google.cloud.aiplatform.container.v1.MatchService.Match 'deployed_index_id: "${DEPLOYED_INDEX_ID}", float_val: [-0.1,..]'

Dans le deuxième exemple, vous combinez deux requêtes distinctes dans la même requête BatchMatch.

./grpc_cli call ${TARGET_IP}:10000 google.cloud.aiplatform.container.v1.MatchService.BatchMatch 'requests: [{deployed_index_id: "${DEPLOYED_INDEX_ID}", requests: [{deployed_index_id: "${DEPLOYED_INDEX_ID}", float_val: [-0.1,..]}, {deployed_index_id: "${DEPLOYED_INDEX_ID}", float_val: [-0.2,..]}]}]'

Vous devez appeler ces API à partir d'un client exécuté dans le même VPC avec lequel le service a été appairé.

Pour exécuter une requête à l'aide d'un embedding_id, référez-vous à l'exemple suivant.

./grpc_cli call ${TARGET_IP}:10000  google.cloud.aiplatform.container.v1.MatchService.Match "deployed_index_id:'"test_index1"',embedding_id: '"606431"'"

Dans cet exemple, vous envoyez une requête en utilisant des restrictions de jeton et des restrictions numériques.

./grpc_cli call ${TARGET_IP}:10000 google.cloud.aiplatform.container.v1.MatchService.Match 'deployed_index_id: "${DEPLOYED_INDEX_ID}", float_val: [1, 1], "sparse_embedding": {"values": [111.0,111.1,111.2], "dimensions": [10,20,30]}, numeric_restricts: [{name: "double-ns", value_double: 0.3, op: LESS_EQUAL}, {name: "double-ns", value_double: -1.2, op: GREATER}, {name: "double-ns", value_double: 0., op: NOT_EQUAL}], restricts: [{name: "color", allow_tokens: ["red"]}]'

Pour en savoir plus, consultez Présentation des bibliothèques clientes.

Console

Suivez ces instructions pour interroger un index VPC dans 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 VPC que vous souhaitez interroger. La page Informations sur l'index s'affiche.
  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'affiche.
  4. Dans la section Interroger l'index, sélectionnez les paramètres de votre requête. Vous pouvez choisir d'effectuer une requête par vecteur ou par point de données spécifique.
  5. Exécutez la requête à l'aide de l'outil Open Source grpc_cli ou à l'aide du SDK Vertex AI pour Python.

Déploiement avec l'appairage de réseaux VPC

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.

Remarque : Le SDK Python recherche automatiquement l'adresse IP d'un IndexEndpoint déployé avec l'appairage de réseaux VPC.

def vector_search_match_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.

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

    # Example queries containing 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]
        ),
    ]

    # Query the index endpoint for matches.
    resp = my_index_endpoint.match(
        deployed_index_id=deployed_index_id,
        queries=hybrid_queries,
        num_neighbors=num_neighbors,
    )
    return resp

Ligne de commande

Chaque DeployedIndex possède une TARGET_IP que vous pouvez récupérer dans votre liste d'IndexEndpoints.

Pour interroger un DeployedIndex, connectez-vous à son TARGET_IP sur le port 10000, puis appelez la méthode Match ou BatchMatch. Vous pouvez également effectuer des requêtes à l'aide d'un ID d'embedding spécifique.

Les exemples suivants utilisent l'outil Open Source grpc_cli pour envoyer des requêtes gRPC au serveur d'index déployé.

Dans le premier exemple, vous envoyez une seule requête à l'aide de la méthode Match. 

./grpc_cli call ${TARGET_IP}:10000 google.cloud.aiplatform.container.v1.MatchService.Match 'deployed_index_id: "${DEPLOYED_INDEX_ID}", float_val: [-0.1,..]'

Dans le deuxième exemple, vous combinez deux requêtes distinctes dans la même requête BatchMatch.

./grpc_cli call ${TARGET_IP}:10000 google.cloud.aiplatform.container.v1.MatchService.BatchMatch 'requests: [{deployed_index_id: "${DEPLOYED_INDEX_ID}", requests: [{deployed_index_id: "${DEPLOYED_INDEX_ID}", float_val: [-0.1,..]}, {deployed_index_id: "${DEPLOYED_INDEX_ID}", float_val: [-0.2,..]}]}]'

Vous devez appeler ces API à partir d'un client exécuté dans le même VPC avec lequel le service a été appairé.

Pour exécuter une requête à l'aide d'un embedding_id, référez-vous à l'exemple suivant.

./grpc_cli call ${TARGET_IP}:10000  google.cloud.aiplatform.container.v1.MatchService.Match "deployed_index_id:'"test_index1"',embedding_id: '"606431"'"

Dans cet exemple, vous envoyez une requête en utilisant des restrictions de jeton et des restrictions numériques.

./grpc_cli call ${TARGET_IP}:10000 google.cloud.aiplatform.container.v1.MatchService.Match 'deployed_index_id: "${DEPLOYED_INDEX_ID}", float_val: [1, 1], "sparse_embedding": {"values": [111.0,111.1,111.2], "dimensions": [10,20,30]}, numeric_restricts: [{name: "double-ns", value_double: 0.3, op: LESS_EQUAL}, {name: "double-ns", value_double: -1.2, op: GREATER}, {name: "double-ns", value_double: 0., op: NOT_EQUAL}], restricts: [{name: "color", allow_tokens: ["red"]}]'

Pour en savoir plus, consultez Présentation des bibliothèques clientes.

Console

Suivez ces instructions pour interroger un index VPC dans 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 VPC que vous souhaitez interroger. La page Informations sur l'index s'affiche.
  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'affiche.
  4. Dans la section Interroger l'index, sélectionnez les paramètres de votre requête. Vous pouvez choisir d'effectuer une requête par vecteur ou par point de données spécifique.
  5. Exécutez la requête à l'aide de l'outil Open Source grpc_cli ou à l'aide du SDK Vertex AI pour Python.

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

Étapes suivantes