ML.UNDERSTAND_TEXT 関数を使用してテキストを理解する

このドキュメントでは、リモートモデルで ML.UNDERSTAND_TEXT 関数を使用して、BigQuery 標準テーブルのテキスト上で自然言語のテキスト分析関数を実行する方法について説明します。

必要なロール

リモートモデルを作成してテキストを分析するには、プロジェクト レベルで次の Identity and Access Management（IAM）ロールが必要です。

• BigQuery データセット、テーブル、モデルの作成と使用: BigQuery データ編集者（roles/bigquery.dataEditor）

• BigQuery 接続の作成、委任、使用: BigQuery 接続管理者（roles/bigquery.connectionsAdmin）

  デフォルト接続が構成されていない場合は、CREATE MODEL ステートメントの実行時に作成して設定できます。これを行うには、プロジェクトに対する BigQuery 管理者（roles/bigquery.admin）が必要です。詳細については、デフォルト接続を構成するをご覧ください。

• 接続のサービス アカウントに権限を付与する: Project IAM 管理者（roles/resourcemanager.projectIamAdmin）。

• 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

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

始める前に

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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 API, and Cloud Natural Language API 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

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 API, and Cloud Natural Language API 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 データセットを作成します。

コンソール

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

   BigQuery に移動

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

   

   左側のペインが表示されていない場合は、 左側のペインを開くをクリックしてペインを開きます。

3. [エクスプローラ] ペインで、プロジェクト名をクリックします。

4. [アクションを表示] > [データセットを作成] をクリックします。

5. [データセットを作成する] ページで、次の操作を行います。

   1. [データセット ID] に、データセットの名前を入力します。

   2. [ロケーション タイプ] で、[リージョン] または [マルチリージョン] を選択します。

      • [リージョン] を選択した場合は、[リージョン] リストからロケーションを選択します。
      • [マルチリージョン] を選択した場合は、[マルチリージョン] リストから [US] または [ヨーロッパ] を選択します。

   3. [データセットを作成] をクリックします。

bq

1. 新しいデータセットを作成するには、--location フラグを指定した bq mk コマンドを使用します。

   bq --location=LOCATION mk -d DATASET_ID

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

   • LOCATION: データセットのロケーション。
   • DATASET_ID は、作成するデータセットの ID です。

2. データセットが作成されたことを確認します。

   bq ls

接続を作成する

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

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

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

コンソール

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

   [BigQuery] に移動

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

   

   [データを追加] ダイアログが開きます。

3. [フィルタ条件] ペインの [データソースのタイプ] セクションで、[ビジネス アプリケーション] を選択します。

   または、[データソースを検索] フィールドに「Vertex AI」と入力します。

4. [特徴量データソース] セクションで、[Vertex AI] をクリックします。

5. [Vertex AI モデル: BigQuery フェデレーション] ソリューション カードをクリックします。

6. [接続タイプ] リストで、[Vertex AI リモートモデル、リモート関数、BigLake、Spanner（Cloud リソース）] を選択します。

7. [接続 ID] フィールドに接続の名前を入力します。

8. [接続を作成] をクリックします。

9. [接続へ移動] をクリックします。

10. [接続情報] ペインで、次の手順で使用するサービス アカウント ID をコピーします。

bq

1. コマンドライン環境で接続を作成します。

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

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

   bq show --connection PROJECT_ID.REGION.CONNECTION_ID

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

   name                          properties
   1234.REGION.CONNECTION_ID     {"serviceAccountId": "[e-mail]"}
   

Terraform

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

注: Terraform を使用して BigQuery オブジェクトを作成するには、Cloud Resource Manager API を有効にする必要があります。

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 を準備する

1. Cloud Shell を起動します。

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

   このコマンドは、プロジェクトごとに 1 回だけ実行する必要があります。これは任意のディレクトリで実行できます。

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   Terraform 構成ファイルに明示的な値を設定すると、環境変数がオーバーライドされます。

ディレクトリを準備する

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

1. Cloud Shell で、ディレクトリを作成し、そのディレクトリ内に新しいファイルを作成します。ファイルの拡張子は .tf にする必要があります（例: main.tf）。このチュートリアルでは、このファイルを main.tf とします。

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. チュートリアルを使用している場合は、各セクションまたはステップのサンプルコードをコピーできます。

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

   必要に応じて、GitHub からコードをコピーします。Terraform スニペットがエンドツーエンドのソリューションの一部である場合は、この方法をおすすめします。

3. 環境に適用するサンプル パラメータを確認し、変更します。
4. 変更を保存します。
5. Terraform を初期化します。これは、ディレクトリごとに 1 回だけ行います。

   terraform init

   最新バージョンの Google プロバイダを使用する場合は、-upgrade オプションを使用します。

   terraform init -upgrade

変更を適用する

