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

このドキュメントでは、RetinaNet オブジェクト検出モデルの実装について説明します。コードは、GitHub で入手できます。

以下の手順では、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
Cloud Storage

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

始める前に

このセクションでは、Cloud Storage バケットと Compute Engine VM の設定について説明します。

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

Cloud Shell を開く
プロジェクト ID の変数を作成します。
```
export PROJECT_ID=project-id
```
Cloud TPU を作成するプロジェクトを使用するように gcloud コマンドラインツールを構成します。
```
gcloud config set project ${PROJECT_ID}
```
次のコマンドを使用して Cloud Storage バケットを作成します。
注: 次のコマンドの bucket-name は、バケットに割り当てる名前に置き換えてください。
```
gsutil mb -p ${PROJECT_ID} -c standard -l europe-west4 -b on gs://bucket-name
```
この Cloud Storage バケットには、モデルのトレーニングに使用するデータとトレーニング結果が格納されます。
ctpu up コマンドを使用して、Compute Engine VM を起動します。
```
ctpu up --zone=europe-west4-a \
 --vm-only \
 --disk-size-gb=300 \
 --machine-type=n1-standard-8 \
 --tf-version=1.15.3 \
 --name=retinanet-tutorial
```
注: プロジェクトが複数ある場合は、--project を使用してプロジェクト名を指定する必要があります。--name が指定されていない場合、TPU と VM の名前はデフォルトでユーザー名になります。
指定した構成が表示されます。承認する場合は y、キャンセルする場合は n を入力してください。
ctpu up コマンドの実行が終了したら、shell プロンプトが username@projectname から username@vm-name に変更されたことを確認します。変更されていれば、Compute Engine VM にログインしていることになります。

注: プロジェクトで初めて ctpu up を実行する場合、SSH 認証鍵の伝播や API の始動などの起動タスクの実行に数分かかることがあります。SSH 認証鍵の伝播中に、エラーメッセージ（ERROR: (gcloud.compute.ssh) [/usr/bin/ssh] exited with return code [255]）が返されることがあります。その場合は、次のコマンドを実行して問題を解決してください。
```
gcloud compute ssh retinanet-tutorial --zone=europe-west4-a
```
これらの手順を続行する場合は、VM セッションウィンドウで、(vm)$ で始まる各コマンドを実行します。

ctpu コマンドは Compute Engine 仮想マシン（VM）を起動するときに、/usr/share/tpu/models/official/detection/ ディレクトリにあるTensorFlow ブランチから RetinaNet モデルファイルを自動的に取得して配置します。
これらの環境変数を設定するには、export コマンドを使用します。
注: 次のコマンドで、bucket-name を実際のバケット名に置き換えてください。
```
(vm)$ export STORAGE_BUCKET=gs://bucket-name
```
```
(vm)$ export TPU_NAME=retinanet-tutorial
(vm)$ export DATA_DIR=${STORAGE_BUCKET}/coco
```

追加のパッケージをインストールする

RetinaNet トレーニングアプリケーションには、いくつかの追加パッケージが必要です。この時点で、これらのパッケージをインストールしておきます。

(vm)$ sudo apt-get install -y python3-tk

(vm)$ pip3 install --user Cython matplotlib opencv-python-headless pyyaml Pillow

(vm)$ pip3 install --user 'git+https://github.com/cocodataset/cocoapi#egg=pycocotools&subdirectory=PythonAPI'

(vm)$ pip3 install --user -U gast==0.2.2

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

download_and_preprocess_coco.sh スクリプトを実行して、COCO データセットを、トレーニングアプリケーションで想定される一連の TFRecord（*.tfrecord）に変換します。
```
(vm)$ sudo bash /usr/share/tpu/tools/datasets/download_and_preprocess_coco.sh ./data/dir/coco
```
これにより、必要なライブラリがインストールされ、前処理スクリプトが実行されます。ローカルのデータディレクトリにいくつかの *.tfrecord ファイルが出力されます。

注: COCO のダウンロードと変換スクリプトの完了には約 1 時間かかります。
データを 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}
```

トレーニング環境を設定する

次のコマンドを実行して Cloud TPU を作成します。

(vm)$ ctpu up --tpu-only \
  --tf-version=1.15.3 \
  --name=retinanet-tutorial

パラメータ	説明
`--tpu-only`	Cloud TPU のみを作成し、VM は作成しないでください。
`--tf-version`	Tensorflow「ctpu」のバージョンが VM にインストールされます。
`--name`	Cloud TPU の名前です。

指定した構成が表示されます。承認する場合は y、キャンセルする場合は n を入力してください。

Operation success; not ssh-ing to Compute Engine VM due to --tpu-only flag というメッセージが表示されます。SSH 鍵の伝播は完了しているため、このメッセージは無視できます。
VM 接続に対するキープアライブ値を更新する

このチュートリアルでは、Compute Engine インスタンスに長時間接続する必要があります。インスタンスへの接続が切断されないようにするには、次のコマンドを実行します。
```
(vm)$ sudo /sbin/sysctl \
  -w net.ipv4.tcp_keepalive_time=120 \
  net.ipv4.tcp_keepalive_intvl=120 \
  net.ipv4.tcp_keepalive_probes=5
