Utiliser des représentations vectorielles continues

Cette page explique comment utiliser Cloud SQL pour PostgreSQL pour effectuer les actions suivantes :

  • Générer et stocker des représentations vectorielles continues basées sur un modèle

  • Indexer et interroger des représentations vectorielles continues à l'aide de l'extension pgvector.

Pour en savoir plus, consultez la page Créer des applications d'IA générative à l'aide de Cloud SQL.

Cloud SQL vous permet d'utiliser un modèle de représentation vectorielle continue hébergé par Vertex AI pour traduire une chaîne de texte en représentation vectorielle continue, qui est la représentation par le modèle de la signification sémantique du texte donné en tant que vecteur numérique.

Cloud SQL implémente les représentations vectorielles continues sous forme de tableaux de valeurs real. Cela vous permet d'utiliser des représentations vectorielles continues générées en tant qu'entrées pour les fonctions de l'extension pgvector.

Avant de commencer

Certaines exigences varient selon que vous souhaitez utiliser Cloud SQL pour générer des représentations vectorielles continues, ou que vous devez simplement exploiter des représentations vectorielles continues qui sont stockées dans votre base de données, à partir d'une autre source.

Restrictions régionales

Pour générer des représentations vectorielles continues avec Cloud SQL, votre instance doit se trouver dans la région us-central1. Le modèle Vertex AI que Cloud SQL peut utiliser pour les représentations vectorielles continues, textembedding-gecko, est situé dans cette région.

Extensions de base de données requises

Pour utiliser des représentations vectorielles continues, vous devez avoir installé l'extension google_ml_integration, version 1.2 ou ultérieure, sur votre instance Cloud SQL.

Si vous souhaitez stocker ces représentations vectorielles continues, et utiliser sur celles-ci des fonctions vectorielles et des opérateurs, vous aurez également besoin de l'extension pgvector.

Cloud SQL inclut ces deux extensions. Vous pouvez les installer sur n'importe quelle base de données de votre instance. Pour en savoir plus, consultez la section Configurer des extensions PostgreSQL.

Configurer l'accès au modèle

Avant de pouvoir générer des représentations vectorielles continues à partir d'une instance Cloud SQL, vous devez configurer Cloud SQL pour qu'il fonctionne avec un modèle de représentation vectorielle continue de texte.

Pour utiliser le modèle cloud textembeddings-gecko, vous devez intégrer Cloud SQL à Vertex AI.

Autoriser les utilisateurs de la base de données à générer des représentations vectorielles continues

Accordez aux utilisateurs de la base de données l'autorisation d'utiliser la fonction embedding pour exécuter des prédictions :

  1. Connectez un client psql à l'instance principale, comme décrit dans la section Se connecter à l'aide d'un client psql.

  2. À l'invite de commande psql, connectez-vous à la base de données et accordez les autorisations :

    \c DB_NAME

GRANT EXECUTE ON FUNCTION embedding TO USER_NAME;

    Remplacez les éléments suivants :

    • DB_NAME : nom de la base de données pour laquelle vous accordez des autorisations.

    • USER_NAME : nom de l'utilisateur auquel vous accordez des autorisations.

Générer des représentations vectorielles continues

Cloud SQL fournit une fonction qui vous permet de traduire du texte en une représentation vectorielle continue. Vous pouvez ensuite stocker cette représentation vectorielle continue dans votre base de données en tant que données vectorielles, et éventuellement utiliser des fonctions pgvector pour exécuter des requêtes sur ces données vectorielles.

Générer une représentation vectorielle continue

Pour générer une représentation vectorielle continue à l'aide de Cloud SQL, utilisez la fonction embedding() fournie par l'extension google_ml_integration :

SELECT embedding( 'MODEL_IDVERSION_TAG', 'TEXT');

Effectuez les remplacements suivants :

  • MODEL_ID : ID du modèle à interroger.

    Si vous utilisez la plate-forme Vertex AI Model Garden, spécifiez textembedding-gecko ou
    textembedding-gecko-multilingual. Il s'agit des modèles cloud que Cloud SQL peut utiliser pour les représentations vectorielles continues de texte. Pour en savoir plus, consultez la page Représentations vectorielles continues de texte.

  • VERSION_TAG (facultatif) : tag tde version du modèle à interroger. Ajoutez le préfixe @ au tag.

    Si vous utilisez l'un des modèles textembedding-gecko avec Vertex AI, spécifiez l'un des tags de version listés dans la section Versions de modèle.

  • TEXT : texte à traduire en représentation vectorielle continue.

L'exemple suivant utilise la version 001 du modèle textembedding-gecko pour générer une représentation vectorielle continue basée sur une chaîne littérale fournie :

