ML.GENERATE_EMBEDDING 関数を使用して画像エンベディングを生成する

このドキュメントでは、Vertex AI エンベディングモデルを参照する、BigQuery ML のリモートモデルを作成する方法について説明します。次に、そのモデルを ML.GENERATE_EMBEDDING 関数で使用し、BigQuery のオブジェクトテーブルのデータを使用して画像エンベディングに変換します。

必要なロール

接続を作成するには、次の Identity and Access Management（IAM）ロールのメンバーシップが必要です。
- roles/bigquery.connectionAdmin
接続のサービスアカウントに権限を付与するには、次の権限が必要です。
- resourcemanager.projects.setIamPolicy
オブジェクトテーブルを作成するには、次の権限が必要です。
- bigquery.tables.create
- bigquery.tables.update
- bigquery.connections.delegate
BigQuery ML を使用してモデルを作成するには、次の IAM 権限が必要です。
- bigquery.jobs.create
- bigquery.models.create
- bigquery.models.getData
- bigquery.models.updateData
- bigquery.models.updateMetadata
推論を実行するには、次の権限が必要です。
- テーブルに対する bigquery.tables.getData
- モデルに対する bigquery.models.getData
- bigquery.jobs.create

始める前に

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
Make sure that billing is enabled for your Google Cloud project.
Enable the BigQuery, BigQuery Connection, Cloud Storage, and Vertex AI APIs.
Enable the APIs

データセットを作成する

オブジェクトテーブルとモデルを保存する BigQuery データセットを作成します。

コンソール

Google Cloud コンソールで [BigQuery] ページに移動します。

[BigQuery] ページに移動
[エクスプローラ] ペインで、プロジェクト名をクリックします。
[アクションを表示] > [データセットを作成] をクリックします。
[データセットを作成する] ページで、次の操作を行います。
- [データセット ID] に、データセットの名前を入力します。
- [ロケーションタイプ] で、データセットのロケーションを選択します。
- [データセットを作成] をクリックします。

bq

新しいデータセットを作成するには、--location フラグを指定した bq mk コマンドを使用します。
```
bq --location=LOCATION mk -d DATASET_ID
```
次のように置き換えます。
- LOCATION: データセットのロケーション。
- DATASET_ID は、作成するデータセットの ID です。
データセットが作成されたことを確認します。
```
bq ls
```

接続を作成する

クラウドリソース接続を作成し、接続のサービスアカウントを取得します。前の手順で作成したデータセットと同じロケーションに接続を作成します。

次のオプションのいずれかを選択します。

コンソール

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

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

[データを追加] ダイアログが開きます。
[フィルタ条件] ペインの [データソースのタイプ] セクションで、[データベース] を選択します。

または、[データソースを検索] フィールドに「Vertex AI」と入力します。
[特徴量データソース] セクションで、[Vertex AI] をクリックします。
[Vertex AI モデル: BigQuery フェデレーション] ソリューションカードをクリックします。
[接続タイプ] リストで、[Vertex AI リモートモデル、リモート関数、BigLake（Cloud リソース）] を選択します。
[接続 ID] フィールドに接続の名前を入力します。
[接続を作成] をクリックします。
[接続へ移動] をクリックします。
[接続情報] ペインで、次の手順で使用するサービスアカウント ID をコピーします。

bq

コマンドライン環境で接続を作成します。
```
bq mk --connection --location=REGION --project_id=PROJECT_ID \
    --connection_type=CLOUD_RESOURCE CONNECTION_ID
```
--project_id パラメータは、デフォルトプロジェクトをオーバーライドします。

次のように置き換えます。
- REGION: 接続のリージョン
- PROJECT_ID: 実際の Google Cloud プロジェクト ID
- CONNECTION_ID: 接続の ID
接続リソースを作成すると、BigQuery は、一意のシステムサービスアカウントを作成し、それを接続に関連付けます。

トラブルシューティング: 次の接続エラーが発生した場合は、Google Cloud SDK を更新します。
```
Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...
```

後の手順で使用するため、サービスアカウント ID を取得してコピーします。

bq show --connection PROJECT_ID.REGION.CONNECTION_ID

出力は次のようになります。

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

Terraform

google_bigquery_connection リソースを使用します。

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアントライブラリの認証を設定するをご覧ください。

次の例では、US リージョンに my_cloud_resource_connection という名前の Cloud リソース接続を作成します。


# This queries the provider for project information.
data "google_project" "default" {}

# This creates a cloud resource connection in the US region named my_cloud_resource_connection.
# Note: The cloud resource nested object has only one output field - serviceAccountId.
resource "google_bigquery_connection" "default" {
  connection_id = "my_cloud_resource_connection"
  project       = data.google_project.default.project_id
  location      = "US"
  cloud_resource {}
}

