更新模型元数据

本页面介绍如何更新 BigQuery ML 模型元数据。您可以通过以下方式更新模型元数据：

• 使用 Google Cloud 控制台。
• 在 bq 命令行工具中使用 bq update 命令。
• 直接调用或使用客户端库调用 models.patch API 方法。

您可以更新以下模型元数据：

• 说明：可使用Google Cloud 控制台、bq 命令行工具、API 或客户端库进行更新。
• 标签：可使用 Google Cloud 控制台、bq 命令行工具、API 或客户端库进行更新。
• 到期时间：可使用 bq 工具、API 或客户端库进行更新。

所需权限

如需更新模型元数据，您必须分配有数据集的 WRITER 角色，或者您必须分配有包含 bigquery.models.updateMetadata 权限的项目级 Identity and Access Management (IAM)。如果您拥有项目级的 bigquery.models.updateMetadata 权限，则可以更新项目内任何数据集中模型的元数据。以下预定义的项目级 IAM 角色具有 bigquery.models.updateMetadata 权限：

• bigquery.dataEditor
• bigquery.dataOwner
• bigquery.admin

如需详细了解 BigQuery ML 中的 IAM 角色和权限，请参阅访问权限控制。

更新模型的说明

模型的说明是用于识别模型的文本字符串。

要更新模型的说明，请执行以下操作：

控制台

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

   转到 BigQuery 页面

2. 在探索器窗格中，展开您的项目，然后展开数据集。

3. 展开数据集中的 Models 文件夹，然后点击模型名称以选择该模型。

4. 点击详情标签页。

5. 如需更新模型的说明，请点击修改图标 。

6. 在修改详细信息对话框中，更新说明，然后点击保存。

bq

要更新模型的说明，请发出带有 --model 或 -m 标志和 --description 标志的 bq update 命令。

如果您要在非默认项目中更新模型，请按以下格式将相应项目 ID 添加到数据集内：[PROJECT_ID]:[DATASET]。

bq update --model --description "[STRING]" PROJECT_ID:DATASET.MODEL

替换以下内容：

• STRING 是由英文引号引起来的文本字符串，用于对模型进行说明。
• PROJECT_ID 是您的项目 ID。
• DATASET 是数据集的名称。
• MODEL 是模型的名称。

命令输出如下所示：

Model 'myproject.mydataset.mymodel' successfully updated.

您可以通过发出 bq show 命令来确认更改。如需了解详情，请参阅获取模型元数据。

示例：

输入以下命令可更新默认项目内 mydataset 中 mymodel 的说明。

bq update --model --description "My updated description" \
mydataset.mymodel

输入以下命令可更新 myotherproject 内 mydataset 中 mymodel 的说明。

bq update --model --description "My updated description" \
myotherproject:mydataset.mymodel

API

要使用 API 更新模型的说明，请调用 models.patch 方法并提供 projectId、datasetId 和 modelId。如需修改说明，请添加或更新模型资源的“description”属性。

Go

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

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

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// updateModelDescription demonstrates fetching BigQuery ML model metadata and updating the
// Description metadata.
func updateModelDescription(projectID, datasetID, modelID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// modelID := "mymodel"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %w", err)
	}
	defer client.Close()

	model := client.Dataset(datasetID).Model(modelID)
	oldMeta, err := model.Metadata(ctx)
	if err != nil {
		return fmt.Errorf("couldn't retrieve model metadata: %w", err)
	}
	update := bigquery.ModelMetadataToUpdate{
		Description: "This model was modified from a Go program",
	}
	if _, err = model.Update(ctx, update, oldMeta.ETag); err != nil {
		return fmt.Errorf("couldn't update model: %w", err)
	}
	return nil
}

Java

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

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

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Model;
import com.google.cloud.bigquery.ModelId;

// Sample to update description on a model
public class UpdateModelDescription {

  public static void runUpdateModelDescription() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String modelName = "MY_MODEL_NAME";
    String newDescription = "A really great model.";
    updateModelDescription(datasetName, modelName, newDescription);
  }

  public static void updateModelDescription(
      String datasetName, String modelName, String newDescription) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      Model model = bigquery.getModel(ModelId.of(datasetName, modelName));
      bigquery.update(model.toBuilder().setDescription(newDescription).build());
      System.out.println("Model description updated successfully to " + newDescription);
    } catch (BigQueryException e) {
      System.out.println("Model description was not updated \n" + e.toString());
    }
  }
}

Node.js

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

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

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function updateModel() {
  // Updates a model's metadata.

  /**
   * TODO(developer): Uncomment the following lines before running the sample
   */
  // const datasetId = "my_dataset";
  // const modelId = "my__model";

  const metadata = {
    description: 'A really great model.',
  };

  const dataset = bigquery.dataset(datasetId);
  const [apiResponse] = await dataset.model(modelId).setMetadata(metadata);
  const newDescription = apiResponse.description;

  console.log(`${modelId} description: ${newDescription}`);
}

Python

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

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

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set model_id to the ID of the model to fetch.
# model_id = 'your-project.your_dataset.your_model'

model = client.get_model(model_id)  # Make an API request.
model.description = "This model was modified from a Python program."
model = client.update_model(model, ["description"])  # Make an API request.

