此页面由 Cloud Translation API 翻译。

使用 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

准备工作

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.

Go to project selector

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

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

Enable the APIs

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

Go to project selector

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

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

Enable the APIs

创建连接

创建 Cloud 资源连接并获取连接的服务账号。

从下列选项中选择一项：

控制台

转到 BigQuery 页面。

转到 BigQuery
如需创建连接，请点击添加，然后点击与外部数据源的连接。
在连接类型列表中，选择 Vertex AI 远程模型、远程函数和 BigLake（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 项目。

您只需为每个项目运行一次以下命令，即可在任何目录中运行它。
```
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。您只需为每个目录执行一次此操作。
```
terraform init
```
（可选）如需使用最新的 Google 提供程序版本，请添加 -upgrade 选项：
```
terraform init -upgrade
```

应用更改

查看配置并验证 Terraform 将创建或更新的资源是否符合您的预期：
```
terraform plan
```
根据需要更正配置。
通过运行以下命令并在提示符处输入 yes 来应用 Terraform 配置：
```
terraform apply
```
等待 Terraform 显示“应用完成！”消息。
打开您的 Google Cloud 项目以查看结果。在 Google Cloud 控制台的界面中找到资源，以确保 Terraform 已创建或更新它们。

向服务账号授予访问权限

从下列选项中选择一项：

控制台

前往 IAM 和管理页面。

转到“IAM 和管理”
点击 Add。

系统随即会打开添加主账号对话框。
在新的主账号字段中，输入您之前复制的服务账号 ID。
在选择角色字段中，选择 Service Usage，然后选择 Service Usage Consumer。
点击添加其他角色。
在选择角色字段中，选择 BigQuery，然后选择 BigQuery Connection User。
点击保存。

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 预训练模型进行非结构化数据分析笔记本。