Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

使用数据调优模型

本文档介绍了如何创建引用 Gemini Enterprise Agent Platform 模型的 BigQuery ML 远程模型，然后配置该模型以执行监督式调优。Agent Platform 模型必须是以下模型之一：

gemini-2.5-pro
gemini-2.5-flash-lite
gemini-2.0-flash-001
gemini-2.0-flash-lite-001

创建远程模型后，您可以使用 ML.EVALUATE 函数来评估模型并确认模型的性能是否适合您的应用场景。然后，您可以将该模型与 AI.GENERATE_TEXT 函数结合使用，以分析 BigQuery 表中的文本。

如需了解详情，请参阅 Vertex AI Gemini API 模型监督式调优。

所需的角色

如需创建和评估调优的模型，您需要以下 Identity and Access Management (IAM) 角色：

创建和使用 BigQuery 数据集、表和模型：项目的 BigQuery Data Editor (roles/bigquery.dataEditor)。
创建、委托和使用 BigQuery 连接：项目的 BigQuery Connections Admin (roles/bigquery.connectionsAdmin)。

如果您尚未配置默认连接，则可以在运行 CREATE MODEL 语句时创建并设置一个连接。为此，您必须拥有项目的 BigQuery Admin (roles/bigquery.admin) 角色。如需了解详情，请参阅配置默认连接。
为连接的服务账号授予权限：包含 Gemini Enterprise Agent Platform 端点的项目的 Project IAM Admin (roles/resourcemanager.projectIamAdmin)。这是通过将模型名称指定为端点而创建的远程模型的当前项目。这是通过将网址指定为端点而创建的远程模型的网址中标识的项目。
创建 BigQuery 作业：项目的 BigQuery Job User (roles/bigquery.jobUser)。

这些预定义角色包含执行本文档中的任务所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

创建数据集：bigquery.datasets.create
创建、委托和使用连接：bigquery.connections.*
设置服务账号权限：resourcemanager.projects.getIamPolicy 和 resourcemanager.projects.setIamPolicy
创建模型并运行推断：
- bigquery.jobs.create
- bigquery.models.create
- bigquery.models.getData
- bigquery.models.updateData
- bigquery.models.updateMetadata

您也可以使用自定义角色或其他预定义角色来获取这些权限。

准备工作

在 Google Cloud 控制台的项目选择器页面上，选择或创建 Google Cloud 项目。
选择或创建项目所需的角色
- 选择项目：选择项目不需要特定的 IAM 角色，您可以选择已获授角色的任何项目。
- 创建项目：如需创建项目，您需要拥有 Project Creator 角色 (roles/resourcemanager.projectCreator)，该角色包含 resourcemanager.projects.create 权限。了解如何授予角色。
注意：如果您不打算保留在此过程中创建的资源，请创建新的项目，而不要选择现有的项目。完成本教程介绍的步骤后，您可以删除所创建的项目，并移除与该项目关联的所有资源。

转到“项目选择器”
验证是否已为您的 Google Cloud 项目启用结算功能。
启用 BigQuery、BigQuery Connection、Agent Platform API 和 Compute Engine API。
启用 API 所需的角色
如需启用 API，您需要拥有 serviceusage.services.enable 权限。如果您创建了项目，则可能已经通过 Owner 角色 (roles/owner) 获得了此权限。否则，您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获得此权限。了解如何授予角色。
启用 API

创建数据集

创建 BigQuery 数据集以包含您的资源：

控制台

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

转到 BigQuery
在左侧窗格中，点击 探索器：

如果您没有看到左侧窗格，请点击 展开左侧窗格以打开该窗格。
在探索器窗格中，点击您的项目名称。
点击 查看操作 > 创建数据集。
在 创建数据集 页面上，执行以下操作：
1. 在数据集 ID 中，输入数据集的名称。
2. 在位置类型部分，选择区域或多区域。
  - 如果您选择了区域，请从区域列表中选择一个位置。
  - 如果您选择了多区域，请从多区域列表中选择美国或欧洲。
3. 点击创建数据集。

