更新模型元数据

本页面介绍如何更新 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 角色和权限，请参阅访问权限控制。

更新模型的说明

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

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

控制台

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

转到 BigQuery 页面
在导航面板的资源部分中，展开项目名称和数据集名称。
点击您的模型名称。模型由模型图标表示。
点击详情标签页。
要更新模型的说明，请点击说明右边的修改图标（铅笔）。
在修改说明对话框中，输入文本，然后点击更新。

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 '[PROJECT_ID]:[DATASET].[MODEL]' 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 资源时，并不是必须要添加标签。如需了解详情，请参阅添加和使用标签。

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

控制台

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

转到 BigQuery 页面
在导航面板的资源部分中，展开项目名称和数据集名称。
点击您的模型名称。模型由模型图标表示。
点击详情标签页。
要更新模型的标签，请点击标签右边的修改图标（铅笔）。
在修改标签对话框中：
- 要应用更多标签，请点击添加标签。每个键只能在每个数据集内使用一次，但您可以在同一项目的不同数据集内使用同一个键。
- 修改现有键或值以更新标签。
- 点击更新以保存更改。

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 '[PROJECT_ID]:[DATASET].[MODEL]' 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。

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

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

在命令行工具中，到期时间以自当前世界协调时间 (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 '[PROJECT_ID]:[DATASET].[MODEL]' 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 中创建机器学习模型。
如需详细了解如何使用模型，请参阅以下内容：