SELECT embedding( 'textembedding-gecko@001', 'Cloud SQL is a managed, cloud-hosted SQL database service.');

Stocker une représentation vectorielle continue générée

La valeur renvoyée par la fonction embedding() est un tableau de valeurs real. Pour stocker cette valeur dans une table, ajoutez une colonne real[] :

ALTER TABLE TABLE ADD COLUMN EMBEDDING_COLUMN real[DIMENSIONS];

Effectuez les remplacements suivants :

  • TABLE : nom de la table

  • EMBEDDING_COLUMN : nom de la nouvelle colonne de représentations vectorielles continues

  • DIMENSIONS : nombre de dimensions acceptées par le modèle

    Si vous utilisez l'un des modèles textembedding-gecko avec Vertex AI, spécifiez la valeur 768.

Si vous avez installé l'extension pgvector, vous pouvez éventuellement stocker les représentations vectorielles continues sous la forme de valeurs vector :

ALTER TABLE TABLE ADD COLUMN EMBEDDING_COLUMN vector(DIMENSIONS);

Après avoir créé une colonne pour stocker des représentations vectorielles continues, vous pouvez la renseigner en fonction des valeurs déjà stockées dans une autre colonne de la même table :

UPDATE TABLE SET EMBEDDING_COLUMN = embedding('MODEL_IDVERSION_TAG', SOURCE_TEXT_COLUMN);

Effectuez les remplacements suivants :

  • TABLE : nom de la table.

  • EMBEDDING_COLUMN : nom de la colonne de représentations vectorielles continues.

  • MODEL_ID : ID du modèle à interroger.

    Si vous utilisez la plate-forme Vertex AI Model Garden, spécifiez textembedding-gecko ou
    textembedding-gecko-multilingual. Il s'agit des modèles cloud que Cloud SQL peut utiliser pour les représentations vectorielles continues de texte. Pour en savoir plus, consultez la page Représentations vectorielles continues de texte.

  • VERSION_TAG (facultatif) : tag de version du modèle à interroger. Ajoutez le préfixe @ au tag.

    Si vous utilisez l'un des modèles textembedding-gecko avec Vertex AI, spécifiez l'un des tags de version listés dans la section Versions de modèle.

  • SOURCE_TEXT_COLUMN : nom de la colonne qui stocke le texte, qui sera traduit en représentations vectorielles continues.

La commande précédente fonctionne à la fois pour les colonnes de représentations vectorielles continues real[] et vector. Si votre colonne de représentations vectorielles continues est de type vector, Cloud SQL convertit implicitement la valeur renvoyée par embedding(), partant d'un tableau real pour obtenir une valeur vector.

L'exemple suivant utilise la version 001 du modèle textembedding-gecko pour renseigner la colonne messages.message_vector avec des représentations vectorielles continues en fonction du contenu de la colonne messages.message :

UPDATE messages SET message_vector = embedding( 'textembedding-gecko@001', message);

Interroger et indexer des représentations vectorielles continues à l'aide de pgvector

L'extension PostgreSQL pgvector vous permet d'utiliser des opérateurs et des fonctions spécifiques aux vecteurs lorsque vous stockez, indexez et interrogez des représentations vectorielles continues de texte dans votre base de données. Cloud SQL dispose de ses propres optimisations pour exploiter l'extension pgvector, ce qui vous permet de créer des index pouvant accélérer les requêtes impliquant des représentations vectorielles continues.

Créer un index des plus proches voisins optimisé

L'extension pgvector est compatible avec la recherche des plus proches voisins approximatifs via l'indexation. Cloud SQL étend cette compatibilité avec une fonctionnalité de quantification scalaire, que vous pouvez spécifier lorsque vous créez un index. Lorsque vous activez cette fonctionnalité, la quantification scalaire peut accélérer les requêtes ayant des vecteurs dimensionnels plus importants. En outre, cette fonctionnalité vous permet de stocker des vecteurs comportant jusqu'à 8 000 dimensions.

Pour activer la quantification scalaire sur un index basé sur l'extension pgvector, spécifiez ivf comme méthode d'index et SQ8 comme quantificateur :

CREATE INDEX ON TABLE
  USING ivf (EMBEDDING_COLUMN DISTANCE_FUNCTION)
  WITH (lists = LIST_COUNT, quantizer = 'SQ8');

Effectuez les remplacements suivants :

  • TABLE : table à laquelle vous ajoutez l'index.

  • EMBEDDING_COLUMN : colonne qui stocke les données vector.

  • DISTANCE_FUNCTION : fonction de distance à utiliser avec cet index. Choisissez l'une des options suivantes :

    • Distance L2 : vector_l2_ops

    • Produit interne : vector_ip_ops

    • Distance de cosinus : vector_cosine_ops

  • LIST_COUNT : nombre de listes à utiliser avec cet index.

