Effectuer une recherche vectorielle

---

Ce tutoriel explique comment configurer et effectuer une recherche vectorielle dans AlloyDB pour PostgreSQL à l'aide de la console Google Cloud . Des exemples sont inclus pour illustrer les fonctionnalités de recherche vectorielle. Ils sont fournis à des fins de démonstration uniquement.

Pour savoir comment utiliser la recherche vectorielle filtrée afin d'affiner vos recherches de similarité, consultez Recherche vectorielle filtrée dans AlloyDB pour PostgreSQL.

Pour savoir comment effectuer une recherche vectorielle avec les embeddings Vertex AI, consultez Premiers pas avec les embeddings vectoriels AlloyDB/AI.

Objectifs

• Créez un cluster AlloyDB et une instance principale.
• Connectez-vous à votre base de données et installez les extensions requises.
• Créez un tableau product et product inventory.
• Insérez des données dans les tables product et product inventory, puis effectuez une recherche vectorielle de base.
• Créez un index ScaNN sur la table "products".
• Effectuez une recherche vectorielle simple.
• Effectuez une recherche vectorielle complexe avec un filtre et une jointure.

Coûts

Dans ce document, vous utilisez les composants facturables de Google Cloudsuivants :

• AlloyDB for PostgreSQL
• Vertex AI

Obtenez une estimation des coûts en fonction de votre utilisation prévue à l'aide du simulateur de coût.

Les nouveaux utilisateurs de Google Cloud peuvent bénéficier d'un essai gratuit.

Une fois que vous avez terminé les tâches décrites dans ce document, supprimez les ressources que vous avez créées pour éviter que des frais vous soient facturés. Pour en savoir plus, consultez la section Effectuer un nettoyage.

Avant de commencer

Remarque : Si vous avez déjà effectué les étapes de cette section, passez directement à Insérer des données sur les produits et leur inventaire, et effectuer une recherche vectorielle de base pour poursuivre le tutoriel.

Activer la facturation et les API requises

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

   Accéder au sélecteur de projet

2. Assurez-vous que la facturation est activée pour votre projet Google Cloud .

3. Activez les APIs Cloud nécessaires pour créer et vous connecter à AlloyDB pour PostgreSQL.

   Activer les API

   1. À l'étape Confirmer le projet, cliquez sur Suivant pour confirmer le nom du projet que vous allez modifier.

   2. À l'étape Activer les API, cliquez sur Activer pour activer les éléments suivants :

      • API AlloyDB
      • API Compute Engine
      • API Service Networking
      • API Vertex AI

Créer un cluster et une instance principale AlloyDB

Remarque : Certaines régions disponibles pour AlloyDB ne le sont pas pour les modèles d'embedding de texte Vertex AI. Pour savoir quelles fonctionnalités Vertex AI sont disponibles dans chaque région Vertex AI, consultez la page Disponibilité des fonctionnalités.

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

   accéder aux clusters

2. Cliquez sur Créer un cluster.

3. Dans le champ ID du cluster, saisissez my-cluster.

4. Saisissez un mot de passe. Notez ce mot de passe, car vous l'utiliserez dans ce tutoriel.

5. Sélectionnez une région, par exemple us-central1 (Iowa).

6. Sélectionnez le réseau par défaut.

   Si vous disposez d'une connexion d'accès privé, passez à l'étape suivante. Sinon, cliquez sur Configurer la connexion et procédez comme suit :

   1. Dans Allouer une plage d'adresses IP, cliquez sur Utiliser une plage d'adresses IP automatiquement allouée.
   2. Cliquez sur Continuer, puis sur Créer une connexion.

7. Dans Disponibilité zonale, sélectionnez Zone unique.

8. Sélectionnez le type de machine 2 vCPU,16 GB.

9. Dans Connectivité, sélectionnez Activer l'adresse IP publique.

10. Cliquez sur Créer un cluster. La création du cluster par AlloyDB et son affichage sur la page Présentation du cluster principal peuvent prendre plusieurs minutes.

