Es posible que parte de la información de esta página (o toda) no se aplique a Cloud de Confiance de S3NS. Consulta Diferencias con Google Cloud para obtener más información.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Analiza datos multimodales con SQL y BigQuery DataFrames

En este instructivo, se muestra cómo analizar datos multimodales con consultas de SQL y BigQuery DataFrames.

En este instructivo, se usa el catálogo de productos del conjunto de datos públicos de la tienda de mascotas de Cymbal.

Objetivos

Usa valores de ObjectRef para almacenar datos de imágenes junto con datos estructurados en una tabla estándar de BigQuery.
Enriquece tus datos con descripciones de imágenes, palabras clave, tipos de animales y subcategorías con la función AI.GENERATE.
Genera embeddings basados en datos de imágenes con la función AI.EMBED.
Encuentra imágenes similares con la función VECTOR_SEARCH.
Resume los manuales del usuario procesando datos multimodales ordenados con arrays de valores de ObjectRef.

Costos

En este documento, usarás los siguientes componentes facturables de Cloud de Confiance by S3NS:

BigQuery: you incur costs for the data that you process in BigQuery.
Cloud Storage: you incur costs for the objects stored in Cloud Storage.
Gemini Enterprise Agent Platform: you incur costs for calls to Agent Platform models.

Para obtener más información, consulta las siguientes páginas de precios:

Antes de comenzar

En la consola de Cloud de Confiance , en la página del selector de proyectos, selecciona o crea un proyecto de Cloud de Confiance .
Roles necesarios para seleccionar o crear un proyecto
- Selecciona 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.
- Crear un proyecto: Para crear un proyecto, necesitas el rol de Creador de proyectos (roles/resourcemanager.projectCreator), que contiene el permiso resourcemanager.projects.create. Obtén más información para otorgar roles.
Nota: Si no planeas conservar los recursos que creaste durante este procedimiento, crea un proyecto en lugar de seleccionar uno existente. Cuando termines, puedes borrar el proyecto y quitar todos los recursos asociados con él.

Ir al selector de proyectos
Verifica que la facturación esté habilitada para tu proyecto de Cloud de Confiance .
Habilita las APIs de BigQuery, BigQuery Connection, Cloud Storage y Agent Platform.
Roles necesarios para habilitar las APIs
Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. 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:

Crea una conexión: Administrador de conexión de BigQuery (roles/bigquery.connectionAdmin)
Otorga permisos a la cuenta de servicio de la conexión: Administrador de IAM del proyecto (roles/resourcemanager.projectIamAdmin)
Crea un bucket de Cloud Storage: Administrador de almacenamiento (roles/storage.admin)
Crear conjuntos de datos, modelos, UDF y tablas, y ejecutar trabajos de BigQuery: Administrador de BigQuery (roles/bigquery.admin)
Crea URLs que te permitan leer y modificar objetos de Cloud Storage: Administrador de ObjectRef de BigQuery (roles/bigquery.objectRefAdmin)

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

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Configurar

En esta sección, crearás el conjunto de datos, la conexión, las tablas y los modelos que se usan en este instructivo.

Crea un conjunto de datos

Crea un conjunto de datos de BigQuery que contenga los objetos que crearás en este instructivo:

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

Ir a 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, selecciona tu proyecto.
Haz clic en Ver acciones y, luego, en Crear conjunto de datos. Se abrirá el panel Crear conjunto de datos.
En ID de conjunto de datos, ingresa cymbal_pets.
Haz clic en Crear conjunto de datos.

Crear una conexión

Crea una conexión de recurso de Cloud y obtén la cuenta de servicio de la conexión. BigQuery usa la conexión para acceder a los objetos en Cloud Storage:

Ve a la página de BigQuery.

Ir a BigQuery
En el panel de la izquierda, haz clic en Explorar.
En el panel Explorador, haz clic en Agregar datos.

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

También puedes ingresar Vertex AI en el campo Buscar fuentes de datos.
En la sección Fuentes de datos destacadas, haz 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 de Vertex AI, funciones remotas, BigLake y Spanner (Cloud Resource).
En el campo ID de conexión, escribe cymbal_conn.
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 siguiente.

Otorga permisos a la cuenta de servicio de las conexiones

Otorga a la cuenta de servicio de la conexión los roles adecuados para acceder a otros servicios. Debes otorgar estos roles en el mismo proyecto que creaste o seleccionaste en la sección Antes de comenzar. Si otorgas los roles en un proyecto diferente, se produce el error bqcx-1234567890-xxxx@gcp-sa-bigquery-condel.s3ns.iam.gserviceaccount.com does not have the permission to access resource.

Crea un bucket

