使用 ML.GENERATE_EMBEDDING 函数生成文本嵌入

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

所需的角色

如需创建连接，您需要拥有以下 Identity and Access Management (IAM) 角色的成员资格：
- roles/bigquery.connectionAdmin
如需向连接的服务账号授予权限，您需要以下权限：
- resourcemanager.projects.setIamPolicy
如需使用 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, and Vertex AI APIs.
Enable the APIs

创建数据集

创建 BigQuery 数据集以存储您的机器学习模型：

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

转到 BigQuery 页面
在探索器窗格中，点击您的项目名称。
点击 查看操作 > 创建数据集。
在创建数据集页面上，执行以下操作：
- 在数据集 ID 部分，输入 bqml_tutorial。
- 在位置类型部分，选择多区域，然后选择 US (multiple regions in United States)（美国[美国的多个区域]）。
  
  公共数据集存储在 US 多区域中。为简单起见，请将数据集存储在同一位置。
- 保持其余默认设置不变，然后点击创建数据集。

创建连接

创建 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

将以下部分附加到 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：您的连接区域

向服务账号授予访问权限

向您的服务账号授予使用连接的权限。未授予权限会导致错误。从下列选项中选择一项：

控制台

前往 IAM 和管理页面。

转到“IAM 和管理”
点击 授予访问权限。

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

gcloud

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

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

请替换以下内容：

PROJECT_NUMBER：您的项目编号
MEMBER：您之前复制的服务账号 ID

创建模型

在 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：BigQuery 连接的 ID
  当您在 Google Cloud 控制台中查看连接详情时，它是连接 ID 中显示的完全限定连接 ID 的最后一部分中的值，例如 projects/myproject/locations/connection_location/connections/myconnection
- ENDPOINT：要使用的嵌入 LLM。例如 ENDPOINT='multimodalembedding'。
  对于某些类型的模型，您可以通过将 @version 附加到模型名称来指定模型的特定版本。例如 textembedding-gecko@001。如需了解不同模型类型支持的模型版本，请参阅 ENDPOINT。

使用表中的数据生成文本嵌入

使用表列中的文本数据，通过 ML.GENERATE_EMBEDDING 函数生成文本嵌入。

通常，建议将 textembedding-gecko 或 textembedding-gecko-multilingual 模型用于纯文本用例，将 multimodalembedding 模型用于跨模态搜索应用场景，其中文本和视觉内容的嵌入在同一语义空间中生成。

`textembedding-gecko*`

使用基于 textembedding-gecko 或 textembedding-gecko-multilingual LLM 的远程模型生成文本嵌入：

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  TABLE PROJECT_ID.DATASET_ID.TABLE_NAME,
  STRUCT(FLATTEN_JSON AS flatten_json_output,
    TASK_TYPE AS task_type)
);

替换以下内容：

PROJECT_ID：您的项目 ID。
DATASET_ID：包含该模型的数据集的 ID。
MODEL_NAME：基于 textembedding-gecko 或 textembedding-gecko-multilingual 模型的远程模型名称。
TABLE_NAME：包含要嵌入的文本的表的名称。该表必须具有名为 content 的列，或者您可以通过别名来使用其他名称的列。
FLATTEN_JSON：指示是否将嵌入解析为单独的列的 BOOL 值。默认值为 TRUE。
TASK_TYPE：STRING 字面量，指定预期的下游应用，可帮助模型生成质量更高的嵌入。TASK_TYPE 接受以下值：
- RETRIEVAL_QUERY：在搜索或检索设置中指定给定文本是查询。
- RETRIEVAL_DOCUMENT：在搜索或检索设置中指定给定文本是文档。
  使用此任务类型时，在查询语句中添加文档标题有助于提高嵌入质量。您可以使用 title 选项指定包含文档标题的列的名称，否则文档标题必须位于名为 title 或别名为 title 的列中，例如：
```
      SELECT *
      FROM
        ML.GENERATE_EMBEDDING(
          MODEL mydataset.embedding_model,
          (SELECT abstract as content, header as title, publication_number
          FROM mydataset.publications),
          STRUCT(TRUE AS flatten_json_output, 'RETRIEVAL_DOCUMENT' as task_type)
      );
      
```
- SEMANTIC_SIMILARITY：指定给定文本用于语义文本相似度 (STS)。
- CLASSIFICATION：指定嵌入用于分类。
- CLUSTERING：指定嵌入用于聚类。

`multimodalembedding`

使用基于 multimodalembedding LLM 的远程模型生成文本嵌入：

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  TABLE PROJECT_ID.DATASET_ID.TABLE_NAME,
  STRUCT(FLATTEN_JSON AS flatten_json_output)
);

替换以下内容：

PROJECT_ID：您的项目 ID。
DATASET_ID：包含该模型的数据集的 ID。
MODEL_NAME：基于 multimodalembedding@001 模型的远程模型的名称。
TABLE_NAME：包含要嵌入的文本的表的名称。该表必须具有名为 content 的列，或者您可以通过别名来使用其他名称的列。
FLATTEN_JSON：指示是否将嵌入解析为单独的列的 BOOL。默认值为 TRUE。

