Guide de démarrage rapide de Vector Search

Découvrez dans le guide de démarrage rapide de Vertex AI Vector Search comment créer un index à partir d'un exemple d'ensemble de données provenant d'un site d'e-commerce de vêtements fictif. Dans le cadre de ce guide de démarrage rapide, les représentations vectorielles continues ont déjà été créées. Ce guide de démarrage rapide est destiné à vous aider à créer et déployer un index en moins de 30 minutes.

Prérequis

Ce tutoriel nécessite un projet Google Cloud associé à un compte de facturation. Pour créer un projet, consultez la page Configurer un projet et un environnement de développement. Vous devez créer un projet et configurer votre compte de facturation.

Choisir l'environnement d'exécution

Ce tutoriel peut être exécuté sur Colab ou Vertex AI Workbench.

Colab : ouvrez ce tutoriel dans Colab.
Vertex AI Workbench : ouvrez ce tutoriel dans Vertex AI Workbench. Si vous utilisez Vertex AI Workbench dans votre projet Google Cloud pour la première fois, accédez à la section Vertex AI Workbench de la console Google Cloud et cliquez sur Activer pour activer l'API Notebooks.

Pour afficher ce notebook dans GitHub, consultez la page GitHub.

Coût pour suivre ce guide de démarrage rapide

L'exécution de ce tutoriel coûte quelques dollars américains. Les tarifs des services Google Cloud utilisés dans ce tutoriel sont disponibles sur les pages suivantes :

Vous pouvez également utiliser le simulateur de coût pour générer une estimation du coût en fonction de l'utilisation prévue.

Préparation

Avant de commencer à utiliser Vertex AI, vous devez effectuer les opérations suivantes :

Installer le SDK Vertex AI pour Python
Définir des variables d'environnement
S'authentifier (Colab uniquement)
Définir les autorisations IAM
Activer les API

Installer le SDK Vertex AI pour Python

Les API Vertex AI et Cloud Storage sont accessibles de plusieurs manières, y compris l'API REST et le SDK Vertex AI pour Python. Dans ce tutoriel, le SDK Vertex AI pour Python est utilisé.

!pip install --upgrade --user google-cloud-aiplatform>=1.29.0 google-cloud-storage

Pour utiliser les packages nouvellement installés dans cet environnement d'exécution Jupyter, vous devez redémarrer l'environnement d'exécution, comme indiqué dans l'extrait de code suivant.

# Restart kernel after installs so that your environment can access the new packages
import IPython

app = IPython.Application.instance()
app.kernel.do_shutdown(True)

Variables d'environnement

Définissez les variables d'environnement. Si vous y êtes invité, remplacez your-project-id par l'ID de votre projet et exécutez la cellule.

# get project ID
PROJECT_ID = ! gcloud config get-value project
PROJECT_ID = PROJECT_ID[0]
LOCATION = "us-central1"
if PROJECT_ID == "(unset)":
    print(f"Please set the project ID manually below")

# define project information
if PROJECT_ID == "(unset)":
  PROJECT_ID = "[your-project-id]"

# generate a unique id for this session
from datetime import datetime
UID = datetime.now().strftime("%m%d%H%M")

Authentification (Colab uniquement)

Si vous exécutez ce notebook sur Colab, vous devez exécuter l'authentification de cellule suivante. Cette étape n'est pas obligatoire si vous utilisez Vertex AI Workbench car il est pré-authentifié.

import sys

# if it's Colab runtime, authenticate the user with Google Cloud
if 'google.colab' in sys.modules:
    from google.colab import auth
    auth.authenticate_user()

Définir les autorisations IAM

Vous devez ajouter des autorisations d'accès au compte de service par défaut pour utiliser les services.

Accédez à la page "IAM" de Google Cloud Console.
Recherchez le compte principal du compte de service Compute par défaut. Le résultat doit ressembler à ceci : [email protected]
Cliquez sur le bouton Modifier et attribuez au compte de service Compute par défaut les rôles d'utilisateur Vertex AI et d'administrateur de l'espace de stockage.

Activer les API

Exécutez la commande suivante pour activer les API pour Compute Engine, Vertex AI et Cloud Storage avec ce projet Google Cloud.

! gcloud services enable compute.googleapis.com aiplatform.googleapis.com storage.googleapis.com --project {PROJECT_ID}

Préparer les exemples de données

