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 embeddings ont déjà été créés. 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.
Configuration
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 :
compute@developer.gserviceaccount.com - 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 l'embedding du nom du produit dans 768 dimensions générées précédemment avec les embeddings Vertex AI pour le texte.
Les embeddings textuels 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 d'embeddings à partir de données dans une table BigQuery et sur leur stockage dans un fichier JSON, consultez les pages Premiers pas avec les embeddings textuels + 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}"
! gcloud storage buckets create $BUCKET_URI --location=$LOCATION --project=$PROJECT_ID
! gcloud storage 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 :
! gcloud storage 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 embeddings 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.
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 embedding. Dans ce cas, elle est définie sur 768, car vous utilisez les embeddings provenant de l'API d'embedding textuel.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.
Exécuter une requête avec Vector Search
Dans le code suivant la fonction trouve un embedding pour un nom de produit spécifié, ainsi que des noms de produits similaires avec Vector Search.
Obtenir un embedding pour exécuter une requête
Commencez par charger le fichier JSON d'embedding pour créer un dict de noms de produits et d'embeddings.
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 un embedding.
# 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 l'embedding à 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.
Nettoyer
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
! gcloud storage rm {BUCKET_URI} --recursive
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.
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)