bq

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

创建连接

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

如果您已配置默认连接，或者您具有 BigQuery Admin 角色，则可以跳过此步骤。

从下列选项中选择一项：

控制台

前往 BigQuery 页面。

转到 BigQuery
在左侧窗格中，点击 探索器：

如果您没有看到左侧窗格，请点击 展开左侧窗格以打开该窗格。
在探索器窗格中，展开您的项目名称，然后点击连接。
在连接页面上，点击创建连接。
对于连接类型，请选择 Vertex AI 远程模型、远程函数、BigLake 和 Spanner（Cloud 资源）。
在连接 ID 字段中，输入连接的名称。
对于位置类型，为连接选择一个位置。连接应与数据集等其他资源位于同一位置。
点击创建连接。
点击转到连接。
在连接信息窗格中，复制服务账号 ID 以在后续步骤中使用。

SQL

使用 CREATE CONNECTION 语句：

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

转到 BigQuery
在查询编辑器中，输入以下语句：
```
CREATE CONNECTION [IF NOT EXISTS] `CONNECTION_NAME`
OPTIONS (
  connection_type = "CLOUD_RESOURCE",
  friendly_name = "FRIENDLY_NAME",
  description = "DESCRIPTION"
  );
```
请替换以下内容：
- CONNECTION_NAME：连接的名称，格式为 PROJECT_ID.LOCATION.CONNECTION_ID、LOCATION.CONNECTION_ID 或 CONNECTION_ID。如果省略项目或位置，则系统会根据运行语句的项目和位置推断出相应信息。
- FRIENDLY_NAME（可选）：连接的描述性名称。
- DESCRIPTION（可选）：连接的说明。
点击运行。

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

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"}

Python

试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 Python 设置说明进行操作。如需了解详情，请参阅 BigQuery Python API 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭证。如需了解详情，请参阅为客户端库设置身份验证。

import google.api_core.exceptions
from google.cloud import bigquery_connection_v1

client = bigquery_connection_v1.ConnectionServiceClient()


def create_connection(
    project_id: str,
    location: str,
    connection_id: str,
):
    """Creates a BigQuery connection to a Cloud Resource.

    Cloud Resource connection creates a service account which can then be
    granted access to other Google Cloud resources for federated queries.

    Args:
        project_id: The Google Cloud project ID.
        location: The location of the connection (for example, "us-central1").
        connection_id: The ID of the connection to create.
    """

    parent = client.common_location_path(project_id, location)

    connection = bigquery_connection_v1.Connection(
        friendly_name="Example Connection",
        description="A sample connection for a Cloud Resource.",
        cloud_resource=bigquery_connection_v1.CloudResourceProperties(),
    )

    try:
        created_connection = client.create_connection(
            parent=parent, connection_id=connection_id, connection=connection
        )
        print(f"Successfully created connection: {created_connection.name}")
        print(f"Friendly name: {created_connection.friendly_name}")
        print(
            f"Service Account: {created_connection.cloud_resource.service_account_id}"
        )

    except google.api_core.exceptions.AlreadyExists:
        print(f"Connection with ID '{connection_id}' already exists.")
        print("Please use a different connection ID.")
    except Exception as e:
        print(f"An unexpected error occurred while creating the connection: {e}")

Node.js

试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 Node.js 设置说明进行操作。如需了解详情，请参阅 BigQuery Node.js API 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭证。如需了解详情，请参阅为客户端库设置身份验证。

const {ConnectionServiceClient} =
  require('@google-cloud/bigquery-connection').v1;
const {status} = require('@grpc/grpc-js');

const client = new ConnectionServiceClient();

/**
 * Creates a new BigQuery connection to a Cloud Resource.
 *
 * A Cloud Resource connection creates a service account that can be granted access
 * to other Google Cloud resources.
 *
 * @param {string} projectId The Google Cloud project ID. for example, 'example-project-id'
 * @param {string} location The location of the project to create the connection in. for example, 'us-central1'
 * @param {string} connectionId The ID of the connection to create. for example, 'example-connection-id'
 */
