モデルのエクスポート

概要

このページでは、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 モデル)
  • PCA

モデルの形式とサンプルをエクスポートする

次のテーブルに、各 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
PCA
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 モデルのインポート時に存在していたものとまったく同じファイル

トレーニング中に SELECT ステートメントで実行された特徴量エンジニアリングに関する情報はモデルに含まれないため、エクスポートされたモデルにフィードする前に、入力データを手動で変換する必要があります。

制限事項

モデルをエクスポートする場合は、次の制限が適用されます。

  • トレーニング中に次のいずれかの機能が使用された場合、モデルのエクスポートはサポートされません。

    • ARRAYTIMESTAMPGEOGRAPHY のいずれかの機能タイプが入力データに存在している。
    • BigQuery ML Transform 句が特徴量エンジニアリングに使用されていた。
  • モデルタイプ AUTOML_REGRESSORAUTOML_CLASSIFIER 用にエクスポートされたモデルは、オンライン予測の AI Platform デプロイをサポートしていません。

  • 行列分解モデルのエクスポートの場合、モデルサイズの上限は 1 GB です。モデルサイズは num_factors にほぼ比例します。この上限に達したときは、トレーニング中に num_factors を小さくすることでモデルサイズを縮小できます。

  • 顧客管理の暗号鍵に関連する機能は、モデルのエクスポートではサポートされていません。

BigQuery ML モデルのエクスポート

モデルをエクスポートするには:

Console

  1. Cloud Console で [BigQuery] ページを開きます。

    [BigQuery] ページに移動

  2. ナビゲーション パネルの [リソース] セクションでプロジェクトを展開し、目的のデータセットをクリックして展開します。エクスポートするモデルを見つけてクリックします。

  3. ウィンドウの右側にある [モデルをエクスポート] をクリックします。

    モデルをエクスポート

  4. [Google Cloud Storage へのモデルのエクスポート] ダイアログで、次の操作を行います。

    • [GCS の場所を選択] で、モデルをエクスポートする先のバケットまたはフォルダのロケーションを参照します。
    • [エクスポート] をクリックしてモデルをエクスポートします。

ジョブの進行状況を確認するには、ナビゲーションの上部にある [エクスポート] ジョブの [ジョブ履歴] を確認します。

SQL

EXPORT MODEL ステートメントを使用すると、標準 SQL クエリ構文を使用して BigQuery ML モデルを Cloud Storage にエクスポートできます。

Cloud Console で EXPORT MODEL ステートメントを使用して 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 extract コマンドを使用し、--model フラグを指定します。

(省略可)--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 は、エクスポートされるモデルファイルが書き込まれるフォルダの名前です。

例:

たとえば、次のコマンドは mydataset.mymodel を TensorFlow SavedModel 形式で mymodel_folder という名前の Cloud Storage バケットにエクスポートします。

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

destination_format のデフォルト値は ML_TF_SAVED_MODEL です。

次のコマンドは、mymodel_folder という Cloud Storage バケットに XGBoost ブースター形式で mydataset.mymodel をエクスポートします。

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

API

モデルをエクスポートするには、extract ジョブを作成してジョブ構成に入力します。

(省略可)ジョブリソースjobReference セクションにある location プロパティでロケーションを指定します。

  1. 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 を生成して、その ID を jobReference.jobId として渡します。この手法は、ネットワーク障害時にクライアントは既知のジョブ ID を使ってポーリングまたは再試行できるので、より確実です。

  • 特定のジョブ ID で jobs.insert を呼び出す操作は「べき等」です。つまり、同じジョブ ID で何回でも再試行できますが、成功するオペレーションはそのうちの 1 回だけです。

Java

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 Service Docker コンテナにデプロイできます。