11. Dans Instances dans votre cluster, développez le volet Connectivité. Notez l'URI de connexion, car vous l'utiliserez dans ce tutoriel.

    L'URI de connexion est au format projects/<var>PROJECT_ID</var>/locations/<var>REGION_ID</var>/clusters/my-cluster/instances/my-cluster-primary.

Accorder l'autorisation Utilisateur Vertex AI à l'agent de service AlloyDB

Pour permettre à AlloyDB d'utiliser les modèles d'embedding de texte Vertex AI, vous devez ajouter des autorisations utilisateur Vertex AI à l'agent de service AlloyDB pour le projet où se trouvent votre cluster et votre instance.

Pour savoir comment ajouter les autorisations, consultez Accorder l'autorisation d'utilisateur Vertex AI à l'agent de service AlloyDB.

Se connecter à votre base de données à l'aide d'un navigateur Web

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

   accéder aux clusters

2. Dans la colonne Nom de la ressource, cliquez sur le nom de votre cluster, my-cluster.

3. Dans le volet de navigation, cliquez sur AlloyDB Studio.

4. Sur la page Se connecter à AlloyDB Studio, procédez comme suit :

   1. Sélectionnez la base de données postgres.
   2. Sélectionnez l'utilisateur postgres.
   3. Saisissez le mot de passe que vous avez créé dans Créer un cluster et son instance principale.
   4. Cliquez sur Authentifier. Le volet Explorateur affiche la liste des objets de la base de données postgres.

5. Ouvrez un nouvel onglet en cliquant sur + Nouvel onglet de l'éditeur SQL ou sur + Nouvel onglet.

Installer les extensions requises

Exécutez la requête suivante pour installer les extensions vector et alloydb_scann :

  CREATE EXTENSION IF NOT EXISTS vector;
  CREATE EXTENSION IF NOT EXISTS alloydb_scann;

Insérer des données produit et d'inventaire de produits, et effectuer une recherche vectorielle de base

1. Exécutez l'instruction suivante pour créer une table product qui effectue les opérations suivantes :

   • Stocke les informations de base sur les produits.
   • Inclut une colonne de vecteur embedding qui calcule et stocke un vecteur d'embedding pour la description de chaque produit.
   Remarque : Si une table contient plus de 100 000 lignes, nous vous déconseillons d'utiliser la fonction embedding() pour générer des embeddings stockés sur les données existantes d'une table. Il est particulièrement adapté à la génération d'embeddings intégrés.

     CREATE TABLE product (
       id INT PRIMARY KEY,
       name VARCHAR(255) NOT NULL,
       description TEXT,
       category VARCHAR(255),
       color VARCHAR(255),
       embedding vector(768) GENERATED ALWAYS AS (embedding('text-embedding-005', description)) STORED
     );
   

   Si nécessaire, vous pouvez utiliser l'explorateur de journaux pour afficher les journaux et résoudre les problèmes.

2. Exécutez la requête suivante pour créer une table product_inventory qui stocke des informations sur l'inventaire disponible et les prix correspondants. Les tables product_inventory et product sont utilisées dans ce tutoriel pour exécuter des requêtes de recherche vectorielle complexes.

   CREATE TABLE product_inventory (
     id INT PRIMARY KEY,
     product_id INT REFERENCES product(id),
     inventory INT,
     price DECIMAL(10,2)
   );
   