Google Cloud プロジェクトで Terraform 構成を適用するには、次のセクションの手順を完了します。

Cloud Shell を準備する

Cloud Shell を起動します。
Terraform 構成を適用するデフォルトの Google Cloud プロジェクトを設定します。

このコマンドは、プロジェクトごとに 1 回だけ実行する必要があります。これは任意のディレクトリで実行できます。
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
```
Terraform 構成ファイルに明示的な値を設定すると、環境変数がオーバーライドされます。

ディレクトリを準備する

Terraform 構成ファイルには独自のディレクトリ（ルートモジュールとも呼ばれます）が必要です。

Cloud Shell で、ディレクトリを作成し、そのディレクトリ内に新しいファイルを作成します。ファイルの拡張子は .tf にする必要があります（例: main.tf）。このチュートリアルでは、このファイルを main.tf とします。
```
mkdir DIRECTORY && cd DIRECTORY && touch main.tf
```
チュートリアルを使用している場合は、各セクションまたはステップのサンプルコードをコピーできます。

新しく作成した main.tf にサンプルコードをコピーします。

必要に応じて、GitHub からコードをコピーします。Terraform スニペットがエンドツーエンドのソリューションの一部である場合は、この方法をおすすめします。
環境に適用するサンプルパラメータを確認し、変更します。
変更を保存します。
Terraform を初期化します。これは、ディレクトリごとに 1 回だけ行います。
```
terraform init
```
最新バージョンの Google プロバイダを使用する場合は、-upgrade オプションを使用します。
```
terraform init -upgrade
```

変更を適用する

構成を確認して、Terraform が作成または更新するリソースが想定どおりであることを確認します。
```
terraform plan
```
必要に応じて構成を修正します。
次のコマンドを実行します。プロンプトで「yes」と入力して、Terraform 構成を適用します。
```
terraform apply
```
Terraform に「Apply complete!」というメッセージが表示されるまで待ちます。
Google Cloud プロジェクトを開いて結果を表示します。Google Cloud コンソールの UI でリソースに移動して、Terraform によって作成または更新されたことを確認します。

サービスアカウントにアクセス権を付与する

接続のサービスアカウントに Vertex AI ユーザーと Storage オブジェクト閲覧者のロールを付与します。

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

コンソール

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

[IAM と管理] に移動
[追加] をクリックします。

[プリンシパルを追加] ダイアログが開きます。
[新しいプリンシパル] フィールドに、前の手順でコピーしたサービスアカウント ID を入力します。
[ロールを選択] フィールドで、[Vertex AI] を選択し、[Vertex AI ユーザー] を選択します。
[別のロールを追加] をクリックします。
[ロールを選択] フィールドで、[Cloud Storage] を選択し、続いて [Storage オブジェクト閲覧者] を選択します。
[保存] をクリックします。

gcloud

gcloud projects add-iam-policy-binding コマンドを使用します。

gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/aiplatform.user' --condition=None
gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/storage.objectViewer' --condition=None

次のように置き換えます。

PROJECT_NUMBER: ロールを付与するプロジェクトのプロジェクト番号。
MEMBER: 先ほどコピーしたサービスアカウント ID。

オブジェクトテーブルを作成する

Cloud Storage から画像を移動せずに分析するには、オブジェクトテーブルを作成します。

オブジェクトテーブルを作成するには:

SQL

CREATE EXTERNAL TABLE ステートメントを使用します。

Google Cloud コンソールで [BigQuery Studio] ページに移動します。

[BigQuery Studio] に移動
クエリエディタで次のステートメントを入力します。
```
CREATE EXTERNAL TABLE `PROJECT_ID.DATASET_ID.TABLE_NAME`
WITH CONNECTION {`PROJECT_ID.REGION.CONNECTION_ID`| DEFAULT}
OPTIONS(
  object_metadata = 'SIMPLE',
  uris = ['BUCKET_PATH'[,...]],
  max_staleness = STALENESS_INTERVAL,
  metadata_cache_mode = 'CACHE_MODE');
