ML.GENERATE_TEXT 関数を使用してテキストを生成する

このドキュメントでは、Vertex AI の自然言語基盤モデルを参照する BigQuery ML リモートモデルを作成する方法について説明します。このモデルを ML.GENERATE_TEXT 関数と組み合わせて使用すると、BigQuery テーブルのテキストを分析できます。

必要な権限

接続を作成するには、次の Identity and Access Management（IAM）ロールのメンバーシップが必要です。
- roles/bigquery.connectionAdmin
接続のサービスアカウントに権限を付与するには、次の権限が必要です。
- resourcemanager.projects.setIamPolicy
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, and Vertex AI APIs.
Enable the APIs

接続を作成する

クラウドリソース接続を作成し、接続のサービスアカウントを取得します。

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

コンソール

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

[BigQuery] に移動
接続を作成するには、[データを追加] をクリックし、続いて [外部データソースへの接続] をクリックします。
[接続タイプ] リストで、[BigLake とリモート関数（クラウドリソース）] を選択します。
[接続 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

main.tf ファイルに次のセクションを追加します。

 ## This creates a cloud resource connection.
 ## Note: The cloud resource nested object has only one output only field - serviceAccountId.
 resource "google_bigquery_connection" "connection" {
    connection_id = "CONNECTION_ID"
    project = "PROJECT_ID"
    location = "REGION"
    cloud_resource {}
}

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

CONNECTION_ID: 接続の ID
PROJECT_ID: 実際の Google Cloud プロジェクト ID
REGION: 接続のリージョン

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

接続の使用権限をサービスアカウントに付与します。権限を付与しないと、エラーが発生します。次のオプションのいずれかを選択します。

コンソール

[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

モデルを作成する

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: BigQuery 接続の ID
  Google Cloud コンソールで接続の詳細を表示する場合、これは [接続 ID] に表示される完全修飾接続 ID の最後のセクションの値です。例: projects/myproject/locations/connection_location/connections/myconnection
- ENDPOINT: 使用するテキストの LLM。例: ENDPOINT='text-bison-32k'。
  モデル名に @version を追加すると、モデルの特定のバージョンを指定できます。例: text-bison@001。バージョンを指定しない場合は、モデルの最新バージョンが使用されます。

テキストを生成する

ML.GENERATE_TEXT 関数を使用してテキストを生成します。

プロンプト列

テーブルの列を使用してプロンプトを入力することで、テキストを生成します。

SELECT *
FROM ML.GENERATE_TEXT(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  TABLE PROJECT_ID.DATASET_ID.TABLE_NAME,
  STRUCT(TOKENS AS max_output_tokens, TEMPERATURE AS temperature,
  TOP_K AS top_k, TOP_P AS top_p, FLATTEN_JSON AS flatten_json_output)
);

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

PROJECT_ID: プロジェクト ID。
DATASET_ID: モデルを格納するデータセットの ID。
MODEL_NAME: モデルの名前。
TABLE_NAME: プロンプトを含むテーブルの名前。このテーブルには、prompt という名前のテーブルが必要です。または、エイリアスを使用して別の名前の列を使用することもできます。
TOKENS: モデルによって出力されるトークンの最大数を設定する [1,1024] の範囲内の INT64 値。レスポンスを短くしたい場合は小さい値を、長くしたい場合は大きい値を指定します。デフォルトは 50 です。
TEMPERATURE: トークン選択のランダム性の度合いを制御する [0.0,1.0] の範囲内の FLOAT64 値。デフォルトは 1.0 です。
temperature の値が低いほど、確定的で自由度や創造性を抑えたレスポンスが求められるプロンプトに適しています。一方、temperature の値が高いほど、より多様で創造的な結果を導くことができます。temperature の 0 の値は確定的であり、最も高い確率のレスポンスが常に選択されることを意味します。
TOP_K: [1,40] の範囲内の INT64 値。これにより、モデルが選択を検討するトークンの初期プールが決まります。ランダムなレスポンスを減らしたい場合は小さい値を、ランダムなレスポンスを増やしたい場合は大きい値を指定します。デフォルトは 40 です。
TOP_P: [0.0,1.0] の範囲内の FLOAT64 値は、TOP_K によって決定されるプールからどのトークンを選択するかを決定します。ランダムなレスポンスを減らしたい場合は小さい値を、ランダムなレスポンスを増やしたい場合は大きい値を指定します。デフォルトは 1.0 です。
FLATTEN_JSON: 生成されたテキストと安全性属性を別々の列で返すかどうかを決定する BOOL 値。デフォルトは FALSE です。

次の例は、これらの特性を持つリクエストを示しています。

プロンプトに prompts テーブルの prompt 列を使用します。
短く、中程度の確率のレスポンスを返します。
生成されたテキストと安全性属性を別々の列で返します。

SELECT *
FROM
  ML.GENERATE_TEXT(
    MODEL `mydataset.llm_model`,
    TABLE mydataset.prompts,
    STRUCT(
      0.4 AS temperature, 100 AS max_output_tokens, 0.5 AS top_p,
      40 AS top_k, TRUE AS flatten_json_output));

プロンプトクエリ

クエリを使用してプロンプトを入力することでテキストを生成します。

SELECT *
FROM ML.GENERATE_TEXT(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  (PROMPT_QUERY),
  STRUCT(TOKENS AS max_output_tokens, TEMPERATURE AS temperature,
  TOP_K AS top_k, TOP_P AS top_p, FLATTEN_JSON AS flatten_json_output)
);

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

PROJECT_ID: プロジェクト ID。
DATASET_ID: モデルを格納するデータセットの ID。
MODEL_NAME: モデルの名前。
PROMPT_QUERY: プロンプトデータを提供するクエリ。
TOKENS: モデルによって出力されるトークンの最大数を設定する [1,1024] の範囲内の INT64 値。レスポンスを短くしたい場合は小さい値を、長くしたい場合は大きい値を指定します。デフォルトは 50 です。
TEMPERATURE: トークン選択のランダム性の度合いを制御する [0.0,1.0] の範囲内の FLOAT64 値。デフォルトは 1.0 です。
temperature の値が低いほど、確定的で自由度や創造性を抑えたレスポンスが求められるプロンプトに適しています。一方、temperature の値が高いほど、より多様で創造的な結果を導くことができます。temperature の 0 の値は確定的であり、最も高い確率のレスポンスが常に選択されることを意味します。
TOP_K: [1,40] の範囲内の INT64 値。これにより、モデルが選択を検討するトークンの初期プールが決まります。ランダムなレスポンスを減らしたい場合は小さい値を、ランダムなレスポンスを増やしたい場合は大きい値を指定します。デフォルトは 40 です。
TOP_P: [0.0,1.0] の範囲内の FLOAT64 値は、TOP_K によって決定されるプールからどのトークンを選択するかを決定します。ランダムなレスポンスを減らしたい場合は小さい値を、ランダムなレスポンスを増やしたい場合は大きい値を指定します。デフォルトは 1.0 です。
FLATTEN_JSON: 生成されたテキストと安全性属性を別々の列で返すかどうかを決定する BOOL 値。

例 1

次の例は、これらの特性を持つリクエストを示しています。

articles テーブルの body 列のテキストの概要を求めます。
やや長く、より高確率のレスポンスを返します。
生成されたテキストと安全性属性を別々の列で返します。

SELECT *
FROM
  ML.GENERATE_TEXT(
    MODEL `mydataset.llm_model`,
    (
      SELECT CONCAT('Summarize this text', body) AS prompt
      FROM mydataset.articles
    ),
    STRUCT(
      0.2 AS temperature, 650 AS max_output_tokens, 0.2 AS top_p,
      15 AS top_k, TRUE AS flatten_json_output));

例 2

次の例は、これらの特性を持つリクエストを示しています。

クエリを使用して、プロンプトの接頭辞とテーブル列を連結する文字列を連結して、プロンプトデータを作成します。
短く、中程度の確率のレスポンスを返します。
生成されたテキストと安全性属性を別々の列で返しません。

SELECT *
FROM
  ML.GENERATE_TEXT(
    MODEL `mydataset.llm_model`,
    (
      SELECT CONCAT(question, 'Text:', description, 'Category') AS prompt
      FROM mydataset.input_table
    ),
    STRUCT(
      0.4 AS temperature, 100 AS max_output_tokens, 0.5 AS top_p,
      30 AS top_k, FALSE AS flatten_json_output));

ML.GENERATE_TEXT 関数を使用してテキストを生成する

必要な権限

始める前に

接続を作成する

コンソール

bq

Terraform

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

コンソール

gcloud

モデルを作成する

テキストを生成する

プロンプト列

プロンプト クエリ

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

プロンプトクエリ