自主嵌入生成

本文档介绍了如何为数据使用自主嵌入生成功能，该功能可让 BigQuery 根据源列在表中维护一个嵌入列。当您在源列中添加或修改数据时，BigQuery 会使用 Vertex AI 嵌入模型自动为该数据生成或更新嵌入列。如果您希望在源数据定期更新时让 BigQuery 维护您的嵌入内容，此功能会很有帮助。

嵌入对于检索增强生成 (RAG) 等现代生成式 AI 应用非常有用，但创建、管理和查询起来可能很复杂。您可以使用自主嵌入生成功能来简化创建、维护和查询嵌入项的过程，以便在相似度搜索和其他生成式 AI 应用中使用这些嵌入项。

例如，您可以使用类似于以下内容的查询来创建启用自主嵌入生成的表、插入数据，然后执行语义搜索：

CREATE TABLE mydataset.products (
  name STRING,
  description STRING,
  description_embedding STRUCT<result ARRAY<FLOAT64>, status STRING>
    GENERATED ALWAYS AS (
      AI.EMBED(description, connection_id => 'us.example_connection',
        endpoint => 'text-embedding-005'))
    STORED OPTIONS( asynchronous = TRUE ));

# Values in the description_embedding column are automatically generated.
INSERT INTO mydataset.products (name, description) VALUES
  ("Super slingers"), ("An exciting board game for the whole family"), ...;

SELECT * FROM AI.SEARCH(TABLE mydataset.products, 'description', "A really fun toy");

准备工作

如需在表格中启用自主嵌入生成功能，您必须拥有必要的权限和连接。

所需的角色

如需获得启用自主生成嵌入所需的权限，请让您的管理员为您授予以下 IAM 角色：

  • 如需使用连接资源，您需要拥有以下权限： 针对连接的 BigQuery Connections User (roles/bigquery.connectionUser)
  • 如需创建表，您需要拥有以下角色： 针对表的 BigQuery Data Editor (roles/bigquery.dataEditor)
  • 向连接的服务账号授予以下角色，以便其可以访问 Vertex AI 端点中托管的模型： Vertex AI User (roles/aiplatform.user) 在具有连接的项目中

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

创建连接并向服务账号授予权限

如需在表格中启用自主生成嵌入功能，您必须创建 Cloud 资源连接。然后，向创建连接时创建的服务账号授予 Vertex AI User 角色 (roles/aiplatform.user)。

创建具有自主嵌入生成的表

您可以在 CREATE TABLE 语句中使用 AI.EMBED 函数，通过自主嵌入生成来生成嵌入。

CREATE TABLE DATASET_ID.TABLE (
  [COLUMN, ...]
  STRING_COL STRING,
  EMBEDDING_COL_NAME STRUCT<result ARRAY<FLOAT64>, status STRING>
    GENERATED ALWAYS AS (
      AI.EMBED(
        STRING_COL,
        connection_id => CONNECTION_ID,
        endpoint => ENDPOINT)
    )
    STORED OPTIONS (asynchronous = TRUE)
);

替换以下内容：

  • DATASET_ID：您要在其中创建表的相应数据集的名称。
  • TABLE：要为其创建自主嵌入生成的表的名称。
  • COLUMN, ...：除了要自动嵌入的列之外，您的表应包含的任何列。
  • STRING_COL：要自动嵌入的 STRING 列的名称。
  • EMBEDDING_COL_NAME：自动生成的嵌入列的名称。
  • CONNECTION_ID：包含要使用的连接名称的 STRING 值，例如 my_project.us.example_connection。您必须向创建表的项目中的连接服务账号授予 Vertex AI User 角色。
  • ENDPOINT：一个 STRING 值，用于指定要用于文本嵌入模型的受支持的 Vertex AI 文本嵌入模型端点。您指定的端点值必须包含模型版本，例如 text-embedding-005。如果您指定模型名称（而非网址），BigQuery ML 会自动识别模型并使用模型的完整端点。

