Cloud TPU での ShapeMask のトレーニング

このドキュメントでは、COCO データセットで Cloud TPU を使用して ShapeMask モデルを実行する方法を示します。

以下の手順では、Cloud TPU でモデルを実行する方法をすでに理解していることを前提としています。Cloud TPU を初めて使用する場合は、クイックスタートで基本的な概要をご確認ください。

TPU Pod スライスでトレーニングする場合は、TPU Pod でのトレーニングを確認して、Pod スライスに必要なパラメータの変更を確認してください。

目標

データセットとモデルの出力を格納する Cloud Storage バケットを作成する
COCO データセットを準備する
トレーニングと評価のための Compute Engine VM と Cloud TPU ノードを設定する
単一の Cloud TPU または Cloud TPU Pod でトレーニングと評価を実行する

費用

このチュートリアルでは、Google Cloud の課金対象となる以下のコンポーネントを使用します。

Compute Engine
Cloud TPU
クラウドストレージ

料金計算ツールを使うと、予想使用量に基づいて費用の見積もりを出すことができます。新しい Google Cloud ユーザーは無料トライアルをご利用いただける場合があります。

始める前に

このチュートリアルを開始する前に、Google Cloud プロジェクトが正しく設定されていることを確認します。

Google Cloud アカウントにログインします。Google Cloud を初めて使用する場合は、アカウントを作成して、実際のシナリオでの Google プロダクトのパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。

Google Cloud Console の [プロジェクトセレクタ] ページで、Google Cloud プロジェクトを選択または作成します。

注: この手順で作成するリソースをそのまま保持する予定でない場合、既存のプロジェクトを選択するのではなく、新しいプロジェクトを作成してください。チュートリアルの終了後にそのプロジェクトを削除すれば、プロジェクトに関連するすべてのリソースを削除できます。

プロジェクトセレクタに移動

Cloud プロジェクトに対して課金が有効になっていることを確認します。プロジェクトに対して課金が有効になっていることを確認する方法を学習する。

このチュートリアルでは、Google Cloud の課金対象となるコンポーネントを使用します。費用を見積もるには、Cloud TPU の料金ページを確認してください。不要な課金を回避するために、このチュートリアルを完了したら、作成したリソースを必ずクリーンアップしてください。

TPU Pod スライスでトレーニングする場合は、TPU Pod でのトレーニングを確認して、ポッドスライスに必要なパラメータの変更を確認してください。

リソースを設定する

このセクションでは、このチュートリアルで使用する Cloud Storage、VM、Cloud TPU の各リソースを設定する方法を説明します。

Cloud Shell ウィンドウを開きます。

Cloud Shell を開く
プロジェクト ID の変数を作成します。
```
export PROJECT_ID=project-id
```
Cloud TPU を作成するプロジェクトを使用するように gcloud コマンドラインツールを構成します。
```
gcloud config set project ${PROJECT_ID}
```
このコマンドを新しい Cloud Shell VM で初めて実行すると、Authorize Cloud Shell ページが表示されます。ページの下部にある [Authorize] をクリックして、gcloud に認証情報を使用した GCP API の呼び出しを許可します。
Cloud TPU プロジェクトのサービスアカウントを作成します。
```
gcloud beta services identity create --service tpu.googleapis.com --project $PROJECT_ID
```
このコマンドでは、Cloud TPU サービスアカウントを次の形式で返します。
```
service-PROJECT_NUMBER@cloud-tpu.iam.gserviceaccount.com
```
次のコマンドを使用して Cloud Storage バケットを作成します。
注: 次のコマンドの bucket-name は、バケットに割り当てる名前に置き換えてください。
```
gsutil mb -p ${PROJECT_ID} -c standard -l europe-west4 -b on gs://bucket-name
```
この Cloud Storage バケットには、モデルのトレーニングに使用するデータとトレーニング結果が格納されます。このチュートリアルで使用する gcloud compute tpus execution-groups ツールは、Cloud TPU サービスアカウントのデフォルトの権限を設定します。権限の詳細な設定が必要な場合は、アクセスレベル権限をご覧ください。

