Obtén embeddings de texto de Agent Platform

En esta página, se describe cómo usar la API de embedding de texto de Gemini Enterprise Agent Platform para generar, almacenar y actualizar embeddings de texto para los datos almacenados en Spanner para bases de datos de dialecto de GoogleSQL y de PostgreSQL.

Un embedding de texto es una representación vectorial de datos de texto y se usa de muchas maneras para encontrar elementos similares. Interactúas con ellos cada vez que completas una Búsqueda de Google o ves recomendaciones cuando compras en línea. Cuando creas incorporaciones de texto, obtienes representaciones vectoriales de texto natural como arrays de números de punto flotante. Esto significa que todo tu texto de entrada tiene asignada una representación numérica. A través de la comparación de la distancia numérica entre las representaciones vectoriales de dos textos, una aplicación puede determinar la similitud entre el texto o los objetos representados por el texto.

Con la API de embeddings de texto de Agent Platform, puedes crear un embedding de texto con IA generativa. En este instructivo, usarás el modelo de embedding de texto de Agent Platform para generar embeddings de texto para los datos almacenados en Spanner.

Para saber qué modelos y ubicaciones de extremos funcionan con Spanner, consulta Modelos y ubicaciones de extremos compatibles. Para obtener más información sobre los embeddings de texto, consulta Obtén embeddings de texto.

Objetivo

En este instructivo, aprenderás a realizar lo siguiente:

  • Registra un modelo de embedding de texto de Agent Platform en un esquema de Spanner con instrucciones de DDL.
  • Haz referencia al modelo registrado con consultas en SQL para generar embeddings a partir de los datos almacenados en Spanner.

Precios

En este instructivo, se usan componentes facturables de Google Cloud, incluidos los siguientes:

  • Spanner
  • Agent Platform

Para obtener más información sobre los costos de Spanner, consulta la página de precios de Spanner.

Para obtener más información sobre los costos de Agent Platform, consulta la página de precios de Agent Platform.

Modelos y ubicaciones de extremos compatibles

En la ruta de acceso del extremo, especifica un modelo de embedding de texto que use la API de predict de Agent Platform y una ubicación en la que Agent Platform entregue ese modelo. Spanner no aloja modelos de incorporación ni mantiene su propia lista de modelos compatibles. En su lugar, la función ML.PREDICT en GoogleSQL y la función spanner.ML_PREDICT_ROW en PostgreSQL envían cada solicitud de embedding a la API de predict en la ruta del extremo que especifiques.

En la ruta del extremo, Spanner acepta ubicaciones regionales, como us-central1 o europe-west1, las ubicaciones multirregionales us y eu, y la ubicación global. El modelo, no Spanner, determina cuál de estas ubicaciones funciona. La configuración de tu instancia de Spanner no restringe la ubicación del extremo. Para reducir la latencia, elige un extremo en la misma región que tu instancia de Spanner o en el mismo continente para las instancias multirregionales.

Si el extremo se encuentra en una región diferente a la del servidor de Spanner que ejecuta la consulta, pagas por la transferencia de datos entre regiones.

En la siguiente tabla, se enumeran los IDs de modelos de publicador de Agent Platform que usan la API de predict. Usa el ID del modelo del publicador en el segmento publishers/google/models/ de la ruta del extremo.

ID del modelo del publicador Dimensiones de la salida
gemini-embedding-001 Hasta 3,072
text-embedding-005 Hasta 768
text-multilingual-embedding-002 Hasta 768

Todos estos modelos se entregan solo en ubicaciones regionales, como us-central1 o europe-west1. Ninguno de ellos admite las ubicaciones us, eu o global. Para obtener la lista completa de regiones, consulta Ubicaciones de extremos de modelos de Google y selecciona una pestaña regional, como Estados Unidos o Europa. En esa página, gemini-embedding-001 aparece como Gemini Embedding, y text-embedding-005 y text-multilingual-embedding-002 aparecen en Embeddings for Text.

