此页面由 Cloud Translation API 翻译。

使用 ML.GENERATE_EMBEDDING 函数生成图片嵌入

本文档介绍了如何创建引用 Vertex AI 嵌入模型的 BigQuery ML 远程模型。然后，将该模型与 ML.GENERATE_EMBEDDING 函数搭配使用，以使用 BigQuery 对象表中的数据创建图片嵌入。

所需的角色

如需创建连接，您需要拥有以下 Identity and Access Management (IAM) 角色的成员资格：
- roles/bigquery.connectionAdmin
如需向连接的服务账号授予权限，您需要以下权限：
- resourcemanager.projects.setIamPolicy
如需创建对象表，您需要拥有以下权限：
- bigquery.tables.create
- bigquery.tables.update
- bigquery.connections.delegate
如需使用 BigQuery ML 创建模型，您需要以下 IAM 权限：
- bigquery.jobs.create
- bigquery.models.create
- bigquery.models.getData
- bigquery.models.updateData
- bigquery.models.updateMetadata
如需运行推理，您需要以下权限：
- 表的 bigquery.tables.getData 权限
- 模型的 bigquery.models.getData 权限
- bigquery.jobs.create

须知事项

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
Make sure that billing is enabled for your Google Cloud project.
Enable the BigQuery, BigQuery Connection, Cloud Storage, and Vertex AI APIs.
Enable the APIs

创建数据集

创建 BigQuery 数据集以存储对象表和模型。

控制台

在 Google Cloud 控制台中，转到 BigQuery 页面。

转到 BigQuery 页面
在探索器窗格中，点击您的项目名称。
点击 查看操作 > 创建数据集。
在 创建数据集 页面上，执行以下操作：
- 在 Dataset ID 中，输入数据集的名称。
- 对于位置类型，为数据集选择一个位置。
- 点击创建数据集。

bq

如需创建新数据集，请使用带有 --location 标志的 bq mk 命令：
```
bq --location=LOCATION mk -d DATASET_ID
```
替换以下内容：
- LOCATION：数据集的位置。
- DATASET_ID 是您要创建的数据集的 ID。
确认已创建数据集：
```
bq ls
```

创建连接

创建 Cloud 资源连接并获取连接的服务账号。在与上一步中创建的数据集相同的位置创建连接。

从下列选项中选择一项：

控制台

转到 BigQuery 页面。

转到 BigQuery
在浏览器窗格中，点击 添加数据。

系统随即会打开添加数据对话框。
在过滤条件窗格的数据源类型部分中，选择数据库。

或者，您也可以在搜索数据源字段中输入 Vertex AI。
在精选数据源部分中，点击 Vertex AI。
点击 Vertex AI 模型：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 已创建或更新它们。

向服务账号授予访问权限

向连接的服务账号授予 Vertex AI User 和 Storage Object Viewer 角色。

如需授予这些角色，请按以下步骤操作：

控制台

前往 IAM 和管理页面。

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

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

gcloud

使用 gcloud projects add-iam-policy-binding 命令。

gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/aiplatform.user' --condition=None
gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/storage.objectViewer' --condition=None

请替换以下内容：

PROJECT_NUMBER：要授予角色的项目的项目编号。
MEMBER：您之前复制的服务账号 ID。

创建对象表

如需分析图片，而无需将其从 Cloud Storage 中移动，请创建对象表。

如需创建对象表，请执行以下操作：

SQL

使用 CREATE EXTERNAL TABLE 语句。

在 Google Cloud 控制台中，转到 BigQuery Studio 页面。

进入 BigQuery Studio
在查询编辑器中，输入以下语句：
```
CREATE EXTERNAL TABLE `PROJECT_ID.DATASET_ID.TABLE_NAME`
WITH CONNECTION {`PROJECT_ID.REGION.CONNECTION_ID`| DEFAULT}
OPTIONS(
  object_metadata = 'SIMPLE',
  uris = ['BUCKET_PATH'[,...]],
  max_staleness = STALENESS_INTERVAL,
  metadata_cache_mode = 'CACHE_MODE');
```
请替换以下内容：
- PROJECT_ID：您的项目 ID。
- DATASET_ID：您创建的数据集的 ID。
- TABLE_NAME：对象表的名称。
- REGION：包含连接的单区域或多区域。
- CONNECTION_ID：您创建的连接的 ID。
  当您在 Google Cloud 控制台中查看连接详情时，它是连接 ID 中显示的完全限定连接 ID 的最后一部分中的值，例如 projects/myproject/locations/connection_location/connections/myconnection。
  
  如需使用默认连接，请指定 DEFAULT，而不是包含 PROJECT_ID.REGION.CONNECTION_ID 的连接字符串。