async function createConnection(projectId, location, connectionId) {
  const parent = client.locationPath(projectId, location);

  const connection = {
    friendlyName: 'Example Connection',
    description: 'A sample connection for a Cloud Resource',
    // The service account for this cloudResource will be created by the API.
    // Its ID will be available in the response.
    cloudResource: {},
  };

  const request = {
    parent,
    connectionId,
    connection,
  };

  try {
    const [response] = await client.createConnection(request);

    console.log(`Successfully created connection: ${response.name}`);
    console.log(`Friendly name: ${response.friendlyName}`);

    console.log(`Service Account: ${response.cloudResource.serviceAccountId}`);
  } catch (err) {
    if (err.code === status.ALREADY_EXISTS) {
      console.log(`Connection '${connectionId}' already exists.`);
    } else {
      console.error(`Error creating connection: ${err.message}`);
    }
  }
}

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 Service Agent 角色。

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

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

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

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

控制台

前往 IAM 和管理页面。

转到“IAM 和管理”
点击 授予访问权限。
在新的主账号部分，输入您之前复制的服务账号 ID。
点击选择角色
在过滤条件中，输入 Vertex AI Service Agent，然后选择该角色。
点击保存。

gcloud

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

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

替换以下内容：

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

与您的连接关联的服务账号是 BigQuery 连接委托服务代理的实例，因此可以为其分配服务代理角色。

创建使用监督式调优的模型

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

转到 BigQuery
在查询编辑器中，运行以下查询以创建远程模型：
```
CREATE OR REPLACE MODEL
`PROJECT_ID.DATASET_ID.MODEL_NAME`
REMOTE WITH CONNECTION {DEFAULT | `PROJECT_ID.REGION.CONNECTION_ID`}
OPTIONS (
  ENDPOINT = 'ENDPOINT',
  MAX_ITERATIONS = MAX_ITERATIONS,
  LEARNING_RATE_MULTIPLIER = LEARNING_RATE_MULTIPLIER,
  DATA_SPLIT_METHOD = 'DATA_SPLIT_METHOD',
  DATA_SPLIT_EVAL_FRACTION = DATA_SPLIT_EVAL_FRACTION,
  DATA_SPLIT_COL = 'DATA_SPLIT_COL',
  EVALUATION_TASK = 'EVALUATION_TASK',
  PROMPT_COL = 'INPUT_PROMPT_COL',
  INPUT_LABEL_COLS = INPUT_LABEL_COLS)
AS SELECT PROMPT_COLUMN, LABEL_COLUMN
FROM `TABLE_PROJECT_ID.TABLE_DATASET.TABLE_NAME`;
```
替换以下内容：
- PROJECT_ID：要在其中创建模型的项目的项目 ID。
- DATASET_ID：包含模型的数据集的 ID。此数据集必须位于受支持的 Gemini Enterprise Agent Platform 区域。
- MODEL_NAME：模型的名称。
- REGION：连接使用的区域。
- CONNECTION_ID：BigQuery 连接的 ID。此连接必须与您使用的数据集位于同一位置。
  当您在 Google Cloud 控制台中查看连接详情时，它是连接 ID 中显示的完全限定连接 ID 的最后一部分中的值，例如 projects/myproject/locations/connection_location/connections/myconnection。
- ENDPOINT：STRING 值，指定要使用的模型的名称。
- MAX_ITERATIONS：INT64 值，指定为进行监督式调优而运行的步数。MAX_ITERATIONS 值必须在 1 到 ∞ 之间。
  Gemini 模型使用周期而非步骤进行训练，因此 BigQuery ML 会将 MAX_ITERATIONS 值转换为周期。MAX_ITERATIONS 的默认值是输入数据中的行数，等同于一个周期。如需使用多个周期，请指定训练数据中行数的倍数。例如，如果您有 100 行输入数据，并且想要使用两个周期，请将参数值指定为 200。如果您提供的值不是输入数据中行数的倍数，BigQuery ML 会向上舍入到最接近的周期。例如，如果您有 100 行输入数据，并且将 MAX_ITERATIONS 值指定为 101，则会执行两个周期的训练。
  
  如需详细了解用于调优 Gemini 模型的参数，请参阅创建调优作业。
