使用 AI.GENERATE_TABLE 函数生成结构化数据

本文档介绍了如何使用 Gemini Pro 1.5、Gemini Flash 1.5 或 Gemini Flash 2.0 模型生成结构化数据，然后使用 SQL 架构设置模型的回答格式。

为此，请完成以下任务：

• 创建表示托管式 Vertex AI Gemini 1.5 或 2.0 模型的 BigQuery ML 远程模型。
• 将模型与 AI.GENERATE_TABLE 函数搭配使用，根据标准表中的数据生成结构化数据。

所需权限

• 如需创建连接，您需要拥有以下 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

准备工作

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

   Go to project selector

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

3. Enable the BigQuery, BigQuery Connection, and Vertex AI APIs.

   Enable the APIs

创建连接

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

向服务账号授予访问权限

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

如果您打算在创建远程模型时将端点指定为网址（例如 endpoint = 'https://us-central1-aiplatform.googleapis.com/v1/projects/myproject/locations/us-central1/publishers/google/models/gemini-1.5-flash'），请在网址中指定的项目中授予此角色。

如果您打算在创建远程模型时使用模型名称指定端点（例如 endpoint = 'gemini-1.5-flash'），请在打算创建远程模型的项目中授予此角色。

在其他项目中授予此角色会导致错误 bqcx-1234567890-xxxx@gcp-sa-bigquery-condel.iam.gserviceaccount.com does not have the permission to access resource。

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

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

创建 BigQuery 机器学习远程模型

1. 在 Google Cloud 控制台中，前往 BigQuery 页面。

   转到 BigQuery

2. 使用 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：要使用的 Gemini 模型的名称。支持以下模型：
     • gemini-2.0-flash-001
     • gemini-1.5-flash-001
     • gemini-1.5-flash-002
     • gemini-1.5-pro-001
     • gemini-1.5-pro-002
     如需了解详情，请参阅 ENDPOINT。

生成结构化数据

将 AI.GENERATE_TABLE 函数与远程模型结合使用并使用表列中的提示数据来生成结构化数据：

SELECT *
FROM AI.GENERATE_TABLE(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  [TABLE `PROJECT_ID.DATASET_ID.TABLE_NAME` / (PROMPT_QUERY)],
  STRUCT(TOKENS AS max_output_tokens, TEMPERATURE AS temperature,
  TOP_P AS top_p, STOP_SEQUENCES AS stop_sequences,
  SAFETY_SETTINGS AS safety_settings,
  OUTPUT_SCHEMA AS output_schema)
);

请替换以下内容：

• PROJECT_ID：您的项目 ID。
• DATASET_ID：包含该模型的数据集的 ID。
• MODEL_NAME：模型的名称。
• TABLE_NAME：包含提示的表的名称。该表必须具有名为 prompt 的列，或者您可以通过别名来使用其他名称的列。
• PROMPT_QUERY：用于生成提示数据的 GoogleSQL 查询。提示值本身可以从列中提取，也可以将其指定为包含任意数量的字符串和列名称子字段的结构体值。例如：SELECT ('Analyze the sentiment in ', feedback_column, 'using the following categories: positive, negative, neutral') AS prompt。
• TOKENS：一个 INT64 值，用于设置回答中可生成的词元数上限。此值必须在范围 [1,8192] 内。指定较低的值可获得较短的回答，指定较高的值可获得较长的回答。默认值为 128。
• TEMPERATURE：[0.0,2.0] 范围内的一个 FLOAT64 值，用于控制词元选择的随机程度。默认值为 1.0。

  较低的 temperature 值适合需要更具确定性和较少开放性或创造性回答的提示，而较高的 temperature 值可以产生更具多样性或创造性的结果。temperature 的值为 0 表示确定性，即始终选择概率最高的回答。