在您创建表后或更新源列中的数据后不久，系统就会开始执行后台嵌入生成作业。

如需跟踪嵌入生成进度，您可以使用类似于以下的查询：

SELECT
  COUNT(*) AS total_num_rows,
  COUNTIF(description_embedding IS NOT NULL
          AND description_embedding.status = '') AS total_num_generated_embeddings
FROM
  PROJECT_ID.DATASET_ID.TABLE;

创建包含嵌入的表后，您可以针对包含自动生成的嵌入的 STRUCT 列创建向量索引。

示例

假设您是一家销售多种不同商品的大型零售商。您有一个包含商品名称和说明的表格，并且希望帮助客户找到他们要寻找的商品。以下查询展示了如何设置自主嵌入生成功能，以帮助您对产品说明进行语义搜索。

首先，创建数据集：

CREATE SCHEMA mydataset;

接下来，创建一个启用了自主嵌入生成功能的表，用于存储产品信息。自动生成的列名为 description_embedding，它基于 description 列。

# Create a table of products and descriptions with a generated embedding column.
CREATE TABLE mydataset.products (
  name STRING,
  description STRING,
  description_embedding STRUCT<result ARRAY<FLOAT64>, status STRING>
    GENERATED ALWAYS AS (AI.EMBED(
      description,
      connection_id => 'us.example_connection',
      endpoint => 'text-embedding-005'
    ))
    STORED OPTIONS( asynchronous = TRUE )
);

以下查询会将一些商品名称和说明插入到表中。您无需为 description_embedding 指定值，因为该值是自动生成的。

# Insert product descriptions into the table.
# The description_embedding column is automatically updated.
INSERT INTO mydataset.products (name, description) VALUES
  ("Lounger chair", "A comfortable chair for relaxing in."),
  ("Super slingers", "An exciting board game for the whole family."),
  ("Encyclopedia set", "A collection of informational books.");

您可以选择在表上创建向量索引，以加快搜索速度。矢量索引需要三行以上的数据，因此以下查询假设您已插入额外的数据。每次插入数据时，系统都会自动更新 description_embedding 列。

CREATE VECTOR INDEX my_index
ON mydataset.products(description_embedding)
OPTIONS(index_type = 'IVF');

最后，您可以使用 AI.SEARCH 函数对产品进行语义搜索，查找好玩的玩具：

# Search for products that are fun to play with.
SELECT base.name, base.description, distance
FROM AI.SEARCH(TABLE mydataset.products, 'description', "A really fun toy");

/*------------------+----------------------------------------------+----------------------+
 | name             | description                                  | distance             |
 +------------------+----------------------------------------------+----------------------+
 | Super slingers   | An exciting board game for the whole family. | 0.80954913893618929  |
 | Lounger chair    | A comfortable chair for relaxing in.         | 0.938933930620146    |
 | Encyclopedia set | A collection of informational books.         | 1.1119297739353384   |
 +------------------+----------------------------------------------+----------------------*/

获取有关自动生成的嵌入列的信息

如需验证某列是否为自动生成的嵌入列，请查询 INFORMATION_SCHEMA.COLUMNS 视图。

以下查询会显示所有自动生成的嵌入列的相关信息：

SELECT *
FROM PROJECT_ID.DATASET_ID.INFORMATION_SCHEMA.COLUMNS
WHERE is_generated = 'ALWAYS';

generation_expression 字段显示了对 AI.EMBED 函数的调用，该函数用于在列上生成嵌入。

使用您自己的预留

默认情况下，BigQuery 使用按需付费型槽来处理维护生成的嵌入列所需的处理。为确保性能可预测且一致，您可以选择创建预留并将 job_type 设置为 BACKGROUND。如果存在后台预留，BigQuery 会使用该预留来维护生成的嵌入列。

问题排查

