Premiers pas avec Spanner pour les applications d'IA générative

Ce tutoriel explique comment créer une application d'IA générative à l'aide de Spanner et de Vertex AI.

Cette application vous permet d'effectuer une recherche par similarité sémantique, ce qui vous permet de trouver des produits correspondant à une requête en langage naturel. Pour ce faire, il utilise des embeddings, qui sont des représentations numériques de texte qui capturent la signification et le contexte des mots. Vous utiliserez un modèle Vertex AI pour générer ces embeddings, puis vous les stockerez et les rechercherez dans Spanner. Cette approche est particulièrement utile pour les cas d'utilisation tels que la recherche de produits, où les utilisateurs peuvent décrire ce qu'ils veulent en langage naturel au lieu de mots clés spécifiques.

Les rubriques suivantes vous aideront à :

  1. Créer un Google Cloud projet
  2. Créer une instance Spanner
  3. Créer une base de données
  4. Créer un modèle d'embedding
  5. Charger des données dans Spanner
  6. Générer des embeddings pour les données
  7. Effectuer une recherche de similarité vectorielle KNN
  8. Mettre à l'échelle la recherche vectorielle avec un index vectoriel
  9. Nettoyer les ressources

Pour en savoir plus sur les tarifs de Spanner, consultez la page Tarifs de Spanner.

Pour essayer un atelier de programmation, consultez Premiers pas avec la recherche vectorielle Spanner.

Avant de commencer

