导出模型

概览

本页面介绍如何导出 BigQuery ML 模型。您可以将 BigQuery ML 模型导出到 Cloud Storage，并使用它们进行在线预测，或在 Python 中对其进行修改。您可以通过以下方式导出 BigQuery ML 模型：

• 使用 Cloud Console。
• 使用 EXPORT MODEL 语句。
• 在 bq 命令行工具中使用 bq extract 命令。
• 通过 API 或客户端库提交 extract 作业。

您可以导出以下模型类型：

• AUTOML_CLASSIFIER
• AUTOML_REGRESSOR
• BOOSTED_TREE_CLASSIFIER
• BOOSTED_TREE_REGRESSOR
• DNN_CLASSIFIER
• DNN_REGRESSOR
• KMEANS
• LINEAR_REG
• LOGISTIC_REG
• MATRIX_FACTORIZATION
• TENSORFLOW（导入的 TensorFlow 模型）
• XGBOOST（导入的 XGBoost 模型）

导出模型格式和示例

下表展示了每种 BigQuery ML 模型类型的导出目标格式，并提供了写入到 Cloud Storage 存储分区中的文件示例。

模型类型	导出模型格式	导出文件示例
AUTOML_CLASSIFIER	TensorFlow SavedModel (TF 2.1.0)	gcs_bucket/   assets/     f1.txt     f2.txt   saved_model.pb   variables/     variables.data-00-of-01     variables.index
AUTOML_REGRESSOR
DNN_CLASSIFIER	TensorFlow SavedModel（TF 1.15 或更高版本）
DNN_REGRESSOR
KMEANS
LINEAR_REGRESSOR
LOGISTIC_REG
MATRIX_FACTORIZATION
BOOSTED_TREE_CLASSIFIER	增强器 (XGBoost 0.82)	gcs_bucket/   assets/     0.txt     1.txt     model_metadata.json   main.py   model.bst   xgboost_predictor-0.1.tar.gz     ....      predictor.py     .... main.py 用于本地运行。如需了解详情，请参阅模型部署。
BOOSTED_TREE_REGRESSOR
TENSORFLOW（导入的模型）	TensorFlow SavedModel	与导入模型时存在的文件完全相同

注意：在模型创建期间进行的自动数据预处理（例如标准化和标签编码）保存在导出的文件中（作为 TensorFlow SavedModel 图表的一部分并保存在增强器的外部文件中）。因此，在传递数据进行预测之前，不需要进行显式预处理。输入应与用于 BigQuery ML ML.PREDICT 的输入完全相同。STRUCT 特征属于例外情况；您必须将 STRUCT 字段扩展为单独的字段。例如，STRUCT f2 中的字段 f1 应重命名为 f2_f1，并作为单独的列传递。

此模型不包含训练期间在 SELECT 语句中执行的特征工程的信息，因此您需要在将输入数据输入到导出的模型之前手动转换输入数据。

限制

• 如果训练期间使用了以下任何特征，则不支持模型导出：

  • 输入数据中存在 ARRAY、TIMESTAMP 或 GEOGRAPHY 特征类型。
  • 使用 BigQuery ML Transform 子句进行特征工程。

• 模型类型 AUTOML_REGRESSOR 和 AUTOML_CLASSIFIER 的导出模型不支持用于在线预测的 AI Platform 部署。

• 对于矩阵分解模型导出，模型大小限制为 1 GB。模型大小与 num_factors 大致成比例，因此，如果您在训练期间达到模型大小限制，可以减少 num_factors 以缩减模型大小。

导出 BigQuery ML 模型

如需导出模型，请执行以下操作：

控制台

1. 在 Cloud Console 中打开 BigQuery 页面。
   

   转到 BigQuery 页面

2. 在导航面板的资源部分，展开您的项目并点击您的数据集以将其展开。找到并点击要导出的模型。

3. 点击窗口右侧的导出模型。

   

4. 在导出到 Cloud Storage 对话框中，执行以下操作：

   • 在选择 Cloud Storage 位置部分，浏览到要将模型导出到的目标存储分区或文件夹位置。
   • 点击导出以导出模型。

如需检查作业进度，请在导航窗格顶部附近查找相应导出作业的作业记录。

SQL

借助 EXPORT MODEL 语句，您可以使用标准 SQL 查询语法将 BigQuery ML 模型导出到 Cloud Storage。