Crea un bucket de Cloud Storage para almacenar objetos transformados:

Ve a la página Buckets.

Ir a Buckets
Haz clic en Crear.
En la página Crear un bucket, en la sección Comenzar, ingresa un nombre único a nivel global que cumpla con los requisitos de nombres de buckets.
Haz clic en Crear.

Otorga permisos en el bucket de Cloud Storage

Otorga a la cuenta de servicio acceso para usar objetos en el bucket que creaste:

Ve a la página Buckets.

Ir a Buckets
Haz clic en el nombre del bucket que creaste.
Haz clic en Permisos.
Haz clic en Otorgar acceso. Se abrirá el diálogo Otorgar acceso.
En el campo Principales nuevas (New principals), ingresa el ID de la cuenta de servicio que copiaste antes.
En el campo Selecciona un rol, elige Cloud Storage y, luego, selecciona Usuario de objetos de almacenamiento.
Haz clic en Guardar.

Otorga permisos para usar los modelos de Agent Platform

Otorga a la cuenta de servicio acceso para usar los modelos de Agent Platform:

Ir a la página IAM y administración

Ir a IAM y administración
Haz clic en Otorgar acceso. Se abrirá el diálogo Otorgar acceso.
En el campo Principales nuevas (New principals), ingresa el ID de la cuenta de servicio que copiaste antes.
En el campo Seleccionar un rol, ingresa Usuario de la plataforma de agentes.
Haz clic en Guardar.

Crea las tablas de datos de ejemplo

Crea tablas para almacenar la información de los productos de mascotas de Cymbal.

Crea la tabla `products`

Crea una tabla estándar que contenga la información de los productos de mascotas de Cymbal:

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

Ir a BigQuery

Ejecuta el siguiente comando para crear la tabla products:

SQL

LOAD DATA OVERWRITE cymbal_pets.products
FROM
  FILES(
    format = 'avro',
    uris = [
      'gs://cloud-samples-data/bigquery/tutorials/cymbal-pets/tables/products/products_*.avro']);

Permite trabajar con BigQuery DataFrames.

Antes de probar este ejemplo, sigue las instrucciones de configuración de BigQuery DataFrames 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 BigQuery DataFrames.

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

import bigframes.bigquery as bbq
import bigframes.pandas as bpd

bbq.load_data(
    "cymbal_pets.products",
    write_disposition="OVERWRITE",
    from_files_options={
        "format": "avro",
        "uris": [
            "gs://cloud-samples-data/bigquery/tutorials/cymbal-pets/tables/products/products_*.avro"
        ],
    },
)

Crea la tabla `product_images`

Crea una tabla de objetos que contenga las imágenes de los productos de mascotas de Cymbal:

Ejecuta el siguiente comando para crear la tabla product_images:

SQL

CREATE OR REPLACE EXTERNAL TABLE cymbal_pets.product_images
  WITH CONNECTION `us.cymbal_conn`
  OPTIONS (
    object_metadata = 'SIMPLE',
    uris = ['gs://cloud-samples-data/bigquery/tutorials/cymbal-pets/images/*.png'],
    max_staleness = INTERVAL 30 MINUTE,
    metadata_cache_mode = AUTOMATIC);

Permite trabajar con BigQuery DataFrames.

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

bbq.create_external_table(
    "cymbal_pets.product_images",
    replace=True,
    connection_name="us.cymbal_conn",
    options={
        "object_metadata": "SIMPLE",
        "uris": [
            "gs://cloud-samples-data/bigquery/tutorials/cymbal-pets/images/*.png"
        ],
    },
)

Crear modelos

Las instrucciones en SQL de este instructivo muestran cómo llamar a funciones basadas en IA que no requieren que crees un modelo. Si sigues las instrucciones de BigQuery DataFrames, selecciona esa opción para crear modelos remotos que representen un modelo de Gemini y un modelo de incorporación multimodal.

SQL

Puedes omitir este paso.

Permite trabajar con BigQuery DataFrames.

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

gemini_model = bbq.ml.create_model(
    "cymbal_pets.gemini",
    replace=True,
    connection_name="us.cymbal_conn",
    options={"endpoint": "gemini-2.5-flash"},
)

embedding_model = bbq.ml.create_model(
    "cymbal_pets.embedding_model",
    replace=True,
    connection_name="us.cymbal_conn",
    options={"endpoint": "multimodalembedding@001"},
)

Crea una tabla `products_mm` con datos multimodales

Crea una tabla products_mm que contenga una columna image propagada con imágenes de productos de la tabla de objetos product_images. La columna image que se crea es una columna de STRUCT que usa el formato ObjectRef.