3. Exécutez la requête suivante pour insérer des données produit dans la table product :

   INSERT INTO product (id, name, description,category, color) VALUES
   (1, 'Stuffed Elephant', 'Soft plush elephant with floppy ears.', 'Plush Toys', 'Gray'),
   (2, 'Remote Control Airplane', 'Easy-to-fly remote control airplane.', 'Vehicles', 'Red'),
   (3, 'Wooden Train Set', 'Classic wooden train set with tracks and trains.', 'Vehicles', 'Multicolor'),
   (4, 'Kids Tool Set', 'Toy tool set with realistic tools.', 'Pretend Play', 'Multicolor'),
   (5, 'Play Food Set', 'Set of realistic play food items.', 'Pretend Play', 'Multicolor'),
   (6, 'Magnetic Tiles', 'Set of colorful magnetic tiles for building.', 'Construction Toys', 'Multicolor'),
   (7, 'Kids Microscope', 'Microscope for kids with different magnification levels.', 'Educational Toys', 'White'),
   (8, 'Telescope for Kids', 'Telescope designed for kids to explore the night sky.', 'Educational Toys', 'Blue'),
   (9, 'Coding Robot', 'Robot that teaches kids basic coding concepts.', 'Educational Toys', 'White'),
   (10, 'Kids Camera', 'Durable camera for kids to take pictures and videos.', 'Electronics', 'Pink'),
   (11, 'Walkie Talkies', 'Set of walkie talkies for kids to communicate.', 'Electronics', 'Blue'),
   (12, 'Karaoke Machine', 'Karaoke machine with built-in microphone and speaker.', 'Electronics', 'Black'),
   (13, 'Kids Drum Set', 'Drum set designed for kids with adjustable height.', 'Musical Instruments', 'Blue'),
   (14, 'Kids Guitar', 'Acoustic guitar for kids with nylon strings.', 'Musical Instruments', 'Brown'),
   (15, 'Kids Keyboard', 'Electronic keyboard with different instrument sounds.', 'Musical Instruments', 'Black'),
   (16, 'Art Easel', 'Double-sided art easel with chalkboard and whiteboard.', 'Arts & Crafts', 'White'),
   (17, 'Finger Paints', 'Set of non-toxic finger paints for kids.', 'Arts & Crafts', 'Multicolor'),
   (18, 'Modeling Clay', 'Set of colorful modeling clay.', 'Arts & Crafts', 'Multicolor'),
   (19, 'Watercolor Paint Set', 'Watercolor paint set with brushes and palette.', 'Arts & Crafts', 'Multicolor'),
   (20, 'Beading Kit', 'Kit for making bracelets and necklaces with beads.', 'Arts & Crafts', 'Multicolor'),
   (21, '3D Puzzle', '3D puzzle of a famous landmark.', 'Puzzles', 'Multicolor'),
   (22, 'Race Car Track Set', 'Race car track set with cars and accessories.', 'Vehicles', 'Multicolor'),
   (23, 'RC Monster Truck', 'Remote control monster truck with oversized tires.', 'Vehicles', 'Green'),
   (24, 'Train Track Expansion Set', 'Expansion set for wooden train tracks.', 'Vehicles', 'Multicolor');
   

4. Facultatif : Exécutez la requête suivante pour vérifier que les données sont insérées dans la table product :

   SELECT * FROM product;
   

5. Exécutez la requête suivante pour insérer des données d'inventaire dans la table product_inventory :

   INSERT INTO product_inventory (id, product_id, inventory, price) VALUES
   (1, 1, 9, 13.09),
   (2, 2, 40, 79.82),
   (3, 3, 34, 52.49),
   (4, 4, 9, 12.03),
   (5, 5, 36, 71.29),
   (6, 6, 10, 51.49),
   (7, 7, 7, 37.35),
   (8, 8, 6, 10.87),
   (9, 9, 7, 42.47),
   (10, 10, 3, 24.35),
   (11, 11, 4, 10.20),
   (12, 12, 47, 74.57),
   (13, 13, 5, 28.54),
   (14, 14, 11, 25.58),
   (15, 15, 21, 69.84),
   (16, 16, 6, 47.73),
   (17, 17, 26, 81.00),
   (18, 18, 11, 91.60),
   (19, 19, 8, 78.53),
   (20, 20, 43, 84.33),
   (21, 21, 46, 90.01),
   (22, 22, 6, 49.82),
   (23, 23, 37, 50.20),
   (24, 24, 27, 99.27);
   

