Cloud TPU（TF 2.x）での ShapeMask のトレーニング

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

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

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

目標

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

費用

このドキュメントでは、課金対象である次の Google Cloud コンポーネントを使用します。

Compute Engine
Cloud TPU
Cloud Storage

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

始める前に

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

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

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

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

Google Cloud プロジェクトで課金が有効になっていることを確認します。

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

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

Google Cloud プロジェクトで課金が有効になっていることを確認します。

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

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

このセクションでは、単一デバイスのトレーニング用に、Cloud Storage のバケット、VM、Cloud TPU の各リソースを設定する方法を説明します。

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

Cloud Shell で、プロジェクト ID の変数を作成します。
```
export PROJECT_ID=project-id
```
Cloud TPU を作成するプロジェクトを使用するように Google Cloud CLI を構成します。
```
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
```

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

このチュートリアルでは、COCO データセットを使用します。トレーニングに使用するデータセットは、Cloud Storage バケットの TFRecord 形式である必要があります。

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

この Cloud Storage バケットには、モデルのトレーニングに使用するデータとトレーニング結果が格納されます。このチュートリアルで使用する gcloud compute tpus execution-groups ツールは、前の手順で設定した Cloud TPU サービスアカウントのデフォルトの権限を設定します。権限の詳細な設定が必要な場合は、アクセスレベル権限をご覧ください。

モデルのトレーニングに使用するゾーンにある Cloud Storage バケットで COCO データセットがすでに準備されている場合は、TPU リソースを起動してトレーニング用に Cloud TPU を準備できます。それ以外の場合は、次の手順でデータセットを準備します。

Cloud Shell で、gcloud をプロジェクト ID で構成します。

export PROJECT_ID=project-id
gcloud config set project ${PROJECT_ID}

Cloud Shell で、次のコマンドを使用して Cloud Storage バケットを作成します。
注: 次のコマンドの bucket-name は、バケットに割り当てる名前に置き換えてください。
```
gsutil mb -p ${PROJECT_ID} -c standard -l europe-west4 gs://bucket-name
```
Compute Engine VM インスタンスを起動します。

この VM インスタンスは、COCO データセットのダウンロードと前処理にのみ使用されます。instance-name に選択した名前を入力します。
```
$ gcloud compute tpus execution-groups create \
 --vm-only \
 --name=instance-name \
 --zone=europe-west4-a \
 --disk-size=300 \
 --machine-type=n1-standard-16 \
 --tf-version=2.12.0
```
コマンドフラグの説明

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 gcloud compute tpus execution-groups のバージョンが VM にインストールされます。
自動的に Compute Engine インスタンスにログインしない場合は、次の ssh コマンドを実行してログインします。VM にログインすると、シェルプロンプトが username@projectname から username@vm-name に変わります。
```
  $ gcloud compute ssh instance-name --zone=europe-west4-a
  
```
2 つの変数を設定します。1 つは以前に作成したストレージバケット用であり、もう 1 つはストレージバケット上のトレーニングデータ（DATA_DIR）を保持するディレクトリ用です。
```
(vm)$ export STORAGE_BUCKET=gs://bucket-name
```
```
(vm)$ export DATA_DIR=${STORAGE_BUCKET}/coco
```

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