1. 構成を確認して、Terraform が作成または更新するリソースが想定どおりであることを確認します。

   terraform plan

   必要に応じて構成を修正します。

2. 次のコマンドを実行します。プロンプトで「yes」と入力して、Terraform 構成を適用します。

   terraform apply

   Terraform に「Apply complete!」というメッセージが表示されるまで待ちます。

3. Google Cloud プロジェクトを開いて結果を表示します。 Google Cloud コンソールの UI でリソースに移動して、Terraform によって作成または更新されたことを確認します。

注: Terraform のサンプルでは通常、必要な API が Google Cloud プロジェクトで有効になっていることを前提としています。

サービス アカウントへのアクセスを許可する

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

コンソール

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

   [IAM と管理] に移動

2. [追加] をクリックします。

   [プリンシパルを追加] ダイアログが開きます。

3. [新しいプリンシパル] フィールドに、前の手順でコピーしたサービス アカウント ID を入力します。

4. [ロールを選択] フィールドで、[Service Usage] を選択し、[Service Usage コンシューマ] を選択します。

5. [別のロールを追加] をクリックします。

6. [ロールを選択] フィールドで、[BigQuery] を選択し、[BigQuery Connection ユーザー] を選択します。

7. [保存] をクリックします。

gcloud

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

gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/serviceusage.serviceUsageConsumer' --condition=None
gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/bigquery.connectionUser' --condition=None

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

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

権限を付与しないと、エラーが発生します。

モデルを作成する

CLOUD_AI_NATURAL_LANGUAGE_V1 の REMOTE_SERVICE_TYPE を使用してリモートモデルを作成します。

CREATE OR REPLACE MODEL
`PROJECT_ID.DATASET_ID.MODEL_NAME`
REMOTE WITH CONNECTION {DEFAULT | `PROJECT_ID.REGION.CONNECTION_ID`}
OPTIONS (REMOTE_SERVICE_TYPE = 'CLOUD_AI_NATURAL_LANGUAGE_V1');

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

• PROJECT_ID: プロジェクト ID。
• DATASET_ID: モデルを格納するデータセットの ID。このデータセットは、使用している接続と同じロケーションに存在している必要があります。
• MODEL_NAME: モデルの名前。
• REGION: 接続で使用されるリージョン。
• CONNECTION_ID: 接続 ID（例: myconnection）。

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

テキストを理解する

ML.UNDERSTAND_TEXT 関数を使用してテキストを理解します。

SELECT *
FROM ML.UNDERSTAND_TEXT(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  { TABLE PROJECT_ID.DATASET_ID.TABLE_NAME | (QUERY) },
  STRUCT('FEATURE_NAME' AS nlu_option
  [, 'FLATTEN_JSON_OUTPUT' AS flatten_json_output]
  [, ENCODING_TYPE AS encoding_type])
);

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

• PROJECT_ID: プロジェクト ID。
• DATASET_ID: モデルを格納するデータセットの ID。
• MODEL_NAME: モデルの名前。
• TABLE_NAME: text_content という名前の列に分析対象のテキストが含まれているテーブルの名前。異なる名前の列にテキストがある場合は、text_content をその列のエイリアスとして指定します。
• QUERY: text_content という名前の列に記述対象のテキストがあるクエリ。異なる名前の列にテキストがある場合は、text_content をその列のエイリアスとして指定します。
• FEATURE_NAME: サポートされている Natural Language API 機能の名前。
• FLATTEN_JSON_OUTPUT: 関数から返された JSON コンテンツを別の列に解析するかどうかを決定する BOOL 値です。
• ENCODING_TYPE: beginOffset 値などのエンコード依存情報を Cloud Natural Language API が決定するために使用するエンコードを指定する STRING 値。詳細については、EncodingType をご覧ください。

例 1

次の例では、テーブルの text_content 列のテキストを検査し、テキスト内の感情的傾向を特定します。

SELECT * FROM ML.UNDERSTAND_TEXT(
  MODEL `mydataset.mynlpmodel`,
  TABLE mydataset.mytable,
  STRUCT('analyze_sentiment' AS nlu_option)
);

例 2

次の例では、テーブルの comment 列のテキストを検査し、テキストの構文情報を提供します。

SELECT * FROM ML.UNDERSTAND_TEXT(
  MODEL `mydataset.mynlpmodel`,
  (SELECT comment AS text_content from mydataset.mytable),
  STRUCT('analyze_syntax' AS nlu_option)
);

次のステップ

• BigQuery ML でのモデルの推論の詳細については、モデルの推論の概要をご覧ください。
• 生成 AI モデルでサポートされている SQL ステートメントと関数の詳細については、生成 AI モデルのエンドツーエンドのユーザー ジャーニーをご覧ください。
• BigQuery ML と Vertex AI の事前トレーニング済みモデルを使用した非構造化データの分析ノートブックを試す。