6. Exécutez la requête de recherche vectorielle suivante qui tente de trouver des produits similaires au mot music. Cela signifie que même si le mot music n'est pas mentionné explicitement dans la description du produit, le résultat affiche les produits qui correspondent à la requête :

   SELECT * FROM product
   ORDER BY embedding <=> embedding('text-embedding-005', 'music')::vector
   LIMIT 3;
   

   Le résultat de la requête se présente comme suit :

   Une recherche vectorielle de base sans création d'index utilise la recherche exacte du voisin le plus proche (KNN), qui offre un rappel efficace. À grande échelle, l'utilisation de KNN peut avoir un impact sur les performances. Pour améliorer les performances des requêtes, nous vous recommandons d'utiliser l'index ScaNN pour la recherche approximative des voisins les plus proches (ANN), qui offre un rappel élevé avec de faibles latences.

   Sans créer d'index, AlloyDB utilise par défaut la recherche exacte des k plus proches voisins (KNN).

   Pour en savoir plus sur l'utilisation de ScaNN à grande échelle, consultez Premiers pas avec les embeddings vectoriels AlloyDB AI.

Créer un index ScaNN sur la table des produits

Important : Les exemples de ce tutoriel sont fournis à des fins de démonstration uniquement. Nous vous recommandons de ne créer des index ScaNN que sur les tables de plus de 10 000 lignes.

Exécutez la requête suivante pour créer un index ScaNN product_index sur la table product :

  CREATE INDEX product_index ON product
  USING scann (embedding cosine)
  WITH (num_leaves=5);

Le paramètre num_leaves indique le nombre de nœuds feuilles avec lesquels l'index basé sur l'arborescence crée l'index. Pour savoir comment ajuster ce paramètre, consultez Ajuster les performances des requêtes vectorielles.

Effectuer une recherche vectorielle

Exécutez la requête de recherche vectorielle suivante qui tente de trouver des produits similaires à la requête en langage naturel music. Même si le mot music n'est pas inclus dans la description du produit, le résultat affiche des produits pertinents pour la requête :

SET LOCAL scann.num_leaves_to_search = 2;

SELECT * FROM product
ORDER BY embedding <=> embedding('text-embedding-005', 'music')::vector
  LIMIT 3;

Les résultats de la requête sont les suivants :

Le paramètre de requête scann.num_leaves_to_search contrôle le nombre de nœuds feuilles recherchés lors d'une recherche de similarité. Les valeurs des paramètres num_leaves et scann.num_leaves_to_search permettent d'équilibrer les performances et le rappel.

Effectuer une recherche vectorielle qui utilise un filtre et une jointure

Vous pouvez exécuter efficacement des requêtes de recherche vectorielle filtrées, même lorsque vous utilisez l'index ScaNN. Exécutez la requête de recherche vectorielle complexe suivante, qui renvoie des résultats pertinents répondant aux conditions de la requête, même avec des filtres :

SET LOCAL scann.num_leaves_to_search = 2;

SELECT * FROM product p
JOIN product_inventory pi ON p.id = pi.product_id
WHERE pi.price < 80.00
ORDER BY embedding <=> embedding('text-embedding-005', 'music')::vector
LIMIT 3;

Accélérer votre recherche vectorielle filtrée

Preview

Cette fonctionnalité est soumise aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les fonctionnalités de pré-DG sont disponibles "en l'état" et peuvent avoir une prise en charge limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Vous pouvez utiliser le moteur columnar pour améliorer les performances des recherches de similarité vectorielle, en particulier les recherches K-Nearest Neighbor (KNN), lorsqu'il est combiné à un filtrage de prédicats très sélectif (par exemple, à l'aide de LIKE) dans les bases de données. Dans cette section, vous allez utiliser l'extension vector et l'extension AlloyDB google_columnar_engine.

Les améliorations des performances proviennent de l'efficacité intégrée du moteur en colonnes pour analyser de grands ensembles de données et appliquer des filtres (tels que les prédicats LIKE), ainsi que de sa capacité à préfiltrer les lignes à l'aide de la prise en charge des vecteurs. Cette fonctionnalité réduit le nombre de sous-ensembles de données requis pour les calculs de distance vectorielle KNN ultérieurs et permet d'optimiser les requêtes analytiques complexes impliquant un filtrage standard et une recherche vectorielle.