Dans ce tutoriel, nous utilisons l'ensemble de données TheLook qui contient une table de produits avec environ 30 000 lignes de données produit synthétiques pour un site d'e-commerce de vêtements fictif.

À partir de cette table, nous avons préparé le fichier product-embs.json.

Ce fichier est au format JSONL. Chaque ligne contient l'ID du produit, le nom du produit et la représentation vectorielle continue du nom du produit dans 768 dimensions générées précédemment avec les représentations vectorielles continues Vertex AI pour le texte.

Les représentations vectorielles continues de texte représentent la signification des noms des produits d'habillement. Dans ce tutoriel, nous utilisons la recherche vectorielle pour effectuer une recherche sémantique des éléments. Cet exemple de code peut être utilisé comme base pour d'autres systèmes de recommandations rapides qui permettent de trouver rapidement "d'autres produits semblables à celui-ci".

Pour en savoir plus sur la création de représentations vectorielles continues à partir de données dans BigQuery et sur leur stockage dans un fichier JSON, consultez les pages Premiers pas avec les représentations vectorielles continues de texte + Vertex AI Vector Search.

Préparer les données sur Cloud Storage

Pour créer un index avec Vertex AI, placez le fichier de représentations vectorielles continues dans un bucket Cloud Storage. Le code suivant effectue deux tâches :

crée un bucket Cloud Storage ;
copie l'exemple de fichier dans votre bucket Cloud Storage.

BUCKET_URI = f"gs://{PROJECT_ID}-vs-quickstart-{UID}"

! gsutil mb -l $LOCATION -p $PROJECT_ID $BUCKET_URI
! gsutil cp "gs://github-repo/data/vs-quickstart/product-embs.json" $BUCKET_URI

Pour exécuter des requêtes à l'aide de Vector Search, vous devez également copier le fichier de représentations vectorielles continues dans le répertoire local :

! gsutil cp "gs://github-repo/data/vs-quickstart/product-embs.json" . # for query tests

Créer et déployer un index Vector Search

Découvrez comment créer un index, créer un point de terminaison d'index, puis déployer l'index sur ce point de terminaison.

Créer un index

Il est temps de charger les représentations vectorielles continues dans Vector Search. Les API sont disponibles dans le package aiplatform du SDK.

# init the aiplatform package
from google.cloud import aiplatform
aiplatform.init(project=PROJECT_ID, location=LOCATION)

