Obtenir des embeddings textuels Agent Platform

Cette page explique comment utiliser l'API Gemini Enterprise Agent Platform text embedding pour générer, stocker et mettre à jour des embeddings textuels pour les données stockées dans Spanner pour les bases de données utilisant le dialecte GoogleSQL et celles utilisant le dialecte PostgreSQL.

Un embedding textuel est une représentation vectorielle de données textuelles, qui est utilisé de nombreuses manières pour trouver des éléments similaires. Vous interagissez avec ces représentations chaque fois que vous effectuez une recherche Google ou consultez des recommandations lorsque vous faites des achats en ligne. Lorsque vous créez des embeddings textuels, vous obtenez des représentations vectorielles de texte naturel sous forme de tableaux de nombres à virgule flottante. Cela signifie que tout le texte d'entrée se voit attribuer une représentation numérique. En comparant la distance numérique entre les représentations vectorielles de deux éléments de texte, une application peut déterminer la similarité entre le texte ou les objets représentés par le texte.

L'API d'embeddings textuels Agent Platform vous permet de créer un embedding textuel avec l'IA générative. Dans ce tutoriel, vous allez utiliser le modèle d'embedding textuel Agent Platform pour générer des embeddings textuels pour les données stockées dans Spanner.

Pour en savoir plus sur les embeddings textuels et les modèles compatibles, consultez Obtenir des embeddings textuels.

Objectif

Dans ce tutoriel, vous allez apprendre à effectuer les opérations suivantes :

  • Enregistrez un modèle d'embedding textuel Agent Platform dans un schéma Spanner à l'aide d'instructions LDD.
  • Référencez le modèle enregistré à l'aide de requêtes SQL pour générer des embeddings à partir des données stockées dans Spanner.

Tarifs

Ce tutoriel fait appel à des composants payants de Google Cloud, y compris :

  • Spanner
  • Agent Platform

Pour en savoir plus sur les coûts de Spanner, consultez la page Tarifs de Spanner.

Pour en savoir plus sur les coûts d'Agent Platform, consultez la page Tarifs d'Agent Platform.

Générer et stocker des embeddings textuels

Selon le modèle que vous utilisez, la génération d'embeddings peut prendre un certain temps. Pour les charges de travail plus sensibles aux performances, il est recommandé d'éviter de générer des embeddings dans les transactions en lecture-écriture. Générez plutôt les embeddings dans une transaction en lecture seule à l'aide des exemples SQL suivants.

GoogleSQL

Enregistrer un modèle d'embeddings textuels dans Spanner

En GoogleSQL, vous devez enregistrer un modèle avant de l'utiliser avec la fonction ML.PREDICT. Pour enregistrer le modèle d'embedding textuel Agent Platform dans une base de données Spanner, exécutez l'instruction LDD suivante :

CREATE MODEL MODEL_NAME
INPUT(
  content STRING(MAX),
  -- Optional: For models that support specifying task type.
  task_type STRING(MAX),
)
OUTPUT(
  embeddings
    STRUCT<
      statistics STRUCT<truncated BOOL, token_count FLOAT64>,
      values ARRAY<FLOAT64>>
)
REMOTE OPTIONS (
  endpoint = '//aiplatform.googleapis.com/projects/PROJECT/locations/LOCATION/publishers/google/models/$MODEL_NAME'
);

Remplacez les éléments suivants :

  • MODEL_NAME : nom du modèle d'embedding textuel Agent Platform.
  • PROJECT : projet hébergeant le point de terminaison Agent Platform
  • LOCATION : emplacement du point de terminaison Agent Platform.

Spanner accorde automatiquement les autorisations appropriées. Si ce n'est pas le cas, vérifiez le contrôle des accès au point de terminaison du modèle.

La découverte et la validation de schémas ne sont pas disponibles pour les modèles d'IA générative. Vous devez fournir des clauses INPUT et OUTPUT qui correspondent au schéma du modèle. Pour obtenir le schéma complet du modèle d'embedding textuel, consultez Obtenir des embeddings textuels.

Générer des embeddings textuels

Pour générer des embeddings, transmettez un extrait de texte directement à la fonction ML.PREDICT à l'aide du code SQL suivant :

SELECT embeddings.values
FROM ML.PREDICT(
  MODEL MODEL_NAME,
  (SELECT "A product description" as content)
);

Pour générer des embeddings pour les données stockées dans une table, utilisez le code SQL suivant :

SELECT id, embeddings.values
FROM ML.PREDICT(
  MODEL MODEL_NAME,
  (SELECT id, description as content FROM Products)
);

Pour spécifier le type de tâche et les dimensions de sortie :

UPDATE Products p
SET description_embedding = (
  SELECT embeddings.values
  FROM ML.PREDICT(
    MODEL MODEL_NAME,
    (SELECT p.description as content, "RETRIEVAL_DOCUMENT" as task_type),
    STRUCT(768 AS outputDimensionality)
  ));

SELECT p.product_id, p.name, p.description, COSINE_DISTANCE(
    p.description_embedding,
    (
      SELECT embeddings.values 
      FROM ML.PREDICT(
        MODEL MODEL_NAME,
        (SELECT @user_query as content, "RETRIEVAL_QUERY" as task_type),
        STRUCT(768 AS outputDimensionality)
      ) 
    )
  ) AS distance
FROM Products p
ORDER BY distance
LIMIT 5;

Stocker des embeddings textuels

Après avoir généré les embeddings dans une transaction en lecture seule, stockez-les dans Spanner afin de pouvoir les gérer avec vos données opérationnelles. Pour stocker les embeddings, utilisez une transaction en lecture-écriture.