- DATA_SPLIT_METHOD：STRING 值，指定将输入数据拆分为训练集和评估集的方法。有效选项如下：
  - AUTO_SPLIT：BigQuery ML 会自动拆分数据。数据的拆分方式因输入表中的行数而异。此设置为默认值。
  - RANDOM：数据在拆分为各个集之前会随机化。如需自定义数据拆分，您可以将此选项与 DATA_SPLIT_EVAL_FRACTION 选项结合使用。
  - CUSTOM：使用 DATA_SPLIT_COL 选项中提供的列拆分数据。DATA_SPLIT_COL 值必须是 BOOL 类型的列的名称。值为 TRUE 或 NULL 的行用作评估数据，值为 FALSE 的行用作训练数据。
  - SEQ：使用 DATA_SPLIT_COL 选项中提供的列拆分数据。DATA_SPLIT_COL 值必须是以下任一类型的列的名称：
    - NUMERIC
    - BIGNUMERIC
    - STRING
    - TIMESTAMP
    数据根据指定列从小到大排序。
    
    前 n 行用作评估数据，其中 n 是为 DATA_SPLIT_EVAL_FRACTION 指定的值。其余行用作训练数据。
  - NO_SPLIT：不拆分数据；所有输入数据都用作训练数据。
  如需详细了解这些数据拆分选项，请参阅 DATA_SPLIT_METHOD。
- DATA_SPLIT_EVAL_FRACTION：FLOAT64 值，指定在执行监督式调优时用作评估数据的数据比例。必须是 [0, 1.0] 范围内的值。默认值为 0.2。
  当您指定 RANDOM 或 SEQ 作为 DATA_SPLIT_METHOD 选项的值时，请使用此选项。如需自定义数据拆分，您可以将 DATA_SPLIT_METHOD 选项与 DATA_SPLIT_EVAL_FRACTION 选项结合使用。
- DATA_SPLIT_COL：STRING 值，指定用于将输入数据分类到训练集或评估集中的列的名称。在指定 CUSTOM 或 SEQ 作为 DATA_SPLIT_METHOD 选项的值时使用。
- EVALUATION_TASK：STRING 值，指定您要对模型进行调优以执行的任务类型。有效选项包括：
  - TEXT_GENERATION
  - CLASSIFICATION
  - SUMMARIZATION
  - QUESTION_ANSWERING
  - UNSPECIFIED
  默认值为 UNSPECIFIED。
- INPUT_PROMPT_COL：STRING 值，包含执行监督式调优时使用的训练数据表中提示列的名称。默认值为 prompt。
- INPUT_LABEL_COLS：ARRAY<<STRING> 值，包含要在监督式调优中使用的训练数据表中标签列的名称。只能在数组中指定一个元素。默认值为空数组。这会使 label 成为 LABEL_COLUMN 参数的默认值。
- PROMPT_COLUMN：训练数据表中包含用于评估 LABEL_COLUMN 列中内容的提示的列。此列必须是 STRING 类型或转换为 STRING。如果您为 INPUT_PROMPT_COL 选项指定了值，则必须为 PROMPT_COLUMN 指定相同的值。否则，此值必须为 prompt。如果您的表没有 prompt 列，请使用别名指定现有表列。例如 AS SELECT hint AS prompt, label FROM mydataset.mytable。
- LABEL_COLUMN：训练数据表中包含用于训练模型的样本的列。此列必须是 STRING 类型或转换为 STRING。如果您为 INPUT_LABEL_COLS 选项指定了值，则必须为 LABEL_COLUMN 指定相同的值。否则，此值必须为 label。如果您的表没有 label 列，请使用别名指定现有表列。例如 AS SELECT prompt, feature AS label FROM mydataset.mytable。
- TABLE_PROJECT_ID：包含训练数据表的项目的项目 ID。
- TABLE_DATASET：包含训练数据表的数据集的名称。
- TABLE_NAME：包含用于训练模型的数据的表的名称。