(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"

download_and_preprocess_coco.sh スクリプトを実行して、COCO データセットを、トレーニングアプリケーションで想定される一連の TFRecord（*.tfrecord）に変換します。
```
(vm)$ git clone https://github.com/tensorflow/tpu.git
(vm)$ sudo bash tpu/tools/datasets/download_and_preprocess_coco.sh ./data/dir/coco
```
これにより、必要なライブラリがインストールされ、前処理スクリプトが実行されます。ローカルのデータディレクトリにいくつかの *.tfrecord ファイルが出力されます。COCO のダウンロードと変換スクリプトが完了するまでには約 1 時間かかります。
データを Cloud Storage バケットにコピーする

データを 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}
```
VM リソースをクリーンアップする

COCO データセットが TFRecord に変換され、Cloud Storage バケットの DATA_DIR にコピーされたら、Compute Engine インスタンスを削除できます。

Compute Engine インスタンスから接続を切断します。
```
(vm)$ exit
```
プロンプトが username@projectname に変わります。これは、現在、Cloud Shell 内にいることを示しています。

Compute Engine インスタンスを削除します。

  $ gcloud compute instances delete instance-name
    --zone=europe-west4-a

TPU リソースを起動してモデルをトレーニングする

gcloud コマンドを使用して TPU リソースを起動します。使用するコマンドは、TPU VM を使用するか TPU ノードを使用するかによって異なります。2 つの VM アーキテクチャの詳細については、システムアーキテクチャをご覧ください。
TPU VM
```
$ gcloud compute tpus tpu-vm create shapemask-tutorial \
--zone=europe-west4-a \
--accelerator-type=v3-8 \
--version=tpu-vm-tf-2.13.0
```
コマンドフラグの説明

zone

Cloud TPU を作成するゾーン。

accelerator-type
作成する Cloud TPU のタイプ。
version

Cloud TPU ランタイムのバージョン。
TPU ノード
```
$ gcloud compute tpus execution-groups create  \
 --zone=europe-west4-a \
 --name=shapemask-tutorial \
 --accelerator-type=v3-8 \
 --machine-type=n1-standard-8 \
 --disk-size=300 \
 --tf-version=2.12.0
```
コマンドフラグの説明

zone
Cloud TPU を作成するゾーン。
name

TPU 名。指定しない場合、デフォルトでユーザー名が使用されます。

accelerator-type

作成する Cloud TPU のタイプ。

machine-type
作成する Compute Engine VM のマシンタイプ。
disk-size

Compute Engine VM のルートボリュームサイズ（GB）。

tf-version
Tensorflow gcloud のバージョンが VM にインストールされます。
注: 複数のプロジェクトがある場合は、--project フラグでプロジェクト ID を指定する必要があります。

gcloud コマンドの詳細については、gcloud リファレンスをご覧ください。

注: プロジェクトで初めて gcloud compute tpus を実行する場合、SSH 認証鍵の伝播や API の始動などの起動タスクの実行に約 5 分かかります。
自動的に Compute Engine インスタンスにログインしない場合は、次の ssh コマンドを実行してログインします。VM にログインすると、シェルプロンプトが username@projectname から username@vm-name に変わります。
TPU VM
```
gcloud compute tpus tpu-vm ssh shapemask-tutorial --zone=europe-west4-a
```
TPU ノード
```
gcloud compute ssh shapemask-tutorial --zone=europe-west4-a
```
重要なポイント: これ以降、接頭辞 (vm) $ は Compute Engine VM インスタンスでコマンドを実行する必要があることを意味します。

これらの手順を続行する場合は、VM セッションウィンドウで、(vm)$ で始まる各コマンドを実行します。

TensorFlow の要件をインストールします。

TPU VM

(vm)$ pip3 install -r /usr/share/tpu/models/official/requirements.txt

TPU ノード

(vm)$ pip3 install -r /usr/share/models/official/requirements.txt

トレーニングスクリプトには、追加のパッケージが必要です。この時点でインストールしておきます。
TPU VM
```
(vm)$ pip3 install --user tensorflow-model-optimization>=0.1.3
```
TPU ノード
```
(vm)$ pip3 install --user tensorflow-model-optimization>=0.1.3
```
ストレージバケット名の変数を設定します。bucket-name は、ストレージバケットの名前で置き換えます。
```
(vm)$ export STORAGE_BUCKET=gs://bucket-name
```

Cloud TPU 名の変数を設定します。

TPU VM

(vm)$ export TPU_NAME=local

TPU ノード

(vm)$ export TPU_NAME=shapemask-tutorial

PYTHONPATH 環境変数を設定します。

TPU VM

(vm)$ export PYTHONPATH="/usr/share/tpu/models:${PYTHONPATH}"

TPU ノード

(vm)$ export PYTHONPATH="${PYTHONPATH}:/usr/share/models"

モデルが保存されているディレクトリに移動します。

TPU VM

(vm)$ cd /usr/share/tpu/models/official/legacy/detection

TPU ノード

(vm)$ cd /usr/share/models/official/legacy/detection

必要となる環境変数を追加します。

(vm)$ export RESNET_CHECKPOINT=gs://cloud-tpu-checkpoints/retinanet/resnet50-checkpoint-2018-02-07
(vm)$ export DATA_DIR=${STORAGE_BUCKET}/coco
(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 MODEL_DIR=${STORAGE_BUCKET}/shapemask

ShapeMask モデルをトレーニングします。

次のスクリプトは、わずか 100 ステップのサンプルトレーニングを行い、v3-8 TPU で完了するまでに約 10 分かかります。収束するようにトレーニングするには、v3-8 TPU では約 22,500 ステップ、約 6 時間かかります。
```
(vm)$ python3 main.py \
  --strategy_type=tpu \
  --tpu=${TPU_NAME} \
  --model_dir=${MODEL_DIR} \
  --mode=train \
  --model=shapemask \
  --params_override="{train: {total_steps: 100, learning_rate: {init_learning_rate: 0.08, learning_rate_levels: [0.008, 0.0008], learning_rate_steps: [15000, 20000], }, checkpoint: { path: ${RESNET_CHECKPOINT},prefix: resnet50}, train_file_pattern: ${TRAIN_FILE_PATTERN}}, shapemask_head: {use_category_for_mask: true, shape_prior_path: ${SHAPE_PRIOR_PATH}}, shapemask_parser: {output_size: [640, 640]}}"
