La
función AI.GENERATE_TABLE
te permite extraer atributos estructurados de texto no estructurado en columnas de tablas con tipo
en BigQuery. En este instructivo, crearás un
modelo remoto
sobre un modelo de Gemini y extraerás opiniones y palabras clave de un conjunto de datos público
de opiniones sobre películas.
Objetivos
- Crea un conjunto de datos y una conexión a recursos de Cloud.
- Otorgar permisos a la cuenta de servicio de la conexión
- Crear un modelo remoto de BigQuery ML
- Genera datos estructurados a partir de texto no estructurado con la
función
AI.GENERATE_TABLE.
Costos
En este documento, usarás los siguientes componentes facturables de Google Cloud:
- BigQuery: 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
Console
- 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.
Enable the BigQuery, BigQuery Connection, and Agent Platform API APIs, if any are not already enabled.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.-
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.
Enable the BigQuery, BigQuery Connection, and Agent Platform API APIs, if any are not already enabled.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.-
Asegúrate de tener los siguientes roles en el proyecto: Administrador de BigQuery, Administrador de IAM del proyecto
Verifica los roles
-
En la consola de Google Cloud , dirígete a la página IAM.
Ir a IAM - Selecciona el proyecto.
-
En la columna Principal, busca todas las filas que te identifiquen a ti o a un grupo en el que se te incluya. Para saber en qué grupos estás incluido, comunícate con tu administrador.
- Para todas las filas en las que se te especifique o se te incluya, verifica la columna Rol para ver si la lista de roles incluye los roles necesarios.
Otorga los roles
-
En la consola de Google Cloud , dirígete a la página IAM.
Ir a IAM - Selecciona el proyecto.
- Haz clic en Otorgar acceso.
-
En el campo Principales nuevas, ingresa tu identificador de usuario. Esta suele ser la dirección de correo electrónico de una Cuenta de Google.
- Haz clic en Selecciona un rol y, luego, busca el rol.
- Para otorgar roles adicionales, haz clic en Agregar otro rol y agrega uno más.
- Haz clic en Guardar.
-
gcloud
- 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.
-
Instala Google Cloud CLI.
-
Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.
-
Para inicializar gcloud CLI, ejecuta el siguiente comando:
gcloud init -
Crea o selecciona un proyecto de Google Cloud .
Roles necesarios para seleccionar o crear un proyecto
- Seleccionar 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.
-
Crea un proyecto: Para crear un proyecto, necesitas el rol de creador de proyectos
(
roles/resourcemanager.projectCreator), que contiene el permisoresourcemanager.projects.create. Obtén más información para otorgar roles.
-
Crea un proyecto de Google Cloud :
gcloud projects create PROJECT_ID
Reemplaza
PROJECT_IDpor un nombre para el proyecto de Google Cloud que estás creando. -
Selecciona el proyecto de Google Cloud que creaste:
gcloud config set project PROJECT_ID
Reemplaza
PROJECT_IDpor el nombre de tu proyecto de Google Cloud .
-
Verifica que la facturación esté habilitada para tu proyecto de Google Cloud .
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.gcloud services enable bigquery.googleapis.com
bigqueryconnection.googleapis.com aiplatform.googleapis.com -
Instala Google Cloud CLI.
-
Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.
-
Para inicializar gcloud CLI, ejecuta el siguiente comando:
gcloud init -
Crea o selecciona un proyecto de Google Cloud .
Roles necesarios para seleccionar o crear un proyecto
- Seleccionar 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.
-
Crea un proyecto: Para crear un proyecto, necesitas el rol de creador de proyectos
(
roles/resourcemanager.projectCreator), que contiene el permisoresourcemanager.projects.create. Obtén más información para otorgar roles.
-
Crea un proyecto de Google Cloud :
gcloud projects create PROJECT_ID
Reemplaza
PROJECT_IDpor un nombre para el proyecto de Google Cloud que estás creando. -
Selecciona el proyecto de Google Cloud que creaste:
gcloud config set project PROJECT_ID
Reemplaza
PROJECT_IDpor el nombre de tu proyecto de Google Cloud .
-
Verifica que la facturación esté habilitada para tu proyecto de Google Cloud .
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.gcloud services enable bigquery.googleapis.com
bigqueryconnection.googleapis.com aiplatform.googleapis.com -
Otorga roles a tu cuenta de usuario. Ejecuta el siguiente comando una vez para cada uno de los siguientes roles de IAM:
roles/bigquery.admin, roles/resourcemanager.projectIamAdmingcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE
Reemplaza lo siguiente:
PROJECT_ID: ID del proyectoUSER_IDENTIFIER: Es el identificador de tu cuenta de usuario de . Por ejemplo,myemail@example.com. cuenta deROLE: Es el rol de IAM que otorgas a tu cuenta de usuario.
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 US.
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" } }
Crear una conexión
Crea una
conexión a recursos de Cloud en
la multirregión US, en la que creaste el conjunto de datos. Luego, obtén la cuenta de servicio
de la conexión.
Console
Ve a la página de 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 el panel Explorador, expande el nombre de tu proyecto y, luego, haz clic en Conexiones.
En la página Conexiones, haz clic en Crear conexión.
En Tipo de conexión, elige Modelos remotos de Vertex AI, funciones remotas, BigLake y Spanner (recurso de Cloud).
En el campo ID de conexión, escribe un nombre para tu conexión.
En Tipo de ubicación, selecciona una ubicación para tu conexión. La conexión debe estar ubicada junto con tus otros recursos, como los conjuntos de datos.
Haz clic en Crear conexión.
Haz clic en Ir a la conexión.
En el panel Información de conexión, copia el ID de la cuenta de servicio para usarlo en un paso posterior.
SQL
Usa la sentencia CREATE CONNECTION:
En la consola de Google Cloud , ve a la página BigQuery.
En el editor de consultas, escribe la siguiente oración:
CREATE CONNECTION [IF NOT EXISTS] `CONNECTION_NAME` OPTIONS ( connection_type = "CLOUD_RESOURCE", friendly_name = "FRIENDLY_NAME", description = "DESCRIPTION" );
Reemplaza lo siguiente:
-
CONNECTION_NAME: Es el nombre de la conexión en el formatoPROJECT_ID.LOCATION.CONNECTION_ID,LOCATION.CONNECTION_IDoCONNECTION_ID. Si se omiten el proyecto o la ubicación, se infieren del proyecto y la ubicación en los que se ejecuta la sentencia. -
FRIENDLY_NAME(opcional): Es un nombre descriptivo para la conexión. -
DESCRIPTION(opcional): Es una descripción de la conexión.
-
Haz clic en Ejecutar.
Si deseas obtener información sobre cómo ejecutar consultas, visita Ejecuta una consulta interactiva.
bq
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_idanula el proyecto predeterminado.Reemplaza lo siguiente:
REGION: tu región de conexiónPROJECT_ID: Es 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...
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 lo siguiente:
name properties 1234.REGION.CONNECTION_ID {"serviceAccountId": "connection-1234-9u56h9@gcp-sa-bigquery-condel.iam.gserviceaccount.com"}
Python
Antes de probar este ejemplo, sigue las instrucciones de configuración para Python incluidas en la guía de inicio rápido de Vertex AI sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de Vertex AI Python.
Para autenticarte en Vertex AI, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.
Node.js
Antes de probar este ejemplo, sigue las instrucciones de configuración para Node.js incluidas en la guía de inicio rápido de Vertex AI sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de Vertex AI Node.js.
Para autenticarte en Vertex AI, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.
Terraform
Usa el recurso google_bigquery_connection.
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 a recursos de Cloud llamada
my_cloud_resource_connection en la región US:
Para aplicar tu configuración de Terraform en un proyecto de Google Cloud , completa los pasos de las siguientes secciones.
Prepara Cloud Shell
- Inicia Cloud Shell
-
Establece el proyecto de Google Cloud predeterminado en el que deseas aplicar tus parámetros de configuración 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).
-
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 denominamain.tf.mkdir DIRECTORY && cd DIRECTORY && touch main.tf
-
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.tfrecié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.
- Revisa y modifica los parámetros de muestra que se aplicarán a tu entorno.
- Guarda los cambios.
-
Inicializa Terraform. Solo debes hacerlo una vez por directorio.
terraform init
De manera opcional, incluye la opción
-upgradepara usar la última versión del proveedor de Google:terraform init -upgrade
Aplica los cambios
-
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.
-
Para aplicar la configuración de Terraform, ejecuta el siguiente comando y, luego, escribe
yescuando se te solicite:terraform apply
Espera hasta que Terraform muestre el mensaje “¡Aplicación completa!”.
- 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.
Otorga permisos a la cuenta de servicio de las conexiones
Otorga a la cuenta de servicio de la conexión el rol de usuario de Agent Platform
(roles/aiplatform.user). Debes otorgar este rol en el mismo proyecto que creaste o seleccionaste en la sección
Antes de comenzar. Si otorgas el rol en un proyecto diferente, se produce el error bqcx-1234567890-xxxx@gcp-sa-bigquery-condel.iam.gserviceaccount.com does not have the permission to access resource.
Para otorgar el rol, sigue estos pasos:
Ir a la página IAM y administración
Haz clic en Otorgar acceso.
En el campo Principales nuevas, ingresa el ID de la cuenta de servicio que copiaste antes.
En el campo Selecciona un rol, busca el rol de usuario de Agent Platform.
Haz clic en Guardar.
Crea el modelo remoto
Usa la sentencia
CREATE MODEL
para crear un modelo remoto que represente un modelo 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.gemini_model` REMOTE WITH CONNECTION `LOCATION.CONNECTION_ID` OPTIONS (ENDPOINT = 'gemini-3.5-flash-lite');
Reemplaza lo siguiente:
LOCATION: la ubicación de la conexiónCONNECTION_IDpor el ID de la conexión de BigQueryCuando 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 ID de conexión, por ejemplo,
projects/myproject/locations/connection_location/connections/myconnection
La consulta tarda varios segundos en completarse, después de eso, el modelo
gemini_modelaparece en el conjunto de datosbqml_tutorial. No hay resultados de la consulta.
Genera datos estructurados
Extrae opiniones y palabras clave estructuradas de las opiniones de películas con la
función AI.GENERATE_TABLE
y el modelo remoto:
En la consola de Google Cloud , ve a la página BigQuery.
En el editor de consultas, ejecuta la siguiente sentencia para extraer opiniones y palabras clave de cinco opiniones de películas:
SELECT movie_id, sentiment, keywords FROM AI.GENERATE_TABLE( MODEL `bqml_tutorial.gemini_model`, ( SELECT CONCAT( """Analyze the following movie review. Extract a sentiment (positive or negative) and up to 3 keywords: """, review) AS prompt, movie_id FROM `bigquery-public-data.imdb.reviews` LIMIT 5 ), STRUCT( "sentiment STRING, keywords ARRAY<STRING>" AS output_schema));
El resultado es similar a lo siguiente:
+-----------+-----------+----------------------------------------------+ | movie_id | sentiment | keywords | +-----------+-----------+----------------------------------------------+ | tt0369053 | positive | ["cinematography", "performances", "comedy"] | | tt0328400 | negative | ["disregarded", "disappointing", "poorly"] | | ... | ... | ... | +-----------+-----------+----------------------------------------------+
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 el 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 borra el modelo remoto.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.
Borra la conexión.
En el panel Explorador, expande tu proyecto y haz clic en Conexiones.
En la lista Conexiones, haz clic en la conexión que creaste.
En el panel de detalles, haz clic en Borrar.
En el cuadro de diálogo Borrar conexión, ingresa
deletepara confirmar la eliminación.Haz clic en Borrar.
gcloud
Borra el conjunto de datos
bqml_tutorialy el modelo remoto:bq rm --dataset --recursive bqml_tutorialBorra la conexión:
bq rm --connection <var>PROJECT_ID</var>.<var>LOCATION</var>.<var>CONNECTION_ID</var>Reemplaza lo siguiente:
<var>PROJECT_ID</var>: Es el ID del proyecto de Google Cloud .<var>LOCATION</var>: la ubicación de la conexión<var>CONNECTION_ID</var>: el ID de conexión
¿Qué sigue?
- Obtén más información sobre la
función
AI.GENERATE_TABLE. - Obtén más información sobre la IA generativa en BigQuery.
- Obtén más información para elegir una función de generación de texto.