Generación autónoma de embeddings

En este documento, se describe cómo usar la generación autónoma de embeddings para tus datos, lo que permite que BigQuery mantenga una columna de embeddings en una tabla en función de una columna de origen. La columna de origen debe tener un tipo de datos STRING o ObjectRef. Cuando agregas o modificas datos en la columna de origen, BigQuery genera o actualiza automáticamente la columna de embeddings para esos datos con un modelo de embeddings de Agent Platform. Esto es útil si deseas que BigQuery mantenga tus embeddings cuando se actualicen los datos de origen con regularidad.

Los embeddings son útiles para las aplicaciones modernas de IA generativa, como la generación mejorada por recuperación (RAG), pero pueden ser complejos de crear, administrar y consultar. Puedes usar la generación autónoma de embeddings para simplificar el proceso de creación, mantenimiento y consulta de embeddings para su uso en búsquedas de similitud y otras aplicaciones de IA generativa.

Por ejemplo, puedes usar consultas similares a las siguientes para crear una tabla con la generación autónoma de embeddings habilitada, insertar datos y, luego, realizar una búsqueda semántica:

CREATE TABLE mydataset.products (
  name STRING,
  description STRING,
  description_embedding STRUCT<result ARRAY<FLOAT64>, status STRING>
    GENERATED ALWAYS AS (
      AI.EMBED(description, connection_id => 'us.example_connection',
        endpoint => 'text-embedding-005')
      # Alternatively, you can use the syntax for a built-in model.
      # AI.EMBED(description, model => 'embeddinggemma-300m')
    ) STORED OPTIONS( asynchronous = TRUE ));

# Values in the description_embedding column are automatically generated.
INSERT INTO mydataset.products (name, description) VALUES
  ('Super slingers', 'An exciting board game for the whole family'), ...;

SELECT * FROM AI.SEARCH(TABLE mydataset.products, 'description', 'A really fun toy');

Antes de comenzar

Para habilitar la generación autónoma de embeddings en una tabla, debes tener los permisos y la conexión necesarios, y habilitar la API de Vertex AI para tu proyecto.

Roles obligatorios

Para obtener los permisos que necesitas para habilitar la generación autónoma de embeddings, pídele a tu administrador que te otorgue los siguientes roles de IAM:

• Para usar un recurso de conexión: Usuario de conexiones de BigQuery (roles/bigquery.connectionUser) en la conexión
• Para crear o modificar una tabla: Editor de datos de BigQuery (roles/bigquery.dataEditor) en la tabla
• Otorga a la cuenta de servicio de la conexión el siguiente rol para que pueda acceder a los modelos alojados en los extremos de Agent Platform: Usuario de Agent Platform (roles/aiplatform.user) en el proyecto que tiene la conexión

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Crea una conexión y otorga permiso a una cuenta de servicio

Para habilitar la generación autónoma de embeddings en una tabla, debes crear una conexión de recursos de Cloud. Luego, otorga el rol de usuario de Agent Platform (roles/aiplatform.user) a la cuenta de servicio que se creó cuando creaste la conexión.

Crea una columna de embeddings generada automáticamente

Puedes crear una columna de embeddings generada automáticamente dentro de una tabla nueva o agregar una a una tabla existente.

Crea una tabla con una columna de embeddings generada automáticamente

Puedes usar la generación autónoma de embeddings para generar embeddings con la AI.EMBED función en una CREATE TABLE instrucción.

Reemplaza lo siguiente:

• DATASET_ID: Es el nombre del conjunto de datos en el que deseas crear la tabla.
• TABLE: Es el nombre de la tabla en la que se creará la generación autónoma de embeddings.
• COLUMN, ...: Son las columnas que debe contener tu tabla, además de la columna que deseas incorporar automáticamente.
• STRING_COL: Es el nombre de la columna STRING que deseas incorporar automáticamente.
• EMBEDDING_COL_NAME: Es el nombre de la columna de embeddings generada automáticamente.
• CONNECTION_ID: Es un valor STRING que contiene el nombre de una conexión para usar, como my_project.us.example_connection. Debes otorgar el rol de usuario de Agent Platform a la cuenta de servicio de la conexión en el proyecto en el que creas la tabla.
• ENDPOINT: Es un valor STRING que especifica un extremo de modelo de embeddings de texto de Agent Platform compatible para usar con el modelo de embeddings de texto. El valor del extremo que especifiques debe incluir la versión del modelo, por ejemplo, text-embedding-005. Si especificas el nombre del modelo en lugar de una URL, BigQuery ML identifica automáticamente el modelo y usa el extremo completo del modelo.