```
次のように置き換えます。
- PROJECT_ID: プロジェクト ID。
- DATASET_ID: 作成したデータセットの ID。
- TABLE_NAME: オブジェクトテーブルの名前。
- REGION: 接続を含むリージョンまたはマルチリージョン。
- CONNECTION_ID: 作成した接続の ID。
  これは、Google Cloud コンソールで接続の詳細を表示すると [接続 ID] に表示される完全修飾接続 ID の最後のセクションの値です（例: projects/myproject/locations/connection_location/connections/myconnection）。
  
  デフォルトの接続を使用するには、PROJECT_ID.REGION.CONNECTION_ID を含む接続文字列の代わりに DEFAULT を指定します。
- BUCKET_PATH: 画像を含む Cloud Storage バケットへのパス（['gs://bucket_name/[folder_name/]*'] 形式）。
  使用する Cloud Storage バケットは、モデルを作成し、ML.GENERATE_EMBEDDING 関数を呼び出すプロジェクトに含まれている必要があります。オブジェクトテーブルで使用される Cloud Storage バケットを含むプロジェクトとは異なるプロジェクトで ML.GENERATE_EMBEDDING 関数を呼び出す場合は、[email protected] サービスアカウントにバケットレベルでストレージ管理者ロールを付与する必要があります。
- STALENESS_INTERVAL: キャッシュ内のメタデータをオブジェクトテーブルに対するオペレーションで使用するかどうかを指定します。また、オペレーションがキャッシュ内のメタデータを使用するために必要な鮮度を指定します。メタデータキャッシュに関する考慮事項の詳細については、メタデータキャッシュによるパフォーマンスの向上をご覧ください。
  メタデータのキャッシュ保存を無効にするには、0 を指定します。これがデフォルトです。
  
  メタデータキャッシュを有効にするには、30 分から 7 日の間で間隔リテラルの値を指定します。たとえば、4 時間の未更新間隔の場合、INTERVAL 4 HOUR を指定します。この値を指定すると、キャッシュに保存されたメタデータが過去 4 時間以内に更新されていれば、テーブルに対するオペレーションはそのメタデータを使用します。キャッシュに保存されているメタデータがそれより古い場合、オペレーションは代わりに Cloud Storage からメタデータを取得します。
- CACHE_MODE: メタデータキャッシュを自動的に更新するか手動で更新するかを指定します。メタデータキャッシュに関する考慮事項の詳細については、メタデータキャッシュのパフォーマンスをご覧ください。
  AUTOMATIC に設定すると、メタデータキャッシュがシステムで定義された間隔（通常は 30～60 分）で更新されます。
  
  自身で決めたスケジュールでメタデータキャッシュを更新する場合は、MANUAL に設定します。この場合は、BQ.REFRESH_EXTERNAL_METADATA_CACHE システムプロシージャを呼び出してキャッシュを更新できます。
  
  STALENESS_INTERVAL が 0 より大きい値に設定されている場合は、CACHE_MODE を設定する必要があります。
[実行] をクリックします。

クエリの実行方法については、インタラクティブクエリを実行するをご覧ください。

bq

bq mk コマンドを使用します。

bq mk --table \
--external_table_definition=BUCKET_PATH@REGION.CONNECTION_ID \
--object_metadata=SIMPLE \
--max_staleness=STALENESS_INTERVAL \
--metadata_cache_mode=CACHE_MODE \
PROJECT_ID:DATASET_ID.TABLE_NAME

次のように置き換えます。

BUCKET_PATH: 画像を含む Cloud Storage バケットへのパス（['gs://bucket_name/[folder_name/]*'] 形式）。
使用する Cloud Storage バケットは、モデルを作成し、ML.GENERATE_EMBEDDING 関数を呼び出すプロジェクトに含まれている必要があります。オブジェクトテーブルで使用される Cloud Storage バケットを含むプロジェクトとは異なるプロジェクトで ML.GENERATE_EMBEDDING 関数を呼び出す場合は、[email protected] サービスアカウントにバケットレベルでストレージ管理者ロールを付与する必要があります。
REGION: 接続を含むリージョンまたはマルチリージョン。
CONNECTION_ID: 作成した接続の ID。
これは、Google Cloud コンソールで接続の詳細を表示すると [接続 ID] に表示される完全修飾接続 ID の最後のセクションの値です（例: projects/myproject/locations/connection_location/connections/myconnection）。
STALENESS_INTERVAL: キャッシュ内のメタデータをオブジェクトテーブルに対するオペレーションで使用するかどうかを指定します。また、オペレーションがキャッシュ内のメタデータを使用するために必要な鮮度を指定します。メタデータキャッシュに関する考慮事項の詳細については、メタデータキャッシュによるパフォーマンスの向上をご覧ください。
メタデータのキャッシュ保存を無効にするには、0 を指定します。これがデフォルトです。

メタデータキャッシュを有効にするには、30 分から 7 日の間で間隔リテラルの値を指定します。たとえば、4 時間の未更新間隔の場合、INTERVAL 4 HOUR を指定します。この値を指定すると、キャッシュに保存されたメタデータが過去 4 時間以内に更新されていれば、テーブルに対するオペレーションはそのメタデータを使用します。キャッシュに保存されているメタデータがそれより古い場合、オペレーションは代わりに Cloud Storage からメタデータを取得します。
CACHE_MODE: メタデータキャッシュを自動的に更新するか手動で更新するかを指定します。メタデータキャッシュに関する考慮事項の詳細については、メタデータキャッシュのパフォーマンスをご覧ください。
AUTOMATIC に設定すると、メタデータキャッシュがシステムで定義された間隔（通常は 30～60 分）で更新されます。

自身で決めたスケジュールでメタデータキャッシュを更新する場合は、MANUAL に設定します。この場合は、BQ.REFRESH_EXTERNAL_METADATA_CACHE システムプロシージャを呼び出してキャッシュを更新できます。

STALENESS_INTERVAL が 0 より大きい値に設定されている場合は、CACHE_MODE を設定する必要があります。
PROJECT_ID: プロジェクト ID。
DATASET_ID: 作成したデータセットの ID。
TABLE_NAME: オブジェクトテーブルの名前。

モデルを作成する

Google Cloud コンソールで [BigQuery] ページに移動します。

[BigQuery] に移動
SQL エディタを使用してリモートモデルを作成します。
```
CREATE OR REPLACE MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`
REMOTE WITH CONNECTION `PROJECT_ID.REGION.CONNECTION_ID`
OPTIONS (ENDPOINT = 'ENDPOINT');
```
次のように置き換えます。
- PROJECT_ID: プロジェクト ID。
- DATASET_ID: 作成したデータセットの ID。
- MODEL_NAME: モデルの名前。
- REGION: 接続を含むリージョンまたはマルチリージョン。
- CONNECTION_ID: 作成した接続の ID。
  これは、Google Cloud コンソールで接続の詳細を表示すると [接続 ID] に表示される完全修飾接続 ID の最後のセクションの値です（例: projects/myproject/locations/connection_location/connections/myconnection）。