Pour les charges de travail moins sensibles aux performances, vous pouvez générer et insérer des embeddings avec le code SQL suivant dans une transaction en lecture-écriture. La spécification de vector_length est facultative pour stocker des embeddings, recommandée pour la recherche KNN et requise pour les index vectoriels. Remplacez VECTOR_LENGTH par la dimension de sortie de votre modèle, par exemple 3072 ou 768, ou omettez vector_length si la colonne stocke des vecteurs de dimensions variables :

CREATE TABLE Products(
  id INT64 NOT NULL,
  description STRING(MAX),
  embeddings ARRAY<FLOAT32>(vector_length=>VECTOR_LENGTH),
) PRIMARY KEY(id);

INSERT INTO Products (id, description, embeddings)
SELECT @Id, @Description, embeddings.values
FROM ML.PREDICT(
  MODEL MODEL_NAME,
  (SELECT @Description as content)
);

PostgreSQL

Générer des embeddings textuels

Pour générer des embeddings, transmettez un extrait de texte directement à la fonction spanner.ML_PREDICT_ROW à l'aide du code SQL suivant :

SELECT
  spanner.ML_PREDICT_ROW(
    'projects/PROJECT/locations/LOCATION/publishers/google/models/$MODEL_NAME',
    '{"instances": [{"content": "A product description"}]}'::jsonb
  ) ->'predictions'->0->'embeddings'->'values';

Remplacez les éléments suivants :

  • PROJECT : projet hébergeant le point de terminaison Agent Platform
  • LOCATION : emplacement du point de terminaison Agent Platform.
  • MODEL_NAME : nom du modèle d'embedding textuel Agent Platform.

Pour générer des embeddings pour les données stockées dans une table, utilisez le code SQL suivant :

SELECT id, 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))))
  ) -> 'predictions'->0->'embeddings'->'values'
FROM Products;

Remplacez les éléments suivants :

  • PROJECT : projet hébergeant le point de terminaison Agent Platform
  • LOCATION : emplacement du point de terminaison Agent Platform.
  • MODEL_NAME : nom du modèle d'embedding textuel Agent Platform.

Pour spécifier le type de tâche et les dimensions de sortie :

UPDATE Products p
SET description_embedding = spanner.float64_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', p.description,
          'task_type', 'RETRIEVAL_DOCUMENT'
        )
      ),
      'parameters', JSONB_BUILD_OBJECT('outputDimensionality', 768)
    )
  )->'predictions'->0->'embeddings'->'values'
);

SELECT p.product_id, p.name, p.description, spanner.COSINE_DISTANCE(
    p.description_embedding,
    spanner.float64_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', $1,
              'task_type', 'RETRIEVAL_QUERY'
            )
          ),
          'parameters', JSONB_BUILD_OBJECT('outputDimensionality', 768)
        )
      )->'predictions'->0->'embeddings'->'values'
    )
  ) AS distance
FROM Products p
ORDER BY distance
LIMIT 5;

Remplacez les éléments suivants :

  • PROJECT : projet hébergeant le point de terminaison Agent Platform
  • LOCATION : emplacement du point de terminaison Agent Platform.
  • MODEL_NAME : nom du modèle d'embedding textuel Agent Platform.

Stocker des embeddings textuels

Après avoir généré les embeddings dans une transaction en lecture seule, stockez-les dans Spanner afin de pouvoir les gérer avec vos données opérationnelles. Pour stocker les embeddings, utilisez une transaction en lecture-écriture.

Pour les charges de travail moins sensibles aux performances, vous pouvez générer et insérer des embeddings avec le code SQL suivant dans une transaction en lecture-écriture. La spécification de VECTOR LENGTH est facultative pour stocker des embeddings, recommandée pour la recherche KNN et requise pour les index vectoriels. Remplacez VECTOR_LENGTH par la dimension de sortie de votre modèle, par exemple 3072 ou 768, ou omettez VECTOR LENGTH si la colonne stocke des vecteurs de dimensions variables :

CREATE TABLE Products (
  id INT8 NOT NULL,
  description TEXT,
  embeddings REAL[] VECTOR LENGTH VECTOR_LENGTH,
  PRIMARY KEY(id)
);

INSERT INTO Products (id, description, embeddings)
SELECT @Id, @Description, 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)))
  ) -> 'predictions'->0->'embeddings'->'values'
));

Remplacez les éléments suivants :

  • PROJECT : projet hébergeant le point de terminaison Agent Platform
  • LOCATION : emplacement du point de terminaison Agent Platform.
  • MODEL_NAME : nom du modèle d'embedding textuel Agent Platform.

Mettre à jour les embeddings textuels

Pour mettre à jour vos embeddings ou ingérer des données en temps réel, utilisez l'instruction UPDATE (GoogleSQL et PostgreSQL).

Pour mettre à jour la table Products de l'exemple précédent, utilisez le code SQL suivant :

GoogleSQL 

UPDATE Products
SET
  description = @description,
  embeddings = (SELECT embeddings.values
                  FROM ML.PREDICT(MODEL MODEL_NAME, (SELECT @description as content))
              )
WHERE id = @id;

Remplacez les éléments suivants :

  • MODEL_NAME : nom du modèle d'embedding textuel Agent Platform.

PostgreSQL 

UPDATE
  Products
SET
  description = $1,
  embeddings = 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', $1)))
    ) -> 'predictions'->0->'embeddings'->'values')
WHERE
  id = $2;

Remplacez les éléments suivants :

  • PROJECT : projet hébergeant le point de terminaison Agent Platform
  • LOCATION : emplacement du point de terminaison Agent Platform.
  • MODEL_NAME : nom du modèle d'embedding textuel Agent Platform.

Étapes suivantes