BigQuery DataFrames を使用して Python でマルチモーダル データを分析する

プレビュー版

この機能は、サービス固有の規約の「一般サービス規約」セクションの「pre-GA サービス規約」の対象となります。 pre-GA の機能は「現状のまま」で提供されるものであり、サポートが制限されることがあります。 詳細については、リリース ステージの説明をご覧ください。

注: この機能に関するフィードバックやサポートのリクエストを行う場合は、[e-mail] 宛てにメールを送信してください。

このチュートリアルでは、BigQuery DataFrames のクラスとメソッドを使用して、Python ノートブックでマルチモーダル データを分析する方法について説明します。

このチュートリアルでは、一般公開されている Cymbal ペットショップ データセットの商品カタログを使用します。

このチュートリアルで説明するタスクがすでに入力されているノートブックをアップロードするには、BigFrames マルチモーダル DataFrame をご覧ください。

目標

• マルチモーダル DataFrame を作成する。
• 構造化データと非構造化データを DataFrame に結合する。
• 画像を変換する。
• 画像データに基づいてテキストとエンベディングを生成する。
• PDF をチャンク化してさらに分析する。

費用

このドキュメントでは、課金対象である次の Google Cloudコンポーネントを使用します。

• BigQuery: you incur costs for the data that you process in BigQuery.
• BigQuery Python UDFs: you incur costs for using BigQuery DataFrames image transformation and chunk PDF methods.
• Cloud Storage: you incur costs for the objects stored in Cloud Storage.
• Vertex AI: you incur costs for calls to Vertex AI models.

料金計算ツールを使うと、予想使用量に基づいて費用の見積もりを生成できます。

新規の Google Cloud ユーザーは無料トライアルをご利用いただける場合があります。

詳細については、料金についての次のページをご覧ください。

• BigQuery の料金
• BigQuery Python UDF の料金
• Cloud Storage の料金
• Vertex AI の料金

始める前に

1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   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. Make sure that billing is enabled for your Google Cloud project.

3. Enable the BigQuery, BigQuery Connection, Cloud Storage, and Vertex AI APIs.

   Enable the APIs

必要なロール

このチュートリアルを完了するために必要な権限を取得するには、管理者に次の IAM ロールを付与するよう依頼してください。

• 接続を作成する: BigQuery Connection 管理者（roles/bigquery.connectionAdmin）
• 接続のサービス アカウントに権限を付与する: プロジェクト IAM 管理者 （roles/resourcemanager.projectIamAdmin）
• Cloud Storage バケットを作成する: ストレージ管理者（roles/storage.admin）
• BigQuery ジョブを実行する: BigQuery ユーザー（roles/bigquery.user）
• Python UDF を作成して呼び出す: BigQuery データ編集者（roles/bigquery.dataEditor）
• Cloud Storage オブジェクトの読み取りと変更を可能にする URL を作成する: BigQuery ObjectRef 管理者 （roles/bigquery.objectRefAdmin）
• ノートブックを使用する:
  • BigQuery 読み取りセッション ユーザー（roles/bigquery.readSessionUser）
  • ノートブック ランタイム ユーザー（）roles/aiplatform.notebookRuntimeUser
  • ノートブック ランタイム ユーザー（）roles/aiplatform.notebookRuntimeUser
  • コード作成者（）roles/dataform.codeCreator

ロールの付与については、プロジェクト、フォルダ、組織へのアクセスを管理するをご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

設定

このセクションでは、このチュートリアルで使用する Cloud Storage バケット、接続、ノートブックを作成します。

バケットの作成

変換されたオブジェクトを保存する Cloud Storage バケットを作成します。

1. Google Cloud コンソールで [バケット] ページに移動します。

   [バケット] に移動

2. [作成] をクリックします。

3. [バケットの作成] ページの [始める] セクションで、バケット名の要件を満たすグローバルに一意の名前を入力します。

4. [作成] をクリックします。

接続を作成する

クラウド リソース接続を作成し、接続のサービス アカウントを取得します。BigQuery は、この接続を使用して Cloud Storage 内のオブジェクトにアクセスします。

1. [BigQuery] ページに移動します。

   BigQuery に移動

2. [エクスプローラ] ペインで、 [データを追加] をクリックします。

   [データを追加] ダイアログが開きます。

3. [フィルタ条件] ペインの [データソースのタイプ] セクションで、[ビジネス アプリケーション] を選択します。

   または、[データソースを検索] フィールドに「Vertex AI」と入力します。

