Utiliser des embeddings

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

  • Générer et stocker des embeddings basées sur un modèle

  • Indexer et interroger des embeddings à 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 d'embedding hébergé par Vertex AI pour traduire une chaîne de texte en embedding, 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 embeddings sous forme de tableaux de valeurs real. Cela vous permet d'utiliser des embeddings 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 embeddings, ou que vous devez simplement exploiter des embeddings qui sont stockées dans votre base de données, à partir d'une autre source.

Restrictions régionales

Pour générer des embeddings avec Cloud SQL, votre instance doit se trouver dans une région où generative AI foundational models are supported. Les modèles Vertex AI text-embedding et textembedding-gecko que Cloud SQL peut utiliser pour les embeddings sont situés dans cette région.

Extensions de base de données requises

Pour utiliser des embeddings, 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 embeddings, 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 embeddings à partir d'une instance Cloud SQL, vous devez configurer Cloud SQL pour qu'il fonctionne avec un modèle d'embedding de texte.

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

Autoriser les utilisateurs de la base de données à générer des embeddings

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 embeddings

Cloud SQL fournit une fonction qui vous permet de traduire du texte en un embedding vectoriel. Vous pouvez ensuite stocker cet embedding 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 un embedding

Pour générer un embedding à 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 text-embedding-004 ou
    text-multilingual-embedding-002. Il s'agit des modèles cloud que Cloud SQL peut utiliser pour les embeddings de texte. Pour en savoir plus, consultez Embeddings de texte.

  • VERSION_TAG (facultatif) : tag de version du modèle à interroger. Pour les versions de textembedding-gecko antérieures à text-embedding-004 ou text-multilingual-embedding-002, Prepend the tag with@.

    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 embedding vectoriel.

L'exemple suivant utilise le modèle text-embedding-004 pour générer un embedding basé sur une chaîne littérale fournie :

SELECT embedding( 'text-embedding-004', 'Cloud SQL is a managed, cloud-hosted SQL database service.');

Stocker un embedding généré

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 d'embeddings

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

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

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

ALTER TABLE TABLE ADD COLUMN EMBEDDING_COLUMN vector(DIMENSIONS);

Après avoir créé une colonne pour stocker des embeddings, 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 d'embeddings.

  • MODEL_ID : ID du modèle à interroger.

    Si vous utilisez la plate-forme Vertex AI Model Garden, spécifiez text-embedding-004 ou
    text-multilingual-embedding-002. Il s'agit des modèles cloud que Cloud SQL peut utiliser pour les embeddings de texte. Pour en savoir plus, consultez Embeddings de texte.

  • VERSION_TAG (facultatif) : tag de version du modèle à interroger. Pour les versions de textembedding-gecko antérieures à text-embedding-004 ou text-multilingual-embedding-002, Prepend the tag with@.

    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 embeddings.

La commande précédente fonctionne à la fois pour les colonnes d'embeddings real[] et vector. Si votre colonne d'embeddings 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 le modèle text-embedding-004 pour renseigner la colonne messages.message_vector avec des embeddings en fonction du contenu de la colonne messages.message :

UPDATE messages SET message_vector = embedding( 'text-embedding-004', message);

Interroger et indexer des embeddings à 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 embeddings 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 embeddings.

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 d'embeddings 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 d'embeddings.

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 embeddings 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 embeddings 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 l'embedding auquel vous comparez le texte.

  • EMBEDDING_COLUMN : colonne contenant les embeddings stockées.

  • MODEL_ID : ID du modèle à interroger.

    Si vous utilisez la plate-forme Vertex AI Model Garden, spécifiez text-embedding-004 ou
    text-embedding-multilingual-002. Il s'agit des modèles cloud que Cloud SQL peut utiliser pour les embeddings de texte. Pour en savoir plus, consultez Embeddings 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 d'embeddings 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 d'embeddings 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