Il est possible qu'une partie ou l'ensemble des informations de cette page ne s'appliquent pas au Cloud de confiance S3NS. Pour en savoir plus, consultez Différences par rapport à Google Cloud.

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

Analyser des données multimodales avec SQL et les DataFrames BigQuery

Ce tutoriel vous explique comment analyser des données multimodales à l'aide de requêtes SQL et de BigQuery DataFrames.

Ce tutoriel utilise le catalogue de produits de l'ensemble de données public sur l'animalerie Cymbal.

Objectifs

Utilisez les valeurs ObjectRef pour stocker les données d'image avec les données structurées dans une table standard BigQuery.
Enrichissez vos données avec des descriptions d'images, des mots clés, des types d'animaux et des sous-catégories à l'aide de la fonction AI.GENERATE.
Générez des embeddings basés sur des données d'image à l'aide de la fonction AI.EMBED.
Recherchez des images similaires à l'aide de la fonction VECTOR_SEARCH.
Résumez les manuels d'utilisation en traitant les données multimodales ordonnées à l'aide de tableaux de valeurs ObjectRef.

Coûts

Dans ce document, vous utilisez les composants facturables suivants 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.

Pour en savoir plus, consultez les pages suivantes sur les tarifs :

Avant de commencer

Dans la console Cloud de Confiance , sur la page de sélection du projet, sélectionnez ou créez un projet Cloud de Confiance .
Rôles requis pour sélectionner ou créer un projet
- Sélectionnez un projet : la sélection d'un projet ne nécessite pas de rôle IAM spécifique. Vous pouvez sélectionner n'importe quel projet pour lequel un rôle vous a été attribué.
- Créer un projet : pour créer un projet, vous devez disposer du rôle Créateur de projet (roles/resourcemanager.projectCreator), qui contient l'autorisation resourcemanager.projects.create. Découvrez comment attribuer des rôles.
Remarque : Si vous ne comptez pas conserver les ressources créées dans cette procédure, créez un projet au lieu de sélectionner un projet existant. Après avoir suivi ces étapes, vous pouvez supprimer le projet. Cela entraîne la suppression de toutes les ressources qui lui sont associées.

Accéder au sélecteur de projet
Vérifiez que la facturation est activée pour votre projet Cloud de Confiance .
Activez les API BigQuery, BigQuery Connection, Cloud Storage et Agent Platform.
Rôles requis pour activer les API
Pour activer les API, vous avez besoin du rôle IAM Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin), qui contient l'autorisation serviceusage.services.enable. Découvrez comment attribuer des rôles.
Activer les API

Rôles requis

Pour obtenir les autorisations nécessaires pour suivre ce tutoriel, demandez à votre administrateur de vous accorder les rôles IAM suivants :

Créer une connexion : Administrateur de connexion BigQuery (roles/bigquery.connectionAdmin)
Accorder des autorisations au compte de service de la connexion : Administrateur de projet IAM (roles/resourcemanager.projectIamAdmin)
Créez un bucket Cloud Storage : Administrateur de l'espace de stockage (roles/storage.admin)
Créer des ensembles de données, des modèles, des UDF et des tables, et exécuter des jobs BigQuery : Administrateur BigQuery (roles/bigquery.admin)
Créer des URL qui vous permettent de lire et de modifier des objets Cloud Storage : Administrateur d'ObjectRef BigQuery (roles/bigquery.objectRefAdmin)

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Configurer

Dans cette section, vous allez créer l'ensemble de données, la connexion, les tables et les modèles utilisés dans ce tutoriel.

Créer un ensemble de données

Créez un ensemble de données BigQuery pour contenir les objets que vous allez créer dans ce tutoriel :

Dans la console Cloud de Confiance , accédez à la page BigQuery.

Accéder à BigQuery
Dans le volet de gauche, cliquez sur Explorateur :

Si le volet de gauche ne s'affiche pas, cliquez sur Développer le volet de gauche pour l'ouvrir.
Dans le volet Explorateur, sélectionnez votre projet.
Cliquez sur Afficher les actions, puis sur Créer un ensemble de données. Le volet Créer un ensemble de données s'ouvre.
Dans le champ ID de l'ensemble de données, saisissez cymbal_pets.
Cliquez sur Créer un ensemble de données.

Créer une connexion

Créez une connexion de ressource cloud et obtenez le compte de service de la connexion. BigQuery utilise la connexion pour accéder aux objets dans Cloud Storage :

