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

Gemini モデルと ML.GENERATE_TEXT 関数を使用してテキストを生成する

このチュートリアルでは、gemini-2.0-flash モデルに基づいてリモートモデルを作成する方法について説明します。また、そのモデルを ML.GENERATE_TEXT 関数と組み合わせて bigquery-public-data.imdb.reviews 公開テーブルの映画レビューからキーワードを抽出し、感情分析を行う方法についても説明します。

必要なロール

このチュートリアルを実行するには、次の Identity and Access Management（IAM）ロールが必要です。

BigQuery データセット、接続、モデルを作成して使用する: BigQuery 管理者（roles/bigquery.admin）。
接続のサービスアカウントに権限を付与する: Project IAM 管理者（roles/resourcemanager.projectIamAdmin）。

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

必要な権限

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

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

費用

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

BigQuery ML: You incur costs for the data that you process in BigQuery.
Vertex AI: You incur costs for calls to the Vertex AI service that's represented by the remote model.

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

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

BigQuery の料金の詳細については、BigQuery ドキュメントの BigQuery の料金をご覧ください。

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

始める前に

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

データセットを作成する

ML モデルを保存する BigQuery データセットを作成します。

コンソール

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

[BigQuery] ページに移動
[エクスプローラ] ペインで、プロジェクト名をクリックします。
[アクションを表示] > [データセットを作成] をクリックします。
[データセットを作成する] ページで、次の操作を行います。
- [データセット ID] に「bqml_tutorial」と入力します。
- [ロケーションタイプ] で [マルチリージョン] を選択してから、[US（米国の複数のリージョン）] を選択します。
- 残りのデフォルトの設定は変更せず、[データセットを作成] をクリックします。

bq

新しいデータセットを作成するには、--location フラグを指定した bq mk コマンドを使用します。使用可能なパラメータの一覧については、bq mk --dataset コマンドのリファレンスをご覧ください。

データの場所が US に設定され、BigQuery ML tutorial dataset という説明の付いた、bqml_tutorial という名前のデータセットを作成します。
```
bq --location=US mk -d \
 --description "BigQuery ML tutorial dataset." \
 bqml_tutorial
```
このコマンドでは、--dataset フラグの代わりに -d ショートカットを使用しています。-d と --dataset を省略した場合、このコマンドはデフォルトでデータセットを作成します。
データセットが作成されたことを確認します。
```
bq ls
```

API

定義済みのデータセットリソースを使用して datasets.insert メソッドを呼び出します。

{
  "datasetReference": {
     "datasetId": "bqml_tutorial"
  }
}

BigQuery DataFrames

このサンプルを試す前に、BigQuery DataFrames を使用した BigQuery クイックスタートの手順に沿って BigQuery DataFrames を設定してください。詳細については、BigQuery DataFrames のリファレンスドキュメントをご覧ください。

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の ADC の設定をご覧ください。

import google.cloud.bigquery

bqclient = google.cloud.bigquery.Client()
bqclient.create_dataset("bqml_tutorial", exists_ok=True)

接続を作成する

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

デフォルトの接続が構成されているか、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 ユーザーロールを付与します。このロールは、始める前にで作成または選択したプロジェクトで付与する必要があります。別のプロジェクトでロールを付与すると、「bqcx-1234567890-xxxx@gcp-sa-bigquery-condel.iam.gserviceaccount.com does not have the permission to access resource」というエラーが発生します。

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

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

[IAM と管理] に移動
[アクセス権を付与] をクリックします。
[新しいプリンシパル] フィールドに、前の手順でコピーしたサービスアカウント ID を入力します。
[ロールを選択] フィールドで、[Vertex AI]、[Vertex AI ユーザーロール] の順に選択します。
[保存] をクリックします。

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

Vertex AI モデルを表すリモートモデルを作成します。

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

[BigQuery] に移動
クエリエディタで、次のステートメントを実行します。

CREATE OR REPLACE MODEL `bqml_tutorial.gemini_model`
  REMOTE WITH CONNECTION `LOCATION.CONNECTION_ID`
  OPTIONS (ENDPOINT = 'gemini-2.0-flash');

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

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

クエリが完了するまでに数秒かかります。完了後、モデル gemini_model が bqml_tutorial データセットに表示されます。クエリは CREATE MODEL ステートメントを使用してモデルを作成するため、クエリの結果はありません。

