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

En este instructivo, se muestra cómo usar el procedimiento almacenado público bqutil.procedure.bqml_generate_text de BigQuery para iterar a través de llamadas a la función ML.GENERATE_TEXT. 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 límites que se aplican a la función.

Para revisar el código fuente del procedimiento almacenado bqutil.procedure.bqml_generate_text en GitHub, consulta bqml_generate_text.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 gemini-1.5-flash-002.
• Itera a través de llamadas a la función ML.GENERATE_TEXT 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_text.

Permisos necesarios

• Para crear el conjunto de datos, necesitas el permiso bigquery.datasets.create de Identity and Access Management (IAM).

• Para crear el recurso de conexión, necesitas los siguientes permisos de IAM:

  • bigquery.connections.create
  • bigquery.connections.get

• Para otorgar permisos a la cuenta de servicio de la conexión, necesitas el siguiente permiso:

  • resourcemanager.projects.setIamPolicy

• Para crear el modelo, necesitas los siguientes permisos:

  • bigquery.jobs.create
  • bigquery.models.create
  • bigquery.models.getData
  • bigquery.models.updateData
  • bigquery.connections.delegate

• Para ejecutar inferencias, necesitas los siguientes permisos:

  • bigquery.models.getData
  • bigquery.jobs.create

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 califiquen para obtener 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

1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

2. Make sure that billing is enabled for your Google Cloud project.

3. Enable the BigQuery, BigQuery Connection, and Vertex AI APIs.

   Enable the APIs

Crea un conjunto de datos

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

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

   Ir a la página de BigQuery

2. En el panel Explorador, haz clic en el nombre de tu proyecto.

3. Haz clic en Ver acciones > Crear conjunto de datos.

4. En la página Crear conjunto de datos, haz lo siguiente:

   1. En ID del conjunto de datos, ingresa sample.

   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.

Crear una conexión

Crea una conexión de recurso de Cloud y obtén el ID de la cuenta de servicio de la conexión. Crea la conexión en la misma ubicación que el conjunto de datos que creaste en el paso anterior.

Selecciona una de las siguientes opciones:

Console

1. Ve a la página de BigQuery.

   Ir a BigQuery

2. Para crear una conexión, haz clic en Agregar y, luego, en Conexiones a fuentes de datos externas.

3. En la lista Tipo de conexión, selecciona Modelos remotos de Vertex AI, funciones remotas y BigLake (Cloud Resource).

4. En el campo ID de conexión, escribe un nombre para tu conexión.

5. Haz clic en Crear conexión (Create connection).

6. Haz clic en Ir a la conexión.

7. En el panel Información de conexión, copia el ID de la cuenta de servicio para usarlo en un paso posterior.

bq

1. En un entorno de línea de comandos, crea una conexión:

   bq mk --connection --location=REGION --project_id=PROJECT_ID \
       --connection_type=CLOUD_RESOURCE CONNECTION_ID

   El parámetro --project_id anula el proyecto predeterminado.

   Reemplaza lo siguiente:

   • REGION: tu región de conexión
   • PROJECT_ID: El ID del proyecto de Google Cloud.
   • CONNECTION_ID: Es un ID para tu conexión.

   Cuando creas un recurso de conexión, BigQuery crea una cuenta de servicio del sistema única y la asocia con la conexión.

   Solución de problemas: Si recibes el siguiente error de conexión, actualiza el SDK de Google Cloud:

   Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...
   

2. Recupera y copia el ID de cuenta de servicio para usarlo en un paso posterior:

   bq show --connection PROJECT_ID.REGION.CONNECTION_ID

   El resultado es similar a este:

   name                          properties
   1234.REGION.CONNECTION_ID     {"serviceAccountId": "[e-mail]"}
   

Terraform

Usa el recurso google_bigquery_connection.

Nota: Para crear objetos de BigQuery a través de Terraform, debes habilitar la API de Cloud Resource Manager

.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

En el siguiente ejemplo, se crea una conexión de recursos de Cloud llamada my_cloud_resource_connection en la región US:

# This queries the provider for project information.
data "google_project" "default" {}

# This creates a cloud resource connection in the US region named my_cloud_resource_connection.
# Note: The cloud resource nested object has only one output field - serviceAccountId.
resource "google_bigquery_connection" "default" {
  connection_id = "my_cloud_resource_connection"
  project       = data.google_project.default.project_id
  location      = "US"
  cloud_resource {}
}

Para aplicar tu configuración de Terraform en un proyecto de Google Cloud, completa los pasos de las siguientes secciones.

Prepara Cloud Shell

1. Inicia Cloud Shell

2. Establece el proyecto de Google Cloud predeterminado en el que deseas aplicar tus configuraciones de Terraform.

   Solo necesitas ejecutar este comando una vez por proyecto y puedes ejecutarlo en cualquier directorio.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   Las variables de entorno se anulan si configuras valores explícitos en el archivo de configuración de Terraform.

