このページは Cloud Translation API によって翻訳されました。

AI.GENERATE_TABLE 関数を使用して構造化データを生成する

このドキュメントでは、Gemini モデルを使用して構造化データを生成し、SQL スキーマを使用してモデルのレスポンスをフォーマットする方法について説明します。

これを行うには、次のタスクを完了します。

一般提供またはプレビューの Gemini モデルを使用して BigQuery ML リモートモデルを作成する。
モデルを AI.GENERATE_TABLE 関数で使用し、標準テーブルのデータに基づいて構造化データを生成する。

必要なロール

リモートモデルを作成して AI.GENERATE_TABLE 関数を使用するには、次の Identity and Access Management（IAM）ロールが必要です。

BigQuery データセット、テーブル、モデルの作成と使用: プロジェクトに対する BigQuery データ編集者（roles/bigquery.dataEditor）。
BigQuery 接続の作成、委任、使用: プロジェクトに対する BigQuery 接続管理者（roles/bigquery.connectionsAdmin）。

デフォルト接続が構成されていない場合は、CREATE MODEL ステートメントの実行時に作成して設定できます。これを行うには、プロジェクトに対する BigQuery 管理者（roles/bigquery.admin）が必要です。詳細については、デフォルト接続を構成するをご覧ください。
接続のサービスアカウントに権限を付与する: Vertex AI エンドポイントを含むプロジェクトに対するプロジェクト IAM 管理者（roles/resourcemanager.projectIamAdmin）。これは、モデル名をエンドポイントとして指定して作成するリモートモデルの現在のプロジェクトです。これは、エンドポイントとして URL を指定して作成したリモートモデルの URL で識別されるプロジェクトです。
BigQuery ジョブを作成する: プロジェクトに対する BigQuery ジョブユーザー（roles/bigquery.jobUser）。

これらの事前定義ロールには、このドキュメントのタスクを実行するために必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

必要な権限

データセットを作成する: bigquery.datasets.create
接続を作成、委任、使用する: bigquery.connections.*
サービスアカウントの権限を設定する: resourcemanager.projects.getIamPolicy と resourcemanager.projects.setIamPolicy
モデルを作成して推論を実行する:
- bigquery.jobs.create
- bigquery.models.create
- bigquery.models.getData
- bigquery.models.updateData
- bigquery.models.updateMetadata
テーブルデータをクエリする: bigquery.tables.getData

カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。

始める前に

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
- Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.
Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector
Verify that billing is enabled for your Google Cloud project.
Enable the BigQuery, BigQuery Connection, and Vertex AI APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.
Enable the APIs

データセットを作成する

リソースを格納する BigQuery データセットを作成します。

コンソール

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

BigQuery に移動
左側のペインで、 [エクスプローラ] をクリックします。

左側のペインが表示されていない場合は、 左側のペインを開くをクリックしてペインを開きます。
[エクスプローラ] ペインで、プロジェクト名をクリックします。
[アクションを表示] > [データセットを作成] をクリックします。
[データセットを作成する] ページで、次の操作を行います。
1. [データセット ID] に、データセットの名前を入力します。
2. [ロケーションタイプ] で、[リージョン] または [マルチリージョン] を選択します。
  - [リージョン] を選択した場合は、[リージョン] リストからロケーションを選択します。
  - [マルチリージョン] を選択した場合は、[マルチリージョン] リストから [US] または [ヨーロッパ] を選択します。
3. [データセットを作成] をクリックします。

bq

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

接続を作成する

デフォルトの接続が構成されているか、BigQuery 管理者ロールが付与されている場合は、この手順をスキップできます。

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

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

コンソール

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

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

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