```
これで、前処理した COCO データに対してモデルを実行する準備が整いました。まず、次のコマンドを使用して、Python パスに最上位の /models フォルダを追加します。
```
(vm)$ export PYTHONPATH=${PYTHONPATH}:/usr/share/tpu/models
```

トレーニングと評価には、TensorFlow 1.13 以降のバージョンが必要です。

単一の Cloud TPU デバイスのトレーニング

次の環境変数を設定します。

(vm)$ export MODEL_DIR=${STORAGE_BUCKET}/retinanet-model-train
(vm)$ export RESNET_CHECKPOINT=gs://cloud-tpu-checkpoints/retinanet/resnet50-checkpoint-2018-02-07
(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)$ python3 /usr/share/tpu/models/official/detection/main.py \
--use_tpu=True \
--tpu=${TPU_NAME} \
--num_cores=8 \
--model_dir=${MODEL_DIR} \
--mode="train" \
--eval_after_training=True \
--params_override="{ type: retinanet, train: { checkpoint: { path: ${RESNET_CHECKPOINT}, prefix: resnet50/ }, train_file_pattern: ${TRAIN_FILE_PATTERN} }, eval: { val_json_file: ${VAL_JSON_FILE}, eval_file_pattern: ${EVAL_FILE_PATTERN}, eval_samples: 5000 } }"

パラメータ	説明
`--use_tpu`	単一の Cloud TPU でモデルをトレーニングします。
`--tpu`	Cloud TPU の名前を指定します。環境変数（`TPU_NAME`）を指定することで設定されます。
`--num_cores`	Cloud TPU のコア数を指定します。
`--model_dir`	モデルのトレーニング中にチェックポイントとサマリーが保存されるディレクトリを指定します。該当するフォルダがない場合は、プログラムによって作成されます。Cloud TPU を使用する場合、`model_dir` は Cloud Storage パスにする必要があります（`gs://...`）。以前のチェックポイントが、同じサイズの TPU と TensorFlow バージョンを使用して作成されていれば、既存のフォルダを再利用して現在のチェックポイントデータを読み込んで追加のチェックポイントを保存できます。
`--mode`	モデルを実行するモードを指定します。有効な値は `train` と `eval` です。

単一の Cloud TPU デバイスの評価

次の手順では、COCO 評価データを使用します。評価ステップが完了するまでには約 10 分かかります。

次の環境変数を設定します。
```
(vm)$ export EVAL_SAMPLES=5000
```

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

  (vm)$ python3 /usr/share/tpu/models/official/detection/main.py \
    --use_tpu=True \
    --tpu=${TPU_NAME} \
    --num_cores=8 \
    --model_dir=${MODEL_DIR} \
    --mode="eval" \
    --params_override="{ type: retinanet, eval: { val_json_file: ${VAL_JSON_FILE}, eval_file_pattern: ${EVAL_FILE_PATTERN}, eval_samples: ${EVAL_SAMPLES} } }"

パラメータ	説明
`--use_tpu`	単一の Cloud TPU でモデルを評価します。
`--tpu`	Cloud TPU の名前を指定します。環境変数（`TPU_NAME`）を指定することで設定されます。
`--num_cores`	Cloud TPU のコア数を指定します。
`model_dir`	モデルのトレーニング中にチェックポイントとサマリーが保存されるディレクトリを指定します。該当するフォルダがない場合は、プログラムによって作成されます。Cloud TPU を使用する場合、`model_dir` は Cloud Storage パスにする必要があります（`gs://...`）。以前のチェックポイントが、同じサイズの TPU と TensorFlow バージョンを使用して作成されていれば、既存のフォルダを再利用して現在のチェックポイントデータを読み込んで追加のチェックポイントを保存できます。
`--mode`	モデルを実行するモードを指定します。有効な値は `train` と `eval` です。

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

Cloud TPU Pod を使用してモデルをスケーリングする

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

v2-32
v3-32