Accédez à la page BigQuery.

Accéder à BigQuery
Dans le volet de gauche, cliquez sur Explorateur :
Dans le volet Explorateur, cliquez sur Ajouter des données.

La boîte de dialogue Ajouter des données s'ouvre.
Dans le panneau Filtrer par, dans la section Type de source de données, sélectionnez Applications métier.

Vous pouvez également saisir Vertex AI dans le champ Rechercher des sources de données.
Dans la section Sources de données recommandées, cliquez sur Vertex AI.
Cliquez sur la carte de solution Vertex AI Models: BigQuery Federation (Vertex AI : Fédération BigQuery).
Dans la liste Type de connexion, sélectionnez Modèles distants Vertex AI, fonctions à distance, BigLake et Spanner (ressource Cloud).
Dans le champ ID de connexion, saisissez cymbal_conn.
Cliquez sur Créer une connexion.
Cliquez sur Accéder à la connexion.
Dans le volet Informations de connexion, copiez l'ID du compte de service à utiliser à l'étape suivante.

Accorder des autorisations au compte de service de la connexion

Attribuez au compte de service de la connexion les rôles appropriés pour accéder aux autres services. Vous devez accorder ces rôles dans le projet que vous avez créé ou sélectionné dans la section Avant de commencer. L'attribution des rôles dans un autre projet génère l'erreur bqcx-1234567890-xxxx@gcp-sa-bigquery-condel.s3ns.iam.gserviceaccount.com does not have the permission to access resource.

Créer un bucket

Créez un bucket Cloud Storage pour stocker les objets transformés :

Accédez à la page Buckets.

Accéder à la page "Buckets"
Cliquez sur Créer.
Sur la page Créer un bucket, dans la section Premiers pas, saisissez un nom unique qui répond aux exigences de dénomination des buckets.
Cliquez sur Créer.

Accorder des autorisations sur le bucket Cloud Storage

Accordez au compte de service l'accès aux objets du bucket que vous avez créé :

Accédez à la page Buckets.

Accéder à la page "Buckets"
Cliquez sur le nom du bucket que vous avez créé.
Cliquez sur Autorisations.
Cliquez sur Accorder l'accès. La boîte de dialogue Accorder l'accès s'ouvre.
Dans le champ Nouveaux comptes principaux, saisissez l'ID du compte de service que vous avez copié précédemment.
Dans le champ Sélectionner un rôle, sélectionnez Cloud Storage, puis Utilisateur d'objets Storage.
Cliquez sur Enregistrer.

Accorder des autorisations pour utiliser les modèles Agent Platform

Accordez au compte de service l'accès aux modèles Agent Platform :

Accédez à la page IAM et administration.

Accéder à IAM et administration
Cliquez sur Accorder l'accès. La boîte de dialogue Accorder l'accès s'ouvre.
Dans le champ Nouveaux comptes principaux, saisissez l'ID du compte de service que vous avez copié précédemment.
Dans le champ Sélectionner un rôle, saisissez Utilisateur de la plate-forme d'agent.
Cliquez sur Enregistrer.

Créer les tables de données d'exemple

Créez des tables pour stocker les informations produit pour animaux de compagnie Cymbal.

Créer la table `products`

Créez une table standard contenant les informations sur les produits Cymbal Pets :

Dans la console Cloud de Confiance , accédez à la page BigQuery.

Accéder à BigQuery

Exécutez la commande suivante pour créer la table 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']);

BigQuery DataFrames

Avant d'essayer cet exemple, suivez les instructions de configuration pour BigQuery DataFrames du guide de démarrage rapide de BigQuery DataFrames. Pour en savoir plus, consultez la documentation de référence sur BigQuery DataFrames.

Pour vous authentifier auprès de BigQuery, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer les ADC pour un environnement de développement 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"
        ],
    },
)

Créer la table `product_images`

Créez une table d'objets contenant les images des produits Cymbal Pets :

Exécutez la commande suivante pour créer la table 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);

BigQuery DataFrames

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"
        ],
    },
)

Créer des modèles

Les instructions SQL de ce tutoriel montrent comment appeler des fonctions d'IA qui ne nécessitent pas de créer un modèle. Si vous suivez les instructions de BigQuery DataFrames, sélectionnez cette option pour créer des modèles distants qui représentent un modèle Gemini et un modèle d'embedding multimodal.

SQL

Vous pouvez passer cette étape.