キーワード抽出を行う

リモートモデルと ML.GENERATE_TEXT 関数を使用して、IMDB 映画レビューに対してキーワード抽出を行います。

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

[BigQuery] に移動

クエリエディタで次のステートメントを入力して、5 つの映画レビューでキーワード抽出を行います。

SELECT
  ml_generate_text_result['candidates'][0]['content'] AS generated_text,
  * EXCEPT (ml_generate_text_result)
FROM
  ML.GENERATE_TEXT(
    MODEL `bqml_tutorial.gemini_model`,
    (
      SELECT
        CONCAT('Extract the key words from the text below: ', review) AS prompt,
        *
      FROM
        `bigquery-public-data.imdb.reviews`
      LIMIT 5
    ),
    STRUCT(
      0.2 AS temperature,
      100 AS max_output_tokens));

出力は次のようになります（わかりやすくするために、生成されていない列は省略しています）。

+----------------------------------------+-------------------------+----------------------------+-----+
| generated_text                         | ml_generate_text_status | prompt                     | ... |
+----------------------------------------+-------------------------+----------------------------+-----+
| {"parts":[{"text":"## Key words:\n\n*  |                         | Extract the key words from |     |
| **Negative sentiment:** \"terribly     |                         | the text below: I had to   |     |
| bad acting\", \"dumb story\", \"not    |                         | see this on the British    |     |
| even a kid would enjoy this\",         |                         | Airways plane. It was      |     |
| \"something to switch off\"\n*         |                         | terribly bad acting and    |     |
| **Context:** \"British Airways plane\" |                         | a dumb story. Not even     |     |
| \n* **Genre:** \"movie\" (implied)...  |                         | a kid would enjoy this...  |     |
+----------------------------------------+-------------------------+----------------------------+-----+
| {"parts":[{"text":"## Key words:\n\n*  |                         | Extract the key words from |     |
| **Movie:** The Real Howard Spitz\n*    |                         | the text below: This is    |     |
| **Genre:** Family movie\n*             |                         | a family movie that was    |     |
| **Broadcast:** ITV station, 1.00 am\n* |                         | broadcast on my local      |     |
| **Director:** Vadim Jean\n*            |                         | ITV station at 1.00 am a   |     |
| **Main character:** Howard Spitz,      |                         | couple of nights ago.      |     |
| a children's author who hates...       |                         | This might be a strange... |     |
+----------------------------------------+-------------------------+----------------------------+-----+

結果には次の列が含まれます。

generated_text: 生成されたテキスト。
ml_generate_text_status: 対応する行の API レスポンスステータス。オペレーションが成功した場合、この値は空になります。
prompt: 感情分析に使用されるプロンプト。
bigquery-public-data.imdb.reviews テーブルのすべての列。

省略可: 前の手順で行ったように、関数から返された JSON を手動で解析するのではなく、flatten_json_output 引数を使用して、生成されたテキストと安全性属性を別々の列に返します。

クエリエディタで、次のステートメントを実行します。

SELECT
  *
FROM
  ML.GENERATE_TEXT(
    MODEL `bqml_tutorial.gemini_model`,
    (
      SELECT
        CONCAT('Extract the key words from the text below: ', review) AS prompt,
        *
      FROM
        `bigquery-public-data.imdb.reviews`
      LIMIT 5
    ),
    STRUCT(
      0.2 AS temperature,
      100 AS max_output_tokens,
      TRUE AS flatten_json_output));

出力は次のようになります（わかりやすくするために、生成されていない列は省略しています）。

+----------------------------------------+----------------------------------------------+-------------------------+----------------------------+-----+
| ml_generate_text_llm_result            | ml_generate_text_rai_result                  | ml_generate_text_status | prompt                     | ... |
+----------------------------------------+----------------------------------------------+-------------------------+----------------------------+-----+
| ## Keywords:                           |                                              |                         | Extract the key words from |     |
|                                        |                                              |                         | the text below: I had to   |     |
| * **Negative sentiment:**              |                                              |                         | see this on the British    |     |
| "terribly bad acting", "dumb           |                                              |                         | Airways plane. It was      |     |
| story", "not even a kid would          |                                              |                         | terribly bad acting and    |     |
| enjoy this", "switch off"              |                                              |                         | a dumb story. Not even     |     |
| * **Context:** "British                |                                              |                         | a kid would enjoy this...  |     |
+----------------------------------------+----------------------------------------------+-------------------------+----------------------------+-----+
| ## Key words:                          |                                              |                         | Extract the key words from |     |
|                                        |                                              |                         | the text below: This is    |     |
| * **Movie:** The Real Howard Spitz     |                                              |                         | a family movie that was    |     |
| * **Genre:** Family movie              |                                              |                         | broadcast on my local      |     |
| * **Broadcast:** ITV, 1.00             |                                              |                         | ITV station at 1.00 am a   |     |
| am                                     |                                              |                         | couple of nights ago.      |     |
| - ...                                  |                                              |                         | This might be a strange... |     |
+----------------------------------------+----------------------------------------------+-------------------------+----------------------------+-----+

結果には次の列が含まれます。

ml_generate_text_llm_result: 生成されたテキスト。
ml_generate_text_rai_result: 安全属性と、ブロックカテゴリのいずれかに応じたコンテンツがブロックされているかどうかに関する情報。安全性属性の詳細については、安全性フィルタを構成するをご覧ください。
ml_generate_text_status: 対応する行の API レスポンスステータス。オペレーションが成功した場合、この値は空になります。
prompt: キーワード抽出に使用されるプロンプト。
bigquery-public-data.imdb.reviews テーブルのすべての列。

感情分析を行う

リモートモデルと ML.GENERATE_TEXT 関数を使用して、IMDB 映画レビューに対して感情分析を行います。

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

[BigQuery] に移動

クエリエディタで次のステートメントを実行して、5 つの映画レビューの感情分析を行います。

SELECT
  ml_generate_text_result['candidates'][0]['content'] AS generated_text,
  * EXCEPT (ml_generate_text_result)
FROM
  ML.GENERATE_TEXT(
    MODEL `bqml_tutorial.gemini_model`,
    (
      SELECT
        CONCAT(
          'perform sentiment analysis on the following text, return one the following categories: positive, negative: ',
          review) AS prompt,
        *
      FROM
        `bigquery-public-data.imdb.reviews`
      LIMIT 5
    ),
    STRUCT(
      0.2 AS temperature,
      100 AS max_output_tokens));

出力は次のようになります（わかりやすくするために、生成されていない列は省略しています）。

+--------------------------------------------+-------------------------+----------------------------+-----+
| generated_text                             | ml_generate_text_status | prompt                     | ... |
+--------------------------------------------+-------------------------+----------------------------+-----+
| {"parts":[{"text":"## Sentiment Analysis:  |                         | perform sentiment analysis |     |
| Negative \n\nThis text expresses a         |                         | on the following text,     |     |
| strongly negative sentiment towards the    |                         | return one the following   |     |
| movie. Here's why:\n\n* **Negative         |                         | negative: I  had to see    |     |
| like \"terribly,\" \"dumb,\" and           |                         | this on the British        |     |
| \"not even\" to describe the acting...     |                         | Airways plane. It was...   |     |
+--------------------------------------------+-------------------------+----------------------------+-----+
| {"parts":[{"text":"## Sentiment Analysis:  |                         | perform sentiment analysis |     |
| Negative \n\nThis review expresses a       |                         | on the following text,     |     |
| predominantly negative sentiment towards   |                         | return one the following   |     |
| the movie \"The Real Howard Spitz.\"       |                         | categories: positive,      |     |
| Here's why:\n\n* **Criticism of the film's |                         | negative: This is a family |     |
| premise:** The reviewer finds it strange   |                         | movie that was broadcast   |     |
| that a film about a children's author...   |                         | on my local ITV station... |     |
+--------------------------------------------+-------------------------+----------------------------+-----+

結果には、キーワード抽出を行うで説明したものと同じ列が含まれます。

クリーンアップ

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

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

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

In the Google Cloud console, go to the Manage resources page.
Go to Manage resources
In the project list, select the project that you want to delete, and then click Delete.
In the dialog, type the project ID, and then click Shut down to delete the project.

Gemini モデルと ML.GENERATE_TEXT 関数を使用してテキストを生成する

必要なロール

必要な権限

費用

始める前に

データセットを作成する

コンソール

bq

API

BigQuery DataFrames

接続を作成する

コンソール

bq

Terraform

Cloud Shell を準備する

ディレクトリを準備する

変更を適用する

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

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

キーワード抽出を行う

感情分析を行う

クリーンアップ

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