如需使用 EXPORT MODEL 语句在 Cloud Console 中导出 BigQuery ML 模型，请按以下步骤操作：

1. 在 Cloud Console 中，打开 BigQuery 页面。

   转到 BigQuery

2. 点击编写新查询。

3. 在查询编辑器字段中，输入您的 EXPORT MODEL 语句。

   以下查询会将名为 myproject.mydataset.mymodel 的模型导出到 URI 为 gs://bucket/path/to/saved_model/ 的 Cloud Storage 存储分区。

    EXPORT MODEL `myproject.mydataset.mymodel`
    OPTIONS(URI = 'gs://bucket/path/to/saved_model/')
    

4. 点击运行。查询完成后，查询结果窗格中会显示以下内容：Successfully exported model。

bq

注意：要使用 bq 命令行工具导出模型，您必须拥有 bq 工具版本 2.0.56 或更高版本，它包含在 Cloud SDK 版本 287.0.0 及更高版本中。要查看已安装的 bq 工具版本，请使用 bq version；如果需要，请使用 gcloud components update 更新 Cloud SDK。

使用带有 --model 标志的 bq extract 命令。

（可选）提供 --destination_format 标志并选择导出的模型的格式。（可选）提供 --location 标志并将值设置为您所用的位置。

bq --location=location extract \
--destination_format format \
--model project_id:dataset.model \
gs://bucket/model_folder

其中：

• location 是位置的名称。--location 是可选标志。例如，如果您在东京区域使用 BigQuery，可将该标志的值设置为 asia-northeast1。您可以使用 .bigqueryrc 文件设置默认位置值。
• destination_format 是导出模型的格式：ML_TF_SAVED_MODEL（默认）或 ML_XGBOOST_BOOSTER。
• project_id 是项目 ID。
• dataset 是源数据集的名称。
• model 是您要导出的模型。
• bucket 是要向其中导出数据的 Cloud Storage 存储分区的名称。BigQuery 数据集和 Cloud Storage 存储分区必须位于同一位置。
• model_folder 是将写入导出模型文件的文件夹的名称。

示例：

例如，以下命令将 TensorFlow SavedModel 格式的 mydataset.mymodel 导出到名为 mymodel_folder 的 Cloud Storage 存储分区。

bq extract --model \
'mydataset.mymodel' \
gs://example-bucket/mymodel_folder

destination_format 的默认值为 ML_TF_SAVED_MODEL。

以下命令以 XGBoost 增强器格式将 mydataset.mymodel 导出到名为 mymodel_folder 的 Cloud Storage 存储分区。

bq extract --model \
--destination_format ML_XGBOOST_BOOSTER \
'mydataset.mytable' \
gs://example-bucket/mymodel_folder

API

如需导出模型，请创建一个 extract 作业，并填充作业配置。

（可选）在作业资源的 jobReference 部分的 location 属性中指定您的位置。

1. 创建一个 extract 作业，将其指向 BigQuery ML 模型和 Cloud Storage 目的地。

2. 使用包含项目 ID、数据集 ID 和模型 ID 的 sourceModel 配置对象指定源模型。

3. destination URI(s) 属性必须是完全限定的，格式为 gs://bucket/model_folder。

4. 通过设置 configuration.extract.destinationFormat 属性来指定目的地格式。例如，如需导出提升树模型，请将此属性设置为 ML_XGBOOST_BOOSTER 值。

5. 如需检查作业状态，请使用初始请求返回的作业 ID 来调用 jobs.get(job_id)。

   • 如果 status.state = DONE，则表示作业已成功完成。
   • 如果出现 status.errorResult 属性，则表示请求失败，并且该对象将包含描述问题的相关信息。
   • 如果未出现 status.errorResult，则表示作业已成功完成，但可能存在一些非严重错误。返回的作业对象的 status.errors 属性中列出了非严重错误。

API 说明：

• 在调用 jobs.insert 来创建作业时，最佳做法是生成唯一 ID，并将其作为 jobReference.jobId 传递。此方法受网络故障影响较小，因为客户端可以对已知的作业 ID 进行轮询或重试。

• 对指定的作业 ID 调用 jobs.insert 具有幂等性，也就是说，您可以对同一作业 ID 进行无限次重试，但这些操作中最多只有一个操作会成功。