Ejecuta lo siguiente para crear la tabla products_mm y propagar la columna image:
SQL
CREATE OR REPLACE TABLE cymbal_pets.products_mm AS SELECT products.* EXCEPT (uri), ot.ref AS image FROM cymbal_pets.products INNER JOIN cymbal_pets.product_images ot ON ot.uri = products.uri;
Permite trabajar con BigQuery DataFrames.

Antes de probar este ejemplo, sigue las instrucciones de configuración de BigQuery DataFrames 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 BigQuery DataFrames.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura ADC para un entorno de desarrollo local.
df_images = bpd.read_gbq("SELECT * FROM cymbal_pets.product_images") df_products = bpd.read_gbq("cymbal_pets.products") df_products_mm = df_images.merge(df_products, on="uri").drop(columns="uri") df_products_mm = df_products_mm.rename(columns={"ref": "image"})

Ejecuta lo siguiente para ver los datos de la columna image:

SQL

SELECT product_name, image
FROM cymbal_pets.products_mm

Permite trabajar con BigQuery DataFrames.

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

df_products_mm[["product_name", "image"]]

Los resultados son similares a los siguientes:

+--------------------------------+--------------------------------------+-----------------------------------------------+------------------------------------------------+
| product_name                   | image.uri                            | image.version | image.authorizer              | image.details                                  |
+--------------------------------+--------------------------------------+-----------------------------------------------+------------------------------------------------+
|  AquaClear Aquarium Background | gs://cloud-samples-data/bigquery/    | 1234567891011 | myproject.region.myconnection | {"gcs_metadata":{"content_type":"image/png",   |
|                                | tutorials/cymbal-pets/images/        |               |                               | "md5_hash":"494f63b9b137975ff3e7a11b060edb1d", |
|                                | aquaclear-aquarium-background.png    |               |                               | "size":1282805,"updated":1742492680017000}}    |
+--------------------------------+--------------------------------------+-----------------------------------------------+------------------------------------------------+
|  AquaClear Aquarium            | gs://cloud-samples-data/bigquery/    | 2345678910112 | myproject.region.myconnection | {"gcs_metadata":{"content_type":"image/png",   |
|  Gravel Vacuum                 | tutorials/cymbal-pets/images/        |               |                               | "md5_hash":"b7bfc2e2641a77a402a1937bcf0003fd", |
|                                | aquaclear-aquarium-gravel-vacuum.png |               |                               | "size":820254,"updated":1742492682411000}}     |
+--------------------------------+--------------------------------------+-----------------------------------------------+------------------------------------------------+
| ...                            | ...                                  | ...           |                               | ...                                            |
+--------------------------------+--------------------------------------+-----------------------------------------------+------------------------------------------------+

Genera información del producto

Usa la función AI.GENERATE para generar los siguientes datos de los productos de la tienda de mascotas:

Agrega una columna image_description a la tabla products_mm.
Completa las columnas animal_type, search_keywords y subcategory de la tabla products_mm.
Ejecuta una consulta que devuelva una descripción de cada marca de producto y un recuento de la cantidad de productos de esa marca. La descripción de la marca se genera analizando la información del producto de todos los productos de esa marca, incluidas las imágenes de los productos.

Ejecuta lo siguiente para crear y propagar la columna image_description:

SQL

CREATE OR REPLACE TABLE cymbal_pets.products_mm AS (
  SELECT
    *, AI.GENERATE(('Describe the following image: ', image), endpoint => 'gemini-2.5-pro').result AS image_description
  FROM
    cymbal_pets.products_mm
);

Permite trabajar con BigQuery DataFrames.

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

df_products_mm["url"] = bbq.obj.get_access_url(
    df_products_mm["image"], "R"
).to_frame()
df_products_mm["prompt0"] = "Can you describe the following image?"

df_products_mm["prompt"] = bbq.struct(df_products_mm[["prompt0", "url"]])
df_products_mm = bbq.ai.generate_table(
    gemini_model, df_products_mm, output_schema={"image_description": "STRING"}
)

df_products_mm = df_products_mm[
    [
        "product_id",
        "product_name",
        "brand",
        "category",
        "subcategory",
        "animal_type",
        "search_keywords",
        "price",
        "description",
        "inventory_level",
        "supplier_id",
        "average_rating",
        "image",
        "image_description",
    ]
]

Ejecuta el siguiente comando para actualizar las columnas animal_type, search_keywords y subcategory con los datos generados:

SQL

CREATE OR REPLACE TABLE cymbal_pets.products_mm AS (
SELECT * EXCEPT(animal_type, search_keywords, subcategory),
  AI.GENERATE(
    ('For the image and description of a pet product, concisely generate the following metadata: '
    '1) animal_type and 2) 5 SEO search keywords, and 3) product subcategory. ',
    image,
    description),
    endpoint => 'gemini-2.5-pro',
    output_schema => 'animal_type STRING, search_keywords ARRAY, subcategory STRING').*
FROM cymbal_pets.products_mm);