Vous devez créer un projet Google Cloud associé à un compte de facturation.

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. L'API Spanner doit être activée automatiquement. Si ce n'est pas le cas, activez-le manuellement :

    Activer l'API Spanner
  7. L'API Vertex AI devrait être activée automatiquement. Si ce n'est pas le cas, activez-le manuellement :

    Activer l'API Vertex AI

    1. Pour obtenir les autorisations nécessaires pour créer des instances et des bases de données, demandez à votre administrateur de vous accorder le rôle IAM Administrateur Cloud Spanner (roles/spanner.admin) sur votre projet.

    1. Pour obtenir les autorisations nécessaires pour interroger les graphiques Spanner si vous n'avez pas le rôle Administrateur Cloud Spanner, demandez à votre administrateur de vous accorder le rôle IAM Lecteur de bases de données Cloud Spanner (roles/spanner.databaseReader) sur votre projet.

    Créer une instance

    Lorsque vous utilisez Spanner pour la première fois, vous devez créer une instance, c'est-à-dire une allocation de ressources utilisées par les bases de données Spanner. Cette section vous explique comment créer une instance à l'aide de la console Google Cloud .

    1. Dans la console Google Cloud , accédez à la page Spanner.

      Accéder à Spanner

    2. Sélectionnez ou créez un projet Google Cloud si vous ne l'avez pas déjà fait.

    3. Effectuez l'une des opérations suivantes :

      1. Si vous n'avez jamais créé d'instance Spanner, sur la page Bienvenue dans Spanner, cliquez sur Créer une instance provisionnée.
      2. Si vous avez créé une instance Spanner, sur la page Instances, cliquez sur Créer une instance.

    4. Sur la page Sélectionner une édition, sélectionnez Enterprise Plus ou Enterprise.

      La recherche vectorielle Spanner n'est disponible que dans les éditions Enterprise ou Enterprise Plus. Pour comparer les différentes éditions, cliquez sur Comparer les éditions. Pour en savoir plus, consultez la présentation des éditions Spanner.

    5. Cliquez sur Continuer.

    6. Dans Nom de l'instance, saisissez un nom d'instance (par exemple, test-instance).

    7. Dans ID d'instance, conservez ou modifiez l'ID d'instance. Par défaut, l'ID de votre instance correspond à son nom, mais vous pouvez le modifier. Le nom et l'ID de votre instance peuvent être identiques ou différents.

    8. Cliquez sur Continuer.

    9. Dans Choisir une configuration, procédez comme suit :

      1. Laissez l'option Régional sélectionnée.
      2. Dans Sélectionner une configuration, sélectionnez une région. La région que vous sélectionnez est celle où vos instances sont stockées et répliquées.
      3. Cliquez sur Continuer.

    10. Dans Configurer la capacité de calcul, procédez comme suit :

      1. Dans Sélectionner une unité, sélectionnez Unités de traitement (PU).
      2. Dans Choisir un mode de scaling, conservez l'option Allocation manuelle sélectionnée et, dans Quantité, conservez 1 000 unités de traitement.

    11. Cliquez sur Créer. La console Google Cloud affiche la page Présentation de l'instance que vous avez créée.

    Créer une base de données

    Une fois votre instance en cours d'exécution, vous pouvez créer votre base de données. Vous définissez votre schéma dans la base de données .

    1. Dans la console Google Cloud , accédez à la page Instances Spanner.

      Accéder aux instances Spanner

    2. Cliquez sur l'instance que vous avez créée, par exemple test-instance.

    3. Dans Vue d'ensemble, sous le nom de votre instance, cliquez sur Créer une base de données.

    4. Dans Nom de la base de données, saisissez le nom d'une base de données. Exemple :example-db

    5. Dans Sélectionner le dialecte de la base de données, choisissez SQL standard Google.

      La recherche vectorielle Spanner n'est pas disponible dans le dialecte PostgreSQL.

    6. Copiez et collez le schéma suivant dans l'onglet de l'éditeur Modèles DDL. Le schéma définit une table Products.

        CREATE TABLE products (
    categoryId INT64 NOT NULL,
    productId INT64 NOT NULL,
    productName STRING(MAX) NOT NULL,
    productDescription STRING(MAX) NOT NULL,
    productDescriptionEmbedding ARRAY<FLOAT32>,
    createTime TIMESTAMP NOT NULL OPTIONS (
    allow_commit_timestamp = true
    ), inventoryCount INT64 NOT NULL,
    priceInCents INT64,
  ) PRIMARY KEY(categoryId, productId);

    7. N'apportez aucune modification dans Afficher les options de chiffrement.

    8. Cliquez sur Créer. Google Cloud console affiche la page Présentation de la base de données que vous avez créée.

    Créer un modèle d'embedding

    Lorsque vous utilisez l'instruction LDD CREATE MODEL dans Spanner, vous enregistrez une référence au point de terminaison du modèle Vertex AI à partir de votre base de données. Après avoir enregistré le modèle, vous pouvez utiliser la fonction ML.PREDICT pour accéder au modèle dans vos requêtes.

    L'exemple suivant montre comment enregistrer un modèle d'embedding de texte Vertex AI, qui est ensuite utilisé pour effectuer une recherche de similarité afin de trouver des produits similaires dans une base de données.

    1. Sur la page Présentation de la base de données, cliquez sur Spanner Studio.
    2. Sur la page Spanner Studio, cliquez sur Nouvel onglet ou utilisez l'onglet d'éditeur vide.

    3. Saisissez cette commande :

      CREATE MODEL EmbeddingsModel INPUT(
content STRING(MAX),
) OUTPUT(
embeddings STRUCT<values ARRAY<FLOAT32>>,
) REMOTE OPTIONS (
endpoint = '//aiplatform.googleapis.com/projects/PROJECT_ID/locations/us-central1/publishers/google/models/TEXT_EMBEDDING_MODEL'
);

      Remplacez les éléments suivants :

      • PROJECT_ID : identifiant permanent unique pour votre projetGoogle Cloud .
      • TEXT_EMBEDDING_MODEL : nom du modèle d'embedding de texte. Pour obtenir la liste des modèles d'embedding textuel Vertex AI, consultez Modèles compatibles.

    4. Cliquez sur Exécuter pour créer le modèle.

      Une fois le modèle ajouté, il s'affiche dans le volet Explorateur.

    Charger les données

    Pour charger les exemples de données Cymbal dans la table products, procédez comme suit :

    1. Dans un nouvel onglet de Spanner Studio, copiez et collez l'instruction d'insertion suivante :

      INSERT INTO products (categoryId, productId, productName, productDescription, createTime, inventoryCount, priceInCents)