Java

在 GitHub 上查看 反馈

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.ExtractJobConfiguration;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.ModelId;

// Sample to extract model to GCS bucket
public class ExtractModel {

  public static void main(String[] args) throws InterruptedException {
    // TODO(developer): Replace these variables before running the sample.
    String projectName = "bigquery-public-data";
    String datasetName = "samples";
    String modelName = "model";
    String bucketName = "MY-BUCKET-NAME";
    String destinationUri = "gs://" + bucketName + "/path/to/file";
    extractModel(projectName, datasetName, modelName, destinationUri);
  }

  public static void extractModel(
      String projectName, String datasetName, String modelName, String destinationUri)
      throws InterruptedException {
    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();

      ModelId modelId = ModelId.of(projectName, datasetName, modelName);

      ExtractJobConfiguration extractConfig =
          ExtractJobConfiguration.newBuilder(modelId, destinationUri).build();

      Job job = bigquery.create(JobInfo.of(extractConfig));

      // Blocks until this job completes its execution, either failing or succeeding.
      Job completedJob = job.waitFor();
      if (completedJob == null) {
        System.out.println("Job not executed since it no longer exists.");
        return;
      } else if (completedJob.getStatus().getError() != null) {
        System.out.println(
            "BigQuery was unable to extract due to an error: \n" + job.getStatus().getError());
        return;
      }
      System.out.println("Model extract successful");
    } catch (BigQueryException ex) {
      System.out.println("Model extraction job was interrupted. \n" + ex.toString());
    }
  }
}

模型部署

您可以将导出的模型部署到 Google Cloud AI Platform 以及本地。

AI Platform 部署

导出模型格式	部署
Tensorflow SavedModel（非 AutoML 模型）	部署 Tensorflow SavedModel （1.15 运行时版本或更高版本）
Tensorflow SavedModel（AutoML 模型）	不支持
XGBoost 增强器	自定义预测例程（1.15 运行时版本） 注意：由于导出文件中保存了预处理和后处理信息，因此您必须使用自定义预测例程来部署包含额外导出文件的模型。

本地部署

导出模型格式	部署
Tensorflow SavedModel（非 AutoML 模型）	SavedModel 是一种标准格式，您可以在 Tensorflow Serving Docker 容器中部署此类模型。 您也可以利用 AI Platform 在线预测的本地运行。
Tensorflow SavedModel（AutoML 模型）	运行 AutoML 容器。
XGBoost 增强器	如需在本地运行 XGBoost 增强器模型，您可以使用导出的 main.py 文件： 将所有文件从 Cloud Storage 下载到本地目录。 将 predictor.py 文件从 xgboost_predictor-0.1.tar.gz 解压缩到本地目录。 运行 main.py（请参阅 main.py 中的说明）。

预测输出格式

本部分介绍每种模型类型的导出模型的预测输出格式。所有导出的模型均支持批量预测；它们可以一次处理多个输入行。例如，以下每个输出格式示例中都有两个输入行。

AUTOML_CLASSIFIER

预测输出格式	输出示例
+------------------------------------------+ | predictions | +------------------------------------------+ | [{"scores":[FLOAT], "classes":[STRING]}] | +------------------------------------------+	+---------------------------------------------+ | predictions | +---------------------------------------------+ | [{"scores":[1, 2], "classes":['a', 'b']}, | | {"scores":[3, 0.2], "classes":['a', 'b']}] | +---------------------------------------------+

AUTOML_REGRESSOR

预测输出格式	输出示例
+-----------------+ | predictions | +-----------------+ | [FLOAT] | +-----------------+	+-----------------+ | predictions | +-----------------+ | [1.8, 2.46] | +-----------------+

BOOSTED_TREE_CLASSIFIER

预测输出格式	输出示例
+-------------+--------------+-----------------+ | LABEL_PROBS | LABEL_VALUES | PREDICTED_LABEL | +-------------+--------------+-----------------+ | [FLOAT] | [STRING] | STRING | +-------------+--------------+-----------------+	+-------------+--------------+-----------------+ | LABEL_PROBS | LABEL_VALUES | PREDICTED_LABEL | +-------------+--------------+-----------------+ | [0.1, 0.9] | ['a', 'b'] | ['b'] | +-------------+--------------+-----------------+ | [0.8, 0.2] | ['a', 'b'] | ['a'] | +-------------+--------------+-----------------+

