Maneja errores de cuota mediante una llamada a ML.GENERATE_EMBEDDING de forma iterativa

En este instructivo, se muestra cómo usar el procedimiento almacenado público bqutil.procedure.bqml_generate_embeddings de BigQuery para iterar a través de llamadas a la función ML.GENERATE_EMBEDDING. Llamar a la función de forma iterativa te permite abordar cualquier error que se pueda reintentar que se produzca debido a que se superaron las cuotas y los límites que se aplican a la función.

Para revisar el código fuente del procedimiento almacenado bqutil.procedure.bqml_generate_embeddings en GitHub, consulta bqml_generate_embeddings.sqlx. Para obtener más información sobre los parámetros y el uso del procedimiento almacenado, consulta el archivo readme.

En este instructivo, se te guiará por las siguientes tareas:

Crear un modelo remoto sobre un modelo text-embedding-005.
Itera a través de llamadas a la función ML.GENERATE_EMBEDDING mediante el modelo remoto y la tabla de datos públicos bigquery-public-data.bbc_news.fulltext con el procedimiento almacenado bqutil.procedure.bqml_generate_embeddings.

Permisos necesarios

Para ejecutar este instructivo, necesitas los siguientes roles de Identity and Access Management (IAM):

Crear y usar conjuntos de datos, conexiones y modelos de BigQuery: Administrador de BigQuery (roles/bigquery.admin)
Otorga permisos a la cuenta de servicio de la conexión: Administrador de IAM del proyecto (roles/resourcemanager.projectIamAdmin).

Estos roles predefinidos contienen los permisos necesarios para realizar las tareas de este documento. Para ver los permisos exactos que son necesarios, expande la sección Permisos necesarios:

Permisos necesarios

Crea un conjunto de datos: bigquery.datasets.create
Crea, delega y usa una conexión: bigquery.connections.*
Establece la conexión predeterminada: bigquery.config.*
Configura los permisos de la cuenta de servicio: resourcemanager.projects.getIamPolicy y resourcemanager.projects.setIamPolicy
Crea un modelo y ejecuta la inferencia:
- bigquery.jobs.create
- bigquery.models.create
- bigquery.models.getData
- bigquery.models.updateData
- bigquery.models.updateMetadata

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Costos

En este documento, usarás los siguientes componentes facturables de Google Cloud:

BigQuery ML: You incur costs for the data that you process in BigQuery.
Vertex AI: You incur costs for calls to the Vertex AI model.

Para generar una estimación de costos en función del uso previsto, usa la calculadora de precios.

Es posible que los usuarios nuevos de Google Cloud cumplan con los requisitos para acceder a una prueba gratuita.

Si deseas obtener más información sobre los precios de BigQuery, consulta Precios de BigQuery.

Para obtener más información sobre los precios de Vertex AI, consulta Precios de Vertex AI.

Antes de comenzar

En la consola de Google Cloud , en la página del selector de proyectos, selecciona o crea un proyecto de Google Cloud .
Roles necesarios para seleccionar o crear un proyecto
- Selecciona un proyecto: Para seleccionar un proyecto, no se requiere un rol de IAM específico. Puedes seleccionar cualquier proyecto en el que se te haya otorgado un rol.
- Crear un proyecto: Para crear un proyecto, necesitas el rol de Creador de proyectos (roles/resourcemanager.projectCreator), que contiene el permiso resourcemanager.projects.create. Obtén más información para otorgar roles.
Nota: Si no planeas conservar los recursos que creaste durante este procedimiento, crea un proyecto en lugar de seleccionar uno existente. Cuando termines, puedes borrar el proyecto y quitar todos los recursos asociados con él.

Ir al selector de proyectos
Verifica que la facturación esté habilitada para tu proyecto de Google Cloud .
Habilita las APIs de BigQuery, BigQuery Connection y Vertex AI.
Roles necesarios para habilitar las APIs
Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. Obtén más información para otorgar roles.
Habilitar las API

Crea un conjunto de datos

