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_textpara generar texto de forma iterativa a partir del conjunto de datos públicosbigquery-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.
Para obtener más información, consulta Precios de BigQuery y Precios de Agent Platform.
Antes de comenzar
- 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.
-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
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.
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:
-
Crea y usa conjuntos de datos, conexiones y modelos de BigQuery:
Administrador de BigQuery (
roles/bigquery.admin) en tu proyecto -
Otorga permisos a la cuenta de servicio de la conexión:
Administrador de IAM del proyecto (
roles/resourcemanager.projectIamAdmin) en tu proyecto
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
En la consola de Google Cloud , ve a la página BigQuery.
En el panel de la izquierda, haz clic en Explorar:

Si no ves el panel izquierdo, haz clic en Expandir panel izquierdo para abrirlo.
En Explorador, expande tu proyecto y, luego, haz clic en Conjuntos de datos.
En la página Conjuntos de datos, haz clic en Crear conjunto de datos.
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á.
Haz clic en Crear conjunto de datos.
bq
Para crear un conjunto de datos nuevo, usa el
comando bq mk --dataset.
Crea un conjunto de datos llamado
bqml_tutorialcon la ubicación de los datos establecida enUS:bq mk --dataset \ --location=US \ --description "BigQuery ML tutorial dataset." \ bqml_tutorial
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:
En la consola de Google Cloud , ve a la página BigQuery.
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_textaparece en el conjunto de datosbqml_tutorialen el panel Explorador. Debido a que la consulta usa una declaraciónCREATE MODELpara 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:
En la consola de Google Cloud , ve a la página BigQuery.
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_IDcon el ID del proyecto.El procedimiento almacenado crea la tabla
bqml_tutorial.news_generated_textpara contener el resultado de la funciónML.GENERATE_TEXT.Cuando la consulta termine de ejecutarse, confirma que no haya filas en la tabla
bqml_tutorial.news_generated_textque 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.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
En la consola de Google Cloud , ve a la página BigQuery.
Borra el conjunto de datos
bqml_tutorialSi borras el conjunto de datos, también se borran el modelo remoto y la tabla de resultados:En el panel Explorador, expande tu proyecto y haz clic en Conjuntos de datos.
En la lista Conjuntos de datos, haz clic en el conjunto de datos
bqml_tutorial.En el panel de detalles, haz clic en Borrar.
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?
- Obtén más información sobre la
función
ML.GENERATE_TEXTy la funciónAI.GENERATE_TEXT. - Obtén más información sobre la IA generativa en BigQuery.
- Aprende a elegir una función de generación de texto.