使用 ML.ANNOTATE_IMAGE 函数为图片添加注释

本文档介绍了如何将 ML.ANNOTATE_IMAGE 函数与远程模型搭配使用来为对象表中的图片添加注解。

所需权限

• 如需创建连接，您需要拥有以下角色的成员资格：

  • 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. 登录您的 Google Cloud 账号。如果您是 Google Cloud 新手，请创建一个账号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金，用于运行、测试和部署工作负载。

2. 在 Google Cloud Console 中的项目选择器页面上，选择或创建一个 Google Cloud 项目。

   注意：如果您不打算保留在此过程中创建的资源，请创建新的项目，而不要选择现有的项目。完成本教程介绍的步骤后，您可以删除所创建的项目，并移除与该项目关联的所有资源。

   转到“项目选择器”

3. 确保您的 Google Cloud 项目已启用结算功能。

4. 启用 BigQuery, BigQuery Connection API, and Cloud Vision API API。

   启用 API

5. 在 Google Cloud Console 中的项目选择器页面上，选择或创建一个 Google Cloud 项目。

   注意：如果您不打算保留在此过程中创建的资源，请创建新的项目，而不要选择现有的项目。完成本教程介绍的步骤后，您可以删除所创建的项目，并移除与该项目关联的所有资源。

   转到“项目选择器”

6. 确保您的 Google Cloud 项目已启用结算功能。

7. 启用 BigQuery, BigQuery Connection API, and Cloud Vision API API。

   启用 API

创建连接

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

从下列选项中选择一项：

控制台

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. 点击 Add。

   系统随即会打开添加主账号对话框。

3. 在新的主账号字段中，输入您之前复制的服务账号 ID。

4. 在选择角色字段中，选择 Service Usage，然后选择 Service Usage Consumer。

5. 点击添加其他角色。

6. 在选择角色字段中，选择 BigQuery，然后选择 BigQuery Connection User。

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_VISION_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_VISION_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.ANNOTATE_IMAGE 函数为图片添加注解：

SELECT *
FROM ML.ANNOTATE_IMAGE(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  TABLE PROJECT_ID.DATASET_ID.OBJECT_TABLE_NAME,
  STRUCT(['FEATURE_NAME' [,...]] AS vision_features)
);

请替换以下内容：

• PROJECT_ID：您的项目 ID。
• DATASET_ID：包含该模型的数据集的 ID。
• MODEL_NAME：模型的名称。
• OBJECT_TABLE_NAME：对象表的名称，该对象表包含要添加注解的图片的 URI。
• FEATURE_NAME：支持的 Cloud Vision API 功能的名称。

示例 1

以下示例标记图片中显示的项：

SELECT *
FROM ML.ANNOTATE_IMAGE(
  MODEL `myproject.mydataset.myvisionmodel`,
  TABLE myproject.mydataset.image_table,
  STRUCT(['label_detection'] AS vision_features)
);

示例 2

以下示例检测图片中显示的所有人脸，并返回图片属性，例如主色：

SELECT *
FROM ML.ANNOTATE_IMAGE(
  MODEL `myproject.mydataset.myvisionmodel`,
  TABLE myproject.mydataset.image_table,
  STRUCT(['face_detection', 'image_properties'] AS vision_features)
);

后续步骤

• 查看有关如何使用 ML.ANNOTATE_IMAGE 函数为图片添加注释的分步说明。
• 如需详细了解模型推断，包括可用于分析 BigQuery 数据的其他函数，请参阅模型推断概览。
• 如需了解每种模型类型支持的 SQL 语句和函数，请参阅每个模型的端到端用户体验历程。
• 试用使用 BigQuery ML 和 Vertex AI 预训练模型进行非结构化数据分析笔记本。