BOOSTED_TREE_REGRESSOR

预测输出格式	输出示例
+-----------------+ | predicted_label | +-----------------+ | FLOAT | +-----------------+	+-----------------+ | predicted_label | +-----------------+ | [1.8] | +-----------------+ | [2.46] | +-----------------+

DNN_CLASSIFIER

预测输出格式

输出示例

+---------------+-------------+-----------+---------+------------------------+--------+---------------+ | ALL_CLASS_IDS | ALL_CLASSES | CLASS_IDS | CLASSES | LOGISTIC (binary only) | LOGITS | PROBABILITIES | +---------------+-------------+-----------+---------+------------------------+--------+---------------+ | [INT64] | [STRING] | INT64 | STRING | FLOAT | [FLOAT]| [FLOAT] | +---------------+-------------+-----------+---------+------------------------+--------+---------------+

+---------------+-------------+-----------+---------+------------------------+--------+---------------+ | ALL_CLASS_IDS | ALL_CLASSES | CLASS_IDS | CLASSES | LOGISTIC (binary only) | LOGITS | PROBABILITIES | +---------------+-------------+-----------+---------+------------------------+--------+---------------+ | [0, 1] | ['a', 'b'] | [0] | ['a'] | [0.36] | [-0.53]| [0.64, 0.36] | +---------------+-------------+-----------+---------+------------------------+--------+---------------+ | [0, 1] | ['a', 'b'] | [0] | ['a'] | [0.2] | [-1.38]| [0.8, 0.2] | +---------------+-------------+-----------+---------+------------------------+--------+---------------+

DNN_REGRESSOR

预测输出格式	输出示例
+-----------------+ | PREDICTED_LABEL | +-----------------+ | FLOAT | +-----------------+	+-----------------+ | PREDICTED_LABEL | +-----------------+ | [1.8] | +-----------------+ | [2.46] | +-----------------+

KMEANS

预测输出格式	输出示例
+--------------------+--------------+---------------------+ | CENTROID_DISTANCES | CENTROID_IDS | NEAREST_CENTROID_ID | +--------------------+--------------+---------------------+ | [FLOAT] | [INT64] | INT64 | +--------------------+--------------+---------------------+	+--------------------+--------------+---------------------+ | CENTROID_DISTANCES | CENTROID_IDS | NEAREST_CENTROID_ID | +--------------------+--------------+---------------------+ | [1.2, 1.3] | [1, 2] | [1] | +--------------------+--------------+---------------------+ | [0.4, 0.1] | [1, 2] | [2] | +--------------------+--------------+---------------------+

LINEAR_REG

预测输出格式	输出示例
+-----------------+ | PREDICTED_LABEL | +-----------------+ | FLOAT | +-----------------+	+-----------------+ | PREDICTED_LABEL | +-----------------+ | [1.8] | +-----------------+ | [2.46] | +-----------------+

LOGISTIC_REG

预测输出格式	输出示例
+-------------+--------------+-----------------+ | LABEL_PROBS | LABEL_VALUES | PREDICTED_LABEL | +-------------+--------------+-----------------+ | [FLOAT] | [STRING] | STRING | +-------------+--------------+-----------------+	+-------------+--------------+-----------------+ | LABEL_PROBS | LABEL_VALUES | PREDICTED_LABEL | +-------------+--------------+-----------------+ | [0.1, 0.9] | ['a', 'b'] | ['b'] | +-------------+--------------+-----------------+ | [0.8, 0.2] | ['a', 'b'] | ['a'] | +-------------+--------------+-----------------+

MATRIX_FACTORIZATION

注意：我们目前仅支持接受输入用户并输出按 predicted_rating 降序排列的前 50 个 (predicted_rating, predicted_item) 对。

预测输出格式	输出示例
+--------------------+--------------+ | PREDICTED_RATING | PREDICTED_ITEM | +------------------+----------------+ | [FLOAT] | [STRING] | +------------------+----------------+	+--------------------+--------------+ | PREDICTED_RATING | PREDICTED_ITEM | +------------------+----------------+ | [5.5, 1.7] | ['A', 'B'] | +------------------+----------------+ | [7.2, 2.7] | ['B', 'A'] | +------------------+----------------+