Permite trabajar con BigQuery DataFrames.

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

df_prompt = bbq.obj.get_access_url(df_products_mm["image"], "R").to_frame()
df_prompt[
    "prompt0"
] = "For the image of a pet product, concisely generate the following metadata: 1) animal_type and 2) 5 SEO search keywords, and 3) product subcategory."

df_products_mm["prompt"] = bbq.struct(df_prompt[["prompt0", "image"]])

df_products_mm = df_products_mm.drop(
    columns=["animal_type", "search_keywords", "subcategory"]
)
df_products_mm = bbq.ai.generate_table(
    gemini_model,
    df_products_mm,
    output_schema="animal_type STRING, search_keywords ARRAY<STRING>, subcategory STRING",
)

Ejecuta el siguiente comando para ver los datos generados:

SQL

SELECT
  product_name,
  image_description,
  animal_type,
  search_keywords,
  subcategory,
FROM cymbal_pets.products_mm;

Permite trabajar con BigQuery DataFrames.

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

df_products_mm[
    [
        "product_name",
        "image_description",
        "animal_type",
        "search_keywords",
        "subcategory",
    ]
]

Los resultados son similares a los siguientes:

+--------------------------------+-------------------------------------+-------------+------------------------+------------------+
| product_name                   | image.description                   | animal_type | search_keywords        | subcategory      |
+--------------------------------+-------------------------------------+-------------+------------------------+------------------+
|  AquaClear Aquarium Background | The image shows a colorful coral    | fish        | aquarium background    | aquarium decor   |
|                                | reef backdrop. The background is a  |             | fish tank backdrop     |                  |
|                                | blue ocean with a bright light...   |             | coral reef decor       |                  |
|                                |                                     |             | underwater scenery     |                  |
|                                |                                     |             | aquarium decoration    |                  |
+--------------------------------+-------------------------------------+-------------+------------------------+------------------+
|  AquaClear Aquarium            | The image shows a long, clear       | fish        | aquarium gravel vacuum | aquarium         |
|  Gravel Vacuum                 | plastic tube with a green hose      |             | aquarium cleaning      | cleaning         |
|                                | attached to one end. The tube...    |             | aquarium maintenance   |                  |
|                                |                                     |             | fish tank cleaning     |                  |
|                                |                                     |             | gravel siphon          |                  |
+--------------------------------+-------------------------------------+-------------+------------------------+------------------+
| ...                            | ...                                 | ...         |  ...                   | ...              |
+--------------------------------+-------------------------------------+-------------+------------------------+------------------+

Ejecuta lo siguiente para generar una descripción de cada marca de producto y un recuento de la cantidad de productos de esa marca:

SQL

SELECT
  brand,
  COUNT(*) AS cnt,
  AI.GENERATE(('Use the images and text to give one concise brand description ',
              'for a website brand page. Return the description only.',
                ARRAY_AGG(image LIMIT 10), ARRAY_AGG(description), ARRAY_AGG(category),
                ARRAY_AGG(subcategory)),
              endpoint => 'gemini-2.5-pro').result AS brand_description
FROM
  cymbal_pets.products_mm
GROUP BY brand
ORDER BY cnt DESC;

Permite trabajar con BigQuery DataFrames.

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

df_agg = df_products_mm[
    ["image", "description", "category", "subcategory", "brand"]
]
df_agg["image"] = bbq.obj.get_access_url(df_products_mm["image"], "R")
df_agg = bbq.array_agg(df_agg.groupby(by=["brand"]))

df_agg["cnt"] = bbq.array_length(df_agg["image"])

df_prompt = df_agg[["image", "description", "category", "subcategory"]]
df_prompt[
    "prompt0"
] = "Use the images and text to give one concise brand description for a website brand page. Return the description only. "

df_agg["prompt"] = bbq.struct(
    df_prompt[["prompt0", "image", "description", "category", "subcategory"]]
)

df_agg = df_agg.reset_index()

df_agg = bbq.ai.generate_table(
    gemini_model, df_agg, output_schema={"brand_description": "STRING"}
)
df_agg[["brand", "brand_description", "cnt"]]

Los resultados son similares a los siguientes:

+--------------+-------------------------------------+-----+
| brand        | brand.description                   | cnt |
+--------------+-------------------------------------+-----+
|  AquaClear   | AquaClear is a brand of aquarium    | 33  |
|              | and pond care products that offer   |     |
|              | a wide range of solutions for...    |     |
+--------------+-------------------------------------+-----+
|  Ocean       | Ocean Bites is a brand of cat food  | 28  |
|  Bites       | that offers a variety of recipes    |     |
|              | and formulas to meet the specific.. |     |
+--------------+-------------------------------------+-----+
|  ...         | ...                                 |...  |
+--------------+-------------------------------------+-----+

Genera embeddings y realiza una búsqueda de vectores

Generar embeddings a partir de datos de imágenes y, luego, usar los embeddings para devolver imágenes similares con la búsqueda de vectores

En una situación de producción, te recomendamos que crees un índice de vectores antes de ejecutar una búsqueda vectorial. Un índice de vectores te permite realizar la búsqueda vectorial más rápidamente, con la compensación de reducir la recuperación y, de esa forma, mostrar resultados más aproximados.

Ejecuta el siguiente comando para crear la tabla products_embeddings:
SQL
CREATE OR REPLACE TABLE cymbal_pets.products_embedding AS ( SELECT product_id, AI.EMBED(image, endpoint => 'multimodalembedding@001').result AS embedding, image FROM cymbal_pets.products_mm );
Permite trabajar con BigQuery DataFrames.

Antes de probar este ejemplo, sigue las instrucciones de configuración de BigQuery DataFrames 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 BigQuery DataFrames.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura ADC para un entorno de desarrollo local.
df_products_mm["content"] = bbq.obj.get_access_url(df_products_mm["image"], "R") df_embed = bbq.ai.generate_embedding( embedding_model, df_products_mm[["content", "product_id"]] ) df_embed.to_gbq("cymbal_pets.products_embedding", if_exists="replace")

Ejecuta el siguiente comando para realizar una búsqueda de vectores y devolver imágenes de productos similares a la imagen de entrada proporcionada:

SQL

SELECT *
FROM
  VECTOR_SEARCH(
    TABLE cymbal_pets.products_embedding,
    'embedding',
    query_value => AI.EMBED(
                    OBJ.MAKE_REF('gs://cloud-samples-data/bigquery/tutorials/cymbal-pets/images/cozy-naps-cat-scratching-post-with-condo.png'),
                    endpoint => 'multimodalembedding@001').result);

Permite trabajar con BigQuery DataFrames.

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

df_image = bpd.DataFrame(
    {
        "uri": [
            "gs://cloud-samples-data/bigquery/tutorials/cymbal-pets/images/cozy-naps-cat-scratching-post-with-condo.png"
        ]
    }
).cache()
df_image["image"] = bbq.obj.make_ref(df_image["uri"], "us.cymbal_conn")
df_search = bbq.ai.generate_embedding(
    embedding_model,
    bbq.obj.get_access_url(bbq.obj.fetch_metadata(df_image["image"]), "R"),
)

search_result = bbq.vector_search(
    "cymbal_pets.products_embedding", "embedding", df_search["embedding"]
)
search_result

Los resultados son similares a los siguientes:

+-----------------+-----------------+----------------+----------------------------------------------+--------------------+-------------------------------+------------------------------------------------+----------------+
| query.embedding | base.product_id | base.embedding | base.image.uri                               | base.image.version | base.image.authorizer         | base.image.details                             | distance       |
+-----------------+-----------------+----------------+----------------------------------------------+--------------------+-------------------------------+------------------------------------------------+----------------+
| -0.0112330541   | 181             | -0.0112330541  | gs://cloud-samples-data/bigquery/            | 12345678910        | myproject.region.myconnection | {"gcs_metadata":{"content_type":               | 0.0            |
| 0.0142525584    |                 |  0.0142525584  | tutorials/cymbal-pets/images/                |                    |                               | "image/png","md5_hash":"21234567hst16555w60j", |                |
| 0.0135886827    |                 |  0.0135886827  | cozy-naps-cat-scratching-post-with-condo.png |                    |                               | "size":828318,"updated":1742492688982000}}     |                |
| 0.0149955815    |                 |  0.0149955815  |                                              |                    |                               |                                                |                |
| ...             |                 |  ...           |                                              |                    |                               |                                                |                |
|                 |                 |                |                                              |                    |                               |                                                |                |
|                 |                 |                |                                              |                    |                               |                                                |                |
+-----------------+-----------------+----------------+----------------------------------------------+--------------------+-------------------------------+------------------------------------------------+----------------+
| -0.0112330541   | 187             | -0.0190353896  | gs://cloud-samples-data/bigquery/            | 23456789101        | myproject.region.myconnection | {"gcs_metadata":{"content_type":               | 0.4216330832.. |
| 0.0142525584    |                 |  0.0116206668  | tutorials/cymbal-pets/images/                |                    |                               | "image/png","md5_hash":"7328728fhakd9937djo4", |                |
| 0.0135886827    |                 |  0.0136198215  | cozy-naps-cat-scratching-post-with-bed.png   |                    |                               | "size":860113,"updated":1742492688774000}}     |                |
| 0.0149955815    |                 |  0.0173457414  |                                              |                    |                               |                                                |                |
| ...             |                 |  ...           |                                              |                    |                               |                                                |                |
|                 |                 |                |                                              |                    |                               |                                                |                |
|                 |                 |                |                                              |                    |                               |                                                |                |
+-----------------+-----------------+----------------+----------------------------------------------+--------------------+-------------------------------+------------------------------------------------+----------------+
| ...             | ...             | ...            | ...                                          | ...                | ...                           | ...                                            | ...            |
+-----------------+-----------------+----------------+----------------------------------------------+--------------------+-------------------------------+------------------------------------------------+----------------+