• MODEL (Versión preliminar): Es un valor STRING que especifica un modelo de embeddings de texto integrado. El único valor admitido es el embeddinggemma-300m modelo. Si especificas este parámetro, no puedes especificar los parámetros endpoint ni connection_id.

  Cuando especificas el parámetro MODEL, tus datos permanecen en BigQuery y tus ranuras se usan para crear los embeddings. No se envían datos a Agent Platform y no se generan cargos en Agent Platform.

Agrega una columna de embeddings generada automáticamente a una tabla existente

También puedes agregar una columna de embeddings generada automáticamente a una tabla existente con una ALTER TABLE ADD COLUMN instrucción.

El trabajo de generación de embeddings en segundo plano comienza poco después de que se crea o modifica la tabla, o después de que actualizas los datos en la columna de origen.

Para hacer un seguimiento del progreso de la generación de embeddings, puedes usar una consulta similar a la siguiente:

SELECT
  COUNT(*) AS total_num_rows,
  COUNTIF(description_embedding IS NOT NULL
          AND description_embedding.status = '') AS total_num_generated_embeddings
FROM
  PROJECT_ID.DATASET_ID.TABLE;

Después de tener la tabla con embeddings, puedes crear un índice vectorial en la columna STRUCT que contiene el embedding generado automáticamente.

Ejemplo

Supongamos que eres un gran comercio minorista que vende muchos productos diferentes. Tienes una tabla de nombres y descripciones de productos, y deseas ayudar a tus clientes a encontrar los productos que buscan. En las siguientes consultas, se muestra cómo configurar la generación autónoma de embeddings para ayudar con la búsqueda semántica de las descripciones de tus productos.

Primero, crea un conjunto de datos:

CREATE SCHEMA mydataset;

Luego, crea una tabla con la generación autónoma de embeddings habilitada para contener la información de tus productos. La columna generada automáticamente se llama description_embedding y se basa en la columna description.

# Create a table of products and descriptions with a generated embedding column.
CREATE TABLE mydataset.products (
  name STRING,
  description STRING,
  description_embedding STRUCT<result ARRAY<FLOAT64>, status STRING>
    GENERATED ALWAYS AS (
      AI.EMBED(description, connection_id => 'us.example_connection',
        endpoint => 'text-embedding-005')
      # Alternatively, you can use the syntax for a built-in model.
      # AI.EMBED(description, model => 'embeddinggemma-300m')
    ) STORED OPTIONS( asynchronous = TRUE )
);

En la siguiente consulta, se insertan algunos nombres y descripciones de productos en la tabla. No especificas un valor para description_embedding porque se genera automáticamente.

# Insert product descriptions into the table.
# The description_embedding column is automatically updated.
INSERT INTO mydataset.products (name, description) VALUES
  ("Lounger chair", "A comfortable chair for relaxing in."),
  ("Super slingers", "An exciting board game for the whole family."),
  ("Encyclopedia set", "A collection of informational books.");

De manera opcional, puedes crear un índice vectorial en la tabla para acelerar la búsqueda. Un índice vectorial requiere más de tres filas, por lo que la siguiente consulta supone que insertaste datos adicionales. Cada vez que insertas datos, la columna description_embedding se actualiza automáticamente.

CREATE VECTOR INDEX my_index
ON mydataset.products(description_embedding)
OPTIONS(index_type = 'IVF');

Por último, puedes usar la AI.SEARCH función para realizar una búsqueda semántica de tus productos en busca de un juguete divertido:

# Search for products that are fun to play with.
SELECT base.name, base.description, distance
FROM AI.SEARCH(TABLE mydataset.products, 'description', "A really fun toy");

/*------------------+----------------------------------------------+----------------------+
 | name             | description                                  | distance             |
 +------------------+----------------------------------------------+----------------------+
 | Super slingers   | An exciting board game for the whole family. | 0.80954913893618929  |
 | Lounger chair    | A comfortable chair for relaxing in.         | 0.938933930620146    |
 | Encyclopedia set | A collection of informational books.         | 1.1119297739353384   |
 +------------------+----------------------------------------------+----------------------*/

Embeddings generados a partir de columnas ObjectRef

Puedes agregar columnas de embeddings generadas para una columna ObjectRef en una tabla.

En el siguiente ejemplo, se muestra cómo crear una tabla con una columna ObjectRef y, luego, agregar una columna de embeddings generada para esa columna:

# Create a table with ObjectRef columns.
CREATE TABLE mydataset.images AS
SELECT
  REGEXP_EXTRACT(ref.uri, r'.*/(.*).jpg$') AS name,
  ref
FROM mydataset.object_table;

# Add a generated embedding column for the ObjectRef column.
ALTER TABLE mydataset.images
ADD COLUMN image_embedding STRUCT<result ARRAY<FLOAT64>, status STRING>
GENERATED ALWAYS AS (
  AI.EMBED(
    ref,
    connection_id => "us.my_connection",
    endpoint => "multimodalembedding@001")
)
STORED OPTIONS (asynchronous = true);