full_model_id = "{}.{}.{}".format(model.project, model.dataset_id, model.model_id)
print(
    "Updated model '{}' with description '{}'.".format(
        full_model_id, model.description
    )
)

更新模型的标签

标签是可以附加到资源的键值对。创建 BigQuery ML 资源时，并不是必须要添加标签。如需了解详情，请参阅添加和使用标签。

要更新模型的标签，请执行以下操作：

控制台

1. 在探索器窗格中，展开您的项目，然后展开数据集。

2. 展开数据集中的 Models 文件夹，然后点击模型名称以选择该模型。

3. 点击详情标签页。

4. 如需更新模型的标签，请点击修改图标 。

5. 在修改详细信息对话框中，添加、删除或修改标签，然后点击保存。

bq

要更新模型的标签，请发出带有 --model 或 -m 标志和 --set_label 标志的 bq update 命令。重复使用 --set_label 标志可添加或更新多个标签。

如果您要在非默认项目中更新模型，请按以下格式将相应项目 ID 添加到数据集内：[PROJECT_ID]:[DATASET]。

bq update --model --set_label KEY:VALUE \
PROJECT_ID:DATASET.MODEL

替换以下内容：

• KEY:VALUE 与要添加或更新的标签的键值对相对应。如果您指定与现有标签相同的键，则系统会更新现有标签的值。键必须是唯一的。
• PROJECT_ID 是您的项目 ID。
• DATASET 是数据集的名称。
• MODEL 是模型的名称。

命令输出如下所示。

Model 'myproject.mydataset.mymodel' successfully updated.

您可以通过发出 bq show 命令来确认更改。如需了解详情，请参阅获取模型元数据。

示例：

要更新 mymodel 的 department 标签，请输入 bq update 命令并将 department 指定为标签键。例如，要将 department:shipping 标签更新为 department:logistics，请输入以下命令。mydataset 在 myotherproject 中，不在默认项目中。

bq update --model --set_label department:logistics \
myotherproject:mydataset.mymodel

API

要使用 API 更新模型的标签，请调用 models.patch 方法并提供 projectId、datasetId 和 modelId。要修改标签，请添加或更新模型资源的“labels”属性。

更新模型的到期时间

模型的到期时间是指示何时删除模型的时间戳值。您可以在使用 CLI、API 或客户端库创建模型时设置模型的到期时间。您还可以在模型创建后设置或更新模型的到期时间。模型的到期时间通常称为“存留时间”或 TTL。

如果未设置模型的到期时间，则模型永不过期，您必须手动删除模型。

注意 ： Google Cloud 控制台不支持设置或更新模型的到期时间。

根据该值的设置位置，到期时间值的表示方式有所不同。请根据自己所需的细化程度选择适当的方法：

• 在命令行工具中，到期时间以自当前世界协调时间 (UTC) 起计的秒数表示。在命令行上指定到期时间时，系统会将以秒为单位的整数值添加到当前的 UTC 时间戳。
• 在 API 中，到期时间以自 Epoch 时间起计的毫秒数表示。如果指定的到期时间值小于当前时间戳，则模型会立即过期。

要更新模型的到期时间，请执行以下操作：

控制台

Google Cloud 控制台不支持设置或更新模型的到期时间。

bq

要更新模型的到期时间，请发出带有 --model 或 -m 标志和 --expiration 标志的 bq update 命令。

如果您要在非默认项目中更新模型，请按以下格式将相应项目 ID 添加到数据集内：[PROJECT_ID]:[DATASET]。

bq update --model --expiration INTEGER \
PROJECT_ID:DATASET.MODEL

替换以下内容：

• INTEGER 是模型的生命周期（以秒为单位）。最小值为 3600 秒（1 小时）。到期时间以当前 UTC 时间加上该整数值为准。
• PROJECT_ID 是您的项目 ID。
• DATASET 是数据集的名称。
• MODEL 是模型的名称。

命令输出如下所示。

Model 'myproject.mydataset.mymodel' successfully updated.

您可以通过发出 bq show 命令来确认更改。如需了解详情，请参阅获取模型元数据。

示例：

输入以下命令可将 mydataset 中 mymodel 的到期时间更新为 5 天（432000 秒）。mydataset 属于默认项目。

bq update --model --expiration 432000 mydataset.mymodel

输入以下命令可将 mydataset 中 mymodel 的到期时间更新为 5 天（432000 秒）。mydataset 在 myotherproject 中，不在默认项目中。

bq update --model --expiration 432000 myotherproject:mydataset.mymodel

API

要使用 API 更新模型的到期时间，请调用 models.patch 方法并提供 projectId、datasetId 和 modelId。要修改到期时间，请添加或更新模型资源的“expirationTime”属性。“expirationTime”以自 Epoch 时间起计的毫秒数表示。

后续步骤

• 如需大致了解 BigQuery ML，请参阅 BigQuery ML 简介。
• 如需开始使用 BigQuery ML，请参阅在 BigQuery ML 中创建机器学习模型。
• 如需详细了解如何使用模型，请参阅以下内容：
  • 获取模型元数据
  • 列出模型
  • 管理模型
  • 删除模型