评估调优后的模型

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

转到 BigQuery
在查询编辑器中，运行以下查询以评估调优后模型：
```
SELECT
*
FROM
ML.EVALUATE(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  TABLE `TABLE_PROJECT_ID.TABLE_DATASET.TABLE_NAME`,
  STRUCT('TASK_TYPE' AS task_type, TOKENS AS max_output_tokens,
    TEMPERATURE AS temperature, TOP_K AS top_k,
    TOP_P AS top_p));
```
替换以下内容：
- PROJECT_ID：包含该模型的项目的 ID。
- DATASET_ID：包含该模型的数据集的 ID。
- MODEL_NAME：模型的名称。
- TABLE_PROJECT_ID：包含评估数据表的项目的 ID。
- TABLE_DATASET：包含训练数据表的数据集的名称。
- TABLE_NAME：包含评估数据的表的名称。
  该表必须有一列的名称与模型训练期间提供的提示列名称相同。您可以在模型训练期间使用 prompt_col 选项来提供此值。如果未指定 prompt_col，系统会使用训练数据中名为 prompt 的列。如果没有名为 prompt 的列，则会返回错误。
  
  该表必须有一列的名称与模型训练期间提供的标签列名称相同。您可以在模型训练期间使用 input_label_cols 选项来提供此值。如果未指定 input_label_cols，系统会使用训练数据中名为 label 的列。如果没有名为 label 的列，则会返回错误。
- TASK_TYPE：一个 STRING 值，用于指定要为其评估模型的任务类型。有效选项包括：
  - TEXT_GENERATION
  - CLASSIFICATION
  - SUMMARIZATION
  - QUESTION_ANSWERING
  - UNSPECIFIED
- TOKENS：一个 INT64 值，用于设置回答中可生成的词元数上限。此值必须在范围 [1,1024] 内。指定较低的值可获得较短的回答，指定较高的值可获得较长的回答。默认值为 128。
- TEMPERATURE：[0.0,1.0] 范围内的一个 FLOAT64 值，用于控制词元选择中的随机程度。默认值为 0。
  较低的 temperature 值适合需要更具确定性和较少开放性或创造性响应的提示，而较高的 temperature 值可以产生更具多样性或创造性的结果。temperature 的值为 0 表示确定性，即始终选择概率最高的回答。
- TOP_K：[1,40] 范围内的一个 INT64 值，用于确定模型考虑选择的初始词元池。指定较低的值可获得随机程度较低的响应，指定较高的值可获得随机程度较高的响应。默认值为 40。
- TOP_P：[0.0,1.0] 范围内的 FLOAT64 值有助于确定选择了 TOP_K 确定的池中的哪些词元。指定较低的值可获得随机程度较低的响应，指定较高的值可获得随机程度较高的响应。默认值为 0.95。

生成文本

使用 AI.GENERATE_TEXT 函数生成文本：

提示列

使用表列提供提示来生成文本。

SELECT *
FROM AI.GENERATE_TEXT(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  TABLE PROJECT_ID.DATASET_ID.TABLE_NAME,
  STRUCT(TOKENS AS max_output_tokens, TEMPERATURE AS temperature,
  TOP_P AS top_p,
  STOP_SEQUENCES AS stop_sequences)
);

请替换以下内容：