バケットのロケーションは、仮想マシン（VM）および TPU ノードと同じリージョンにする必要があります。VM と TPU ノードは、リージョン内のサブディビジョンである特定のゾーンに配置されます。
Compute Engine VM インスタンスを起動します。

注: このチュートリアルでは、TensorFlow 1.15.5 を使用します。Debian 10 イメージに基づいており、Python 3.6 にデフォルト設定されています。以前のバージョンの TensorFlow 1.15.x は Debian 9 に基づいており、Python 3.5 にデフォルト設定されていました。
```
$ gcloud compute tpus execution-groups create --vm-only \
 --name=shapemask-tutorial \
 --zone=us-central1-a \
 --disk-size=300 \
 --machine-type=n1-standard-16 \
 --tf-version=1.15.5
```
コマンドフラグの説明

vm-only

VM のみを作成します。デフォルトでは、gcloud compute tpus execution-groups コマンドは VM と Cloud TPU を作成します。

name
作成する Cloud TPU の名前。
zone
Cloud TPU を作成するゾーン。
disk-size
gcloud compute tpus execution-groups コマンドで作成された VM のハードディスクのサイズ（GB）。
machine-type
作成する Compute Engine VM のマシンタイプ。
tf-version
Tensorflow ctpu のバージョンが VM にインストールされます。
指定した構成が表示されます。承認する場合は y、キャンセルする場合は n を入力してください。

注: プロジェクトで初めて gcloud compute tpus execution-groups を実行する場合、SSH 認証鍵の伝播や API の始動などの起動タスクの実行に約 5 分かかります。

gcloud compute tpus execution-groups コマンドの実行が終了したら、shell プロンプトが username@projectname から username@vm-name に変更されたことを確認します。変更されていれば、Compute Engine VM にログインしていることになります。
注: Compute Engine インスタンスに接続していない場合は、次のコマンドを実行して接続できます。
```
gcloud compute ssh shapemask-tutorial --zone=us-central1-a
```
これらの手順を続行する場合は、Compute Engine インスタンスで (vm)$ で始まる各コマンドを実行します。
Cloud Storage バケットのロケーションを保存する環境変数を作成します。
```
(vm)$ export STORAGE_BUCKET=gs://bucket-name
```
データディレクトリの環境変数を作成します。
```
(vm)$ export DATA_DIR=${STORAGE_BUCKET}/coco
```

tpu リポジトリのクローンを作成します。

(vm)$ git clone -b shapemask https://github.com/tensorflow/tpu/

データの前処理に必要なパッケージをインストールします。

(vm)$ sudo apt-get install -y python3-tk && \
  pip3 install --user Cython matplotlib opencv-python-headless pyyaml Pillow && \
  pip3 install --user "git+https://github.com/cocodataset/cocoapi#egg=pycocotools&subdirectory=PythonAPI"

COCO データセットを準備する

download_and_preprocess_coco.sh スクリプトを実行して、COCO データセットを、トレーニングアプリケーションで想定される一連の TFRecord（*.tfrecord）に変換します。

注: COCO のダウンロードと変換スクリプトの完了には約 1 時間かかります。
```
(vm)$ sudo bash /usr/share/tpu/tools/datasets/download_and_preprocess_coco.sh ./data/dir/coco
```
これにより、必要なライブラリがインストールされ、前処理スクリプトが実行されます。ローカルのデータディレクトリにいくつかの *.tfrecord ファイルが出力されます。
データを TFRecord に変換した後、gsutil コマンドを使用して、ローカルストレージから Cloud Storage バケットに変換後のデータをコピーします。アノテーションファイルもコピーする必要があります。アノテーションファイルは、モデルのパフォーマンスの検証に利用できます。
```
(vm)$ gsutil -m cp ./data/dir/coco/*.tfrecord ${DATA_DIR}
(vm)$ gsutil cp ./data/dir/coco/raw-data/annotations/*.json ${DATA_DIR}
```
注: モデルの出力とパフォーマンスをモニタリングする場合は、TensorBoard の設定に関するガイドをご覧ください。