Pour créer cet index sur une colonne de représentations vectorielles continues qui utilise le type de données real[] au lieu de vector, convertissez la colonne en type de données vector :

CREATE INDEX ON TABLE
  USING ivf ((CAST(EMBEDDING_COLUMN AS vector(DIMENSIONS)))'}} DISTANCE_FUNCTION)
  WITH (lists = LIST_COUNT, quantizer = 'SQ8');

Remplacez DIMENSIONS par la largeur dimensionnelle de la colonne de représentations vectorielles continues.

La section suivante présente un exemple de ce type d'index.

Envoyer une requête de type plus proches voisins avec un texte donné

Une fois que vous avez stocké et indexé les représentations vectorielles continues dans votre base de données, toutes les fonctionnalités de requête pgvector sont à votre disposition.

Pour trouver les plus proches voisins sémantiques d'un texte, utilisez la fonction embedding() pour traduire le texte en vecteur. Dans la même requête, appliquez ce vecteur à l'opérateur pgvector correspondant aux plus proches voisins, <->, afin de rechercher les lignes de la base de données présentant les représentations vectorielles continues les plus similaires sur le plan de la sémantique.

Comme embedding() renvoie un tableau real, vous devez convertir l'appel embedding() en type de données vector pour utiliser ces valeurs avec les opérateurs pgvector.

  SELECT RESULT_COLUMNS FROM TABLE
    ORDER BY EMBEDDING_COLUMN
    <-> embedding('MODEL_IDVERSION_TAG', 'TEXT')::vector
    LIMIT ROW_COUNT

Effectuez les remplacements suivants :

  • RESULT_COLUMNS : colonnes à afficher à partir de lignes sémantiquement similaires.

  • TABLE : table contenant la représentation vectorielle continue à laquelle vous comparez le texte.

  • EMBEDDING_COLUMN : colonne contenant les représentations vectorielles continues stockées.

  • MODEL_ID : ID du modèle à interroger.

    Si vous utilisez la plate-forme Vertex AI Model Garden, spécifiez textembedding-gecko ou
    textembedding-gecko-multilingual. Il s'agit des modèles cloud que Cloud SQL peut utiliser pour les représentations vectorielles continues de texte. Pour en savoir plus, consultez la page Représentations vectorielles continues de texte.

  • VERSION_TAG (facultatif) : tag de version du modèle à interroger. Ajoutez le préfixe @ au tag.

    Si vous utilisez l'un des modèles textembedding-gecko avec Vertex AI, spécifiez l'un des tags de version listés dans la section Versions de modèle.

  • TEXT : texte sur la base duquel vous souhaitez trouver les plus proches voisins sémantiques qui sont stockés.

  • ROW_COUNT : nombre de lignes à afficher. Si vous souhaitez n'obtenir que la meilleure correspondance, spécifiez 1 comme valeur pour ce paramètre.

Pour exécuter cette requête avec une colonne de représentations vectorielles continues stockées qui utilise le type de données real[] au lieu de vector, convertissez la colonne en type de données vector :

  SELECT RESULT_COLUMNS::vector FROM TABLE
    ORDER BY EMBEDDING_COLUMN
    <-> embedding('MODEL_IDVERSION_TAG', 'TEXT')::vector
    LIMIT ROW_COUNT

Utiliser des tags de version de modèle pour éviter les erreurs

Google vous recommande vivement de toujours utiliser une version stable du modèle de représentations vectorielles continues que vous avez choisi. Pour la plupart des modèles, cela signifie définir explicitement un tag de version.

Le fait d'appeler la fonction embedding() sans spécifier de tag de version du modèle est certes valide d'un point de vue syntaxique, mais cela peut également entraîner des erreurs.

Si vous omettez le tag de version lorsque vous utilisez un modèle sur la plate-forme Vertex AI Model Garden, Vertex AI va utiliser la dernière version en date du modèle. Il ne s'agit peut-être pas de la dernière version stable. Pour en savoir plus sur les versions de modèle Vertex AI disponibles, consultez la section Versions de modèle.

Une version donnée de modèle Vertex AI renvoie toujours la même réponse embedding() à une entrée de texte donnée. Si vous ne spécifiez pas de versions de modèle dans vos appels à embedding(), une nouvelle version de modèle publiée peut modifier soudainement le vecteur renvoyé pour une entrée donnée. Cela peut entraîner des erreurs ou d'autres comportements inattendus dans vos applications.

Pour éviter ces problèmes, spécifiez toujours la version du modèle.

Étapes suivantes