VALUES (1, 1, "Cymbal Helios Helmet", "Safety meets style with the Cymbal children's bike helmet. Its lightweight design, superior ventilation, and adjustable fit ensure comfort and protection on every ride. Stay bright and keep your child safe under the sun with Cymbal Helios!", PENDING_COMMIT_TIMESTAMP(), 100, 10999),
      (1, 2, "Cymbal Sprout", "Let their cycling journey begin with the Cymbal Sprout, the ideal balance bike for beginning riders ages 2-4 years. Its lightweight frame, low seat height, and puncture-proof tires promote stability and confidence as little ones learn to balance and steer. Watch them sprout into cycling enthusiasts with Cymbal Sprout!", PENDING_COMMIT_TIMESTAMP(), 10, 13999),
      (1, 3, "Cymbal Spark Jr.", "Light, vibrant, and ready for adventure, the Spark Jr. is the perfect first bike for young riders (ages 5-8). Its sturdy frame, easy-to-use brakes, and puncture-resistant tires inspire confidence and endless playtime. Let the spark of cycling ignite with Cymbal!", PENDING_COMMIT_TIMESTAMP(), 34, 13900),
      (1, 4, "Cymbal Summit", "Conquering trails is a breeze with the Summit mountain bike. Its lightweight aluminum frame, responsive suspension, and powerful disc brakes provide exceptional control and comfort for experienced bikers navigating rocky climbs or shredding downhill. Reach new heights with Cymbal Summit!", PENDING_COMMIT_TIMESTAMP(), 0, 79999),
      (1, 5, "Cymbal Breeze", "Cruise in style and embrace effortless pedaling with the Breeze electric bike. Its whisper-quiet motor and long-lasting battery let you conquer hills and distances with ease. Enjoy scenic rides, commutes, or errands with a boost of confidence from Cymbal Breeze!", PENDING_COMMIT_TIMESTAMP(), 72, 129999),
      (1, 6, "Cymbal Trailblazer Backpack", "Carry all your essentials in style with the Trailblazer backpack. Its water-resistant material, multiple compartments, and comfortable straps keep your gear organized and accessible, allowing you to focus on the adventure. Blaze new trails with Cymbal Trailblazer!", PENDING_COMMIT_TIMESTAMP(), 24, 7999),
      (1, 7, "Cymbal Phoenix Lights", "See and be seen with the Phoenix bike lights. Powerful LEDs and multiple light modes ensure superior visibility, enhancing your safety and enjoyment during day or night rides. Light up your journey with Cymbal Phoenix!", PENDING_COMMIT_TIMESTAMP(), 87, 3999),
      (1, 8, "Cymbal Windstar Pump", "Flat tires are no match for the Windstar pump. Its compact design, lightweight construction, and high-pressure capacity make inflating tires quick and effortless. Get back on the road in no time with Cymbal Windstar!", PENDING_COMMIT_TIMESTAMP(), 36, 24999),
      (1, 9,"Cymbal Odyssey Multi-Tool","Be prepared for anything with the Odyssey multi-tool. This handy gadget features essential tools like screwdrivers, hex wrenches, and tire levers, keeping you ready for minor repairs and adjustments on the go. Conquer your journey with Cymbal Odyssey!", PENDING_COMMIT_TIMESTAMP(), 52, 999),
      (1, 10,"Cymbal Nomad Water Bottle","Stay hydrated on every ride with the Nomad water bottle. Its sleek design, BPA-free construction, and secure lock lid make it the perfect companion for staying refreshed and motivated throughout your adventures. Hydrate and explore with Cymbal Nomad!", PENDING_COMMIT_TIMESTAMP(), 42, 1299);

    2. Cliquez sur Exécuter pour insérer les données.

    Générer des embeddings

    Après avoir enregistré un modèle et chargé des données dans Spanner, vous pouvez générer des embeddings vectoriels avec les descriptions de produits de vos données. Les embeddings vectoriels transforment les données textuelles en valeurs numériques qui capturent la signification et le contexte des mots. Cette transformation est essentielle pour effectuer une recherche sémantique.

    Dans cette étape, vous allez remplir la colonne productDescriptionEmbedding en générant des embeddings à partir de la colonne productDescription à l'aide de ML.PREDICT. Cela vous permettra d'effectuer une recherche de similarité vectorielle à l'étape suivante.

    1. Dans un nouvel onglet de Spanner Studio, copiez et collez l'instruction de mise à jour suivante :

      UPDATE products p1