Cloud TPU を設定して起動する

gcloud コマンドを使用して Cloud TPU リソースを起動します。
```
(vm)$ gcloud compute tpus execution-groups create \
 --tpu-only \
 --accelerator-type=v3-8  \
 --name=shapemask-tutorial \
 --zone=us-central1-a \
 --tf-version=1.15.5
```
コマンドフラグの説明

tpu-only

VM を作成せずに Cloud TPU を作成します。デフォルトでは、gcloud compute tpus execution-groups コマンドは VM と Cloud TPU を作成します。

accelerator-type
作成する Cloud TPU のタイプ。
name
作成する Cloud TPU の名前。
zone
Cloud TPU を作成するゾーン。
tf-version
Tensorflow ctpu のバージョンが VM にインストールされます。
指定した構成が表示されます。承認する場合は y、キャンセルする場合は n を入力してください。

Operation success; not ssh-ing to Compute Engine VM due to --tpu-only flag というメッセージが表示されます。SSH 鍵の伝播は完了しているため、このメッセージは無視できます。
Cloud TPU の名前の環境変数を追加します。
```
(vm)$ export TPU_NAME=shapemask-tutorial
```

トレーニングと評価のスクリプトを実行する

次の環境変数を作成します。

(vm)$ export MODEL_DIR=${STORAGE_BUCKET}/shapemask_exp
(vm)$ export RESNET_CHECKPOINT=gs://cloud-tpu-checkpoints/shapemask/retinanet/resnet101-checkpoint-2018-02-24
(vm)$ export TRAIN_FILE_PATTERN=${DATA_DIR}/train-*
(vm)$ export EVAL_FILE_PATTERN=${DATA_DIR}/val-*
(vm)$ export VAL_JSON_FILE=${DATA_DIR}/instances_val2017.json
(vm)$ export SHAPE_PRIOR_PATH=gs://cloud-tpu-checkpoints/shapemask/kmeans_class_priors_91x20x32x32.npy
(vm)$ export PYTHONPATH=${PYTHONPATH}:$HOME/tpu/models

次のスクリプトを実行してトレーニングを行います。
注：スクリプトの実行には約 25 分かかります。
```
(vm)$ python3 ~/tpu/models/official/detection/main.py \
--model=shapemask \
--use_tpu=True \
--tpu=${TPU_NAME} \
--num_cores=8 \
--model_dir=${MODEL_DIR} \
--mode="train" \
--eval_after_training=False \
--params_override="{train: {iterations_per_loop: 1000, train_batch_size: 64, total_steps: 1000, learning_rate: {total_steps: 1000, warmup_learning_rate: 0.0067, warmup_steps: 500, init_learning_rate: 0.08, learning_rate_levels: [0.008, 0.0008], learning_rate_steps: [30000, 40000]}, checkpoint: { path: ${RESNET_CHECKPOINT}, prefix: resnet101/ }, train_file_pattern: ${TRAIN_FILE_PATTERN} }, resnet: {resnet_depth: 101}, eval: { val_json_file: ${VAL_JSON_FILE}, eval_file_pattern: ${EVAL_FILE_PATTERN}, eval_samples: 5000 }, shapemask_head: {use_category_for_mask: true, shape_prior_path: ${SHAPE_PRIOR_PATH}}, shapemask_parser: {output_size: [1024, 1024]}, }"
```
コマンドフラグの説明

model

トレーニングするモデル。

use_tpu

Cloud TPU でトレーニングするには、true に設定します。

tpu_name

トレーニングに使用する Cloud TPU の名前。

num_cores

トレーニング時に使用する Cloud TPU コアの数。

model_dir

トレーニング中にチェックポイントとサマリーが保存される Cloud Storage バケット。既存のフォルダを使用して、同じサイズの TPU と TensorFlow バージョンで以前に生成されたチェックポイントを読み込むことができます。

mode