Prepara el directorio

Cada archivo de configuración de Terraform debe tener su propio directorio (también llamado módulo raíz).

1. En Cloud Shell, crea un directorio y un archivo nuevo dentro de ese directorio. El nombre del archivo debe tener la extensión .tf, por ejemplo, main.tf. En este instructivo, el archivo se denomina main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. Si sigues un instructivo, puedes copiar el código de muestra en cada sección o paso.

   Copia el código de muestra en el main.tf recién creado.

   De manera opcional, copia el código de GitHub. Esto se recomienda cuando el fragmento de Terraform es parte de una solución de extremo a extremo.

3. Revisa y modifica los parámetros de muestra que se aplicarán a tu entorno.
4. Guarda los cambios.
5. Inicializa Terraform. Solo debes hacerlo una vez por directorio.

   terraform init

   De manera opcional, incluye la opción -upgrade para usar la última versión del proveedor de Google:

   terraform init -upgrade

Aplica los cambios

1. Revisa la configuración y verifica que los recursos que creará o actualizará Terraform coincidan con tus expectativas:

   terraform plan

   Corrige la configuración según sea necesario.

2. Para aplicar la configuración de Terraform, ejecuta el siguiente comando y, luego, escribe yes cuando se te solicite:

   terraform apply

   Espera hasta que Terraform muestre el mensaje “¡Aplicación completa!”.

3. Abre tu proyecto de Google Cloud para ver los resultados. En la consola de Google Cloud, navega a tus recursos en la IU para asegurarte de que Terraform los haya creado o actualizado.

Nota: Por lo general, las muestras de Terraform suponen que las APIs necesarias están habilitadas en tu proyecto de Google Cloud.

Otorga permisos a la cuenta de servicio de las conexiones

Para otorgar a la cuenta de servicio de la conexión los roles adecuados para acceder a los servicios de Cloud Storage y Vertex AI, sigue estos pasos:

1. Ir a la página IAM y administración

   Ir a IAM y administración

2. Haz clic en Grant access.

3. En el campo Principales nuevas (New principals), ingresa el ID de la cuenta de servicio que copiaste antes.

4. En el menú Selecciona un rol, elige Vertex AI > Usuario de Vertex AI.

5. Haz clic en Guardar.

Crea el modelo de generación de texto

Crea un modelo remoto que represente un modelo gemini-1.5-flash-002 de Vertex AI alojado:

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

   Ir a BigQuery

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

   CREATE OR REPLACE MODEL `sample.generate_text`
     REMOTE WITH CONNECTION `LOCATION.CONNECTION_ID`
     OPTIONS (ENDPOINT = 'gemini-1.5-flash-002');

   Reemplaza lo siguiente:

   • LOCATION: la ubicación de la conexión.
   • CONNECTION_ID: el ID de la conexión de BigQuery.

     Cuando ves los detalles de conexión en la consola de Google Cloud, este es el valor en la última sección del ID de conexión completamente calificado que se muestra en Conexión ID, por ejemplo, projects/myproject/locations/connection_location/connections/myconnection.

   La consulta tarda varios segundos en completarse, después de eso, el modelo generate_text 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_text, que itera a través de llamadas a la función ML.GENERATE_TEXT mediante el modelo sample.generate_text y la tabla de datos públicos bigquery-public-data.bbc_news.fulltext:

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

   Ir a BigQuery

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

   CALL `bqutil.procedure.bqml_generate_text`(
       "bigquery-public-data.bbc_news.fulltext",   -- source table
       "PROJECT_ID.sample.news_generated_text",  -- destination table
       "PROJECT_ID.sample.generate_text",        -- model
       "body",                                     -- content column
       ["filename"],                               -- key columns
       '{}'                                        -- optional arguments
   );

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

   El procedimiento almacenado crea una tabla sample.news_generated_text para contener el resultado de la función ML.GENERATE_TEXT.

3. Cuando la consulta termine de ejecutarse, confirma que no haya filas en la tabla sample.news_generated_text que contengan un error que se pueda volver a intentar. En el editor de consultas, ejecuta la siguiente declaración:

   SELECT *
   FROM `sample.news_generated_text`
   WHERE ml_generate_text_status LIKE '%A retryable error occurred%';

   La consulta muestra el mensaje No data to display.

Limpia

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

• Se borra todo en el proyecto. 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 ID personalizados de proyectos. Cuando creaste este proyecto, es posible que hayas creado un ID del proyecto personalizado que desees utilizar en el futuro. Para conservar las URL que utilizan el ID del proyecto, como una URL appspot.com, borra los recursos seleccionados dentro del proyecto en lugar de borrar todo el proyecto.

Si planeas explorar varias infraestructuras, instructivos y guías de inicio rápido la reutilización de proyectos puede ayudarte a evitar exceder los límites de las cuotas del proyecto.

1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.