- BUCKET_PATH：包含图片的 Cloud Storage 存储分区的路径，格式为 ['gs://bucket_name/[folder_name/]*']。
  您使用的 Cloud Storage 存储分区应位于您计划创建模型并调用 ML.GENERATE_EMBEDDING 函数所在的项目中。如果您要在不同于对象表使用的 Cloud Storage 存储分区所属项目中调用 ML.GENERATE_EMBEDDING 函数，您必须在存储分区级层将 Storage Admin 角色授予 service-A@gcp-sa-aiplatform.iam.gserviceaccount.com 服务账号。
- STALENESS_INTERVAL：指定对对象表执行的操作是否使用了缓存的元数据，以及操作使用的缓存元数据的新鲜度。如需详细了解元数据缓存注意事项，请参阅启用元数据缓存以提高性能。
  如需停用元数据缓存，请指定 0。这是默认设置。
  
  如需启用元数据缓存，请指定 30 分钟到 7 天之间的间隔时间字面量值。例如，指定 INTERVAL 4 HOUR 表示 4 小时过时间隔时间。使用此值时，如果缓存的元数据在过去 4 小时内刷新，则对表执行的操作会使用缓存的元数据。如果缓存的元数据早于该值，则操作会从 Cloud Storage 检索元数据。
- CACHE_MODE：指定元数据缓存是自动刷新还是手动刷新。如需详细了解元数据缓存注意事项，请参阅启用元数据缓存以提高性能。
  如果设置为 AUTOMATIC，元数据缓存会按系统定义的间隔时间刷新，通常在 30 到 60 分钟之间。
  
  如果要根据您确定的时间表刷新元数据缓存，请设置为 MANUAL。在这种情况下，您可以调用 BQ.REFRESH_EXTERNAL_METADATA_CACHE 系统过程来刷新缓存。
  
  如果 STALENESS_INTERVAL 设置为大于 0 的值，您必须设置 CACHE_MODE。
点击运行。

如需详细了解如何运行查询，请参阅运行交互式查询。

bq

使用 bq mk 命令。

bq mk --table \
--external_table_definition=BUCKET_PATH@REGION.CONNECTION_ID \
--object_metadata=SIMPLE \
--max_staleness=STALENESS_INTERVAL \
--metadata_cache_mode=CACHE_MODE \
PROJECT_ID:DATASET_ID.TABLE_NAME

请替换以下内容：

BUCKET_PATH：包含图片的 Cloud Storage 存储分区的路径，格式为 ['gs://bucket_name/[folder_name/]*']。
您使用的 Cloud Storage 存储分区应位于您计划创建模型并调用 ML.GENERATE_EMBEDDING 函数所在的项目中。如果您要在不同于对象表使用的 Cloud Storage 存储分区所属项目中调用 ML.GENERATE_EMBEDDING 函数，您必须在存储分区级层将 Storage Admin 角色授予 service-A@gcp-sa-aiplatform.iam.gserviceaccount.com 服务账号。
REGION：包含连接的单区域或多区域。
CONNECTION_ID：您创建的连接的 ID。
当您在 Google Cloud 控制台中查看连接详情时，它是连接 ID 中显示的完全限定连接 ID 的最后一部分中的值，例如 projects/myproject/locations/connection_location/connections/myconnection。
STALENESS_INTERVAL：指定对对象表执行的操作是否使用了缓存的元数据，以及操作使用的缓存元数据的新鲜度。如需详细了解元数据缓存注意事项，请参阅启用元数据缓存以提高性能。
如需停用元数据缓存，请指定 0。这是默认设置。