- ENDPOINT: 使用するエンベディングモデル。この場合は multimodalembedding@001 です。
  リモートモデルの作成時にエンドポイントとして URL（endpoint = 'https://us-central1-aiplatform.googleapis.com/v1/projects/myproject/locations/us-central1/publishers/google/models/text-embedding-004' など）を指定する場合は、URL で指定するプロジェクトが、接続のサービスアカウントに Vertex AI ユーザーロールを付与したプロジェクトであることを表示できます。
  
  リモートモデルを作成するロケーションで multimodalembedding@001 モデルが使用可能である必要があります。詳細については、ロケーションをご覧ください。

画像のエンベディングを生成する

オブジェクトテーブルの画像データを使用して、ML.GENERATE_EMBEDDING 関数で画像エンベディングを生成します。

  SELECT *
  FROM ML.GENERATE_EMBEDDING(
    MODEL <var>PROJECT_ID</var>.<var>DATASET_ID</var>.<var>MODEL_NAME</var>,
    TABLE <var>PROJECT_ID</var>.<var>DATASET_ID</var>.<var>TABLE_NAME</var>,
    STRUCT(FLATTEN_JSON AS flatten_json_output,
    OUTPUT_DIMENSIONALITY AS output_dimensionality)
  );

次のように置き換えます。

PROJECT_ID: プロジェクト ID。
DATASET_ID: モデルを保存するデータセットの ID。
MODEL_NAME: multimodalembedding@001 モデルのリモートモデルの名前。
TABLE_NAME: 埋め込む画像を含むオブジェクトテーブルの名前。
FLATTEN_JSON: 埋め込みを解析して別の列に変換するかどうかを示す BOOL 値。デフォルト値は TRUE です。
OUTPUT_DIMENSIONALITY: エンベディングの生成時に使用する次元の数を指定する INT64 値。有効な値は 128、256、512、1408 です。デフォルト値は 1408 です。たとえば、256 AS output_dimensionality を指定すると、ml_generate_embedding_result 出力列には、入力値ごとに 256 個のエンベディングが含まれます。

例

次の例は、images オブジェクトテーブル内に画像エンベディングを作成する方法を示しています。

SELECT *
FROM
  ML.GENERATE_EMBEDDING(
    MODEL `mydataset.embedding_model`,
    TABLE `mydataset.images`,
    STRUCT(TRUE AS flatten_json_output, 512 AS output_dimensionality)
  );

ML.GENERATE_EMBEDDING 関数を使用して画像エンベディングを生成する

必要なロール

始める前に

データセットを作成する

コンソール

bq

接続を作成する

コンソール

bq

Terraform

Cloud Shell を準備する

ディレクトリを準備する

変更を適用する

サービス アカウントにアクセス権を付与する

コンソール

gcloud

オブジェクト テーブルを作成する

SQL

bq

モデルを作成する

画像のエンベディングを生成する

例

サービスアカウントにアクセス権を付与する

オブジェクトテーブルを作成する