Procesa datos multimodales ordenados con arrays de valores de `ObjectRef`

En esta sección, se muestra cómo completar las siguientes tareas:

Crea la tabla product_manuals de modo que contenga un archivo PDF para el manual del producto Crittercuisine Pro 5000 y archivos PDF para cada página de ese manual.
Crea una tabla que asigne el manual a sus fragmentos. El manual completo y las páginas del manual se almacenan en una columna ObjectRef.
Analiza un array de valores ObjectRef en conjunto para devolver un solo valor generado.
Analiza un array de valores de ObjectRef por separado y devuelve un valor generado para cada valor del array.

Sigue estos pasos para procesar datos multimodales ordenados con valores de ObjectRef:

Ve a la página de BigQuery.

Ir a BigQuery

Ejecuta el siguiente comando para crear la tabla product_manuals:

SQL

CREATE OR REPLACE EXTERNAL TABLE `cymbal_pets.product_manuals`
  WITH CONNECTION `us.cymbal_conn`
  OPTIONS (
    object_metadata = 'SIMPLE',
    uris = [
        'gs://cloud-samples-data/bigquery/tutorials/cymbal-pets/documents/*.pdf',
        'gs://cloud-samples-data/bigquery/tutorials/cymbal-pets/document_chunks/*.pdf']);

Permite trabajar con BigQuery DataFrames.

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

bbq.create_external_table(
    "cymbal_pets.product_manuals_all",
    replace=True,
    connection_name="us.cymbal_conn",
    options={
        "object_metadata": "SIMPLE",
        "uris": [
            "gs://cloud-samples-data/bigquery/tutorials/cymbal-pets/documents/*.pdf",
            "gs://cloud-samples-data/bigquery/tutorials/cymbal-pets/document_chunks/*.pdf",
        ],
    },
)

Ejecuta el siguiente comando para escribir datos de PDF en la tabla map_manual_to_chunks:

SQL

-- Extract the file and chunks into a single table.
-- Store the chunks in the chunks column as array of ObjectRefs (ordered by page number)
CREATE OR REPLACE TABLE cymbal_pets.map_manual_to_chunks
AS
SELECT ARRAY_AGG(m1.ref)[0] manual, ARRAY_AGG(m2.ref ORDER BY m2.ref.uri) chunks
FROM cymbal_pets.product_manuals m1
JOIN cymbal_pets.product_manuals m2
  ON
    REGEXP_EXTRACT(m1.uri, r'.*/([^.]*).[^/]+')
    = REGEXP_EXTRACT(m2.uri, r'.*/([^.]*)_page[0-9]+.[^/]+')
GROUP BY m1.uri;

Permite trabajar con BigQuery DataFrames.

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

df1 = bpd.read_gbq("SELECT * FROM cymbal_pets.product_manuals_all").sort_values(
    "uri"
)
df2 = df1.copy()
df1["name"] = df1["uri"].str.extract(r".*/([^.]*).[^/]+")
df2["name"] = df2["uri"].str.extract(r".*/([^.]*)_page[0-9]+.[^/]+")
df_manuals_all = df1.merge(df2, on="name")
df_manuals_agg = (
    bbq.array_agg(df_manuals_all[["ref_x", "uri_x"]].groupby("uri_x"))["ref_x"]
    .str[0]
    .to_frame()
)
df_manuals_agg["chunks"] = bbq.array_agg(
    df_manuals_all[["ref_y", "uri_x"]].groupby("uri_x")
)["ref_y"]

Ejecuta el siguiente comando para ver los datos del PDF en la tabla map_manual_to_chunks:

SQL

SELECT *
FROM cymbal_pets.map_manual_to_chunks;

Permite trabajar con BigQuery DataFrames.

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