Obtén información sobre las columnas de embeddings generadas automáticamente

Para verificar que una columna sea una columna de embeddings generada automáticamente, consulta la INFORMATION_SCHEMA.COLUMNS vista.

En la siguiente consulta, se muestra información sobre todas tus columnas de embeddings generadas automáticamente:

SELECT *
FROM PROJECT_ID.DATASET_ID.INFORMATION_SCHEMA.COLUMNS
WHERE is_generated = 'ALWAYS';

El campo generation_expression muestra la llamada a la función AI.EMBED que se usa para generar los embeddings en la columna.

Usa tu propia reserva

De forma predeterminada, BigQuery usa ranuras según demanda para controlar el procesamiento necesario para mantener la columna de embeddings generada. Para garantizar un rendimiento predecible y coherente, puedes opcionalmente crear una reserva y establecer job_type en BACKGROUND. Cuando hay una reserva en segundo plano, BigQuery la usa para mantener la columna de embeddings generada.

Cuotas

Cuando usas un extremo de Agent Platform para la generación de embeddings especificando el parámetro endpoint en la función AI.EMBED, BigQuery envía solicitudes a Agent Platform para generar embeddings. Estas solicitudes están sujetas a las cuotas de Agent Platform. La cuota de solicitudes por minuto para tu modelo de embeddings afecta directamente la capacidad de procesamiento de los trabajos de generación de embeddings en segundo plano. Si la generación de embeddings es lenta, solicita un límite de cuota más alto para Agent Platform siguiendo las instrucciones que se indican en Solicita una cuota más alta. Si especificas el parámetro model en la función AI.EMBED, los embeddings se generan en BigQuery y no se envían solicitudes a Agent Platform, por lo que no se aplican las cuotas de Agent Platform.

Soluciona problemas

La columna de embeddings generada contiene dos campos: result y status. Si se produce un error cuando BigQuery intenta generar un embedding para una fila en particular de tu tabla, el campo result es NULL y el campo status describe el error. Por ejemplo, si la columna de origen es NULL entonces el result embedding también es NULL y el estado es NULL value is not supported for embedding generation.

Un error más grave puede detener la generación de embeddings. En este caso, puedes consultar la columna async_generation_status en la INFORMATION_SCHEMA.COLUMNS vista para identificar el error de bloqueo.

Los errores de bloqueo pueden incluir lo siguiente:

• Errores de permiso denegado
• Errores no encontrados
• Errores de extremos de modelos de embeddings no compatibles
• Errores de API de Vertex AI no habilitada

Una vez que el siguiente trabajo de generación de embeddings se realice correctamente, se borrará la columna async_generation_status.

En la siguiente consulta, se muestra cómo verificar los errores de bloqueo:

SELECT
  column_name,
  async_generation_status
FROM
  mydataset.INFORMATION_SCHEMA.COLUMNS
WHERE
  table_name = 'images';

Si la columna image_embedding tiene un error de bloqueo, el resultado es similar al siguiente:

[
  {
    "column_name": "image_embedding",
    "async_generation_status": {
      "blocking_error": {
        "message": "<service_account> does not have the permission to access resources used by AI.EMBED. Please follow https://cloud.google.com/bigquery/docs/permissions-for-ai-functions to set up permissions.",
        ...
      }
    }
  }
]

También puedes consultar la INFORMATION_SCHEMA.JOBS vista para el trabajo en segundo plano y consultar la información en el error_result campo. El ID de trabajo de un trabajo de embeddings en segundo plano tiene el prefijo gc_. Por ejemplo, la siguiente consulta extrae todos los trabajos en segundo plano cuyo resultado de error no es NULL:

SELECT * FROM `region-REGION.INFORMATION_SCHEMA.JOBS` j
WHERE EXISTS (
  SELECT 1
  FROM unnest(j.referenced_tables) t
  WHERE
    j.project_id = 'PROJECT_ID'
    AND t.dataset_id = 'DATASET_ID'
    AND t.table_id = 'TABLE'
)
AND starts_with(job_id, 'gc')
AND error_result IS NOT NULL
ORDER BY j.creation_time DESC;

Realizar un seguimiento de los costos

Los costos de la generación autónoma de embeddings se dividen en las siguientes categorías.

Costos de DML en segundo plano de BigQuery

Los embeddings generados se escriben en tu tabla con trabajos de DML en segundo plano. De forma predeterminada, BigQuery usa ranuras según demanda para controlar estos trabajos. El proyecto de la tabla se factura según el modelo de facturación según demanda de DML.

Como alternativa, para garantizar un rendimiento predecible y coherente, puedes crear una reserva y establecer job_type en BACKGROUND. Cuando hay una reserva en segundo plano, BigQuery la usa para ejecutar los trabajos de DML en segundo plano. Además, la reserva en segundo plano se facturará por el uso del tiempo de ranura de los trabajos de DML en segundo plano.