PROJECT_ID：您的项目 ID。
DATASET_ID：包含该模型的数据集的 ID。
MODEL_NAME：模型的名称。
TABLE_NAME：包含提示的表的名称。此表必须有一列的名称与调优后的模型中的特征列的名称相同。在创建模型时，可以使用 PROMPT_COL 选项设置模型中的特征列名称。否则，模型中的特征列名称默认为 prompt，您也可以使用别名来使用其他名称的列。
TOKENS：一个 INT64 值，用于设置回答中可生成的词元数上限。此值必须在范围 [1,8192] 内。指定较低的值可获得较短的回答，指定较高的值可获得较长的回答。默认为 128。
TEMPERATURE：范围 [0.0,1.0] 内的一个 FLOAT64 值，用于控制 token 选择的随机程度。默认值为 0。
较低的 temperature 值适合需要更具确定性和较少开放性或创造性响应的提示，而较高的 temperature 值可以产生更具多样性或创造性的结果。temperature 的值为 0 表示确定性，即始终选择概率最高的回答。
TOP_P：范围 [0.0,1.0] 内的一个 FLOAT64 值，用于确定所选词元的概率。指定较低的值可获得随机程度较低的回答，指定较高的值可获得随机程度较高的回答。默认值为 0.95。
STOP_SEQUENCES：一个 ARRAY<STRING> 值，如果模型的回答中包含指定的字符串，则用于移除这些字符串。字符串需要完全匹配，包括大小写。默认值为空数组。
GROUND_WITH_GOOGLE_SEARCH：一个 BOOL 值，用于确定 Gemini Enterprise Agent Platform 模型在生成回答时是否使用依托 Google 搜索进行接地。通过建立依据，模型可以在生成回答时使用网络上的其他信息来生成更具体的真实模型回答。如果此字段设置为 True，结果中会包含一个额外的 grounding_result 列，其中提供了模型用于收集更多信息的来源。默认值为 FALSE。
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
如需了解详情，请参阅安全类别和阻塞阈值的定义。
REQUEST_TYPE：STRING 值，指定要发送到 Gemini 模型的推理请求的类型。请求类型决定了请求使用的配额。有效值如下：
- DEDICATED：AI.GENERATE_TEXT 函数仅使用预配吞吐量配额。如果预配吞吐量配额不可用，AI.GENERATE_TEXT 函数会返回错误 Provisioned throughput is not purchased or is not active。
- SHARED：即使您购买了预配吞吐量配额，AI.GENERATE_TEXT 函数也只会使用动态共享配额 (DSQ)。
- UNSPECIFIED：AI.GENERATE_TEXT 函数使用如下所示的配额：
  - 如果您尚未购买预配吞吐量配额，则 AI.GENERATE_TEXT 函数会使用 DSQ 配额。
  - 如果您购买了预配吞吐量配额，AI.GENERATE_TEXT 函数会优先使用预配吞吐量配额。如果请求超出预配吞吐量配额，溢出流量将使用 DSQ 配额。
默认值为 UNSPECIFIED。

如需了解详情，请参阅使用 Agent Platform 预配吞吐量。
MODEL_PARAMS：一个 JSON 格式的字符串字面量，用于向模型提供参数。该值必须符合 generateContent 请求正文格式。您可以为请求正文中的任何字段提供值，但 contents[] 字段除外。如果您设置了此字段，则不能在 AI.GENERATE_TEXT 函数的顶级结构实参中同时指定任何模型参数。您必须在 MODEL_PARAMS 字段中指定所有模型参数，或省略此字段并单独指定各个参数。

以下示例显示了具有以下特征的请求：

将 prompts 表的 prompt 列用于提示。
返回概率中等的简短回答。
分列返回生成的文本和安全属性。

SELECT *
FROM
  AI.GENERATE_TEXT(
    MODEL `mydataset.mymodel`,
    TABLE mydataset.prompts,
    STRUCT(
      0.4 AS temperature, 100 AS max_output_tokens, 0.5 AS top_p));

提示查询

使用查询提供提示来生成文本。

SELECT *
FROM AI.GENERATE_TEXT(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  (PROMPT_QUERY),
  STRUCT(TOKENS AS max_output_tokens, TEMPERATURE AS temperature,
  TOP_P AS top_p,
  STOP_SEQUENCES AS stop_sequences)
);

请替换以下内容：