BigQuery DataFrames

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"},
)

Créer une table `products_mm` avec des données multimodales

Créez une table products_mm contenant une colonne image remplie avec des images de produits provenant de la table d'objets product_images. La colonne image qui est créée est une colonne STRUCT qui utilise le format ObjectRef.

Exécutez la requête suivante pour créer la table products_mm et remplir la colonne 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;
BigQuery DataFrames

Avant d'essayer cet exemple, suivez les instructions de configuration pour BigQuery DataFrames du guide de démarrage rapide de BigQuery DataFrames. Pour en savoir plus, consultez la documentation de référence sur BigQuery DataFrames.

Pour vous authentifier auprès de BigQuery, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer les ADC pour un environnement de développement 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"})

Exécutez la commande suivante pour afficher les données de la colonne image :

SQL

SELECT product_name, image
FROM cymbal_pets.products_mm

BigQuery DataFrames

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

Les résultats ressemblent à ce qui suit :

+--------------------------------+--------------------------------------+-----------------------------------------------+------------------------------------------------+
| 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}}     |
+--------------------------------+--------------------------------------+-----------------------------------------------+------------------------------------------------+
| ...                            | ...                                  | ...           |                               | ...                                            |
+--------------------------------+--------------------------------------+-----------------------------------------------+------------------------------------------------+

Générer des informations produit

Utilisez la fonction AI.GENERATE pour générer les données suivantes pour les produits de l'animalerie :

Ajoutez une colonne image_description au tableau products_mm.
Remplissez les colonnes animal_type, search_keywords et subcategory de la table products_mm.
Exécutez une requête qui renvoie une description de chaque marque de produit ainsi que le nombre de produits de cette marque. La description de la marque est générée en analysant les informations produit pour tous les produits de cette marque, y compris les images des produits.

Exécutez la commande suivante pour créer et remplir la colonne 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
);

BigQuery DataFrames

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",
    ]
]

Exécutez la commande suivante pour mettre à jour les colonnes animal_type, search_keywords et subcategory avec les données générées :

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);

BigQuery DataFrames

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",
)

Exécutez la commande suivante pour afficher les données générées :

SQL

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

BigQuery DataFrames

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

Les résultats ressemblent à ce qui suit :

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

Exécutez la requête suivante pour générer une description de chaque marque de produit et le nombre de produits de cette marque :

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;

BigQuery DataFrames

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"]]

Les résultats ressemblent à ce qui suit :

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

Générer des embeddings et effectuer une recherche vectorielle

Générez des embeddings à partir de données d'image, puis utilisez-les pour renvoyer des images similaires à l'aide de la recherche vectorielle.

Dans un scénario de production, nous vous recommandons de créer un index vectoriel avant d'exécuter une recherche vectorielle. Un index vectoriel vous permet d'effectuer une recherche vectorielle plus rapidement, avec le compromis de réduire le rappel et donc de renvoyer des résultats plus approximatifs.

Exécutez la requête suivante pour créer la table 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 );
BigQuery DataFrames

Avant d'essayer cet exemple, suivez les instructions de configuration pour BigQuery DataFrames du guide de démarrage rapide de BigQuery DataFrames. Pour en savoir plus, consultez la documentation de référence sur BigQuery DataFrames.

Pour vous authentifier auprès de BigQuery, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer les ADC pour un environnement de développement 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")

Exécutez la commande suivante pour effectuer une recherche vectorielle et renvoyer des images de produits similaires à l'image d'entrée donnée :

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);

BigQuery DataFrames

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

Les résultats ressemblent à ce qui suit :

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

Traiter des données multimodales ordonnées à l'aide de tableaux de valeurs `ObjectRef`

Ce guide vous explique comment effectuer les tâches suivantes :

Créez le tableau product_manuals de sorte qu'il contienne à la fois un fichier PDF pour le manuel du produit Crittercuisine Pro 5000 et des fichiers PDF pour chaque page de ce manuel.
Créez un tableau qui mappe le manuel à ses blocs. Le manuel complet et les pages du manuel sont chacun stockés dans une colonne ObjectRef.
Analysez un tableau de valeurs ObjectRef ensemble pour renvoyer une seule valeur générée.
Analysez un tableau de valeurs ObjectRef séparément et renvoyez une valeur générée pour chaque valeur du tableau.

Suivez ces étapes pour traiter les données multimodales ordonnées à l'aide des valeurs ObjectRef :