train、eval、train_and_eval のいずれか。

eval_after_training

トレーニング後にモデルを評価するには、true に設定します。

params_override

デフォルトのスクリプトパラメータをオーバーライドする JSON 文字列。スクリプトパラメータの詳細については、/usr/share/models/official/vision/detection/main.py をご覧ください。

この時点で、このチュートリアルを終了して、GCP リソースをクリーンアップすることも、Cloud TPU Pod でのモデルの実行をさらに詳しく調べることもできます。

Cloud TPU Pod を使用したモデルのスケーリング

Cloud TPU Pod を使用してモデルをスケーリングすると、より迅速に結果を得ることができます。完全にサポートされている Mask RCNN モデルは、次の Pod スライスを使用できます。

v2-32
v3-32

Cloud TPU Pod を使用する場合は、まず Pod を使用してモデルをトレーニングし、その後、単一の Cloud TPU デバイスを使用してモデルを評価します。

Cloud TPU Pod を使用したトレーニング

Compute Engine インスタンスをすでに削除している場合は、リソースのセットアップの手順に沿って新しいインスタンスを作成します。

単一のデバイスでモデルをトレーニングするために作成した Cloud TPU リソースを削除します。
```
(vm)$ gcloud compute tpus execution-groups delete shapemask-tutorial \
  --zone=us-central1-a \
  --tpu-only
```
Cloud Storage バケットに移動して、checkpoint ファイルを削除します。
使用する Pod スライスを指定するための accelerator-typeパラメータを使用して、gcloud compute tpus execution-groups コマンドを実行します。たとえば、次のコマンドは v3-32 の Pod スライスを使用します。
```
(vm)$ gcloud compute tpus execution-groups  create --name=shapemask-tutorial \
  --accelerator-type=v2-32  \
  --zone=us-central1-a \
  --tf-version=1.15.5 \
  --tpu-only
```
コマンドフラグの説明

name
作成する Cloud TPU の名前。
accelerator-type
作成する Cloud TPU のタイプ。
zone
Cloud TPU を作成するゾーン。
tf-version
Tensorflow gcloud のバージョンが VM にインストールされます。
tpu-only

Cloud TPU のみを作成します。デフォルトでは、gcloud コマンドは VM と Cloud TPU を作成します。
次のスクリプトを実行して、Pod でモデルをトレーニングします。

指定されたコマンドラインでは、トレーニングスクリプトの実行に約 45 分かかります。収束まで実行するには、total_steps を 22000 に設定します。
```
(vm)$ python3 ~/tpu/models/official/detection/main.py \
--model shapemask \
--use_tpu=True \
--tpu=${TPU_NAME} \
--num_cores=32 \
--model_dir=${MODEL_DIR} \
--mode="train" \
--eval_after_training=False \
--params_override="{train: {iterations_per_loop: 1000, train_batch_size: 256, total_steps: 1000, learning_rate: {total_steps: 1000, warmup_learning_rate: 0.0067, warmup_steps: 500, init_learning_rate: 0.08, learning_rate_levels: [0.008, 0.0008], learning_rate_steps: [15000, 20000]}, checkpoint: { path: ${RESNET_CHECKPOINT}, prefix: resnet101/ }, train_file_pattern: ${TRAIN_FILE_PATTERN} }, resnet: {resnet_depth: 101}, eval: { val_json_file: ${VAL_JSON_FILE}, eval_file_pattern: ${EVAL_FILE_PATTERN}, eval_samples: 5000 }, shapemask_head: {use_category_for_mask: true, shape_prior_path: ${SHAPE_PRIOR_PATH}}, shapemask_parser: {output_size: [1024, 1024]}, }"
```
コマンドフラグの説明

strategy_type

TPU で RetinaNet モデルをトレーニングするには、distribution_strategy を tpu に設定する必要があります。

tpu

Cloud TPU の名前。TPU_NAME 環境変数を使用して設定します。

model_dir