PROJECT_ID：您的项目 ID。
DATASET_ID：包含该模型的数据集的 ID。
MODEL_NAME：模型的名称。
PROMPT_QUERY：提供提示数据的查询。
TOKENS：一个 INT64 值，用于设置回答中可生成的词元数上限。此值必须在范围 [1,8192] 内。指定较低的值可获得较短的回答，指定较高的值可获得较长的回答。默认为 128。
TEMPERATURE：范围 [0.0,1.0] 内的一个 FLOAT64 值，用于控制 token 选择的随机程度。默认值为 0。
较低的 temperature 值适合需要更具确定性和较少开放性或创造性响应的提示，而较高的 temperature 值可以产生更具多样性或创造性的结果。temperature 的值为 0 表示确定性，即始终选择概率最高的回答。
TOP_P：范围 [0.0,1.0] 内的一个 FLOAT64 值，用于确定所选词元的概率。指定较低的值可获得随机程度较低的回答，指定较高的值可获得随机程度较高的回答。默认值为 0.95。
STOP_SEQUENCES：一个 ARRAY<STRING> 值，如果模型的回答中包含指定的字符串，则用于移除这些字符串。字符串需要完全匹配，包括大小写。默认值为空数组。
GROUND_WITH_GOOGLE_SEARCH：一个 BOOL 值，用于确定 Gemini Enterprise Agent Platform 模型在生成回答时是否使用依托 Google 搜索进行接地。通过建立依据，模型可以在生成回答时使用网络上的其他信息来生成更具体的真实模型回答。如果此字段设置为 True，结果中会包含一个额外的 grounding_result 列，其中提供了模型用于收集更多信息的来源。默认值为 FALSE。
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
如需了解详情，请参阅安全类别和阻塞阈值的定义。
REQUEST_TYPE：STRING 值，指定要发送到 Gemini 模型的推理请求的类型。请求类型决定了请求使用的配额。有效值如下：
- DEDICATED：AI.GENERATE_TEXT 函数仅使用预配吞吐量配额。如果预配吞吐量配额不可用，AI.GENERATE_TEXT 函数会返回错误 Provisioned throughput is not purchased or is not active。
- SHARED：即使您购买了预配吞吐量配额，AI.GENERATE_TEXT 函数也只会使用动态共享配额 (DSQ)。
- UNSPECIFIED：AI.GENERATE_TEXT 函数使用如下所示的配额：
  - 如果您尚未购买预配吞吐量配额，则 AI.GENERATE_TEXT 函数会使用 DSQ 配额。
  - 如果您购买了预配吞吐量配额，AI.GENERATE_TEXT 函数会优先使用预配吞吐量配额。如果请求超出预配吞吐量配额，溢出流量将使用 DSQ 配额。
默认值为 UNSPECIFIED。

如需了解详情，请参阅使用 Agent Platform 预配吞吐量。
MODEL_PARAMS：一个 JSON 格式的字符串字面量，用于向模型提供参数。该值必须符合 generateContent 请求正文格式。您可以为请求正文中的任何字段提供值，但 contents[] 字段除外。如果您设置了此字段，则不能在 AI.GENERATE_TEXT 函数的顶级结构实参中同时指定任何模型参数。您必须在 MODEL_PARAMS 字段中指定所有模型参数，或省略此字段并单独指定各个参数。

示例 1

以下示例显示了具有以下特征的请求：

提示在 articles 表的 body 列中输入文本摘要。
返回中等长度且概率较高的回答。
分列返回生成的文本和安全属性。

SELECT *
FROM
  AI.GENERATE_TEXT(
    MODEL `mydataset.mymodel`,
    (
      SELECT CONCAT('Summarize this text', body) AS prompt
      FROM mydataset.articles
    ),
    STRUCT(
      0.2 AS temperature, 650 AS max_output_tokens, 0.2 AS top_p));

示例 2

以下示例显示了具有以下特征的请求：

通过将提供提示前缀的字符串与表列串联起来，使用查询创建提示数据。
返回概率中等的简短回答。
不在单独的列中返回生成的文本和安全属性。

SELECT *
FROM
  AI.GENERATE_TEXT(
    MODEL `mydataset.mytuned_model`,
    (
      SELECT CONCAT(question, 'Text:', description, 'Category') AS prompt
      FROM mydataset.input_table
    ),
    STRUCT(
      0.4 AS temperature, 100 AS max_output_tokens, 0.5 AS top_p));