使用查询中的数据生成文本嵌入

使用查询提供的文本数据和基于 textembedding-gecko 或 textembedding-gecko-multilingual LLM 的远程模型，通过 ML.GENERATE_EMBEDDING 函数生成文本嵌入：

`textembedding-gecko*`

使用基于 textembedding-gecko 或 textembedding-gecko-multilingual LLM 的远程模型生成文本嵌入：

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  (CONTENT_QUERY),
  STRUCT(FLATTEN_JSON AS flatten_json_output,
    TASK_TYPE AS task_type
  );

替换以下内容：

PROJECT_ID：您的项目 ID。
DATASET_ID：包含该模型的数据集的 ID。
MODEL_NAME：基于 textembedding-gecko 或 textembedding-gecko-multilingual 模型的远程模型名称。
CONTENT_QUERY：结果包含名为 content 的 STRING 列的查询。
FLATTEN_JSON：指示是否将嵌入解析为单独的列的 BOOL 值。默认值为 TRUE。
TASK_TYPE：STRING 字面量，指定预期的下游应用，可帮助模型生成质量更高的嵌入。TASK_TYPE 接受以下值：
- RETRIEVAL_QUERY：在搜索或检索设置中指定给定文本是查询。
- RETRIEVAL_DOCUMENT：在搜索或检索设置中指定给定文本是查询。
  使用此任务类型时，在查询语句中添加文档标题有助于提高嵌入质量。您可以使用 title 选项指定包含文档标题的列的名称，否则文档标题必须位于名为 title 或别名为 title 的列中，例如：
```
          SELECT *
          FROM
            ML.GENERATE_EMBEDDING(
              MODEL mydataset.embedding_model,
              (SELECT abstract as content, header as title, publication_number
              FROM mydataset.publications),
              STRUCT(TRUE AS flatten_json_output, 'RETRIEVAL_DOCUMENT' as task_type)
          );
          
```
- SEMANTIC_SIMILARITY：指定给定文本用于语义文本相似度 (STS)。
- CLASSIFICATION：指定嵌入用于分类。
- CLUSTERING：指定嵌入用于聚类。

`multimodalembedding`

使用基于 multimodalembedding LLM 的远程模型生成文本嵌入：

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  (CONTENT_QUERY),
  STRUCT(FLATTEN_JSON AS flatten_json_output)
);

替换以下内容：

PROJECT_ID：您的项目 ID。
DATASET_ID：包含该模型的数据集的 ID。
MODEL_NAME：基于 multimodalembedding@001 模型的远程模型的名称。
CONTENT_QUERY：结果包含名为 content 的 STRING 列的查询。
FLATTEN_JSON：指示是否将嵌入解析为单独的列的 BOOL。默认值为 TRUE。

示例

以下示例展示了如何对表和查询调用 ML.GENERATE_EMBEDDING 函数。

在表格中嵌入文本

以下示例展示了嵌入 text_data 表的 content 列的请求：

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

使用嵌入对语义相似性进行排名

以下示例嵌入一组电影评论，并使用 ML.DISTANCE 函数按与评论“此电影比较一般”的余弦距离进行排序。距离越小表示语义相似性越高。

WITH movie_review_embeddings AS (
  SELECT *
  FROM
    ML.GENERATE_EMBEDDING(
      MODEL `bqml_tutorial.embedding_model`,
      (
        SELECT "Movie 1" AS title, "This movie was fantastic" AS content
        UNION ALL
        SELECT "Movie 2" AS title, "This was the best movie I've ever seen!!" AS content
        UNION ALL
        SELECT "Movie 3" AS title, "This movie was just okay..." AS content
        UNION ALL
        SELECT "Movie 4" AS title, "This movie was terrible." AS content
      ),
      STRUCT(TRUE AS flatten_json_output)
    )
),
average_review_embedding AS (
  SELECT ml_generate_embedding_result
  FROM
    ML.GENERATE_EMBEDDING(
      MODEL `bqml_tutorial.embedding_model`,
      (SELECT "This movie was average" AS content),
      STRUCT(TRUE AS flatten_json_output)
    )
)
SELECT
  content,
  ML.DISTANCE(
    (SELECT ml_generate_embedding_result FROM average_review_embedding),
    ml_generate_embedding_result,
    'COSINE'
  ) AS distance_to_average_review
FROM
  movie_review_embeddings
ORDER BY distance_to_average_review;

结果如下：

+------------------------------------------+----------------------------+
| content                                  | distance_to_average_review |
+------------------------------------------+----------------------------+
| This movie was fantastic                 | 0.10028859431058901        |
| This movie was terrible.                 |   0.142427236973374        |
| This was the best movie I've ever seen!! | 0.46742391210381995        |
| This movie was just okay...              | 0.47399255715360622        |
+------------------------------------------+----------------------------+