SET productDescriptionEmbedding =
  (SELECT embeddings.values
    FROM ML.PREDICT(MODEL EmbeddingsModel,
      (SELECT p1.productDescription as content)
    )
  )
WHERE categoryId=1;

    2. Cliquez sur Exécuter pour générer les embeddings.

    Dans l'exemple suivant, vous fournissez une requête de recherche en langage naturel à l'aide d'une requête SQL. La requête SQL effectue une recherche de similarité vectorielle à l'aide des embeddings vectoriels que vous avez générés précédemment. La requête effectue la recherche en procédant comme suit :

    • Utilise ML.PREDICT pour générer un embedding pour la requête de recherche donnée ("J'aimerais acheter un vélo pour débutant pour mon enfant de trois ans").
    • Calcule la COSINE_DISTANCE entre l'embedding de cette requête et le productDescriptionEmbedding de chaque produit du tableau des produits pour trouver des résultats similaires dans votre boutique Cymbal.
    • Filtre les résultats pour n'inclure que les produits dont la valeur inventoryCount est supérieure à 0.
    • Trie les résultats par distance calculée et renvoie les cinq correspondances les plus proches, ainsi que les productName, productDescription et inventoryCount.

    1. Dans un nouvel onglet de Spanner Studio, copiez et collez la requête suivante :

      SELECT productName, productDescription, inventoryCount,
  COSINE_DISTANCE(
    productDescriptionEmbedding,
    (
      SELECT embeddings.values
      FROM
        ML.PREDICT(
          MODEL EmbeddingsModel,
          (SELECT "I'd like to buy a starter bike for my 3 year old child" AS content))
    )) AS distance
FROM products
WHERE inventoryCount > 0
ORDER BY distance
LIMIT 5;

    2. Cliquez sur Exécuter pour afficher les produits qui correspondent le mieux à votre texte de recherche.

      Exemple de résultat :

      /*-----------------+--------------------+----------------+--------------------*
| productName      | productDescription | inventoryCount | distance           |
+------------------+--------------------+----------------+--------------------+
| Cymbal Sprout    | Let their cycling  | 10             | 0.3094387191860244 |
|                  | journey begin with |                |                    |
|                  | the Cymbal Sprout, |                |                    |
|                  | the ideal balance  |                |                    |
|                  | bike for beginning |                |                    |
|                  | riders ages 2-4    |                |                    |
|                  | years...           |                |                    |
| Cymbal Spark Jr  | Light, vibrant,    | 34             | 0.3412342902117166 |
|                  | and ready for      |                |                    |
|                  | adventure, the     |                |                    |
|                  | Spark Jr. is the   |                |                    |
|                  | perfect first bike |                |                    |
|                  | for young riders   |                |                    |
|                  | (ages 5-8)...      |                |                    |
| Cymbal Helios    | Safety meets style | 100            | 0.4197863319656684 |
| Helmet           | with the Cymbal    |                |                    |
|                  | children's bike    |                |                    |
|                  | helmet...          |                |                    |
| Cymbal Breeze    | Cruise in style and| 72             | 0.485231776523978  |
|                  | embrace effortless |                |                    |
|                  | pedaling with the  |                |                    |
|                  | Breeze electric    |                |                    |
|                  | bike...            |                |                    |
| Cymbal Phoenix   | See and be seen    | 87             | 0.525101413779242  |
| Lights           | with the Phoenix   |                |                    |
|                  | bike lights...     |                |                    |
*------------------+--------------------+----------------+--------------------*/

    L'exemple de recherche vectorielle précédent utilise la recherche vectorielle exacte des k plus proches voisins (KNN). Les fonctions de distance vectorielle KNN (distance cosinus, distance euclidienne et produit scalaire) sont utiles lorsque vous pouvez interroger un sous-ensemble spécifique de vos données Spanner. La recherche KNN calcule la distance exacte entre un vecteur de requête et tous les vecteurs de la base de données. Elle est donc efficace lorsque vous pouvez partitionner les données. Si votre requête doit comparer le vecteur de requête à tous les vecteurs de votre base de données sans aucun filtre spécifique, et que vous ne pouvez pas diviser la requête en sous-requêtes indépendantes, vous risquez de rencontrer des problèmes de performances si vous utilisez KNN. La recherche vectorielle des voisins les plus proches approximatifs (ANN) devient utile dans ces situations. Pour en savoir plus, consultez Rechercher les voisins approximatifs les plus proches.

    Si vos charges de travail ne sont pas partitionnables et que vous disposez d'une grande quantité de données, vous pouvez utiliser la recherche vectorielle ANN pour améliorer les performances des requêtes pour les ensembles de données plus volumineux.

    Pour mettre à l'échelle et utiliser la recherche vectorielle ANN dans Spanner, procédez comme suit :

    Créer un index vectoriel

    Spanner accélère les recherches vectorielles ANN en utilisant un index vectoriel spécialisé qui exploite Scalable Nearest Neighbor (ScaNN) de Google Research.

    Pour créer un index vectoriel dans votre ensemble de données, vous devez modifier la colonne productDescriptionEmbeddings afin de définir une annotation vector_length. L'annotation vector_length indique la dimension de chaque vecteur. Les instructions LDD suivantes suppriment la colonne productDescriptionEmbedding et la recréent avec vector_length. La longueur maximale (dimension) du vecteur varie en fonction du modèle d'embedding que vous avez choisi.

    1. Dans un nouvel onglet de Spanner Studio, copiez et collez l'instruction LDD suivante pour recréer la colonne productDescriptionEmbedding :

      ALTER TABLE products DROP COLUMN productDescriptionEmbedding;
