Analizar imágenes con un modelo de Gemini

En este tutorial se explica cómo crear un modelo remoto de BigQuery ML basado en el modelo gemini-2.5-flash y, a continuación, cómo usar ese modelo con las funciones ML.GENERATE_TEXT para analizar un conjunto de imágenes de carteles de películas.

En este tutorial se explican las siguientes tareas:

• Crear una tabla de objetos de BigQuery a partir de datos de imagen en un segmento de Cloud Storage.
• Crear un modelo remoto de BigQuery ML que tenga como objetivo el modelo gemini-2.5-flash de Vertex AI.
• Usar el modelo remoto con la función ML.GENERATE_TEXT para identificar las películas asociadas a un conjunto de carteles de películas.

Los datos del póster de la película están disponibles en el segmento público de Cloud Storage gs://cloud-samples-data/vertex-ai/dataset-management/datasets/classic-movie-posters.

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 una tabla de objetos: bigquery.tables.create y bigquery.tables.update
• 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 model that is represented by the BigQuery 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 la IA generativa de Vertex AI, consulta la página de precios de Vertex AI.

Antes de empezar

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

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

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

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

   Ir a la página de BigQuery

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

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

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

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

2. 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 la tabla de objetos

Crea una tabla de objetos sobre las imágenes de carteles de películas en el segmento público de Cloud Storage. La tabla de objetos permite analizar las imágenes sin moverlas de Cloud Storage.

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

   Ir a BigQuery

2. En el editor de consultas, ejecuta la siguiente consulta para crear la tabla de objetos:

   CREATE OR REPLACE EXTERNAL TABLE `bqml_tutorial.movie_posters`
     WITH CONNECTION DEFAULT
     OPTIONS (
       object_metadata = 'SIMPLE',
       uris =
         ['gs://cloud-samples-data/vertex-ai/dataset-management/datasets/classic-movie-posters/*']);

Crear el modelo remoto

Crea un modelo remoto que represente un modelo de Vertex AI gemini-2.5-flash:

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

   Ir a BigQuery

2. En el editor de consultas, ejecuta la siguiente consulta para crear el modelo remoto:

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

   La consulta tarda varios segundos en completarse. Después, el modelo gemini-vision 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.

Analizar los carteles de películas

Usa el modelo remoto para analizar los carteles de películas y determinar qué película representa cada cartel. Después, escribe estos datos en una tabla.

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

   Ir a BigQuery

2. En el editor de consultas, ejecuta la siguiente consulta para analizar las imágenes de los carteles de películas:

   CREATE OR REPLACE TABLE
     `bqml_tutorial.movie_posters_results` AS (
     SELECT
       uri,
       ml_generate_text_llm_result
     FROM
       ML.GENERATE_TEXT( MODEL `bqml_tutorial.gemini-vision`,
         TABLE `bqml_tutorial.movie_posters`,
         STRUCT( 0.2 AS temperature,
           'For the movie represented by this poster, what is the movie title and year of release? Answer in JSON format with two keys: title, year. title should be string, year should be integer.' AS PROMPT,
           TRUE AS FLATTEN_JSON_OUTPUT)));
       

3. En el editor de consultas, ejecuta la siguiente instrucción para ver los datos de la tabla:

   SELECT * FROM `bqml_tutorial.movie_posters_results`;

   El resultado debería ser similar al siguiente:

   +--------------------------------------------+----------------------------------+
   | uri                                        | ml_generate_text_llm_result      |
   +--------------------------------------------+----------------------------------+
   | gs://cloud-samples-data/vertex-ai/dataset- | json                          |
   | management/datasets/classic-movie-         | {                                |
   | posters/little_annie_rooney.jpg            |  "title": "Little Annie Rooney", |
   |                                            |  "year": 1912                    |
   |                                            | }                                |
   |                                            |                              |
   +--------------------------------------------+----------------------------------+
   | gs://cloud-samples-data/vertex-ai/dataset- | json                          |
   | management/datasets/classic-movie-         | {                                |
   | posters/mighty_like_a_mouse.jpg            |  "title": "Mighty Like a Moose", |
   |                                            |  "year": 1926                    |
   |                                            | }                                |
   |                                            |                              |
   +--------------------------------------------+----------------------------------+
   | gs://cloud-samples-data/vertex-ai/dataset- | json                          |
   | management/datasets/classic-movie-         | {                                |
   | posters/brown_of_harvard.jpeg              |  "title": "Brown of Harvard",    |
   |                                            |  "year": 1926                    |
   |                                            | }                                |
   |                                            |                              |
   +--------------------------------------------+----------------------------------+
   

Dar formato a la salida del modelo

Da formato a los datos de análisis de películas devueltos por el modelo para que el título y el año de la película sean más legibles.

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

   Ir a BigQuery

2. En el editor de consultas, ejecuta la siguiente consulta para dar formato a los datos:

   CREATE OR REPLACE TABLE
     `bqml_tutorial.movie_posters_results_formatted` AS (
     SELECT
       uri,
       JSON_QUERY(RTRIM(LTRIM(results.ml_generate_text_llm_result, " ```json"), "```"), "$.title") AS title,
       JSON_QUERY(RTRIM(LTRIM(results.ml_generate_text_llm_result, " ```json"), "```"), "$.year") AS year
     FROM
       `bqml_tutorial.movie_posters_results` results );

3. En el editor de consultas, ejecuta la siguiente instrucción para ver los datos de la tabla:

   SELECT * FROM `bqml_tutorial.movie_posters_results_formatted`;

   El resultado debería ser similar al siguiente:

   +--------------------------------------------+----------------------------+------+
   | uri                                        | title                      | year |
   +--------------------------------------------+----------------------------+------+
   | gs://cloud-samples-data/vertex-ai/dataset- | "Barque sortant du port"   | 1895 |
   | management/datasets/classic-movie-         |                            |      |
   | posters/barque_sortant_du_port.jpeg        |                            |      |
   +--------------------------------------------+----------------------------+------+
   | gs://cloud-samples-data/vertex-ai/dataset- | "The Great Train Robbery"  | 1903 |
   | management/datasets/classic-movie-         |                            |      |
   | posters/the_great_train_robbery.jpg        |                            |      |
   +--------------------------------------------+----------------------------+------+
   | gs://cloud-samples-data/vertex-ai/dataset- | "Little Annie Rooney"      | 1912 |
   | management/datasets/classic-movie-         |                            |      |
   | posters/little_annie_rooney.jpg            |                            |      |
   +--------------------------------------------+----------------------------+------+
   

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.

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.