トレーニング中にチェックポイントとサマリーが保存される Cloud Storage バケット。既存のフォルダを使用して、同じサイズの TPU と TensorFlow バージョンで以前に生成されたチェックポイントを読み込むことができます。

mode

train、eval、train_and_eval のいずれか。

model

トレーニングするモデル。

eval_after_training

トレーニング後にモデルを評価するには、true に設定します。

params_override

デフォルトのスクリプトパラメータをオーバーライドする JSON 文字列。スクリプトパラメータの詳細については、/usr/share/models/official/vision/detection/main.py をご覧ください。
モデルは単一の Cloud TPU デバイスで評価する必要があります。Cloud TPU Pod デバイスを削除します。
```
$ gcloud compute tpus execution-groups delete shapemask-tutorial \
  --zone=us-central1-a
```
単一の Cloud TPU リソースを作成します。
```
(vm)$ gcloud compute tpus execution-groups create \
 --tpu-only \
 --accelerator-type=v3-8  \
 --name=shapemask-tutorial \
 --zone=us-central1-a \
 --tf-version=1.15.5
```
コマンドフラグの説明

tpu-only

VM を作成せずに Cloud TPU を作成します。デフォルトでは、gcloud compute tpus execution-groups コマンドは VM と Cloud TPU を作成します。

tpu-size
作成する Cloud TPU のタイプ。
name
作成する Cloud TPU の名前。
zone
Cloud TPU を作成するゾーン。
tf-version
Tensorflow ctpu のバージョンが VM にインストールされます。

スクリプトを実行して評価を行います。

(vm)$ python3 ~/tpu/models/official/detection/main.py \
--model shapemask \
--use_tpu=True \
--tpu=${TPU_NAME} \
--num_cores=8 \
--model_dir=${MODEL_DIR} \
--mode="eval" \
--eval_after_training=False \
--params_override="{train: {iterations_per_loop: 1000, train_batch_size: 256, total_steps: 1000, learning_rate: {total_steps: 1000, warmup_learning_rate: 0.0067, warmup_steps: 500, init_learning_rate: 0.08, learning_rate_levels: [0.008, 0.0008], learning_rate_steps: [15000,20000]}, checkpoint: { path: ${RESNET_CHECKPOINT}, prefix: resnet101/ }, train_file_pattern: ${TRAIN_FILE_PATTERN} }, resnet: {resnet_depth: 101}, eval: { val_json_file: ${VAL_JSON_FILE}, eval_file_pattern: ${EVAL_FILE_PATTERN}, eval_samples: 5000 }, shapemask_head: {use_category_for_mask: true, shape_prior_path: ${SHAPE_PRIOR_PATH}}, shapemask_parser: {output_size: [1024, 1024]}, }"

コマンドフラグの説明

model: トレーニングするモデル。
use_tpu: Cloud TPU でトレーニングするには、true に設定します。
tpu: Cloud TPU の名前。TPU_NAME 環境変数を使用して設定します。
num_cores: トレーニング時に使用する Cloud TPU コアの数。
model_dir: トレーニング中にチェックポイントとサマリーが保存される Cloud Storage バケット。既存のフォルダを使用して、同じサイズの TPU と TensorFlow バージョンで以前に生成されたチェックポイントを読み込むことができます。
mode: train、eval、train_and_eval のいずれか。
eval_after_training: トレーニング後にモデルを評価するには、true に設定します。
params_override: デフォルトのスクリプトパラメータをオーバーライドする JSON 文字列。スクリプトパラメータの詳細については、/usr/share/models/official/vision/detection/main.py をご覧ください。

評価スクリプトの出力は次のようになります。