En GoogleSQL, el nombre que le asignas al modelo en la sentencia CREATE MODEL es un identificador de esquema de Spanner que es independiente del ID del modelo del publicador.

Antes de elegir un modelo, verifica su disponibilidad y fecha de retiro en Versiones y ciclo de vida del modelo.

Las funciones ML.PREDICT y spanner.ML_PREDICT_ROW requieren un modelo que use la API de predict. En cambio, el modelo gemini-embedding-2 usa la API de embedContent, por lo que no puedes usarlo con estas funciones. Este modelo también se entrega solo en las ubicaciones global, us y eu. Usa gemini-embedding-001 en su lugar.

En GoogleSQL, la sentencia CREATE MODEL no verifica los extremos predict del publicador cuando registras el modelo. En PostgreSQL, la función spanner.ML_PREDICT_ROW no registra un modelo. En ambos dialectos, un ID, una versión o una ubicación de modelo que Agent Platform no entrega falla en el momento de la consulta con un error NOT_FOUND. En GoogleSQL, una cláusula OUTPUT que no coincide con la respuesta falla con un error INVALID_ARGUMENT. Después de registrar o elegir un modelo, ejecuta una consulta de prueba para confirmar que el modelo y la ubicación funcionen. Para obtener más información, consulta Soluciona problemas de la integración de Spanner Agent Platform.

Genera y almacena embeddings de texto

Según el modelo que uses, la generación de embeddings puede tardar un poco. Para las cargas de trabajo más sensibles al rendimiento, la práctica recomendada es evitar generar incorporaciones en transacciones de lectura y escritura. En su lugar, genera las incorporaciones en una transacción de solo lectura con los siguientes ejemplos de SQL.

GoogleSQL

Registra un modelo de embeddings de texto en Spanner

En GoogleSQL, debes registrar un modelo antes de usarlo con la función ML.PREDICT. Para registrar el modelo de embedding de texto de Agent Platform en una base de datos de Spanner, ejecuta la siguiente instrucción de DDL:

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/PUBLISHER_MODEL_ID'
);

Reemplaza lo siguiente:

  • MODEL_NAME: Es el nombre del modelo en tu esquema de Spanner, como EmbeddingsModel.
  • PROJECT: Es el proyecto que aloja el extremo de Agent Platform.
  • LOCATION: Es la ubicación del extremo de Agent Platform.
  • PUBLISHER_MODEL_ID: Es el ID del modelo de publicador de Modelos y ubicaciones de extremos compatibles, como gemini-embedding-001.

Spanner otorga los permisos adecuados de forma automática. Si no es así, revisa el control de acceso al extremo del modelo.

El descubrimiento y la validación de esquemas no están disponibles para los modelos de IA generativa. Debes proporcionar cláusulas INPUT y OUTPUT que coincidan con el esquema del modelo. La API de embeddings de texto devuelve cada predicción como un objeto con un campo embeddings, que contiene un objeto statistics y un array values. Por lo tanto, la cláusula OUTPUT anterior declara la columna embeddings como un STRUCT (con values y statistics opcional), no como un tipo ARRAY<FLOAT64>. El campo values contiene el vector de embedding, por lo que las consultas de este instructivo seleccionan embeddings.values. Si la cláusula OUTPUT no coincide con la respuesta, la llamada a ML.PREDICT falla en el momento de la consulta con un error INVALID_ARGUMENT. Para conocer el formato de la respuesta, consulta la API de embeddings de texto.

Genera embeddings de texto

Para generar embeddings, pasa un fragmento de texto directamente a la función ML.PREDICT con el siguiente SQL:

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

Para generar embeddings para los datos almacenados en una tabla, usa el siguiente SQL:

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

Para especificar el tipo de tarea y las dimensiones de salida, sigue estos pasos:

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;

Almacena embeddings de texto