```
コマンドフラグの説明

strategy_type

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

tpu

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

model_dir

モデルのトレーニング中にチェックポイントとサマリーが保存されるディレクトリフォルダがない場合は、プログラムによって作成されます。Cloud TPU を使用する場合、model_dir は Cloud Storage のパスにする必要があります（gs://...）。以前に作成されたチェックポイントの Cloud TPU のサイズと TensorFlow のバージョンが同じであれば、既存のフォルダを再利用して現在のチェックポイントデータを読み込み、追加のチェックポイントを保存できます。

mode
モデルをトレーニングするには train、モデルを評価するには eval に設定します。
params_override

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

トレーニングが完了すると、次のようなメッセージが表示されます。
```
Train Step: 100/100  / loss = {'total_loss': 10.815635681152344,
'loss': 10.815635681152344, 'retinanet_cls_loss': 1.4915691614151,
'l2_regularization_loss': 4.483549118041992,
'retinanet_box_loss': 0.013074751943349838,
'shapemask_prior_loss': 0.17314358055591583,
'shapemask_coarse_mask_loss': 1.953366756439209,
'shapemask_fine_mask_loss': 2.216097831726074, 'model_loss': 6.332086086273193,
'learning_rate': 0.021359999} / training metric = {'total_loss': 10.815635681152344,
'loss': 10.815635681152344, 'retinanet_cls_loss': 1.4915691614151,
'l2_regularization_loss': 4.483549118041992,
'retinanet_box_loss': 0.013074751943349838,
'shapemask_prior_loss': 0.17314358055591583,
'shapemask_coarse_mask_loss': 1.953366756439209,
'shapemask_fine_mask_loss': 2.216097831726074,
'model_loss': 6.332086086273193, 'learning_rate': 0.021359999}
```
ShapeMask モデルを評価するスクリプトを実行します。これには、v3-8 TPU では約 10 分を要します。
```
(vm)$ python3 main.py \
    --strategy_type=tpu \
    --tpu=${TPU_NAME} \
    --model_dir=${MODEL_DIR} \
    --checkpoint_path=${MODEL_DIR} \
    --mode=eval_once \
    --model=shapemask \
    --params_override="{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: [640, 640]}}"