Créez un MatchingEngineIndex avec sa fonction create_tree_ah_index (Matching Engine est l'ancien nom de Vector Search).

# create Index
my_index = aiplatform.MatchingEngineIndex.create_tree_ah_index(
    display_name = f"vs-quickstart-index-{UID}",
    contents_delta_uri = BUCKET_URI,
    dimensions = 768,
    approximate_neighbors_count = 10,
)

La méthode MatchingEngineIndex.create_tree_ah_index() crée un index. Cette opération prend moins de 10 minutes si l'ensemble de données est petit. Sinon, comptez environ 60 minutes ou plus en fonction de la taille. Vous pouvez vérifier l'état de la création de l'index dans la console Google Cloud Vector Search.

Afficher les index

Paramètres de création de l'index :

contents_delta_uri : URI du répertoire Cloud Storage dans lequel vous avez stocké les fichiers JSON de représentations vectorielles continues.
dimensions : taille de la dimension de chaque représentation vectorielle continue. Dans ce cas, elle est définie sur 768, car vous utilisez les représentations vectorielles continues provenant de l'API de représentations vectorielles continues de texte.
approximate_neighbors_count : nombre d'articles similaires que vous souhaitez récupérer dans des cas types.

Pour en savoir plus sur la création de l'index et les paramètres disponibles, consultez la page Créer et gérer votre index.

Créer un point de terminaison d'index et déployer l'index

Pour utiliser l'index, vous devez créer un point de terminaison d'index. Il fonctionne en tant qu'instance de serveur acceptant les requêtes de type "query" pour votre index.

## create `IndexEndpoint`
my_index_endpoint = aiplatform.MatchingEngineIndexEndpoint.create(
    display_name = f"vs-quickstart-index-endpoint-{UID}",
    public_endpoint_enabled = True
)

Avec le point de terminaison d'index, déployez l'index en spécifiant un ID d'index déployé unique.

DEPLOYED_INDEX_ID = f"vs_quickstart_deployed_{UID}"

# deploy the Index to the Index Endpoint
my_index_endpoint.deploy_index(
    index = my_index, deployed_index_id = DEPLOYED_INDEX_ID
)

Si vous déployez cet index pour la première fois sur un point de terminaison d'index, la création et le lancement du backend peuvent prendre environ 30 minutes. Pour connaître l'état du déploiement de l'index, dans la section "Vertex AI" de Google Cloud Console, accédez à la section Déployer et utiliser. Sélectionnez Index.

Afficher les index

Exécuter une requête avec Vector Search

Dans le code suivant la fonction trouve une représentation vectorielle continue pour un nom de produit spécifié, ainsi que des noms de produits similaires avec Vector Search.

Obtenir une représentation vectorielle continue pour exécuter une requête

Commencez par charger le fichier JSON de représentation vectorielle continue pour créer un dict de noms de produits et de représentations vectorielles continues.

import json

# build dicts for product names and embs
product_names = {}
product_embs = {}
with open('product-embs.json') as f:
    for l in f.readlines():
        p = json.loads(l)
        id = p['id']
        product_names[id] = p['name']
        product_embs[id] = p['embedding']

Le dictionnaire product_embs vous permet de spécifier un ID produit pour obtenir une représentation vectorielle continue.

 # Get the embedding for ID 6523 "cloudveil women's excursion short"
 you can also try with other IDs such as 12711, 18090, 19536 and 11863
query_emb = product_embs['6523']

Exécuter une requête

Transmettez la représentation vectorielle continue à la fonction Endpoint.find_neighbors() pour rechercher des noms de produits similaires.

# run query
response = my_index_endpoint.find_neighbors(
    deployed_index_id = DEPLOYED_INDEX_ID,
    queries = [query_emb],
    num_neighbors = 10
)

# show the results
for idx, neighbor in enumerate(response[0]):
    print(f"{neighbor.distance:.2f} {product_names[neighbor.id]}")

Grâce à l'algorithme ScaNN, la méthode find_neighbors() ne prend que quelques millisecondes pour récupérer les éléments similaires, même si l'index comporte des milliards d'articles. Vector Search accepte l'autoscaling, qui peut redimensionner automatiquement le nombre de nœuds en fonction des demandes de vos charges de travail.

Effectuer un nettoyage

Si vous utilisez votre propre projet Cloud, et non un projet temporaire sur Qwiklab, veillez à supprimer tous les index, points de terminaison d'index et buckets Cloud Storage une fois ce tutoriel terminé. Cela pourrait entraîner des coûts inattendus liés aux ressources restantes.

Si vous avez utilisé Workbench, vous devrez peut-être aussi supprimer les notebooks de la console.


# wait for a confirmation
input("Press Enter to delete Index Endpoint, Index and Cloud Storage bucket:")

# delete Index Endpoint
my_index_endpoint.undeploy_all()
my_index_endpoint.delete(force = True)

# delete Index
my_index.delete()

# delete Cloud Storage bucket
! gsutil rm -r {BUCKET_URI}

Utilitaires

La création ou le déploiement d'index pouvant prendre un certain temps., vous risquez de perdre la connexion avec l'environnement d'exécution Colab. Si vous perdez la connexion, au lieu de recréer ou redéployer votre nouvel index, vous pouvez rechercher dans la console Google Cloud Vector Search les index existants et les utiliser pour continuer.

Obtenir un index existant

Pour obtenir un objet d'index qui existe déjà, remplacez la valeur your-index-id suivante par l'ID d'index et exécutez la cellule. Vous pouvez obtenir l'ID d'index en consultant la console Google Cloud Vector Search. Dans la section "Vertex AI" de la console Google Cloud, accédez à la section Déployer et utiliser. Sélectionnez Index.

Afficher les index

my_index_id = "[your-index-id]"
my_index = aiplatform.MatchingEngineIndex(my_index_id)

Obtenir un point de terminaison d'index existant

Pour obtenir un objet de point de terminaison d'index qui existe déjà, remplacez la valeur your-index-endpoint-id suivante par l'ID du point de terminaison de l'index et exécutez la cellule. Vous pouvez obtenir le point de terminaison de l'index en consultant la console Google Cloud Vector Search. Dans la section "Vertex AI" de la console Google Cloud, accédez à la section Déployer et utiliser. Sélectionnez Points de terminaison d'index.

Afficher les points de terminaison d'index

my_index_endpoint_id = "[your-index-endpoint-id]"
my_index_endpoint = aiplatform.MatchingEngineIndexEndpoint(my_index_endpoint_id)