または、[データソースを検索] フィールドに「Vertex AI」と入力します。
[特徴量データソース] セクションで、[Vertex AI] をクリックします。
[Vertex AI モデル: BigQuery フェデレーション] ソリューションカードをクリックします。
[接続タイプ] リストで、[Vertex AI リモートモデル、リモート関数、BigLake、Spanner（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 ユーザーロールを付与します。

リモートモデルの作成時にエンドポイントを URL（endpoint = 'https://us-central1-aiplatform.googleapis.com/v1/projects/myproject/locations/us-central1/publishers/google/models/gemini-2.5-flash' など）として指定する場合は、URL に指定する同じプロジェクト内でこのロールを付与してください。

リモートモデルの作成時にモデル名（endpoint = 'gemini-2.5-flash' など）を使用してエンドポイントを指定する場合は、リモートモデルを作成するプロジェクト内でこのロールを付与してください。

別のプロジェクトでロールを付与すると、「bqcx-1234567890-wxyz@gcp-sa-bigquery-condel.iam.gserviceaccount.com does not have the permission to access resource」というエラーが発生します。

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

コンソール

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

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

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

gcloud

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

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

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

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

BigQuery ML リモートモデルを作成する

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

[BigQuery] に移動
SQL エディタを使用してリモートモデルを作成します。
```
CREATE OR REPLACE MODEL
`PROJECT_ID.DATASET_ID.MODEL_NAME`
REMOTE WITH CONNECTION {DEFAULT | `PROJECT_ID.REGION.CONNECTION_ID`}
OPTIONS (ENDPOINT = 'ENDPOINT');
```
次のように置き換えます。
- PROJECT_ID: プロジェクト ID
- DATASET_ID: モデルを格納するデータセットの ID。このデータセットは、使用している接続と同じロケーションに存在している必要があります。
- MODEL_NAME: モデルの名前
- REGION: 接続で使用されるリージョン
- CONNECTION_ID: BigQuery 接続の ID
  Google Cloud コンソールで接続の詳細を表示する場合、これは [接続 ID] に表示される完全修飾接続 ID の最後のセクションの値です（例: projects/myproject/locations/connection_location/connections/myconnection）。
- ENDPOINT: 使用する Gemini モデルの名前。サポートされている Gemini モデルでは、グローバルエンドポイントを指定して可用性を向上させることができます。詳細については、ENDPOINT をご覧ください。

構造化データを生成する

リモートモデルで AI.GENERATE_TABLE 関数を使用し、テーブル列のプロンプトデータを使用して構造化データを生成します。

SELECT *
FROM AI.GENERATE_TABLE(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  [TABLE `PROJECT_ID.DATASET_ID.TABLE_NAME` / (PROMPT_QUERY)],
  STRUCT(TOKENS AS max_output_tokens, TEMPERATURE AS temperature,
  TOP_P AS top_p, STOP_SEQUENCES AS stop_sequences,
  SAFETY_SETTINGS AS safety_settings,
  OUTPUT_SCHEMA AS output_schema)
);

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

PROJECT_ID: プロジェクト ID。
DATASET_ID: モデルを格納するデータセットの ID。
MODEL_NAME: モデルの名前。
TABLE_NAME: プロンプトを含むテーブルの名前。このテーブルには、prompt という名前の列が必要です。または、エイリアスを使用して別の名前の列を使用することもできます。
PROMPT_QUERY: プロンプトデータを生成する GoogleSQL クエリ。プロンプトの値自体は列から取得できます。または、任意の数の文字列と列名サブフィールドを含む構造体の値として指定することもできます。例: SELECT ('Analyze the sentiment in ', feedback_column, 'using the following categories: positive, negative, neutral') AS prompt
TOKENS: INT64 値。レスポンスで生成できるトークンの最大数を設定します。この値は [1,8192] の範囲内であることが必要です。レスポンスを短くする場合は小さい値を、長くする場合は大きい値を指定します。デフォルト値は 128 です。
TEMPERATURE: FLOAT64 値。トークン選択のランダム性の度合いを制御します。[0.0,2.0] の範囲内の値にする必要があります。デフォルト値は 1.0 です。
temperature の値が低いほど、自由度や創造性を抑えた決定的なレスポンスが求められるプロンプトに適しています。一方、temperature の値が高いほど、より多様で創造的な結果を導くことができます。temperature の 0 の値は決定的です。すなわち、最も高い確率のレスポンスが常に選択されます。
TOP_P: FLOAT64 値。[0.0,1.0] の範囲内の値にする必要があります。これによって、トークンが選択される確率を特定できます。ランダムなレスポンスを削減する場合は小さい値を、ランダムな回答を増加させる場合は大きい値を指定します。デフォルト値は 0.95 です。
STOP_SEQUENCES: ARRAY<STRING> 値。指定された文字列がモデルからのレスポンスに含まれている場合に、その文字列を削除します。文字列は、大文字と小文字の区別を含めて完全に一致します。デフォルトは空の配列です。
SAFETY_SETTINGS: レスポンスのフィルタリングに使用するコンテンツセーフティのしきい値を構成する ARRAY<STRUCT<STRING AS category, STRING AS threshold>> 値。構造体の最初の要素は有害カテゴリを指定し、構造体の 2 番目の要素は対応するブロックしきい値を指定します。モデルは、これらの設定に違反するコンテンツを除外します。一度に指定できるのは、いずれかのカテゴリのみです。たとえば、STRUCT('HARM_CATEGORY_DANGEROUS_CONTENT' AS category, 'BLOCK_MEDIUM_AND_ABOVE' AS threshold) と STRUCT('HARM_CATEGORY_DANGEROUS_CONTENT' AS category, 'BLOCK_ONLY_HIGH' AS threshold) の両方を指定することはできません。特定のカテゴリに安全性設定がない場合は、BLOCK_MEDIUM_AND_ABOVE 安全性設定が使用されます。

サポートされているカテゴリは次のとおりです。
- HARM_CATEGORY_HATE_SPEECH
- HARM_CATEGORY_DANGEROUS_CONTENT
- HARM_CATEGORY_HARASSMENT
- HARM_CATEGORY_SEXUALLY_EXPLICIT
サポートされているしきい値は次のとおりです。
- BLOCK_NONE（制限付き）
- BLOCK_LOW_AND_ABOVE
- BLOCK_MEDIUM_AND_ABOVE（デフォルト）
- BLOCK_ONLY_HIGH
- HARM_BLOCK_THRESHOLD_UNSPECIFIED
詳細については、有害カテゴリとコンテンツフィルタを構成する方法をご覧ください。
OUTPUT_SCHEMA: モデルのレスポンスの形式を指定する STRING 値。output_schema の値は、CREATE TABLE ステートメントで使用されるものと類似した SQL スキーマ定義であることが必要です。次のデータ型がサポートされています。
- INT64
- FLOAT64
- BOOL
- STRING
- ARRAY
- STRUCT
output_schema 引数を使用してテーブルのプロンプトに基づいて構造化データを生成する場合は、適切なスキーマを指定するためにプロンプトデータを理解することが重要です。

たとえば、次のフィールドを含むテーブルから映画のレビューコンテンツを分析するとします。
- movie_id
- review
- prompt
次のようなクエリを実行して、プロンプトテキストを作成できます。
```
UPDATE mydataset.movie_review
SET prompt = CONCAT('Extract the key words and key sentiment from the text below: ', review)
WHERE review IS NOT NULL;
```
"keywords ARRAY<STRING>, sentiment STRING" AS output_schema に類似した output_schema 値を指定することもできます。

例

次の例は、テーブルからプロンプトデータを取得し、モデルのレスポンスをフォーマットするための SQL スキーマを指定するリクエストを示しています。

SELECT
*
FROM
AI.GENERATE_TABLE( MODEL `mydataset.gemini_model`,
  TABLE `mydataset.mytable`,
  STRUCT("keywords ARRAY<STRING>, sentiment STRING" AS output_schema));

次の例は、クエリからプロンプトデータを取得し、モデルのレスポンスをフォーマットするための SQL スキーマを指定するリクエストを示しています。

SELECT *
FROM
  AI.GENERATE_TABLE(
    MODEL `mydataset.gemini_model`,
    (
      SELECT
        'John Smith is a 20-year old single man living at 1234 NW 45th St, Kirkland WA, 98033. He has two phone numbers 123-123-1234, and 234-234-2345. He is 200.5 pounds.'
          AS prompt
    ),
    STRUCT("address STRUCT<street_address STRING, city STRING, state STRING, zip_code STRING>, age INT64, is_married BOOL, name STRING, phone_number ARRAY<STRING>, weight_in_pounds FLOAT64"
        AS output_schema, 8192 AS max_output_tokens));

AI.GENERATE_TABLE 関数を使用して構造化データを生成する

必要なロール

必要な権限

始める前に

データセットを作成する

コンソール

bq

接続を作成する

コンソール

bq

Terraform

Cloud Shell を準備する

ディレクトリを準備する

変更を適用する

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

コンソール

gcloud

BigQuery ML リモートモデルを作成する

構造化データを生成する

例

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