Générer des embeddings vectoriels pour des données textuelles de manière groupée à l'aide d'une instruction LMD partitionnée

Ce document explique comment générer et remplir en bloc des embeddings vectoriels pour des données textuelles (STRING ou JSON) stockées dans Spanner à l'aide de SQL et des modèles d'embedding textuel Gemini Enterprise Agent Platform.

Prérequis

Vous devez disposer d'une table dans votre base de données Spanner contenant des données textuelles (STRING ou JSON). Pour en savoir plus sur l'importation de données, consultez la présentation de l'importation et de l'exportation Spanner.

Exemple d'utilisation

Supposons que vous disposiez d'une table dans Spanner avec le schéma suivant. Cette table contient des millions d'enregistrements.

CREATE TABLE Products (
  product_id INT64 NOT NULL,
  name STRING(MAX),
  description STRING(MAX)
) PRIMARY KEY(product_id);

CREATE TABLE Products (
  product_id INT8 NOT NULL,
  name TEXT,
  description TEXT,
  PRIMARY KEY(product_id)
);

Votre objectif est de générer des embeddings vectoriels pour la colonne description de cette table afin de trouver des articles similaires à recommander aux clients pour améliorer leur expérience d'achat à l'aide de la recherche vectorielle.

Enregistrer un modèle d'embedding

CREATE MODEL MODEL_NAME
INPUT(
  content STRING(MAX)
)
OUTPUT(
  embeddings STRUCT<values ARRAY<FLOAT32>>
)
REMOTE OPTIONS(
    endpoint = '//aiplatform.googleapis.com/projects/PROJECT/locations/LOCATION/publishers/google/models/$MODEL_NAME',
  default_batch_size = 5
)

Pour connaître les bonnes pratiques, tenez compte des éléments suivants :

• Pour maintenir l'isolation des quotas, utilisez un point de terminaison dans un autre projet pour générer et remplir des embeddings que le point de terminaison de production. Réservez le point de terminaison de production pour diffuser le trafic de production.
• Assurez-vous que le point de terminaison du modèle est compatible avec la valeur de default_batch_size. Vous pouvez remplacer default_batch_size par l'indicateur de requête @{remote_udf_max_rows_per_rpc=NEW_NUMBER}. Pour en savoir plus sur la default_batch_size limite pour chaque région, consultez Obtenir des embeddings textuels pour un extrait de texte.
• Définissez le point de terminaison avec une version de modèle spécifique (par exemple, @003) au lieu de @latest. En effet, les vecteurs d'embedding générés pour le même élément de texte peuvent différer selon la version du modèle que vous utilisez. C'est pourquoi vous devez éviter d'utiliser différentes versions de modèle pour générer des embeddings dans le même ensemble de données. De plus, la mise à jour de la version du modèle dans l'instruction de définition du modèle ne met pas à jour les embeddings déjà générés avec ce modèle. Pour gérer la version du modèle pour les embeddings, vous pouvez créer une colonne supplémentaire dans la table qui stocke la version du modèle.
• Les modèles d'embedding textuel personnalisés ne sont pas compatibles avec les fonctions GoogleSQL ML.PREDICT et PostgreSQL spanner.ML_PREDICT_ROW.

Tester l'intégration de bout en bout du modèle d'embeddings

Vous pouvez exécuter une requête pour vérifier que le modèle d'embeddings est correctement configuré et que les embeddings sont récupérés. Par exemple, exécutez la requête suivante :

SELECT embeddings.values
FROM SAFE.ML.PREDICT(
  MODEL MODEL_NAME,
  (SELECT description AS content FROM products LIMIT 10)
);

SELECT spanner.ML_PREDICT_ROW(
    'projects/PROJECT/locations/LOCATION/publishers/google/models/$MODEL_NAME',
    JSONB_BUILD_OBJECT('instances', JSONB_BUILD_ARRAY(JSONB_BUILD_OBJECT('content', description))))
FROM Products
LIMIT 10;

Mettre à jour la table source pour inclure des colonnes supplémentaires afin de stocker les embeddings

Ensuite, mettez à jour le schéma de la table source pour inclure une colonne supplémentaire du type de données ARRAY<FLOAT32> afin de stocker les embeddings générés :

ALTER TABLE TABLE_NAME
ADD COLUMN EMBEDDING_COLUMN_NAME ARRAY<FLOAT32>;

ALTER TABLE TABLE_NAME
ADD COLUMN EMBEDDING_COLUMN_NAME real[];

Par exemple, en utilisant l'exemple de table products, exécutez :

ALTER TABLE Products
ADD COLUMN desc_embed ARRAY<FLOAT32>;

ALTER TABLE Products
ADD COLUMN desc_embed real[];

Vous pouvez ajouter une autre colonne pour gérer la version du modèle d'embeddings.

ALTER TABLE Products
ADD COLUMN desc_embed_model_version INT64;

ALTER TABLE Products
ADD COLUMN desc_embed_model_version INT8;

Augmenter le quota pour Agent Platform

Vous devrez peut-être augmenter le quota de l'API Agent Platform pour la région qui utilise le modèle d'embedding textuel. Pour demander une augmentation, consultez Augmenter le quota Agent Platform.

Remplir les embeddings

Enfin, exécutez l'instruction UPDATE suivante à l'aide du LMD partitionné pour générer des embeddings pour la colonne de données textuelles et stocker les embeddings dans votre base de données. Vous pouvez stocker la version du modèle avec les embeddings. Nous vous recommandons d'exécuter cette requête pendant une période de faible trafic dans votre base de données.