Crea un conjunto de datos de BigQuery para almacenar tus modelos y datos de muestra:

En la consola de Google Cloud , ve a la página BigQuery.

Ir a la página de BigQuery
En el panel Explorador, haz clic en el nombre de tu proyecto.
Haz clic en Ver acciones > Crear conjunto de datos.
En la página Crear conjunto de datos, haz lo siguiente:
1. En ID del conjunto de datos, ingresa target_dataset.
2. En Tipo de ubicación, selecciona Multirregión y, luego, EE.UU. (varias regiones en Estados Unidos).
3. Deja la configuración predeterminada restante como está y haz clic en Crear conjunto de datos.

Crea el modelo de generación de embedding de texto

Crea un modelo remoto que represente un modelo text-embedding-005 de Vertex AI alojado:

En la consola de Google Cloud , ve a la página BigQuery.

Ir a BigQuery
En el editor de consultas, ejecuta la siguiente declaración:
```
CREATE OR REPLACE MODEL `target_dataset.embedding_model`
  REMOTE WITH CONNECTION DEFAULT
  OPTIONS (ENDPOINT = 'text-embedding-005');
```
La consulta tarda varios segundos en completarse, después de eso, el modelo embedding aparece en el conjunto de datos sample en el panel Explorador. Debido a que la consulta usa una declaración CREATE MODEL para crear un modelo, no hay resultados de consultas.

Ejecuta el procedimiento almacenado

Ejecuta el procedimiento almacenado bqutil.procedure.bqml_generate_embeddings, que itera a través de llamadas a la función ML.GENERATE_EMBEDDING mediante el modelo target_dataset.embedding_model y la tabla de datos públicos bigquery-public-data.bbc_news.fulltext:

En la consola de Google Cloud , ve a la página BigQuery.

Ir a BigQuery

En el editor de consultas, ejecuta la siguiente declaración:

CALL `bqutil.procedure.bqml_generate_embeddings`(
    "bigquery-public-data.bbc_news.fulltext",            -- source table
    "PROJECT_ID.target_dataset.news_body_embeddings",  -- destination table
    "PROJECT_ID.target_dataset.embedding_model",       -- model
    "body",                                              -- content column
    ["filename"],                                        -- key columns
    '{}'                                                 -- optional arguments encoded as a JSON string
);

Reemplaza PROJECT_ID por el ID del proyecto que estás usando para este instructivo.

El procedimiento almacenado crea una tabla target_dataset.news_body_embeddings para contener el resultado de la función ML.GENERATE_EMBEDDING.

Cuando la consulta termine de ejecutarse, confirma que no haya filas en la tabla target_dataset.news_body_embeddings que contengan un error que se pueda volver a intentar. En el editor de consultas, ejecuta la siguiente declaración:
```
SELECT *
FROM `target_dataset.news_body_embeddings`
WHERE ml_generate_embedding_status LIKE '%A retryable error occurred%';
```
La consulta muestra el mensaje No data to display.

Realiza una limpieza

Precaución: Borrar un proyecto tiene las siguientes consecuencias:

Se borra todo su contenido. Si usaste un proyecto existente para las tareas de este documento, cuando lo borres, también se borrará cualquier otro trabajo que hayas realizado en el proyecto.
Se pierden los IDs personalizados de los proyectos. Cuando creaste este proyecto, es posible que hayas creado un ID personalizado del proyecto que desees utilizar en el futuro. Para conservar las URLs que usan el ID del proyecto, como una URL appspot.com, borra los recursos seleccionados dentro del proyecto, en lugar de todo el proyecto.

Si planeas explorar varios instructivos, arquitecturas o guías de inicio rápido, reutilizar proyectos puede ser útil para no exceder los límites de cuota de los proyectos.

En la Google Cloud consola, ve a la página Administrar recursos.
Ir a Administrar recursos
En la lista de proyectos, elige el proyecto que quieres borrar y haz clic en Borrar.
En el diálogo, escribe el ID del proyecto y, luego, haz clic en Cerrar para borrar el proyecto.