ALTER TABLE products
  ADD COLUMN productDescriptionEmbedding ARRAY<FLOAT32>(vector_length=>VECTOR_LENGTH_VALUE);

      Remplacez VECTOR_LENGTH_VALUE par les dimensions de sortie maximales du modèle d'embedding que vous avez choisi.

    2. Cliquez sur Exécuter.

    3. Copiez et collez l'instruction d'insertion suivante pour régénérer les embeddings vectoriels :

      UPDATE products p1
SET productDescriptionEmbedding =
(SELECT embeddings.values from ML.PREDICT(MODEL EmbeddingsModel,
(SELECT p1.productDescription as content)))
WHERE categoryId=1;

    4. Cliquez sur Exécuter.

    5. Copiez et collez l'instruction LDD suivante pour créer l'index vectoriel :

      CREATE VECTOR INDEX ProductDescriptionEmbeddingIndex
    ON products(productDescriptionEmbedding)
    WHERE productDescriptionEmbedding IS NOT NULL
OPTIONS (
distance_type = 'COSINE'
);

    6. Cliquez sur Exécuter.

    Utiliser la fonction de distance vectorielle ANN

    Pour utiliser la recherche vectorielle ANN dans Spanner, modifiez les éléments suivants dans votre requête SQL :

    • Générez l'embedding de requête séparément, plutôt que dans la requête SQL.
    • Copiez les résultats des embeddings dans la requête.
    • Utilisez l'indication FORCE_INDEX pour faire référence au nouvel index vectoriel : @{force_index=ProductDescriptionEmbeddingIndex}
    • Utilisez la fonction de distance vectorielle APPROX_COSINE_DISTANCE au lieu de COSINE_DISTANCE. L'option JSON '{"num_leaves_to_search": num_leaves}' est obligatoire.

    1. Dans un nouvel onglet de Spanner Studio, copiez et collez la requête suivante pour générer l'embedding de la requête :

      -- Generate the prompt embedding
SELECT embeddings.values
FROM ML.PREDICT(
  MODEL EmbeddingsModel,
  (SELECT "I'd like to buy a starter bike for my 3 year old child" as content)
  );

    2. Cliquez sur Exécuter.

    3. Copiez le résultat embeddings.values.

    4. Remplacez embedding dans la requête suivante par le résultat d'embedding que vous avez copié à l'étape précédente.

      -- Update embedding query using the vector index
SELECT productName, productDescription, inventoryCount,
  (APPROX_COSINE_DISTANCE(productDescriptionEmbedding,
  array<float32>[embedding],
  options => JSON '{\"num_leaves_to_search\": 10}')) as distance
