Esta página se ha traducido con Cloud Translation API.

Generar texto con un modelo de Gemini y la función ML.GENERATE_TEXT

En este tutorial se explica cómo crear un modelo remoto basado en el modelo gemini-2.0-flash y, a continuación, cómo usar ese modelo con la función ML.GENERATE_TEXT para extraer palabras clave y realizar un análisis de sentimiento de las reseñas de películas de la tabla pública bigquery-public-data.imdb.reviews.

Roles obligatorios

Para completar este tutorial, necesitas los siguientes roles de Gestión de Identidades y Accesos (IAM):

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

Estos roles predefinidos contienen los permisos necesarios para realizar las tareas descritas en este documento. Para ver los permisos exactos que se necesitan, despliega la sección Permisos necesarios:

Permisos obligatorios

Crea un conjunto de datos: bigquery.datasets.create
Crear, delegar y usar una conexión: bigquery.connections.*
Definir la conexión predeterminada: bigquery.config.*
Define 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 u otros roles predefinidos.

Costes

En este documento, se utilizan 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 service that's represented by the remote model.

Para generar una estimación de costes basada en el uso previsto, utiliza la calculadora de precios.

Los usuarios nuevos Google Cloud pueden disfrutar de una prueba gratuita.

Para obtener más información sobre los precios de BigQuery, consulta la página Precios de BigQuery en la documentación de BigQuery.

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

Antes de empezar

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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.
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
Verify that billing is enabled for your Google Cloud project.
Enable the BigQuery, BigQuery Connection, and Vertex AI APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.
Enable the APIs

Crear conjunto de datos

Crea un conjunto de datos de BigQuery para almacenar tu modelo de aprendizaje automático.

Consola

En la Google Cloud consola, 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.
Haga clic en Ver acciones > Crear conjunto de datos.
En la página Crear conjunto de datos, haz lo siguiente:
- En ID del conjunto de datos, introduce bqml_tutorial.
- En Tipo de ubicación, selecciona Multirregión y, a continuación, EE. UU. (varias regiones de Estados Unidos).
- Deje el resto de los ajustes predeterminados como están y haga clic en Crear conjunto de datos.

bq

Para crear un conjunto de datos, usa el comando bq mk con la marca --location. Para ver una lista completa de los parámetros posibles, consulta la referencia del comando bq mk --dataset.

Crea un conjunto de datos llamado bqml_tutorial con la ubicación de los datos definida como US y la descripción BigQuery ML tutorial dataset:
```
bq --location=US mk -d \
 --description "BigQuery ML tutorial dataset." \
 bqml_tutorial
```
En lugar de usar la marca --dataset, el comando usa el acceso directo -d. Si omite -d y --dataset, el comando creará un conjunto de datos de forma predeterminada.
Confirma que se ha 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"
  }
}

BigQuery DataFrames

Antes de probar este ejemplo, sigue las instrucciones de configuración de BigQuery DataFrames que se indican en la guía de inicio rápido de BigQuery con BigQuery DataFrames. Para obtener más información, consulta la documentación de referencia de los DataFrames de BigQuery.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configurar ADC en un entorno de desarrollo local.

import google.cloud.bigquery

bqclient = google.cloud.bigquery.Client()
bqclient.create_dataset("bqml_tutorial", exists_ok=True)

Crear una conexión

Crea una conexión de recursos de Cloud y obtén la cuenta de servicio de la conexión. Crea la conexión en la misma ubicación que el conjunto de datos que has creado en el paso anterior.

Puedes saltarte este paso si tienes una conexión predeterminada configurada o si tienes el rol Administrador de BigQuery.

Crea una conexión de recursos de Cloud para que la use el modelo remoto y obtén la cuenta de servicio de la conexión. Crea la conexión en la misma ubicación que el conjunto de datos que has creado en el paso anterior.

Selecciona una de las opciones siguientes:

Consola

Ve a la página BigQuery.

Ir a BigQuery
En el panel Explorador, haga clic en Añadir datos:

Se abrirá el cuadro de diálogo Añadir datos.
En el panel Filtrar por, en la sección Tipo de fuente de datos, selecciona Aplicaciones empresariales.

También puede introducir Vertex AI en el campo Buscar fuentes de datos.
En la sección Fuentes de datos destacadas, haga clic en Vertex AI.
Haz clic en la tarjeta de solución Modelos de Vertex AI: federación de BigQuery.
En la lista Tipo de conexión, selecciona Modelos remotos, funciones remotas y BigLake (recurso de Cloud) de Vertex AI.
En el campo ID de conexión, introduce un nombre para la conexión.
Haga 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.

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_id anula el proyecto predeterminado.