Pour comparer le temps d'exécution d'une recherche vectorielle KNN filtrée par un prédicat LIKE avant et après l'activation du moteur columnar, procédez comme suit :

1. Activez l'extension vector pour prendre en charge les types de données et les opérations vectorielles. Exécutez les instructions suivantes pour créer une table d'exemple (éléments) avec un ID, une description textuelle et une colonne d'intégration vectorielle de 512 dimensions.

   CREATE EXTENSION IF NOT EXISTS vector;
   
   CREATE TABLE items (
       id SERIAL PRIMARY KEY,
       description TEXT,
       embedding VECTOR(512)
   );
   

2. Remplissez les données en exécutant les instructions suivantes pour insérer un million de lignes dans l'exemple de table items.

   -- Simplified example of inserting matching (~0.1%) and non-matching data
   INSERT INTO items (description, embedding)
   SELECT
       CASE WHEN g % 1000 = 0 THEN 'product_' || md5(random()::text) || '_common' -- ~0.1% match
       ELSE 'generic_item_' || g || '_' || md5(random()::text)    -- ~99.9% don't match
       END,
       random_vector(512) -- Assumes random_vector function exists
   FROM generate_series(1, 999999) g;
   

3. Mesurez les performances de référence de la recherche de similarité vectorielle sans le moteur en colonnes.

   SELECT id, description, embedding <-> '[...]' AS distance
   FROM items
   WHERE description LIKE '%product_%_common%'
   ORDER BY embedding <-> '[...]'
   LIMIT 100;
   

4. Activez le moteur columnar et la compatibilité avec les vecteurs en exécutant la commande suivante dans la Google Cloud CLI. Pour utiliser la gcloud CLI, vous pouvez installer et initialiser la gcloud CLI.

   gcloud beta alloydb instances update INSTANCE_ID \
       --cluster=CLUSTER_ID \
       --region=REGION_ID \
       --project=PROJECT_ID \
       --database-flags=google_columnar_engine.enabled=on,google_columnar_engine.enable_vector_support=on

5. Ajoutez le tableau items au moteur en colonnes :

   SELECT google_columnar_engine_add('items');
   

6. Mesurez les performances de la recherche de similarité vectorielle à l'aide du moteur colonnaire. Vous réexécutez la requête que vous avez exécutée précédemment pour mesurer les performances de référence.

   SELECT id, description, embedding <-> '[...]' AS distance
   FROM items
   WHERE description LIKE '%product_%_common%'
   ORDER BY embedding <-> '[...]'
   LIMIT 100;
   

7. Pour vérifier si la requête a été exécutée avec le moteur columnar, exécutez la commande suivante :

   explain (analyze) SELECT id, description, embedding <-> '[...]' AS distance
   FROM items
   WHERE description LIKE '%product_%_common%'
   ORDER BY embedding <-> '[...]'
   LIMIT 100;
   

Effectuer un nettoyage

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

   accéder aux clusters

2. Dans la colonne Nom de ressource, cliquez sur le nom de votre cluster, my-cluster.

3. Cliquez sur Supprimer le cluster.

4. Dans Delete cluster my-cluster, saisissez my-cluster pour confirmer que vous souhaitez supprimer votre cluster.

5. Cliquez sur Supprimer.

6. Si vous avez créé une connexion privée lorsque vous avez créé un cluster, accédez à la page Réseau de la console Google Cloud , puis cliquez sur Supprimer le réseau VPC.

Étapes suivantes

• Découvrez des cas d'utilisation concrets de la recherche vectorielle.
• Faites vos premiers pas avec les embeddings vectoriels à l'aide d'AlloyDB AI.
• Découvrez comment créer des applications d'IA générative à l'aide d'AlloyDB AI.
• Créez un index ScaNN.
• Ajustez vos index ScaNN.
• Découvrez comment créer un assistant d'achat intelligent avec AlloyDB, pgvector et la gestion des points de terminaison de modèles.
• Résolvez les erreurs à l'aide de l'explorateur de journaux.