```
コマンドフラグの説明

strategy_type

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

tpu

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

model_dir

モデルのトレーニング中にチェックポイントとサマリーが保存されるディレクトリフォルダがない場合は、プログラムによって作成されます。Cloud TPU を使用する場合、model_dir は Cloud Storage のパスにする必要があります（gs://...）。以前に作成されたチェックポイントの Cloud TPU のサイズと TensorFlow のバージョンが同じであれば、既存のフォルダを再利用して現在のチェックポイントデータを読み込み、追加のチェックポイントを保存できます。

mode

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

params_override

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

トレーニングが完了すると、次のようなメッセージが表示されます。
```
DONE (t=5.47s).
 Average Precision  (AP) @[ IoU=0.50:0.95 | area=   all | maxDets=100 ] = 0.000
 Average Precision  (AP) @[ IoU=0.50      | area=   all | maxDets=100 ] = 0.000
 Average Precision  (AP) @[ IoU=0.75      | area=   all | maxDets=100 ] = 0.000
 Average Precision  (AP) @[ IoU=0.50:0.95 | area= small | maxDets=100 ] = 0.000
 Average Precision  (AP) @[ IoU=0.50:0.95 | area=medium | maxDets=100 ] = 0.000
 Average Precision  (AP) @[ IoU=0.50:0.95 | area= large | maxDets=100 ] = 0.000
 Average Recall     (AR) @[ IoU=0.50:0.95 | area=   all | maxDets=  1 ] = 0.000
 Average Recall     (AR) @[ IoU=0.50:0.95 | area=   all | maxDets= 10 ] = 0.000
 Average Recall     (AR) @[ IoU=0.50:0.95 | area=   all | maxDets=100 ] = 0.000
 Average Recall     (AR) @[ IoU=0.50:0.95 | area= small | maxDets=100 ] = 0.000
 Average Recall     (AR) @[ IoU=0.50:0.95 | area=medium | maxDets=100 ] = 0.000
 Average Recall     (AR) @[ IoU=0.50:0.95 | area= large | maxDets=100 ] = 0.000
```
これで、単一デバイスのトレーニングと評価が完了しました。現在の単一デバイスの TPU リソースを削除するには、次の手順を使用します。
Compute Engine インスタンスから接続を切断します。
```
(vm)$ exit
```
プロンプトが username@projectname に変わります。これは、現在、Cloud Shell 内にいることを示しています。
TPU リソースを削除します。
TPU VM
```
$ gcloud compute tpus tpu-vm delete shapemask-tutorial \
--zone=europe-west4-a
```
コマンドフラグの説明

zone

Cloud TPU が存在するゾーン。
TPU ノード
```
$ gcloud compute tpus execution-groups delete shapemask-tutorial \
--tpu-only \
--zone=europe-west4-a
```
コマンドフラグの説明

tpu-only

Cloud TPU のみを削除します。VM は引き続き使用できます。

zone

削除する TPU を含むゾーン。
この時点で、このチュートリアルを終了してクリーンアップすることも、Cloud TPU Pod でのモデルの実行を続行して調べることもできます。

Cloud TPU Pod でモデルのスケーリングする

Cloud TPU Pod でモデルをトレーニングするには、トレーニングスクリプトに変更を加える必要がある場合があります。詳細については、TPU Pod でのトレーニングをご覧ください。

TPU Pod のトレーニング

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

Cloud Shell を開く
プロジェクト ID の変数を作成します。
```
export PROJECT_ID=project-id
```
Cloud TPU を作成するプロジェクトを使用するように Google Cloud CLI を構成します。
```
gcloud config set project ${PROJECT_ID}
```
このコマンドを新しい Cloud Shell VM で初めて実行すると、Authorize Cloud Shell ページが表示されます。ページの下部にある [Authorize] をクリックして、gcloud に認証情報を使用した GCP API の呼び出しを許可します。
Cloud TPU プロジェクトのサービスアカウントを作成します。

サービスアカウントにより、Cloud TPU サービスが他の Google Cloud Platform サービスにアクセスできるようになります。
```
gcloud beta services identity create --service tpu.googleapis.com --project $PROJECT_ID
```
このコマンドでは、Cloud TPU サービスアカウントを次の形式で返します。
```
service-PROJECT_NUMBER@cloud-tpu.iam.gserviceaccount.com
```
次のコマンドを使用して Cloud Storage バケットを作成するか、以前にプロジェクト用に作成したバケットを使用します。

重要: Cloud TPU リソースと Cloud Storage バケットを同じリージョン / ゾーンに設定して、ネットワークレイテンシとネットワークコストを削減してください。Cloud TPU は、リージョン内のサブディビジョンである特定のゾーンに配置されます。
```
gsutil mb -p ${PROJECT_ID} -c standard -l europe-west4 gs://bucket-name
```
以前に COCO データセットを準備してストレージバケットに移動した場合は、これを再び Pod トレーニングに使用できます。COCO データセットをまだ準備していない場合は、今すぐ準備して、ここに戻って Pod のトレーニングを設定してください。
Cloud TPU Pod を起動する

このチュートリアルでは、v3-32 Pod を指定します。他の Pod オプションについては、利用可能な TPU タイプのページをご覧ください。
TPU VM
注: 現在 TPU Pod を作成するのに十分な容量がない場合は、キューに格納されたリソースを使用してリクエストをキューに入れることができます。キューに格納されたリソースを使用すると、利用可能になったときに容量を受信できます。Cloud TPU リソースをキューに登録されたリソースとしてリクエストするには、代わりに gcloud alpha compute tpus queued-resources create コマンドを使用します。詳細については、キューに格納されたリソースの管理をご覧ください。
```
$ gcloud compute tpus tpu-vm create shapemask-tutorial \
--zone=europe-west4-a \
--accelerator-type=v3-32 \
--version=tpu-vm-tf-2.13.0-pod
```
コマンドフラグの説明

zone

Cloud TPU を作成するゾーン。

accelerator-type

作成する Cloud TPU のタイプ。

version

Cloud TPU ランタイムのバージョン。

注: プロジェクトで初めて gcloud を実行する場合、SSH 認証鍵の伝播や API の始動などの起動タスクの実行に約 5 分かかります。
TPU ノード
```
$ gcloud compute tpus execution-groups create  \
 --zone=europe-west4-a \
 --name=shapemask-tutorial \
 --accelerator-type=v3-32 \
 --machine-type=n1-standard-8 \
 --disk-size=300 \
 --tf-version=2.12.0