Después de generar las incorporaciones en una transacción de solo lectura, almacénalas en Spanner para que se puedan administrar con tus datos operativos. Para almacenar las incorporaciones, usa una transacción de lectura y escritura.

Para las cargas de trabajo que son menos sensibles al rendimiento, puedes generar e insertar embeddings con el siguiente SQL en una transacción de lectura y escritura. Especificar vector_length es opcional para almacenar embeddings, se recomienda para la búsqueda de KNN y es obligatorio para los índices de vectores. Reemplaza VECTOR_LENGTH por la dimensión de salida de tu modelo, como 3072 o 768, o bien omite vector_length si la columna almacena vectores de dimensiones 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

Genera embeddings de texto

Para generar embeddings, pasa un fragmento de texto directamente a la función spanner.ML_PREDICT_ROW con el siguiente SQL:

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

Reemplaza lo siguiente:

  • PROJECT: Es el proyecto que aloja el extremo de Agent Platform.
  • LOCATION: Es la ubicación del extremo de Agent Platform.
  • MODEL_NAME: Es el nombre del modelo de embedding de texto de Agent Platform.

La función spanner.ML_PREDICT_ROW devuelve un objeto JSONB con un array predictions. Cada elemento de predictions tiene un objeto embeddings que contiene un objeto statistics y un array values. En los ejemplos de este instructivo, los operadores -> extraen el vector de embedding de la ruta de acceso predictions[0].embeddings.values. Para conocer el formato de la respuesta, consulta la API de embeddings de texto.

Para generar embeddings para los datos almacenados en una tabla, usa el siguiente SQL:

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;

Reemplaza lo siguiente:

  • PROJECT: Es el proyecto que aloja el extremo de Agent Platform.
  • LOCATION: Es la ubicación del extremo de Agent Platform.
  • MODEL_NAME: Es el nombre del modelo de embedding de texto de Agent Platform.

Para especificar el tipo de tarea y las dimensiones de salida, sigue estos pasos:

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;

Reemplaza lo siguiente:

  • PROJECT: Es el proyecto que aloja el extremo de Agent Platform.
  • LOCATION: Es la ubicación del extremo de Agent Platform.
  • MODEL_NAME: Es el nombre del modelo de embedding de texto de Agent Platform.

Almacena embeddings de texto

Después de generar las incorporaciones en una transacción de solo lectura, almacénalas en Spanner para que se puedan administrar con tus datos operativos. Para almacenar las incorporaciones, usa una transacción de lectura y escritura.

Para las cargas de trabajo que son menos sensibles al rendimiento, puedes generar e insertar embeddings con el siguiente SQL en una transacción de lectura y escritura. Especificar VECTOR LENGTH es opcional para almacenar embeddings, se recomienda para la búsqueda de KNN y es obligatorio para los índices de vectores. Reemplaza VECTOR_LENGTH por la dimensión de salida de tu modelo, como 3072 o 768, o bien omite VECTOR LENGTH si la columna almacena vectores de dimensiones 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'
));

Reemplaza lo siguiente:

  • PROJECT: Es el proyecto que aloja el extremo de Agent Platform.
  • LOCATION: Es la ubicación del extremo de Agent Platform.
  • MODEL_NAME: Es el nombre del modelo de embedding de texto de Agent Platform.

Actualiza los embeddings de texto

Para actualizar tus incorporaciones o transferir datos en tiempo real, usa la sentencia UPDATE (GoogleSQL y PostgreSQL).

Para actualizar la tabla Products del ejemplo anterior, usa el siguiente SQL:

GoogleSQL

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

Reemplaza lo siguiente:

  • MODEL_NAME: Es el nombre del modelo de embedding de texto de 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;

Reemplaza lo siguiente:

  • PROJECT: Es el proyecto que aloja el extremo de Agent Platform.
  • LOCATION: Es la ubicación del extremo de Agent Platform.
  • MODEL_NAME: Es el nombre del modelo de embedding de texto de Agent Platform.

¿Qué sigue?