Haz los cambios siguientes:
- REGION: tu región de conexión
- PROJECT_ID: tu ID de proyecto Google Cloud
- CONNECTION_ID: 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 a la conexión.

Solución de problemas: si aparece 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...
```

Obtén y copia el ID de la cuenta de servicio para usarlo en un paso posterior:

bq show --connection PROJECT_ID.REGION.CONNECTION_ID

El resultado debería ser similar al siguiente:

name                          properties
1234.REGION.CONNECTION_ID     {"serviceAccountId": "connection-1234-9u56h9@gcp-sa-bigquery-condel.iam.gserviceaccount.com"}

Terraform

Usa el recurso google_bigquery_connection.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configurar la autenticación para bibliotecas de 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 la configuración de Terraform en un proyecto, sigue los pasos que se indican en las siguientes secciones. Google Cloud

Preparar Cloud Shell

Abre Cloud Shell.
Define el Google Cloud proyecto Google Cloud predeterminado en el que quieras aplicar tus configuraciones de Terraform.

Solo tiene que ejecutar este comando una vez por proyecto y puede hacerlo en cualquier directorio.
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
```
Las variables de entorno se anulan si defines valores explícitos en el archivo de configuración de Terraform.

Preparar 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 en ese directorio. El nombre del archivo debe tener la extensión .tf. Por ejemplo, main.tf. En este tutorial, nos referiremos al archivo como main.tf.
```
mkdir DIRECTORY && cd DIRECTORY && touch main.tf
```
Si estás siguiendo un tutorial, puedes copiar el código de ejemplo de cada sección o paso.

Copia el código de ejemplo en el archivo main.tf que acabas de crear.

También puedes copiar el código de GitHub. Se recomienda cuando el fragmento de Terraform forma parte de una solución integral.
Revisa y modifica los parámetros de ejemplo para aplicarlos a tu entorno.
Guarda los cambios.
Inicializa Terraform. Solo tienes que hacerlo una vez por directorio.
```
terraform init
```
Si quieres usar la versión más reciente del proveedor de Google, incluye la opción -upgrade:
```
terraform init -upgrade
```

Aplica los cambios

Revisa la configuración y comprueba que los recursos que va a crear o actualizar Terraform se ajustan a tus expectativas:
```
terraform plan
```
Haga las correcciones necesarias en la configuración.
Aplica la configuración de Terraform ejecutando el siguiente comando e introduciendo yes en la petición:
```
terraform apply
```
Espera hasta que Terraform muestre el mensaje "Apply complete!".
Abre tu Google Cloud proyecto para ver los resultados. En la Google Cloud consola, ve a tus recursos en la interfaz de usuario para asegurarte de que Terraform los ha creado o actualizado.

Conceder permisos a la cuenta de servicio de la conexión

Asigna el rol Usuario de Vertex AI a la cuenta de servicio de la conexión. Debes asignar este rol en el mismo proyecto que hayas creado o seleccionado en la sección Antes de empezar. Si se asigna el rol en otro proyecto, se produce el error bqcx-1234567890-xxxx@gcp-sa-bigquery-condel.iam.gserviceaccount.com does not have the permission to access resource.

Para conceder el rol, sigue estos pasos:

Ve a la página IAM y administración.

Ir a IAM y administración
Haz clic en Conceder acceso.
En el campo Nuevos principales, introduce el ID de la cuenta de servicio que has copiado anteriormente.
En el campo Selecciona un rol, elige Vertex AI y, a continuación, selecciona Rol de usuario de Vertex AI.
Haz clic en Guardar.

Crear el modelo remoto

Crea un modelo remoto que represente un modelo de Vertex AI alojado:

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

Ir a BigQuery
En el editor de consultas, ejecuta la siguiente instrucción:

CREATE OR REPLACE MODEL `bqml_tutorial.gemini_model`
  REMOTE WITH CONNECTION `LOCATION.CONNECTION_ID`
  OPTIONS (ENDPOINT = 'gemini-2.0-flash');

Haz los cambios siguientes:

LOCATION: la ubicación de la conexión
CONNECTION_ID: el ID de tu conexión de BigQuery
Cuando consultas los detalles de la conexión en la consola de Google Cloud , este es el valor de la última sección del ID de conexión completo 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, el modelo gemini_model aparece en el conjunto de datos bqml_tutorial del panel Explorador. Como la consulta usa una instrucción CREATE MODEL para crear un modelo, no hay resultados de la consulta.

Extraer palabras clave