Costos de Gemini Enterprise Agent Platform

La generación autónoma de embeddings envía solicitudes a Gemini Enterprise Agent Platform, lo que puede generar costos. Para hacer un seguimiento de los costos de Agent Platform que generan los trabajos de embeddings en segundo plano, sigue estos pasos:

1. Consulta tus informes de facturación en la Facturación de Cloud.

2. Usa filtros para segmentar tus resultados.

   En Servicios, selecciona Vertex AI.

3. Para ver los cargos de un trabajo específico, filtra por etiqueta.

   Establece la clave en bigquery_ml_job y el valor en el ID de trabajo del trabajo de embeddings. Todos los trabajos de embeddings en segundo plano tienen un prefijo de gc_.

Algunos cargos pueden tardar hasta 24 horas en aparecer en la Facturación de Cloud.

Limitaciones

• Cada tabla admite como máximo una columna de embeddings generada automáticamente.
• Las operaciones de DML simultáneas pueden causar demoras y fallas temporales en la generación de embeddings. Para obtener un mejor rendimiento y reducir los costos, te recomendamos que insertes datos en lotes y evites las actualizaciones frecuentes de DML.
• Si usas la API de transmisión heredada para transferir datos, es posible que haya algunas demoras antes de que comience la generación de embeddings.
• Cuando se usa la API de BigQuery Storage Write, los trabajos de generación de embeddings en segundo plano pueden fallar si se ejecuta un trabajo de escritura de transmisión de forma simultánea. Cuando esto ocurre, se desperdician la cuota de Agent Platform y los costos de DML en segundo plano. El uso de la API de Storage Write también causa trabajos de generación de embeddings simultáneos en la tabla, pero BigQuery controla esto y no se desperdician la cuota de Agent Platform ni los costos de DML en segundo plano.
• Para obtener un mayor rendimiento en los extremos remotos de Agent Platform, te recomendamos que uses modelos de embeddings de texto en lugar de modelos de Gemini. Para obtener más información, consulta Cuotas.
• No hay ninguna indicación de que una columna se genere automáticamente cuando ves el esquema de una tabla con la Cloud de Confiance consola o el ddl campo de la INFORMATION_SCHEMA.TABLES vista.
• Si creas una copia, una clonación o una instantánea de una tabla que tiene una columna de embeddings generada, solo se copian los datos. La configuración de generación no se aplica a la tabla nueva, y las actualizaciones de la columna de origen de la tabla nueva no generarán embeddings nuevos.
• Si restableces una tabla que tenía habilitada la generación autónoma de embeddings desde una instantánea, no se restablece la configuración de generación de embeddings.
• Cuando usas la API de BigQuery, solo puedes especificar la propiedad generatedColumn cuando creas una columna nueva. No puedes agregar, actualizar ni quitar la propiedad generatedColumn en una columna existente.

• Después de crear la columna de embeddings generada, se aplican las siguientes limitaciones:

  • No puedes descartar ni cambiar el nombre de la columna de origen, pero sí puedes descartar o cambiar el nombre de la columna de embeddings generada. Si descartas la columna de embeddings, puedes descartar o cambiar el nombre de la columna de origen.
  • No puedes cambiar el tipo de datos de la columna de origen ni de la columna de embeddings generada.

• No puedes especificar valores predeterminados para las columnas de embeddings generadas automáticamente.

• No puedes escribir directamente en las columnas de embeddings generadas con estos métodos:

  • DML
  • Operaciones de escritura por transmisión
  • bq insert
  • bq load
  • bq copy -a

• Las tablas con columnas de embeddings generadas no admiten ninguna política de seguridad a nivel de la columna, como las etiquetas de política.

• Cuando llamas a una función de búsqueda, como VECTOR_SEARCH o AI.SEARCH, se omiten las filas con embeddings faltantes en la tabla base durante la búsqueda.

• No puedes crear un índice vectorial particionado en una tabla que tenga habilitada la generación autónoma de embeddings.

• Si creas un índice vectorial en la columna de embeddings generada automáticamente, el entrenamiento del índice comienza después de que al menos el 80% de las filas hayan generado embeddings. Para verificar el progreso de la generación de embeddings, sigue estos pasos:

  Consulta el porcentaje de embeddings de tu tabla que se generaron:

  SELECT
    COUNTIF(description_embedding IS NOT NULL
    AND description_embedding.status = '') * 100.0 / COUNT(*) AS percent
  FROM PROJECT_ID.DATASET_ID.TABLE;
  

¿Qué sigue?

• Obtén más información para crear y administrar índices vectoriales.
• Consulta la Introducción a la búsqueda vectorial.