TENSORFLOW（导入的模型）

预测输出格式
与导入的模型相同

XGBoost 模型可视化

您可以在模型导出后使用 plot_tree Python API 直观呈现提升树。例如，您可以利用 Colab 而不安装依赖项：

1. 将提升树模型导出到 Cloud Storage 存储分区。
2. 从 Cloud Storage 存储分区下载 model.bst 文件。
3. 在 Colab 笔记本中，将 model.bst 文件上传到 Files。

4. 在笔记本中运行以下代码：

   import xgboost as xgb
   import matplotlib.pyplot as plt
   
   model = xgb.Booster(model_file="model.bst")
   num_iterations = <iteration_number>
   for tree_num in range(num_iterations):
     xgb.plot_tree(model, num_trees=tree_num)
   plt.show
   

以下示例绘制了多个树（每个迭代一个树）：

注意：我们使用标签编码器对分类特征进行编码，因此您可以从模型导出 Cloud Storage 存储分区内“assets/”目录中的词汇表文件获取拆分值的相应类别。例如，您在节点中看到“f0 < 2.95”时，可以通过查找第 3 项在词汇表文件中找到相应的类别。

目前，我们不会在模型中保存特征名称，因此您会看到诸如“f0”、“f1”之类的名称。您可以在使用这些名称（例如“f0”）作为索引的 assets/model_metadata.json 导出文件中找到相应的特征名称。

所需权限

如需将 BigQuery ML 模型导出到 Cloud Storage，您需要具有访问 BigQuery ML 模型、运行导出作业，以及将数据写入 Cloud Storage 存储分区的权限。

BigQuery 权限

• 如需导出模型，您至少必须具有 bigquery.models.export 权限。以下预定义的 IAM 角色具有 bigquery.models.export 权限：

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

• 如需运行导出作业，您至少必须具有 bigquery.jobs.create 权限。以下预定义的 IAM 角色具有 bigquery.jobs.create 权限：

  • bigquery.user
  • bigquery.jobUser
  • bigquery.admin

Cloud Storage 权限

• 要将数据写入现有 Cloud Storage 存储分区，您必须具有 storage.objects.create 权限。以下预定义的 IAM 角色具有 storage.objects.create 权限：

  • storage.objectCreator
  • storage.objectAdmin
  • storage.admin

如需详细了解 BigQuery ML 中的 IAM 角色和权限，请参阅访问权限控制。如需详细了解数据集级角色，请参阅 BigQuery 文档中的数据集基本角色。

位置注意事项

在选择数据的位置时，请考虑以下事项：

• 共置 Cloud Storage 存储分区，以导出数据。
• 导出数据时，单区域或多区域 Cloud Storage 存储分区必须与 BigQuery 数据集位于相同位置。例如，如果您的 BigQuery ML 数据集位于欧盟多区域位置，则用于存储您要导出的数据的 Cloud Storage 存储分区也必须位于欧盟的单区域或多区域位置。
• 如果您的数据集位于单区域位置，则您的 Cloud Storage 存储分区必须是同一位置的单区域存储分区。例如，如果您的数据集位于东京区域，则您的 Cloud Storage 存储分区必须是位于东京的单区域存储分区。
• 例外情况：如果您的数据集位于 US 多区域位置，则可以将数据导出到任何单区域或多区域位置的 Cloud Storage 存储分区中。
• 制定数据管理计划。
• 如果您选择的是单区域存储资源（如 BigQuery 数据集或 Cloud Storage 存储分区），请制定按地理位置管理数据的计划。

如需详细了解 Cloud Storage 位置，请参阅 Cloud Storage 文档中的存储分区位置。

在不同位置之间移动 BigQuery 数据

您无法在创建数据集后更改其位置，但可以创建数据集的副本。

配额政策

如需了解导出作业配额，请参阅“配额和限制”页面中的导出作业。

价格

导出 BigQuery ML 模型不收取任何费用，但导出操作受 BigQuery 配额和限制的约束。如需详细了解 BigQuery 价格，请参阅价格页面。

导出数据后，如果您将数据存储在 Cloud Storage 中，则需要为此付费。如需详细了解 Cloud Storage 价格，请参阅 Cloud Storage 价格页面。

后续步骤

• 浏览导出 BigQuery ML 模型以进行在线预测教程。