単一のデバイスでモデルをトレーニングするために作成した Cloud TPU リソースを削除します。
```
(vm)$ ctpu delete --tpu-only --zone=europe-west4-a --name=retinanet-tutorial
```
使用する Pod スライスを指定するための tpu-sizeパラメータを使用して、ctpu up コマンドを実行します。たとえば、次のコマンドは v3-32 の Pod スライスを使用します。
```
(vm)$ ctpu up --tpu-only \
  --tpu-size=v3-32 \
  --zone=europe-west4-a \
  --tf-version=1.15.3 \
  --name=retinanet-tutorial-pod
 
```
指定した構成が表示されます。承認する場合は y、キャンセルする場合は n を入力してください。

Operation success; not ssh-ing to Compute Engine VM due to --tpu-only flag というメッセージが表示されます。SSH 鍵の伝播は完了しているため、このメッセージは無視できます。

次の環境変数を設定します。

(vm)$ export MODEL_DIR=${STORAGE_BUCKET}/retinanet-model-pod
(vm)$ export TPU_NAME=retinanet-tutorial-pod

v3-32 TPU ノードで Pod トレーニングスクリプトを実行します。

(vm)$ python3 /usr/share/tpu/models/official/detection/main.py \
--use_tpu=True \
--tpu=${TPU_NAME} \
--num_cores=32 \
--model_dir=${MODEL_DIR} \
--mode="train" \
--eval_after_training=False \
--params_override="{ type: retinanet, train: { train_batch_size: 1024, total_steps: 2109, learning_rate: { warmup_steps: 820, init_learning_rate: 0.64, learning_rate_levels: [0.064, 0.0064], learning_rate_steps: [1641, 1992] }, checkpoint: { path: ${RESNET_CHECKPOINT}, prefix: resnet50/ }, train_file_pattern: ${TRAIN_FILE_PATTERN} }, resnet: { batch_norm: { batch_norm_momentum: 0.9 }}, fpn: { batch_norm: { batch_norm_momentum: 0.9 }}, retinanet_head: { batch_norm: { batch_norm_momentum: 0.9 }} }"

パラメータ	説明
`--use_tpu`	Cloud TPU Pod でモデルをトレーニングします。
`--tpu`	Cloud TPU の名前を指定します。環境変数（`TPU_NAME`）を指定することで設定されます。
`--num_cores`	Cloud TPU のコア数を指定します。
`--model_dir`	モデルのトレーニング中にチェックポイントとサマリーが保存されるディレクトリを指定します。該当するフォルダがない場合は、プログラムによって作成されます。Cloud TPU を使用する場合、`model_dir` は Cloud Storage パスにする必要があります（`gs://...`）。以前のチェックポイントが、同じサイズの TPU と TensorFlow バージョンを使用して作成されていれば、既存のフォルダを再利用して現在のチェックポイントデータを読み込んで追加のチェックポイントを保存できます。
`--mode`	モデルを実行するモードを指定します。
`--eval_after_training`	トレーニング後にモデルを評価するには、`True` に設定します。
`--params_override`	指定された値で model パラメータをオーバーライドします。

クリーンアップ

このチュートリアルで使用したリソースについて、Google Cloud Platform アカウントに課金されないようにする手順は次のとおりです。

Compute Engine インスタンスとの接続を切断していない場合は切断します。
```
(vm)$ exit
```
プロンプトが username@projectname に変わります。これは、現在、Cloud Shell 内にいることを示しています。
Cloud Shell で、Cloud TPU の設定時に使用した --zone フラグを指定して ctpu delete を実行し、Compute Engine VM と Cloud TPU を削除します。
```
$ ctpu delete --zone=europe-west4-a --name=retinanet-tutorial
```
重要: ctpu up を実行したときに TPU のリソース名を設定した場合は、ctpu delete を実行して TPU リソースをシャットダウンする際に、--name フラグを使用してリソース名を指定する必要があります。
次のコマンドを実行して、Compute Engine VM と Cloud TPU がシャットダウンされたことを確認します。
```
$ ctpu status --zone=europe-west4-a
```
削除には数分かかることがあります。次のようなレスポンスは、割り当てられたインスタンスがないことを示します。
```
2018/04/28 16:16:23 WARNING: Setting zone to "europe-west4-a"
No instances currently exist.
 Compute Engine VM:     --
 Cloud TPU:             --
```
注意: バケットを削除すると、すべてのトレーニングデータが失われます。この手順は、チュートリアルの実行が完了したときにのみ行ってください。
次に示すように gsutil を実行します。bucket-name の部分は、このチュートリアルで作成した Cloud Storage バケット名に置き換えてください。
```
$ gsutil rm -r gs://bucket-name
```

次のステップ

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

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

ハイパーパラメータ調整

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

推論

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

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

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

別のベースを使用する

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