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

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

BigQuery ML でのモデルの推論については、モデルの推論の概要をご覧ください。

各 SQL ステートメントと関数でサポートされているモデルタイプと、各モデルタイプでサポートされているすべての SQL ステートメントと関数については、各モデルのエンドツーエンドのユーザー ジャーニーをご覧ください。

必要な権限

• 接続を作成するには、次のロールのメンバーシップが必要です。

  • roles/bigquery.connectionAdmin

• 接続のサービス アカウントに権限を付与するには、次の権限が必要です。

  • resourcemanager.projects.setIamPolicy

• BigQuery ML を使用してモデルを作成するには、次の権限が必要です。

  • bigquery.jobs.create
  • bigquery.models.create
  • bigquery.models.getData
  • bigquery.models.updateData
  • bigquery.models.updateMetadata

• 推論を実行するには、次の権限が必要です。

  • テーブルに対する bigquery.tables.getData
  • モデルに対する bigquery.models.getData
  • bigquery.jobs.create

始める前に

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

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

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the BigQuery, BigQuery Connection API, and Cloud Natural Language API APIs.

   Enable the APIs

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

6. Make sure that billing is enabled for your Google Cloud project.

7. Enable the BigQuery, BigQuery Connection API, and Cloud Natural Language API APIs.

   Enable the APIs

接続を作成する

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

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

コンソール

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

   [BigQuery] に移動

2. 接続を作成するには、[追加] をクリックし、続いて [外部データソースへの接続] をクリックします。

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

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

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

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

7. [接続情報] ペインで、次の手順で使用するサービス アカウント 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

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: 接続のリージョン

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

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

コンソール

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

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

• PROJECT_ID: プロジェクト ID。
• DATASET_ID: モデルを格納するデータセットの ID。
• MODEL_NAME: モデルの名前。
• TABLE_NAME: text_content という名前の列に分析対象のテキストが含まれているテーブルの名前。異なる名前の列にテキストがある場合は、text_content をその列のエイリアスとして指定します。
• QUERY: text_content という名前の列に記述対象のテキストがあるクエリ。異なる名前の列にテキストがある場合は、text_content をその列のエイリアスとして指定します。
• FEATURE_NAME: サポートされている Natural Language API 機能の名前。

例 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 と Vertex AI の事前トレーニング済みモデルを使用した非構造化データの分析ノートブックを試す。