FROM products @{force_index=ProductDescriptionEmbeddingIndex}
WHERE productDescriptionEmbedding IS NOT NULL AND inventoryCount > 0
ORDER BY distance
LIMIT 5;

      La nouvelle requête SQL ressemble à ceci :

      SELECT productName, productDescription, count,
  (APPROX_COSINE_DISTANCE(productDescriptionEmbedding,
    array<float32>[-0.00457216799,-0.0771846101,-0.0319350846,0.0352052487,-0.0457422845,0.0183265656...],
    options => JSON '{\"num_leaves_to_search\": 10}')) as distance
FROM products @{force_index=ProductDescriptionEmbeddingIndex}
WHERE productDescriptionEmbedding IS NOT NULL AND inventoryCount > 0
ORDER BY distance
LIMIT 5;

      Exemple de résultat :

      /*-----------------+--------------------+----------------+--------------------*
| productName      | productDescription | inventoryCount | distance           |
+------------------+--------------------+----------------+--------------------+
| Cymbal Sprout    | Let their cycling  | 10             | 0.30935457151661594|
|                  | journey begin with |                |                    |
|                  | the Cymbal Sprout, |                |                    |
|                  | the ideal balance  |                |                    |
|                  | bike for beginning |                |                    |
|                  | riders ages 2-4    |                |                    |
|                  | years...           |                |                    |
| Cymbal Spark Jr  | Light, vibrant,    | 34             | 0.34116496551593656|
|                  | and ready for      |                |                    |
|                  | adventure, the     |                |                    |
|                  | Spark Jr. is the   |                |                    |
|                  | perfect first bike |                |                    |
|                  | for young riders   |                |                    |
|                  | (ages 5-8)...      |                |                    |
| Cymbal Helios    | Safety meets style | 100            | 0.4198014303921187 |
| Helmet           | with the Cymbal    |                |                    |
|                  | children's bike    |                |                    |
|                  | helmet...          |                |                    |
| Cymbal Breeze    | Cruise in style and| 72             | 0.4850674854267337 |
|                  | embrace effortless |                |                    |
|                  | pedaling with the  |                |                    |
|                  | Breeze electric    |                |                    |
|                  | bike...            |                |                    |
| Cymbal Phoenix   | See and be seen    | 87             | 0.525101413779242  |
| Lights           | with the Phoenix   |                |                    |
|                  | bike lights...     |                |                    |
*------------------+--------------------+----------------+--------------------*/

      Le Cymbal Sprout, avec son APPROX_COSINE_DISTANCE de 0,30935457151661594, présente le plus haut degré de similarité avec la requête d'origine.

      Pour en savoir plus sur l'interprétation de la relation entre les fonctions vectorielles et la similarité, consultez Choisir parmi les fonctions de distance vectorielle pour mesurer la similarité des embeddings vectoriels.

    Effectuer un nettoyage

    Cette section vous explique comment utiliser la console Google Cloud pour nettoyer vos ressources. Pour éviter des frais supplémentaires sur votre compte de facturation Cloud, supprimez la base de données et l'instance que vous avez créées lors de la configuration. La suppression d'une instance supprime toutes les bases de données créées dans l'instance.

    Supprimer la base de données

    1. Dans la console Google Cloud , accédez à la page Instances Spanner.

      Accéder aux instances Spanner

    2. Cliquez sur le nom de l'instance contenant la base de données que vous souhaitez supprimer (par exemple, test-instance).

    3. Cliquez sur le nom de la base de données que vous souhaitez supprimer, par exemple example-db.

    4. Sur la page Présentation de la base de données, cliquez sur Supprimer la base de données.

    5. Confirmez que vous souhaitez supprimer la base de données en saisissant son nom et en cliquant sur Supprimer.

    Supprimer l'instance

    1. Dans la console Google Cloud , accédez à la page Instances Spanner.

      Accéder aux instances Spanner

    2. Cliquez sur le nom de l'instance que vous souhaitez supprimer, par exemple test-instance.

    3. Cliquez sur Supprimer l'instance.

    4. Confirmez que vous souhaitez supprimer l'instance en saisissant son nom et en cliquant sur Supprimer.

    Étape suivante