UPDATE TABLE_NAME
SET
  TABLE_NAME.EMBEDDING_COLUMN_NAME = (
    SELECT embeddings.values
    FROM SAFE.ML.PREDICT(
      MODEL MODEL_NAME,
      (SELECT TABLE_NAME.DATA_COLUMN_NAME AS content)
    ) @{remote_udf_max_rows_per_rpc=MAX_ROWS}
  ),
  TABLE_NAME.EMBEDDING_VERSION_COLUMN = MODEL_VERSION
WHERE FILTER_CONDITION;

UPDATE TABLE_NAME
SET
  EMBEDDING_COLUMN_NAME = spanner.FLOAT32_ARRAY(spanner.ML_PREDICT_ROW(
    'projects/PROJECT/locations/LOCATION/publishers/google/models/$MODEL_NAME',
    JSONB_BUILD_OBJECT('instances', JSONB_BUILD_ARRAY(JSONB_BUILD_OBJECT('content', DATA_COLUMN_NAME)))
  ) /*@ remote_udf_max_rows_per_rpc=MAX_ROWS */ ->'predictions'->0->'embeddings'->'values'),
  EMBEDDING_VERSION_COLUMN = MODEL_VERSION
WHERE FILTER_CONDITION;

Exemple de requête de remplissage pour la table products :

UPDATE products
SET
  products.desc_embed = (
    SELECT embeddings.values
    FROM SAFE.ML.PREDICT(
      MODEL embedding_model,
      (SELECT products.description AS content)
    ) @{remote_udf_max_rows_per_rpc=200}
  ),
  products.desc_embed_model_version = 3
WHERE products.desc_embed IS NULL;

UPDATE products
SET
  desc_embed = spanner.FLOAT32_ARRAY(spanner.ML_PREDICT_ROW(
    'projects/PROJECT/locations/LOCATION/publishers/google/models/$MODEL_NAME',
    JSONB_BUILD_OBJECT('instances', JSONB_BUILD_ARRAY(JSONB_BUILD_OBJECT('content', description)))
  ) /*@ remote_udf_max_rows_per_rpc=200 */ ->'predictions'->0->'embeddings'->'values'),
  desc_embed_model_version = 3
WHERE desc_embed IS NULL;

Pour connaître les bonnes pratiques, tenez compte des éléments suivants :

• Le délai d'expiration gRPC par défaut pour l'API Spanner est d'une heure. En fonction du nombre d'embeddings que vous remplissez, vous devrez peut-être augmenter ce délai d'expiration pour vous assurer que le LMD partitionné UPDATE dispose de suffisamment de temps pour se terminer. Pour en savoir plus, consultez Configurer des délais d'expiration et des nouvelles tentatives personnalisés.

Performances et autres considérations

Tenez compte des éléments suivants pour optimiser les performances lors du remplissage des données d'embeddings.

Nombre de nœuds

Le LMD partitionné exécute l'instruction LMD donnée sur différentes partitions en parallèle. Pour les instances comportant un nombre élevé de nœuds, vous pouvez observer des erreurs de quota lors de l'exécution du LMD partitionné. Si les requêtes d'API Agent Platform sont limitées en raison des limites de quota de l'API Agent Platform, alors Spanner retente ces échecs en mode de transaction LMD partitionné jusqu'à 20 fois. Si vous constatez un taux élevé d'erreurs de quota dans Agent Platform, alors augmentez le quota pour Agent Platform. Vous pouvez également ajuster le parallélisme à l'aide de l'indicateur au niveau de l'instruction @{pdml_max_parallelism=DESIRED_NUMBER} lorsque vous utilisez GoogleSQL. L'exemple suivant définit le parallélisme sur "5" :

@{pdml_max_parallelism=5} UPDATE products
SET products.desc_embed =(
  SELECT embeddings.values
  FROM SAFE.ML.PREDICT(MODEL embedding_model, (
        SELECT products.value AS CONTENT
        )
  )
      @{remote_udf_max_rows_per_rpc=200}
),
products.desc_embed_model_version = MODEL_VERSION
WHERE products.desc_embed IS NULL;

Taille du texte dans la colonne de données

Le modèle d'embeddings Agent Platform est limité au nombre maximal de jetons pour chaque entrée de texte. Les limites de jetons varient selon les versions du modèle. Chaque requête Agent Platform peut comporter plusieurs champs de texte d'entrée, mais le nombre maximal de jetons présents dans une seule requête est limité. Pour les bases de données GoogleSQL, si vous rencontrez une erreur INVALID_ARGUMENT avec le message "Request is too large" (La requête est trop volumineuse), essayez de réduire la taille du lot pour éviter l'erreur. Pour ce faire, vous pouvez configurer default_batch_size ou utiliser l'indicateur de requête @{remote_udf_max_outstanding_rpcs} lors de l'enregistrement du modèle.

Nombre de requêtes API envoyées à Agent Platform

Vous pouvez utiliser l'indicateur de requête @{remote_udf_max_outstanding_rpcs} pour augmenter ou diminuer le nombre de requêtes envoyées à Agent Platform depuis Spanner. Sachez que l'augmentation de cette limite peut accroître l'utilisation du processeur et de la mémoire de l'instance Spanner. Pour les bases de données GoogleSQL, l'utilisation de cet indicateur de requête remplace le default_batch_size configuré pour votre modèle.

Surveiller la progression du remplissage

Vous pouvez surveiller le nombre de requêtes, la latence et les octets réseau envoyés à Agent Platform depuis Spanner à l'aide du tableau de bord des insights système.

Étape suivante

• Découvrez comment effectuer une recherche vectorielle de similarité en recherchant les k plus proches voisins.
• Pour en savoir plus sur le machine learning et les embeddings, consultez notre cours intensif sur les embeddings.
• En savoir plus sur les modèles d'embedding textuel Agent Platform.