df_manuals_agg

Los resultados son similares a los siguientes:

+-------------------------------------+--------------------------------+-----------------------------------+------------------------------------------------------+-------------------------------------------+---------------------------------+------------------------------------+-------------------------------------------------------+
| manual.uri                          | manual.version                 | manual.authorizer                 | manual.details                                       | chunks.uri                                | chunks.version                  | chunks.authorizer                  | chunks.details                                        |
+-------------------------------------+--------------------------------+-----------------------------------+------------------------------------------------------+-------------------------------------------+---------------------------------+------------------------------------+-------------------------------------------------------+
| gs://cloud-samples-data/bigquery/   | 1742492785900455               | myproject.region.myconnection     | {"gcs_metadata":{"content_type":"application/pef",   | gs://cloud-samples-data/bigquery/         | 1745875761227129                | myproject.region.myconnection      | {"gcs_metadata":{"content_type":"application/pdf",    |
| tutorials/cymbal-pets/documents/    |                                |                                   | "md5_hash":"c9032b037693d15a33210d638c763d0e",       | tutorials/cymbal-pets/documents/          |                                 |                                    | "md5_hash":"5a1116cce4978ec1b094d8e8b49a1d7c",        |
| crittercuisine_5000_user_manual.pdf |                                |                                   | "size":566105,"updated":1742492785941000}}           | crittercuisine_5000_user_manual_page1.pdf |                                 |                                    | "size":504583,"updated":1745875761266000}}            |
|                                     |                                |                                   |                                                      +-------------------------------------------+---------------------------------+------------------------------------+-------------------------------------------------------+
|                                     |                                |                                   |                                                      | crittercuisine_5000_user_manual_page1.pdf | 1745875760613874                | myproject.region.myconnection      | {"gcs_metadata":{"content_type":"application/pdf",    |
|                                     |                                |                                   |                                                      | tutorials/cymbal-pets/documents/          |                                 |                                    | "md5_hash":"94d03ec65d28b173bc87eac7e587b325",        |
|                                     |                                |                                   |                                                      | crittercuisine_5000_user_manual_page2.pdf |                                 |                                    | "size":94622,"updated":1745875760649000}}             |
|                                     |                                |                                   |                                                      +-------------------------------------------+---------------------------------+------------------------------------+-------------------------------------------------------+
|                                     |                                |                                   |                                                      | ...                                       | ...                             |  ...                               | ...                                                   |
+-------------------------------------+--------------------------------+-----------------------------------+------------------------------------------------------+-------------------------------------------+---------------------------------+------------------------------------+-------------------------------------------------------+

Ejecuta lo siguiente para generar una sola respuesta de un modelo de Gemini basada en el análisis de un array de valores de ObjectRef:

SQL

SELECT
  AI.GENERATE((
    '''Can you provide a page by page summary for the first 3 pages of the attached manual?
    Only write one line for each page. The pages are provided in serial order''',
    chunks),
    endpoint => 'gemini-2.5-pro').result AS Response,
FROM cymbal_pets.map_manual_to_chunks

Permite trabajar con BigQuery DataFrames.

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

df_manuals_agg["chunks_url"] = bbq.array_agg(
    bbq.obj.get_access_url(df_manuals_agg.explode("chunks")["chunks"], "R").groupby(
        "uri_x"
    )
)
df_manuals_agg[
    "prompt0"
] = "Can you provide a page by page summary for the first 3 pages of the attached manual? Only write one line for each page. The pages are provided in serial order"
df_manuals_agg["prompt"] = bbq.struct(df_manuals_agg[["prompt0", "chunks_url"]])

result = bbq.ai.generate_text(gemini_model, df_manuals_agg["prompt"])["result"]
result

Los resultados son similares a los siguientes:

+---------------------------------------------------------------------------+
| Response                                                                  |
+---------------------------------------------------------------------------+
| Here is a one-line summary for each of the first 3 pages:                 |
|                                                                           |
| Page 1 introduces the CritterCuisine Pro 5000 automatic pet feeder and    |
| presents the initial part of the manual's Table of Contents.              |
| Page 2 lists the items included with the feeder and details important     |
| safety precautions for its use.                                           |
| Page 3 describes the feeder's key features, provides assembly and initial |
| setup instructions, and begins the programming guide with clock setting.  |
+---------------------------------------------------------------------------+

Ejecuta lo siguiente para generar varias respuestas de un modelo de Gemini basadas en el análisis de un array de valores de ObjectRef:

SQL