```
コマンドフラグの説明

zone

Cloud TPU を作成するゾーン。

name

TPU 名。指定しない場合、デフォルトでユーザー名が使用されます。

accelerator-type

作成する Cloud TPU のタイプ。

machine-type

作成する Compute Engine VM のマシンタイプ。

disk-size

Compute Engine VM のルートボリュームサイズ（GB）。

tf-version

Tensorflow gcloud のバージョンが VM にインストールされます。

注: 複数のプロジェクトがある場合は、--project フラグでプロジェクト ID を指定する必要があります。
自動的に Compute Engine インスタンスにログインしない場合は、次の ssh コマンドを実行してログインします。VM にログインすると、シェルプロンプトが username@projectname から username@vm-name に変わります。
TPU VM
```
gcloud compute tpus tpu-vm ssh shapemask-tutorial --zone=europe-west4-a
```
TPU ノード
```
gcloud compute ssh shapemask-tutorial --zone=europe-west4-a
```
重要なポイント: これ以降、接頭辞 (vm) $ は Compute Engine VM インスタンスでコマンドを実行する必要があることを意味します。

これらの手順を続行する場合は、VM セッションウィンドウで、(vm)$ で始まる各コマンドを実行します。

TensorFlow の要件をインストールします。

TPU VM

(vm)$ pip3 install -r /usr/share/tpu/models/official/requirements.txt

TPU ノード

(vm)$ pip3 install -r /usr/share/models/official/requirements.txt

トレーニングスクリプトには、追加のパッケージが必要です。この時点でインストールしておきます。
TPU VM
```
(vm)$ pip3 install --user tensorflow-model-optimization>=0.1.3
```
TPU ノード
```
(vm)$ pip3 install --user tensorflow-model-optimization>=0.1.3
```
次の環境変数を設定します。bucket-name を Cloud Storage バケットの名前に置き換えます。
```
(vm)$ export STORAGE_BUCKET=gs://bucket-name
```
トレーニングアプリケーションでは、Cloud Storage でトレーニングデータにアクセスできる必要があります。また、トレーニングアプリケーションは、Cloud Storage バケットを使用してトレーニング中にチェックポイントを保存します。

必要なトレーニング変数を更新します。

(vm)$ export MODEL_DIR=${STORAGE_BUCKET}/shapemask-pods
(vm)$ export DATA_DIR=${STORAGE_BUCKET}/coco
(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)$ export SHAPE_PRIOR_PATH=gs://cloud-tpu-checkpoints/shapemask/kmeans_class_priors_91x20x32x32.npy

必要な環境変数を次のように設定します。

TPU VM

(vm)$ export PYTHONPATH="/usr/share/tpu/models:${PYTHONPATH}"
(vm)$ export TPU_LOAD_LIBRARY=0

TPU ノード

(vm)$ export PYTHONPATH="${PYTHONPATH}:/usr/share/models"

モデルが保存されているディレクトリに移動します。

TPU VM

(vm)$ cd /usr/share/tpu/models/official/legacy/detection

TPU ノード

(vm)$ cd /usr/share/models/official/legacy/detection

Pod のトレーニングを開始します。

以下のサンプルトレーニングは、わずか 20 ステップで行われ、v3-32 TPU ノードで完了するまでに約 10 分かかります。収束するようにトレーニングするには、v3-32 TPU Pod では約 11,250 ステップ、約 2 時間かかります。
```
(vm)$ python3 main.py \
 --strategy_type=tpu \
 --tpu=${TPU_NAME} \
 --model_dir=${MODEL_DIR} \
 --mode=train \
 --model=shapemask \
 --params_override="{train: { batch_size: 128, iterations_per_loop: 500, total_steps: 20, learning_rate: {'learning_rate_levels': [0.008, 0.0008], 'learning_rate_steps': [10000, 13000] }, 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}}, shapemask_head: {use_category_for_mask: true, shape_prior_path: ${SHAPE_PRIOR_PATH}} }"