4. [特徴量データソース] セクションで、[Vertex AI] をクリックします。

5. [Vertex AI モデル: BigQuery フェデレーション] ソリューション カードをクリックします。

6. [接続タイプ] リストで、[Vertex AI リモートモデル、リモート関数、BigLake（Cloud リソース）] を選択します。

7. [接続 ID] フィールドに「bigframes-default-connection」と入力します。

8. [接続を作成] をクリックします。

9. [接続へ移動] をクリックします。

10. [接続情報] ペインで、次の手順で使用するサービス アカウント ID をコピーします。

接続のサービス アカウントに権限を付与する

接続のサービス アカウントに、Cloud Storage と Vertex AI へのアクセスに必要なロールを付与します。これらのロールは、始める前にで作成または選択したプロジェクトで付与する必要があります。

ロールを付与する手順は次のとおりです。

1. [IAM と管理] ページに移動します。

   [IAM と管理] に移動

2. [アクセスを許可] をクリックします。

3. [新しいプリンシパル] フィールドに、前の手順でコピーしたサービス アカウント ID を入力します。

4. [ロールを選択] フィールドで、[Cloud Storage] を選択し、続いて [Storage オブジェクト ユーザー] を選択します。

5. [別のロールを追加] をクリックします。

6. [ロールを選択] フィールドで、[Vertex AI] を選択し、[Vertex AI ユーザー] を選択します。

7. [保存] をクリックします。

ノートブックを作成する

Python コードを実行できるノートブックを作成します。

1. [BigQuery] ページに移動します。

   [BigQuery] に移動

2. 編集ペインのタブバーで、SQL クエリアイコン の横にあるプルダウン矢印 をクリックし、[ノートブック] をクリックします。

3. [テンプレートを使って開始] ペインで [閉じる] をクリックします。

4. [接続] > [ランタイムに接続] をクリックします。

5. 既存のランタイムがある場合は、デフォルトの設定をそのまま使用し、[接続] をクリックします。既存のランタイムがない場合は、[新しいランタイムを作成] を選択し、[接続] をクリックします。

   ランタイムの設定には数分かかることがあります。

マルチモーダル DataFrame を作成する

Session クラスの from_glob_path メソッドを使用して、構造化データと非構造化データを統合するマルチモーダル DataFrame を作成します。

1. ノートブックでコードセルを作成し、次のコードをコピーします。
   import bigframes
   
   # Flags to control preview image/video preview size
   bigframes.options.display.blob_display_width = 300
   
   import bigframes.pandas as bpd
   
   # Create blob columns from wildcard path.
   df_image = bpd.from_glob_path(
       "gs://cloud-samples-data/bigquery/tutorials/cymbal-pets/images/*", name="image"
   )
   # Other ways are: from string uri column
   # df = bpd.DataFrame({"uri": ["gs://<my_bucket>/<my_file_0>", "gs://<my_bucket>/<my_file_1>"]})
   # df["blob_col"] = df["uri"].str.to_blob()
   
   # From an existing object table
   # df = bpd.read_gbq_object_table("<my_object_table>", name="blob_col")
   
   # Take only the 5 images to deal with. Preview the content of the Mutimodal DataFrame
   df_image = df_image.head(5)
   df_image

2. [実行] をクリックします。

   df_image の最後の呼び出しにより、DataFrame に追加された画像が返されます。または、.display メソッドを呼び出すこともできます。

DataFrame で構造化データと非構造化データを結合する

マルチモーダル DataFrame でテキストデータと画像データを結合します。

1. ノートブックでコードセルを作成し、次のコードをコピーします。
   # Combine unstructured data with structured data
   df_image["author"] = ["alice", "bob", "bob", "alice", "bob"]  # type: ignore
   df_image["content_type"] = df_image["image"].blob.content_type()
   df_image["size"] = df_image["image"].blob.size()
   df_image["updated"] = df_image["image"].blob.updated()
   df_image

2. [実行] をクリックします。

   このコードは DataFrame データを返します。

3. ノートブックでコードセルを作成し、次のコードをコピーします。

   # Filter images and display, you can also display audio and video types. Use width/height parameters to constrain window sizes.
   df_image[df_image["author"] == "alice"]["image"].blob.display()

4. [実行] をクリックします。

   このコードは、author 列の値が alice である DataFrame から画像を返します。

画像変換を行う

Series.BlobAccessor クラスの次のメソッドを使用して、画像データを変換します。

• image_blur
• image_normalize
• image_resize

変換された画像は Cloud Storage に書き込まれます。