Eval result: {
 'AP75': 0.116238795,
 'AP': 0.121657856,
 'mask_ARmax100': 0.29928473,
 'APl': 0.17029367,
 'mask_ARmax1': 0.17677748,
 'ARs': 0.14137766,
 'mask_AP': 0.12017078,
 'ARmax10': 0.29230836,
 'mask_AP50': 0.20920053,
 'ARm': 0.34366703,
 'AP50': 0.22949784,
 'mask_ARl': 0.41743836,
 'mask_ARs': 0.12669834,
 'APs': 0.046222884,
 'mask_APs': 0.041104294,
 'mask_APl': 0.17535995,
 'mask_ARm': 0.34216145,
 'mask_ARmax10': 0.28690106,
 'APm': 0.14354791,
 'ARmax100': 0.3058479,
 'ARmax1': 0.17576972,
 'ARl': 0.41305476,
 'mask_APm': 0.1422335,
 'mask_AP75': 0.12010279
}

クリーンアップ

このチュートリアルで使用したリソースについて、Google Cloud アカウントに課金されないようにするには、リソースを含むプロジェクトを削除するか、プロジェクトを維持して個々のリソースを削除します。

Compute Engine インスタンスから接続を切断します。
```
(vm)$ exit
```
プロンプトが username@projectname に変わります。これは、現在、Cloud Shell 内にいることを示しています。
Cloud Shell で次のコマンドを使用して、Compute Engine VM と Cloud TPU を削除します。
```
$ gcloud compute tpus execution-groups delete shapemask-tutorial \
  --zone=us-central1-a
```
gcloud compute tpus execution-groups list を実行して、リソースが削除されていることを確認します。削除には数分かかることがあります。次のようなレスポンスは、インスタンスが正常に削除されたことを示します。
```
$ gcloud compute tpus execution-groups list \
 --zone=us-central1-a
```
次のような空の TPU のリストが表示されます。
```
   NAME             STATUS
```
以下に示すように、gsutil を使用して Cloud Storage バケットを削除します。bucket-name を Cloud Storage バケットの名前に置き換えます。

注意: バケットを削除すると、すべてのトレーニングデータが失われます。この手順は、チュートリアルの実行が完了したときにのみ行ってください。
```
$ gsutil rm -r gs://bucket-name
```

次のステップ

このチュートリアルでは、サンプルデータセットを使用して ShapeMask モデルをトレーニングしました。このトレーニングの結果は（ほとんどの場合）推論には使用できません。推論にモデルを使用するには、一般公開されているデータセットまたは独自のデータセットでデータをトレーニングします。Cloud TPU でトレーニングされたモデルでは、データセットを TFRecord 形式にする必要があります。

データセット変換ツールのサンプルを使用して、画像分類データセットを TFRecord 形式に変換できます。画像分類モデルを使用しない場合は、自分でデータセットを TFRecord 形式に変換する必要があります。詳細については、TFRecord と tf.Example をご覧ください。

ハイパーパラメータ調整

データセットでモデルのパフォーマンスを向上させるには、モデルのハイパーパラメータを調整します。すべての TPU でサポートされているモデルに共通のハイパーパラメータに関する情報については、GitHub をご覧ください。モデルに固有のハイパーパラメータに関する情報については、各モデルのソースコードで確認できます。ハイパーパラメータ調整の詳細については、ハイパーパラメータ調整の概要、ハイパーパラメータ調整サービスの使用、ハイパーパラメータを調整するをご覧ください。

推論

モデルをトレーニングしたら、そのモデルを推論（予測）に使用できます。AI Platform は、機械学習モデルを開発、トレーニング、デプロイするためのクラウドベースのソリューションです。モデルをデプロイすれば、AI Platform Prediction サービスを使用できるようになります。

さまざまなサイズの画像でトレーニングする

より規模の大きいニューラルネットワーク（たとえば ResNet-50 ではなく ResNet-101）の使用を試すことが可能です。入力画像のサイズを大きくして、より強力なニューラルネットワークを使用すると、処理時間は長くなりますが、モデルの精度が高くなります。

別のベースを使用する

また、独自のデータセットで ResNet モデルを事前トレーニングし、それを ShapeMask モデルのベースとして使用することもできます。いくつかの作業を行うことで、ResNet の代わりに別のニューラルネットワークに切り替えることもできます。最後に、独自のオブジェクト検出モデルの実装を検討されている場合は、このネットワークを今後のテストに利用することをおすすめします。