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

El procedimiento almacenado público bqutil.procedure.bqml_generate_text de BigQuery te permite iterar a través de llamadas por lotes a la función ML.GENERATE_TEXT para que puedas procesar grandes conjuntos de datos sin exceder las cuotas y los límites del extremo. Debido a que los trabajos de consulta de BigQuery finalizan incluso cuando la función falla en filas individuales, los volúmenes de solicitudes altos pueden dejar errores RESOURCE EXHAUSTED que se pueden reintentar en la tabla de salida. En este instructivo, crearás un modelo remoto y ejecutarás el procedimiento almacenado para reintentar de forma iterativa las filas con errores hasta que se procesen todos los registros de un conjunto de datos de noticias público.

Para revisar el código fuente del procedimiento almacenado 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.

Objetivos

  • Crear un conjunto de datos de BigQuery
  • Crea un modelo remoto de BigQuery ML en un modelo de gemini-3.5-flash-lite.
  • Ejecuta el procedimiento almacenado bqutil.procedure.bqml_generate_text para generar texto de forma iterativa a partir del conjunto de datos públicos bigquery-public-data.bbc_news.fulltext.
  • Verifica los resultados del texto generado y confirma que no queden errores de cuota que se puedan volver a intentar.

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.
  • Gemini Enterprise Agent Platform: You incur costs for calls to the Agent Platform 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.

Para obtener más información, consulta Precios de BigQuery y Precios de Agent Platform.

Antes de comenzar

  1. Accede a tu cuenta de Google Cloud . Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. Habilita las APIs de BigQuery, BigQuery Connection y Agent Platform, si aún no están habilitadas.

    Roles necesarios para habilitar las APIs

    Para habilitar las APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtenerlo a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más información para otorgar roles.

    Habilitar las API

Roles obligatorios

Si quieres obtener los permisos que necesitas para completar este instructivo, pídele a tu administrador que te otorgue los siguientes roles de IAM:

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

Estos roles predefinidos contienen los permisos necesarios para completar este instructivo. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para completar este instructivo:

  • 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
    • 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.

Crea un conjunto de datos

Para crear un conjunto de datos de BigQuery, selecciona una de las siguientes opciones:

Console

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

    Ir a BigQuery

  2. En el panel de la izquierda, haz clic en Explorar:

    Botón destacado del panel Explorador.

    Si no ves el panel izquierdo, haz clic en Expandir panel izquierdo para abrirlo.

  3. En Explorador, expande tu proyecto y, luego, haz clic en Conjuntos de datos.

  4. En la página Conjuntos de datos, haz clic en Crear conjunto de datos.

  5. En el panel Crear conjunto de datos, haz lo siguiente:

    • En ID del conjunto de datos, ingresa bqml_tutorial.

    • En Ubicación de los datos, selecciona EE.UU..

    Deja el resto de la configuración predeterminada como está.

  6. Haz clic en Crear conjunto de datos.

bq

Para crear un conjunto de datos nuevo, usa el comando bq mk --dataset.

  1. Crea un conjunto de datos llamado bqml_tutorial con la ubicación de los datos establecida en US:

    bq mk --dataset \
      --location=US \
      --description "BigQuery ML tutorial dataset." \
      bqml_tutorial
  2. Confirma que se haya creado el conjunto de datos:

    bq ls

API

Llama al método datasets.insert con un recurso de conjunto de datos definido:

{
  "datasetReference": {
     "datasetId": "bqml_tutorial"
  }
}

Crea el modelo remoto

Usa la sentencia CREATE MODEL para crear un modelo remoto que represente un modelo de gemini-3.5-flash-lite de Agent Platform alojado:

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

    Ir a BigQuery

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

    CREATE OR REPLACE MODEL `bqml_tutorial.generate_text`
      REMOTE WITH CONNECTION DEFAULT
      OPTIONS (ENDPOINT = 'gemini-3.5-flash-lite');

    La consulta tarda varios segundos en completarse, después de eso, el modelo generate_text aparece en el conjunto de datos bqml_tutorial 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

Usa la declaración CALL para ejecutar el procedimiento almacenado bqutil.procedure.bqml_generate_text. Este procedimiento almacenado itera a través de llamadas a la función ML.GENERATE_TEXT con el modelo bqml_tutorial.generate_text y la tabla pública bigquery-public-data.bbc_news.fulltext:

  1. En la consola de Google Cloud , ve a la página 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.bqml_tutorial.news_generated_text",  -- destination table
        "PROJECT_ID.bqml_tutorial.generate_text",        -- model
        "body",                                            -- prompt column
        ["filename"],                                      -- key columns
        '{"flatten_json_output": true}'                    -- optional arguments
    );

    Reemplaza PROJECT_ID con el ID del proyecto.

    El procedimiento almacenado crea la tabla bqml_tutorial.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 bqml_tutorial.news_generated_text que contengan un error que se pueda volver a intentar. En el editor de consultas, ejecuta la siguiente sentencia:

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

    La consulta muestra el mensaje There is no data to display.

  4. En el editor de consultas, ejecuta la siguiente sentencia para inspeccionar una muestra de los resultados de texto generados:

    SELECT
      filename,
      prompt,
      ml_generate_text_llm_result,
      ml_generate_text_status
    FROM `bqml_tutorial.news_generated_text`
    LIMIT 3;

    El resultado es similar a lo siguiente:

    +------------------------+------------------------------------------+-----------------------------------------------------------+-------------------------+
    | filename               | prompt                                   | ml_generate_text_llm_result                               | ml_generate_text_status |
    +------------------------+------------------------------------------+-----------------------------------------------------------+-------------------------+
    | bbc/tech/209.txt       | A 20-year-old US man is selling...       | It looks like you shared a news article about Andrew...   |                         |
    | bbc/business/375.txt   | South Korea's largest credit card...     | It looks like you shared a news article about the 2004... |                         |
    | bbc/sport/139.txt      | A brave defensive display, led by...     | It looks like you have shared a match report from a...    |                         |
    +------------------------+------------------------------------------+-----------------------------------------------------------+-------------------------+
    

Realiza una limpieza

Para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos usados en este instructivo, borra el proyecto que contiene los recursos o conserva el proyecto y borra los recursos individuales.

Borra el proyecto

    Borra un proyecto de Google Cloud :

    gcloud projects delete PROJECT_ID

Borra los recursos individuales

Si deseas volver a usar el proyecto, borra los recursos que creaste para este instructivo:

Console

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

    Ir a BigQuery

  2. Borra el conjunto de datos bqml_tutorial Si borras el conjunto de datos, también se borran el modelo remoto y la tabla de resultados:

    1. En el panel Explorador, expande tu proyecto y haz clic en Conjuntos de datos.

    2. En la lista Conjuntos de datos, haz clic en el conjunto de datos bqml_tutorial.

    3. En el panel de detalles, haz clic en Borrar.

    4. En el cuadro de diálogo Borrar conjunto de datos, haz clic en Borrar.

bq

Borra el conjunto de datos bqml_tutorial, el modelo remoto y la tabla de salida:

bq rm --dataset --recursive bqml_tutorial

¿Qué sigue?