画像を変換する:

1. ノートブックでコードセルを作成し、次のコードをコピーします。
   df_image["blurred"] = df_image["image"].blob.image_blur(
       (20, 20), dst=f"{dst_bucket}/image_blur_transformed/", engine="opencv"
   )
   df_image["resized"] = df_image["image"].blob.image_resize(
       (300, 200), dst=f"{dst_bucket}/image_resize_transformed/", engine="opencv"
   )
   df_image["normalized"] = df_image["image"].blob.image_normalize(
       alpha=50.0,
       beta=150.0,
       norm_type="minmax",
       dst=f"{dst_bucket}/image_normalize_transformed/",
       engine="opencv",
   )
   
   # You can also chain functions together
   df_image["blur_resized"] = df_image["blurred"].blob.image_resize(
       (300, 200), dst=f"{dst_bucket}/image_blur_resize_transformed/", engine="opencv"
   )
   df_image

2. {dst_bucket} へのすべての参照を、作成したバケットを参照するように更新します（形式: gs://mybucket）。

3. [実行] をクリックします。

   このコードは、元の画像とすべての変換を返します。

テキストを生成する

GeminiTextGenerator クラスの predict メソッドを使用して、マルチモーダル データからテキストを生成します。

1. ノートブックでコードセルを作成し、次のコードをコピーします。
   from bigframes.ml import llm
   
   gemini = llm.GeminiTextGenerator(model_name="gemini-2.0-flash-001")
   
   # Deal with first 2 images as example
   df_image = df_image.head(2)
   
   # Ask the same question on the images
   df_image = df_image.head(2)
   answer = gemini.predict(df_image, prompt=["what item is it?", df_image["image"]])
   answer[["ml_generate_text_llm_result", "image"]]

2. [実行] をクリックします。

   このコードは、df_image の最初の 2 つの画像と、両方の画像に対する質問 what item is it? への回答として生成されたテキストを返します。

3. ノートブックでコードセルを作成し、次のコードをコピーします。

   # Ask different questions
   df_image["question"] = [  # type: ignore
       "what item is it?",
       "what color is the picture?",
   ]
   answer_alt = gemini.predict(
       df_image, prompt=[df_image["question"], df_image["image"]]
   )
   answer_alt[["ml_generate_text_llm_result", "image"]]

4. [実行] をクリックします。

   このコードは、df_image で最初の 2 つの画像を返します。最初の画像には質問 what item is it? に応答して生成されたテキストが含まれ、2 番目の画像には質問 what color is the picture? に応答して生成されたテキストが含まれます。

エンベディングを生成する

MultimodalEmbeddingGenerator クラスの predict メソッドを使用して、マルチモーダル データのエンベディングを生成します。

1. ノートブックでコードセルを作成し、次のコードをコピーします。
   # Generate embeddings on images
   embed_model = llm.MultimodalEmbeddingGenerator()
   embeddings = embed_model.predict(df_image["image"])
   embeddings

2. [実行] をクリックします。

   このコードは、エンベディング モデルの呼び出しによって生成されたエンベディングを返します。

PDF をチャンク化する

Series.BlobAccessor クラスの pdf_chunk メソッドを使用して、PDF オブジェクトをチャンクします。

1. ノートブックでコードセルを作成し、次のコードをコピーします。
   # PDF chunking
   df_pdf = bpd.from_glob_path(
       "gs://cloud-samples-data/bigquery/tutorials/cymbal-pets/documents/*", name="pdf"
   )
   df_pdf["chunked"] = df_pdf["pdf"].blob.pdf_chunk(engine="pypdf")
   chunked = df_pdf["chunked"].explode()
   chunked

2. [実行] をクリックします。

   コードはチャンク化された PDF データを返します。

クリーンアップする

注意: プロジェクトを削除すると、次のような影響があります。

• プロジェクト内のすべてのものが削除されます。このドキュメントのタスクで既存のプロジェクトを使用した場合、それを削除すると、そのプロジェクトで行った他の作業もすべて削除されます。
• カスタム プロジェクト ID が失われます。このプロジェクトを作成したときに、将来使用するカスタム プロジェクト ID を作成した可能性があります。そのプロジェクト ID を使用した URL（たとえば、appspot.com）を保持するには、プロジェクト全体ではなくプロジェクト内の選択したリソースだけを削除します。

複数のアーキテクチャ、チュートリアル、クイックスタートを実施する予定がある場合は、プロジェクトを再利用すると、プロジェクトの割り当て上限を超えないようにすることができます。

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.