AI Platform のオンライン予測のローカル実行も利用できます。
Tensorflow SavedModel(AutoML モデル) AutoML コンテナを実行します。
XGBoost ブースター XGBoost ブースター モデルをローカルで実行するには、エクスポートされた main.py ファイルを使用します。
  1. すべてのファイルを Cloud Storage からローカル ディレクトリにダウンロードします。
  2. xgboost_predictor-0.1.tar.gz から predictor.py ファイルを解凍して、ローカル ディレクトリに保存します。
  3. main.py を実行します(main.py の手順を参照)。

予測出力形式

このセクションでは、エクスポートされたモデルのモデルタイプごとの予測出力形式について説明します。エクスポートされたすべてのモデルはバッチ予測をサポートしており、一度に複数の入力行を処理できます。たとえば、次の出力形式の例にはそれぞれ 2 つの入力行があります。

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

注: 現在サポートされているのは、入力ユーザーと出力の上位 50 位(predicted_rating、predicted_item)のペアを、predicted_rating 別に降順で並べ替えることだけです。

予測出力形式 出力例

+--------------------+--------------+
| PREDICTED_RATING | PREDICTED_ITEM |
+------------------+----------------+
| [FLOAT]          | [STRING]       |
+------------------+----------------+
        

+--------------------+--------------+
| PREDICTED_RATING | PREDICTED_ITEM |
+------------------+----------------+
| [5.5, 1.7]       | ['A', 'B']     |
+------------------+----------------+
| [7.2, 2.7]       | ['B', 'A']     |
+------------------+----------------+
        

TensorFlow(インポート)

予測出力形式
インポートしたモデルと同じ

PCA

予測出力形式 出力例

+-------------------------+---------------------------------+
| PRINCIPAL_COMPONENT_IDS | PRINCIPAL_COMPONENT_PROJECTIONS |
+-------------------------+---------------------------------+
|       [INT64]           |             [FLOAT]             |
+-------------------------+---------------------------------+
        

+-------------------------+---------------------------------+
| PRINCIPAL_COMPONENT_IDS | PRINCIPAL_COMPONENT_PROJECTIONS |
+-------------------------+---------------------------------+
|       [1, 2]            |             [1.2, 5.0]          |
+-------------------------+---------------------------------+
        

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
    

この例では、複数のツリーを作成します(イテレーションごとに 1 つのツリー)。

モデルをエクスポート

現在、モデルに特徴名を保存していないため、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 データセットが EU マルチリージョン ロケーションにある場合、エクスポートするデータを含む Cloud Storage バケットも EU のリージョンまたはマルチリージョン ロケーションにある必要があります。
    • データセットがリージョン ロケーションにある場合、Cloud Storage バケットは同じロケーションのリージョン バケットに存在する必要があります。たとえば、データセットが東京リージョンにある場合、Cloud Storage バケットは東京のリージョン バケットである必要があります。
    • 例外: データセットが米国のマルチリージョン ロケーションにある場合、任意のリージョンまたはマルチリージョン ロケーションにある Cloud Storage バケットにデータをエクスポートできます。
  • データ管理計画を作成する
    • BigQuery データセットや Cloud Storage バケットなどのリージョン ストレージ リソースを選択する場合は、データの地理的管理を行うための計画を作成します。

Cloud Storage のロケーションの詳細については、Cloud Storage のドキュメントのバケットのロケーションをご覧ください。

ロケーション間での BigQuery データの移動

データセットの作成後にそのロケーションを変更することはできませんが、データセットのコピーを作成することはできます。

割り当てポリシー

エクスポート ジョブの割り当てについては、「割り当てと上限」のページのエクスポート ジョブをご覧ください。

料金

BigQuery ML モデルのエクスポートは無料で利用できますが、エクスポートには BigQuery の割り当てと上限が適用されます。BigQuery の料金設定の詳細については、料金設定のページをご覧ください。

データのエクスポート終了後、Cloud Storage へのデータの保存に対して課金されます。Cloud Storage の料金設定の詳細については、クラウドの料金設定のページをご覧ください。

次のステップ