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）。

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

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

始める前に

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

   Go to project selector

2. Verify that billing is enabled for your Trusted Cloud project.

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

   Enable the APIs

データセットを作成する

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

接続を作成する

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

リモートモデルが使用する 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 {}
}

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

接続のサービス アカウントに 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.s3ns-system.iam.gserviceaccount.com does not have the permission to access resource」というエラーが発生します。

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

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

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

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

   [BigQuery] に移動

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

     Trusted Cloud コンソールで接続の詳細を表示する場合、これは [接続 ID] に表示される完全修飾接続 ID の最後のセクションの値です（例: projects/myproject/locations/connection_location/connections/myconnection）。

   • ENDPOINT: 使用する 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

  Gemini 1.5 モデルの場合は、戻り値が整数にならないことが確実な場合にのみ、FLOAT64 データ型を指定します。これらのモデルでは、小数点以下を切り捨てた値に対して FLOAT64 値ではなく INT64 値が返される場合があります（2.0 ではなく 2 など）。これにより、クエリで解析エラーが発生する可能性があります。

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