WITH results AS (
  SELECT
    AI.GENERATE((
      '''Can you provide a page by page summary for the first 3 pages of the attached manual?
      Only write one line for each page. The pages are provided in serial order''',
      chunks),
      endpoint => 'gemini-2.5-pro'
      output_schema =>  'page1_summary STRING, page2_summary STRING, page3_summary STRING').*
  FROM cymbal_pets.map_manual_to_chunks)
SELECT page1_summary, page2_summary, page3_summary
FROM results;

Permite trabajar con BigQuery DataFrames.

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

result = bbq.ai.generate_table(
    gemini_model,
    df_manuals_agg["prompt"],
    output_schema={
        "page1_summary": "STRING",
        "page2_summary": "STRING",
        "page3_summary": "STRING",
    },
)[["page1_summary", "page2_summary", "page3_summary"]]
result

Los resultados son similares a los siguientes:

+-----------------------------------------------+-------------------------------------------+----------------------------------------------------+
| page1_summary                                 | page2_summary                             | page3_summary                                      |
+-----------------------------------------------+-------------------------------------------+----------------------------------------------------+
| This manual provides an overview of the       | This section explains how to program      | This page covers connecting the feeder to Wi-Fi    |
| CritterCuisine Pro 5000 automatic pet feeder, | the feeder's clock, set feeding           | using the CritterCuisine Connect app,  remote      |
| including its features, safety precautions,   | schedules, copy and delete meal settings, | feeding, managing feeding schedules, viewing       |
| assembly instructions, and initial setup.     | manually feed your pet, record            | feeding logs, receiving low food alerts,           |
|                                               | a voice message, and understand           | updating firmware, creating multiple pet profiles, |
|                                               | the low food level indicator.             | sharing access with other users, and cleaning      |
|                                               |                                           | and maintaining the feeder.                        |
+-----------------------------------------------+-------------------------------------------+----------------------------------------------------+

Realiza una limpieza

Precaución: Borrar un proyecto tiene las siguientes consecuencias:

Se borra todo su contenido. Si usaste un proyecto existente para las tareas de este documento, cuando lo borres, también se borrará cualquier otro trabajo que hayas realizado en el proyecto.
Se pierden los IDs personalizados de los proyectos. Cuando creaste este proyecto, es posible que hayas creado un ID personalizado del proyecto que desees utilizar en el futuro. Para conservar las URLs que usan el ID del proyecto, como una URL appspot.com, borra los recursos seleccionados dentro del proyecto, en lugar de todo el proyecto.

Si planeas explorar varios instructivos, arquitecturas o guías de inicio rápido, reutilizar proyectos puede ser útil para no exceder los límites de cuota de los proyectos.

En la Cloud de Confiance consola, ve a la página Administrar recursos.
Ir a Administrar recursos
En la lista de proyectos, elige el proyecto que quieres borrar y haz clic en Borrar.
En el diálogo, escribe el ID del proyecto y, luego, haz clic en Cerrar para borrar el proyecto.

Analiza datos multimodales con SQL y BigQuery DataFrames

Objetivos

Costos

Antes de comenzar

Roles obligatorios

Configurar

Crea un conjunto de datos

Crear una conexión

Otorga permisos a la cuenta de servicio de las conexiones

Crea un bucket

Otorga permisos en el bucket de Cloud Storage

Otorga permisos para usar los modelos de Agent Platform

Crea las tablas de datos de ejemplo

Crea la tabla products

SQL

Permite trabajar con BigQuery DataFrames.

Crea la tabla product_images

SQL

Permite trabajar con BigQuery DataFrames.

Crear modelos

SQL

Permite trabajar con BigQuery DataFrames.

Crea una tabla products_mm con datos multimodales

SQL

Permite trabajar con BigQuery DataFrames.

SQL

Permite trabajar con BigQuery DataFrames.

Genera información del producto

SQL

Permite trabajar con BigQuery DataFrames.

SQL

Permite trabajar con BigQuery DataFrames.

SQL

Permite trabajar con BigQuery DataFrames.

SQL

Permite trabajar con BigQuery DataFrames.

Genera embeddings y realiza una búsqueda de vectores

SQL

Permite trabajar con BigQuery DataFrames.

SQL

Permite trabajar con BigQuery DataFrames.

Procesa datos multimodales ordenados con arrays de valores de ObjectRef

SQL

Permite trabajar con BigQuery DataFrames.

SQL

Permite trabajar con BigQuery DataFrames.

SQL

Permite trabajar con BigQuery DataFrames.

SQL

Permite trabajar con BigQuery DataFrames.

SQL

Permite trabajar con BigQuery DataFrames.

Realiza una limpieza

Crea la tabla `products`

Crea la tabla `product_images`

Crea una tabla `products_mm` con datos multimodales

Procesa datos multimodales ordenados con arrays de valores de `ObjectRef`