```
コマンドフラグの説明

strategy_type

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

tpu

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

model_dir

モデルのトレーニング中にチェックポイントとサマリーが保存されるディレクトリフォルダがない場合は、プログラムによって作成されます。Cloud TPU を使用する場合、model_dir は Cloud Storage のパスにする必要があります（gs://...）。以前に作成されたチェックポイントの Cloud TPU のサイズと TensorFlow のバージョンが同じであれば、既存のフォルダを再利用して現在のチェックポイントデータを読み込み、追加のチェックポイントを保存できます。

mode

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

params_override

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

クリーンアップ

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

Compute Engine インスタンスとの接続を切断していない場合は切断します。
```
(vm)$ exit
```
プロンプトが username@projectname に変わります。これは、現在、Cloud Shell 内にいることを示しています。
Cloud TPU と Compute Engine リソースを削除します。リソースの削除に使用するコマンドは、TPU VM または TPU ノードのどちらを使用するかによって異なります。詳細については、システムアーキテクチャをご覧ください。
TPU VM
```
$ gcloud compute tpus tpu-vm delete shapemask-tutorial \
--zone=europe-west4-a
```
TPU ノード
```
$ gcloud compute tpus execution-groups delete shapemask-tutorial \
--zone=europe-west4-a
```
gcloud compute tpus execution-groups list を実行して、リソースが削除されたことを確認します。削除には数分かかることがあります。次のコマンドの出力には、このチュートリアルで作成したリソースを含めないでください。
```
$ gcloud compute tpus execution-groups list --zone=europe-west4-a
```
次に示すように gsutil を実行します。bucket-name の部分は、このチュートリアルで作成した Cloud Storage バケット名に置き換えてください。

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

次のステップ

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

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

別のベースを使用する

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

Cloud TPU（TF 2.x）での ShapeMask のトレーニング

目標

費用

始める前に

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

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

コマンドフラグの説明

TPU リソースを起動してモデルをトレーニングする

TPU VM

コマンドフラグの説明

TPU ノード

コマンドフラグの説明

TPU VM

TPU ノード

TPU VM

TPU ノード

TPU VM

TPU ノード

TPU VM

TPU ノード

TPU VM

TPU ノード

TPU VM

TPU ノード

コマンドフラグの説明

コマンドフラグの説明

TPU VM

コマンドフラグの説明

TPU ノード

コマンドフラグの説明

Cloud TPU Pod でモデルのスケーリングする

TPU Pod のトレーニング

TPU VM

コマンドフラグの説明

TPU ノード

コマンドフラグの説明

TPU VM

TPU ノード

TPU VM

TPU ノード

TPU VM

TPU ノード

TPU VM

TPU ノード

TPU VM

TPU ノード

コマンドフラグの説明

クリーンアップ

TPU VM

TPU ノード

次のステップ

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

別のベースを使用する