Accédez à la page BigQuery.

Accéder à BigQuery

Exécutez la requête suivante pour créer la table 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']);

BigQuery DataFrames

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",
        ],
    },
)

Exécutez la requête suivante pour écrire des données PDF dans la table 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;

BigQuery DataFrames

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"]

Exécutez la commande suivante pour afficher les données PDF dans la table map_manual_to_chunks :

SQL

SELECT *
FROM cymbal_pets.map_manual_to_chunks;

BigQuery DataFrames

df_manuals_agg

Les résultats ressemblent à ce qui suit :

+-------------------------------------+--------------------------------+-----------------------------------+------------------------------------------------------+-------------------------------------------+---------------------------------+------------------------------------+-------------------------------------------------------+
| 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}}             |
|                                     |                                |                                   |                                                      +-------------------------------------------+---------------------------------+------------------------------------+-------------------------------------------------------+
|                                     |                                |                                   |                                                      | ...                                       | ...                             |  ...                               | ...                                                   |
+-------------------------------------+--------------------------------+-----------------------------------+------------------------------------------------------+-------------------------------------------+---------------------------------+------------------------------------+-------------------------------------------------------+

Exécutez la commande suivante pour générer une seule réponse à partir d'un modèle Gemini en fonction de l'analyse d'un tableau de valeurs 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

BigQuery DataFrames

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

Les résultats ressemblent à ce qui suit :

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

Exécutez la commande suivante pour générer plusieurs réponses à partir d'un modèle Gemini en fonction de l'analyse d'un tableau de valeurs 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;

BigQuery DataFrames

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

Les résultats ressemblent à ce qui suit :

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

Effectuer un nettoyage

Attention : La suppression d'un projet aura les effets suivants :

Tout le contenu du projet est supprimé. Si vous avez utilisé un projet existant pour les tâches décrites dans ce document et que vous le supprimez, vous supprimerez également tout autre travail effectué dans le projet.
Les ID de projets personnalisés sont perdus. Lorsque vous avez créé ce projet, vous avez peut-être créé un ID de projet personnalisé que vous souhaitez utiliser à l'avenir. Pour conserver les URL qui utilisent l'ID de projet, telle qu'une URL appspot.com, supprimez les ressources sélectionnées dans le projet au lieu de supprimer l'ensemble du projet.

Si vous envisagez d'explorer plusieurs architectures, tutoriels et guides de démarrage rapide, réutiliser des projets peut vous aider à ne pas dépasser les limites de quotas des projets.

Dans la console Cloud de Confiance , accédez à la page Gérer les ressources.
Accéder à la page "Gérer les ressources"
Dans la liste des projets, sélectionnez le projet que vous souhaitez supprimer, puis cliquez sur Supprimer.
Dans la boîte de dialogue, saisissez l'ID du projet, puis cliquez sur Arrêter pour supprimer le projet.

Analyser des données multimodales avec SQL et les DataFrames BigQuery

Objectifs

Coûts

Avant de commencer

Rôles requis

Configurer

Créer un ensemble de données

Créer une connexion

Accorder des autorisations au compte de service de la connexion

Créer un bucket

Accorder des autorisations sur le bucket Cloud Storage

Accorder des autorisations pour utiliser les modèles Agent Platform

Créer les tables de données d'exemple

Créer la table products

SQL

BigQuery DataFrames

Créer la table product_images

SQL

BigQuery DataFrames

Créer des modèles

SQL

BigQuery DataFrames

Créer une table products_mm avec des données multimodales

SQL

BigQuery DataFrames

SQL

BigQuery DataFrames

Générer des informations produit

SQL

BigQuery DataFrames

SQL

BigQuery DataFrames

SQL

BigQuery DataFrames

SQL

BigQuery DataFrames

Générer des embeddings et effectuer une recherche vectorielle

SQL

BigQuery DataFrames

SQL

BigQuery DataFrames

Traiter des données multimodales ordonnées à l'aide de tableaux de valeurs ObjectRef

SQL

BigQuery DataFrames

SQL

BigQuery DataFrames

SQL

BigQuery DataFrames

SQL

BigQuery DataFrames

SQL

BigQuery DataFrames

Effectuer un nettoyage

Créer la table `products`

Créer la table `product_images`

Créer une table `products_mm` avec des données multimodales

Traiter des données multimodales ordonnées à l'aide de tableaux de valeurs `ObjectRef`