• TOP_P：范围 [0.0,1.0] 内的一个 FLOAT64 值，用于确定所选词元的概率。指定较低的值可获得随机程度较低的回答，指定较高的值可获得随机程度较高的回答。默认值为 0.95。
• STOP_SEQUENCES：一个 ARRAY<STRING> 值，如果模型的回答中包含指定的字符串，则用于移除这些字符串。字符串需要完全匹配，包括大小写。默认值为空数组。
• SAFETY_SETTINGS：一个 ARRAY<STRUCT<STRING AS category, STRING AS threshold>> 值，用于配置内容安全阈值以过滤回答。结构体中的第一个元素指定危害类别，结构体中的第二个元素指定相应的屏蔽阈值。模型会过滤掉违反这些设置的内容。您只能指定每个类别一次。例如，您不能同时指定 STRUCT('HARM_CATEGORY_DANGEROUS_CONTENT' AS category, 'BLOCK_MEDIUM_AND_ABOVE' AS threshold) 和 STRUCT('HARM_CATEGORY_DANGEROUS_CONTENT' AS category, 'BLOCK_ONLY_HIGH' AS threshold)。如果给定类别没有安全设置，则系统会使用 BLOCK_MEDIUM_AND_ABOVE 安全设置。

  支持的类别如下：

  • HARM_CATEGORY_HATE_SPEECH
  • HARM_CATEGORY_DANGEROUS_CONTENT
  • HARM_CATEGORY_HARASSMENT
  • HARM_CATEGORY_SEXUALLY_EXPLICIT

  支持的阈值如下：

  • BLOCK_NONE（受限）
  • BLOCK_LOW_AND_ABOVE
  • BLOCK_MEDIUM_AND_ABOVE（默认）
  • BLOCK_ONLY_HIGH
  • HARM_BLOCK_THRESHOLD_UNSPECIFIED

  如需了解详情，请参阅危害类别和如何配置内容过滤器。

• OUTPUT_SCHEMA：一个 STRING 值，用于指定模型回答的格式。output_schema 值必须是 SQL 架构定义，类似于 CREATE TABLE 语句中使用的定义。 支持以下数据类型：
  • INT64
  • FLOAT64
  • BOOL
  • STRING
  • ARRAY
  • STRUCT

  对于 Gemini 1.5 模型，仅当您确定返回值不会是舍入值时，才应指定 FLOAT64 数据类型。 这些模型有时可能会针对舍入数字返回 INT64 值，而不是 FLOAT64 值，例如 2 而不是 2.0，这可能会导致查询中出现解析错误。

  使用 output_schema 参数根据表中的提示生成结构化数据时，请务必了解提示数据，以便指定适当的架构。

  例如，假设您要分析包含以下字段的表格中的电影评论内容：

  • movie_id
  • review
  • 提示

  然后，您可以通过运行类似以下的查询来创建提示文本：

  UPDATE mydataset.movie_review
  SET prompt = CONCAT('Extract the key words and key sentiment from the text below: ', review)
  WHERE review IS NOT NULL;

  您可以指定与 "keywords ARRAY<STRING>, sentiment STRING" AS output_schema 类似的 output_schema 值。

示例

以下示例展示了一个请求，该请求会从表中获取提示数据，并提供 SQL 架构来设置模型响应的格式：

SELECT
*
FROM
AI.GENERATE_TABLE( MODEL `mydataset.gemini_model`,
  TABLE `mydataset.mytable`,
  STRUCT("keywords ARRAY<STRING>, sentiment STRING" AS output_schema));

以下示例展示了一个请求，该请求会从查询中获取提示数据，并提供 SQL 架构来设置模型响应的格式：

SELECT *
FROM
  AI.GENERATE_TABLE(
    MODEL `mydataset.gemini_model`,
    (
      SELECT
        'John Smith is a 20-year old single man living at 1234 NW 45th St, Kirkland WA, 98033. He has two phone numbers 123-123-1234, and 234-234-2345. He is 200.5 pounds.'
          AS prompt
    ),
    STRUCT("address STRUCT<street_address STRING, city STRING, state STRING, zip_code STRING>, age INT64, is_married BOOL, name STRING, phone_number ARRAY<STRING>, weight_in_pounds FLOAT64"
        AS output_schema, 8192 AS max_output_tokens));