如需启用元数据缓存，请指定 30 分钟到 7 天之间的间隔时间字面量值。例如，指定 INTERVAL 4 HOUR 表示 4 小时过时间隔时间。使用此值时，如果缓存的元数据在过去 4 小时内刷新，则对表执行的操作会使用缓存的元数据。如果缓存的元数据早于该值，则操作会从 Cloud Storage 检索元数据。
CACHE_MODE：指定元数据缓存是自动刷新还是手动刷新。如需详细了解元数据缓存注意事项，请参阅启用元数据缓存以提高性能。
如果设置为 AUTOMATIC，元数据缓存会按系统定义的间隔时间刷新，通常在 30 到 60 分钟之间。

如果要根据您确定的时间表刷新元数据缓存，请设置为 MANUAL。在这种情况下，您可以调用 BQ.REFRESH_EXTERNAL_METADATA_CACHE 系统过程来刷新缓存。

如果 STALENESS_INTERVAL 设置为大于 0 的值，您必须设置 CACHE_MODE。
PROJECT_ID：您的项目 ID。
DATASET_ID：您创建的数据集的 ID。
TABLE_NAME：对象表的名称。

创建模型

在 Google Cloud 控制台中，转到 BigQuery 页面。

转到 BigQuery
使用 SQL 编辑器创建远程模型：
```
CREATE OR REPLACE MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`
REMOTE WITH CONNECTION `PROJECT_ID.REGION.CONNECTION_ID`
OPTIONS (ENDPOINT = 'ENDPOINT');
```
请替换以下内容：
- PROJECT_ID：您的项目 ID。
- DATASET_ID：您之前创建的数据集的 ID。
- MODEL_NAME：模型的名称。
- REGION：包含连接的单区域或多区域。
- CONNECTION_ID：您创建的连接的 ID。
  当您在 Google Cloud 控制台中查看连接详情时，它是连接 ID 中显示的完全限定连接 ID 的最后一部分中的值，例如 projects/myproject/locations/connection_location/connections/myconnection。
- ENDPOINT：要使用的嵌入模型，在本例中为 multimodalembedding@001。
  如果您在创建远程模型时将网址（例如 endpoint = 'https://us-central1-aiplatform.googleapis.com/v1/projects/myproject/locations/us-central1/publishers/google/models/text-embedding-004'）指定为端点，请确保您在网址中指定的项目是您向连接的服务账号授予 Vertex AI User 角色的项目。服务账号
  
  您创建远程模型的位置必须有 multimodalembedding@001 模型。如需了解详情，请参阅位置。

生成嵌入图片

使用对象表中的图片数据通过 ML.GENERATE_EMBEDDING 函数生成图片嵌入：

  SELECT *
  FROM ML.GENERATE_EMBEDDING(
    MODEL <var>PROJECT_ID</var>.<var>DATASET_ID</var>.<var>MODEL_NAME</var>,
    TABLE <var>PROJECT_ID</var>.<var>DATASET_ID</var>.<var>TABLE_NAME</var>,
    STRUCT(FLATTEN_JSON AS flatten_json_output,
    OUTPUT_DIMENSIONALITY AS output_dimensionality)
  );

替换以下内容：

PROJECT_ID：您的项目 ID。
DATASET_ID：包含该模型的数据集的 ID。
MODEL_NAME：基于 multimodalembedding@001 模型的远程模型的名称。
TABLE_NAME：包含要嵌入的图片的对象表的名称。
FLATTEN_JSON：指示是否将嵌入解析为单独的列的 BOOL 值。默认值为 TRUE。
OUTPUT_DIMENSIONALITY：INT64 值，用于指定生成嵌入时使用的维度数。有效值包括 128、256、512 和 1408。默认值为 1408。例如，如果您指定 256 AS output_dimensionality，则 ml_generate_embedding_result 输出列将包含每个输入值的 256 个嵌入。

示例

以下示例展示了如何为 images 对象表中的图片创建嵌入：

SELECT *
FROM
  ML.GENERATE_EMBEDDING(
    MODEL `mydataset.embedding_model`,
    TABLE `mydataset.images`,
    STRUCT(TRUE AS flatten_json_output, 512 AS output_dimensionality)
  );