Extrae palabras clave de las reseñas de películas de IMDb mediante el modelo remoto y la función ML.GENERATE_TEXT:

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

Ir a BigQuery

En el editor de consultas, introduce la siguiente instrucción para extraer palabras clave de cinco reseñas de películas:

SELECT
  ml_generate_text_result['candidates'][0]['content'] AS generated_text,
  * EXCEPT (ml_generate_text_result)
FROM
  ML.GENERATE_TEXT(
    MODEL `bqml_tutorial.gemini_model`,
    (
      SELECT
        CONCAT('Extract the key words from the text below: ', review) AS prompt,
        *
      FROM
        `bigquery-public-data.imdb.reviews`
      LIMIT 5
    ),
    STRUCT(
      0.2 AS temperature,
      100 AS max_output_tokens));

El resultado es similar al siguiente, con las columnas no generadas omitidas para que se vea más claro:

+----------------------------------------+-------------------------+----------------------------+-----+
| generated_text                         | ml_generate_text_status | prompt                     | ... |
+----------------------------------------+-------------------------+----------------------------+-----+
| {"parts":[{"text":"## Key words:\n\n*  |                         | Extract the key words from |     |
| **Negative sentiment:** \"terribly     |                         | the text below: I had to   |     |
| bad acting\", \"dumb story\", \"not    |                         | see this on the British    |     |
| even a kid would enjoy this\",         |                         | Airways plane. It was      |     |
| \"something to switch off\"\n*         |                         | terribly bad acting and    |     |
| **Context:** \"British Airways plane\" |                         | a dumb story. Not even     |     |
| \n* **Genre:** \"movie\" (implied)...  |                         | a kid would enjoy this...  |     |
+----------------------------------------+-------------------------+----------------------------+-----+
| {"parts":[{"text":"## Key words:\n\n*  |                         | Extract the key words from |     |
| **Movie:** The Real Howard Spitz\n*    |                         | the text below: This is    |     |
| **Genre:** Family movie\n*             |                         | a family movie that was    |     |
| **Broadcast:** ITV station, 1.00 am\n* |                         | broadcast on my local      |     |
| **Director:** Vadim Jean\n*            |                         | ITV station at 1.00 am a   |     |
| **Main character:** Howard Spitz,      |                         | couple of nights ago.      |     |
| a children's author who hates...       |                         | This might be a strange... |     |
+----------------------------------------+-------------------------+----------------------------+-----+

Los resultados incluyen las siguientes columnas:

generated_text: el texto generado.
ml_generate_text_status: el estado de la respuesta de la API de la fila correspondiente. Si la operación se ha realizado correctamente, este valor estará vacío.
prompt: la petición que se usa para el análisis de sentimiento.
Todas las columnas de la tabla bigquery-public-data.imdb.reviews.

Opcional: En lugar de analizar manualmente el JSON devuelto por la función, como hiciste en el paso anterior, usa el argumento flatten_json_output para devolver el texto generado y los atributos de seguridad en columnas independientes.

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

SELECT
  *
FROM
  ML.GENERATE_TEXT(
    MODEL `bqml_tutorial.gemini_model`,
    (
      SELECT
        CONCAT('Extract the key words from the text below: ', review) AS prompt,
        *
      FROM
        `bigquery-public-data.imdb.reviews`
      LIMIT 5
    ),
    STRUCT(
      0.2 AS temperature,
      100 AS max_output_tokens,
      TRUE AS flatten_json_output));

El resultado es similar al siguiente, con las columnas no generadas omitidas para que se vea más claro:

+----------------------------------------+----------------------------------------------+-------------------------+----------------------------+-----+
| ml_generate_text_llm_result            | ml_generate_text_rai_result                  | ml_generate_text_status | prompt                     | ... |
+----------------------------------------+----------------------------------------------+-------------------------+----------------------------+-----+
| ## Keywords:                           |                                              |                         | Extract the key words from |     |
|                                        |                                              |                         | the text below: I had to   |     |
| * **Negative sentiment:**              |                                              |                         | see this on the British    |     |
| "terribly bad acting", "dumb           |                                              |                         | Airways plane. It was      |     |
| story", "not even a kid would          |                                              |                         | terribly bad acting and    |     |
| enjoy this", "switch off"              |                                              |                         | a dumb story. Not even     |     |
| * **Context:** "British                |                                              |                         | a kid would enjoy this...  |     |
+----------------------------------------+----------------------------------------------+-------------------------+----------------------------+-----+
| ## Key words:                          |                                              |                         | Extract the key words from |     |
|                                        |                                              |                         | the text below: This is    |     |
| * **Movie:** The Real Howard Spitz     |                                              |                         | a family movie that was    |     |
| * **Genre:** Family movie              |                                              |                         | broadcast on my local      |     |
| * **Broadcast:** ITV, 1.00             |                                              |                         | ITV station at 1.00 am a   |     |
| am                                     |                                              |                         | couple of nights ago.      |     |
| - ...                                  |                                              |                         | This might be a strange... |     |
+----------------------------------------+----------------------------------------------+-------------------------+----------------------------+-----+

Los resultados incluyen las siguientes columnas:

ml_generate_text_llm_result: el texto generado.
ml_generate_text_rai_result: los atributos de seguridad, junto con información sobre si el contenido se ha bloqueado debido a una de las categorías de bloqueo. Para obtener más información sobre los atributos de seguridad, consulta Configurar filtros de seguridad.
ml_generate_text_status: el estado de la respuesta de la API de la fila correspondiente. Si la operación se ha realizado correctamente, este valor estará vacío.
prompt: la petición que se usa para la extracción de palabras clave.
Todas las columnas de la tabla bigquery-public-data.imdb.reviews.

Hacer análisis de sentimiento

Realiza un análisis de sentimiento de las reseñas de películas de IMDb usando el modelo remoto y la función ML.GENERATE_TEXT:

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

Ir a BigQuery

En el editor de consultas, ejecuta la siguiente instrucción para realizar un análisis de sentimiento de cinco reseñas de películas:

SELECT
  ml_generate_text_result['candidates'][0]['content'] AS generated_text,
  * EXCEPT (ml_generate_text_result)
FROM
  ML.GENERATE_TEXT(
    MODEL `bqml_tutorial.gemini_model`,
    (
      SELECT
        CONCAT(
          'perform sentiment analysis on the following text, return one the following categories: positive, negative: ',
          review) AS prompt,
        *
      FROM
        `bigquery-public-data.imdb.reviews`
      LIMIT 5
    ),
    STRUCT(
      0.2 AS temperature,
      100 AS max_output_tokens));

El resultado es similar al siguiente, con las columnas no generadas omitidas para que se vea más claro:

+--------------------------------------------+-------------------------+----------------------------+-----+
| generated_text                             | ml_generate_text_status | prompt                     | ... |
+--------------------------------------------+-------------------------+----------------------------+-----+
| {"parts":[{"text":"## Sentiment Analysis:  |                         | perform sentiment analysis |     |
| Negative \n\nThis text expresses a         |                         | on the following text,     |     |
| strongly negative sentiment towards the    |                         | return one the following   |     |
| movie. Here's why:\n\n* **Negative         |                         | negative: I  had to see    |     |
| like \"terribly,\" \"dumb,\" and           |                         | this on the British        |     |
| \"not even\" to describe the acting...     |                         | Airways plane. It was...   |     |
+--------------------------------------------+-------------------------+----------------------------+-----+
| {"parts":[{"text":"## Sentiment Analysis:  |                         | perform sentiment analysis |     |
| Negative \n\nThis review expresses a       |                         | on the following text,     |     |
| predominantly negative sentiment towards   |                         | return one the following   |     |
| the movie \"The Real Howard Spitz.\"       |                         | categories: positive,      |     |
| Here's why:\n\n* **Criticism of the film's |                         | negative: This is a family |     |
| premise:** The reviewer finds it strange   |                         | movie that was broadcast   |     |
| that a film about a children's author...   |                         | on my local ITV station... |     |
+--------------------------------------------+-------------------------+----------------------------+-----+

Los resultados incluyen las mismas columnas que se describen en el artículo sobre cómo extraer palabras clave.

Limpieza

Precaución: Eliminar un proyecto tiene los siguientes efectos:

Se elimina todo el contenido del proyecto. Si has usado un proyecto que ya existía para las tareas de este documento, cuando lo elimines, también se eliminará cualquier otro trabajo que hayas realizado en él.
Se pierden los IDs de proyecto personalizados. Cuando creaste este proyecto, es posible que hayas creado un ID de proyecto personalizado que quieras usar en el futuro. Para conservar las URLs que usan el ID del proyecto, como una URL appspot.com, elimina los recursos seleccionados dentro del proyecto en lugar de eliminar todo el proyecto.

Si tienes previsto consultar varias arquitecturas, tutoriales o guías de inicio rápido, reutilizar los proyectos puede ayudarte a no superar los límites de cuota de proyectos.

In the Google Cloud console, go to the Manage resources page.
Go to Manage resources
In the project list, select the project that you want to delete, and then click Delete.
In the dialog, type the project ID, and then click Shut down to delete the project.