生成的嵌入列包含两个字段：result 和 status。如果 BigQuery 尝试为表中的特定行生成嵌入内容时发生错误，则 result 字段为 NULL，而 status 字段会描述该错误。例如，如果源列为 NULL，则 result 嵌入也是 NULL，状态为 NULL value is not supported for embedding generation。

更严重的错误可能会导致嵌入生成停滞。在这种情况下，您可以查询后台作业的 INFORMATION_SCHEMA.JOBS 视图，并查看 error_result 字段中的信息。后台嵌入作业的作业 ID 以 gc_ 为前缀。例如，以下查询会提取所有错误结果不是 NULL 的后台作业：

SELECT * FROM `region-REGION.INFORMATION_SCHEMA.JOBS` j
WHERE EXISTS (
  SELECT 1
  FROM unnest(j.referenced_tables) t
  WHERE
    j.project_id = 'PROJECT_ID'
    AND t.dataset_id = 'DATASET_ID'
    AND t.table_id = 'TABLE'
)
AND starts_with(job_id, 'gc')
AND error_result IS NOT NULL
ORDER BY j.creation_time DESC;

跟踪费用

自动生成嵌入会向 Vertex AI 发送请求，这可能会产生费用。如需跟踪后台嵌入作业产生的 Vertex AI 费用，请按照以下步骤操作：

  1. 在 Cloud Billing 中查看结算报告。

  2. 使用过滤条件优化结果。

    对于服务，请选择 Vertex AI。

  3. 如需查看特定作业的费用，请按标签过滤。

    将键设置为 bigquery_ml_job，并将值设置为嵌入作业的作业 ID。所有后台嵌入作业都有 gc_ 前缀。

某些费用最长可能需要 24 小时才会显示在 Cloud Billing 中。

限制

  • 每个表最多支持一个自动生成的嵌入列。
  • 当您使用 Google Cloud 控制台、bq show 命令或 INFORMATION_SCHEMA.TABLES 视图的 ddl 字段查看表架构时，系统不会指示列是否为自动生成。
  • 您无法使用 ALTER TABLE ADD COLUMN 向现有表添加生成的嵌入列。
  • 如果您创建具有生成的嵌入列的表的副本、克隆或快照，则只会复制数据。生成配置不适用于新表，并且对新表的源列进行更新不会生成新的嵌入。
  • 如果您从快照恢复之前已启用自主嵌入生成功能的表，则嵌入生成配置不会恢复。
  • 您只能使用 SQL 创建生成的嵌入列。您无法使用 bq mk 或 bq update 命令创建生成的嵌入列。
  • 所生成列的源列必须为 STRING 列。

  • 创建生成的嵌入列后，需要遵循以下限制：

    • 您无法删除或重命名源列，但仍可以删除或重命名生成的嵌入列。如果您舍弃嵌入列，则可以舍弃或重命名源列。
    • 您无法更改源列或生成的嵌入列的数据类型。

  • 您无法为自动生成的嵌入列指定默认值。

  • 您无法使用以下方法直接写入生成的嵌入列：

    • DML
    • 流式写入
    • bq insert
    • bq copy -a

  • 具有生成的嵌入列的表不支持任何列级安全政策，例如政策标记。

  • 当您调用搜索函数（例如 VECTOR_SEARCH 或 AI.SEARCH）时，系统会在搜索期间跳过基表中缺少嵌入的行。

  • 您无法在已启用自主嵌入生成功能的表上创建分区向量索引。

  • 如果您在自动生成的嵌入列上创建向量索引，则在至少 80% 的行生成嵌入后，系统会开始训练索引。您可以使用以下查询来检查表中有多少百分比的嵌入已生成：

    SELECT
  COUNTIF(description_embedding IS NOT NULL
  AND description_embedding.status = '') * 100.0 / COUNT(*) AS percent
FROM PROJECT_ID.DATASET_ID.TABLE;

后续步骤