ImageNet データセットのダウンロード、前処理、アップロード

このドキュメントでは、Cloud TPU VM アーキテクチャで使用する ImageNet データセットをダウンロード、前処理、アップロードする方法を説明します。

ImageNet は画像データベースです。このデータベース内では画像が階層に編成されていて、階層の各ノードを数百、数千もの画像で表しています。

ImageNet データベースのサイズによっては、モデルのトレーニングにはかなりの時間がかかる場合があります。代替手段として、このデータセットの fake_imagenet と呼ばれるデモバージョンを使用する方法もあります。このデモバージョンを使用すると、モデルのテストが可能になり、同時に、完全な ImageNet データベースの使用に伴うストレージ要件と時間要件が削減されます。

完全版の ImageNet データセットの前処理

ImageNet データセットは、トレーニングデータ、検証データ、画像ラベルの 3 つの部分で構成されます。

トレーニングデータには 1,000 個のカテゴリと 120 万個の画像が含まれており、ダウンロードしやすいようにパッケージ化されています。検証データとテストデータは、ImageNet トレーニングデータには含まれていません（重複は削除されています）。

検証データとテストデータは、Flickr やその他の検索エンジンから収集された 150,000 枚の写真で構成され、1,000 個のオブジェクトカテゴリの存在または不在のラベルが付いています。1, 000 個のオブジェクトカテゴリには ImageNet の内部ノードとリーフノードの両方が含まれますが、両者は重複しません。ラベルの付いた 50,000 枚の画像のランダムなサブセットが、1,000 個のカテゴリのリストとともに検証データとしてリリースされています。残りの画像は評価用に使用され、ラベルなしでリリースされています。

完全な ImageNet データセットの前処理手順

機械学習モデルで使用する ImageNet の完全なデータセットを準備するには、次の 5 つの手順を行います。

ダウンロード先に空き容量があることを確認します。
ターゲットディレクトリを設定する
ImageNet サイトに登録して、ダウンロード権限をリクエストします。
データセットをローカルディスクまたは VM インスタンスにダウンロードします。

注: Imagenet データセットを VM インスタンスにダウンロードするには、ローカルマシンにダウンロードする場合よりも大幅に時間がかかります（約 7 時間に対して 40 時間）。データセットをローカルマシンにダウンロードする場合、前処理のためにファイルを VM インスタンスにコピーする必要があります。その後、このファイルを使用してモデルをトレーニングする前に、Cloud Storage にアップロードする必要があります。トレーニングファイルと検証ファイルをローカルマシンから VM インスタンスにコピーするには約 13 時間かかります。データセットを VM インスタンスにダウンロードすることをおすすめします。
前処理スクリプトとアップロードスクリプトを実行します。

容量の要件を確認する

データセットをローカルマシンにダウンロードする場合でも、VM インスタンスにダウンロードする場合でも、ダウンロード先に約 300 GB の空き容量が必要です。

TPU VM のデフォルトのディスク割り当ては 100 GB です。TPU VM へのダウンロードには 300 GB が必要なため、TPU VM インスタンスにダウンロードする場合は、永続ディスクと 200 GB の追加容量を追加してからダウンロードする必要があります。TPU VM の場合、df -ha コマンドを実行して空き容量を確認できます。

永続ディスクを追加するときは、次のことを行ってください。

VM の削除時にディスクが削除されるように、[インスタンスを削除したときの動作] を [ディスクを削除] に設定します。
新しいディスクのパスをメモします。例: /mnt/disks/mnt-dir。

ターゲットディレクトリを設定する

ローカルマシンまたは VM インスタンスで、ダウンロードしたデータを格納するディレクトリ構造を設定します。

ダウンロードターゲット（ローカルマシンまたは TPU VM）のホームディレクトリの下に imagenet などのディレクトリを作成します。
```
mkdir imagenet
```
このディレクトリに、train と validation という 2 つのサブディレクトリを作成します。
```
mkdir imagenet/train
mkdir imagenet/validation
```
imagenet ディレクトリを IMAGENET_HOME としてエクスポートします。
```
export IMAGENET_HOME=~/imagenet
```

データセットをダウンロードするための登録と権限のリクエストを行う

Imagenet ウェブサイトに登録します。ImageNet が登録を確認して確認メールを送信するまで、データセットをダウンロードすることはできません。数日以内に確認メールが届かない場合は、ImageNet サポートに連絡して、登録が確認されていない理由を確認してください。登録が確認されたら、データセットをダウンロードできます。ImageNet データセットを使用する Cloud TPU チュートリアルでは、ImageNet Large Scale Visual Recognition Challenge 2012（ILSVRC2012）の画像を使用します。

ImageNet データセットをダウンロードする

LSRVC 2012 ダウンロードサイトから、ページの [Images] セクションに移動し、[Training images (Task 1 & 2)] を右クリックします。トレーニングセットの大部分をダウンロードするための URL。このURL を保存します。

[Training images (Task 3)] を右クリックして、2 番目のトレーニングセットの URL を取得します。このURL を保存します。

"Validation images (all tasks)" を右クリックして、検証データセットの URL を取得します。このURL を保存します。

ImageNet ファイルをローカルマシンにダウンロードする場合、ローカルマシン上のディレクトリを、VM インスタンス上の対応する $IMAGENET_HOME ディレクトリにコピーする必要があります。ImageNet データセットをローカルホストから VM インスタンスにコピーするには、約 13 時間かかります。

ImageNet データセットを VM にコピーする前に、VM インスタンスの名前を特定する必要があります。これを行うには、SSH を使用して TPU VM に接続します。 VM インスタンス名は、@ 記号の後にコマンドプロンプトに表示されます。

次のコマンドを使用して、ローカルマシン上の ~/imagenet の下にあるファイルを、VM 上の $IMAGENET_HOME にコピーします。
```
gcloud compute scp --recurse $IMAGENET_HOME username@vm-instance-name:~/imagenet
```
$IMAGENET_HOME から、保存した URL を使用して「Training images (Task 1 & 2)」ファイルをダウンロードします。

「Training images (Task 1 & 2)」は、大規模なトレーニングセットです。これは 138 GB で、Cloud Shell を使用して TPU VM にダウンロードする場合、ダウンロードは約 40 時間かかります。Cloud Shell と VM との接続が失われた場合は、コマンドの前に nohup を付けるか、screen を使用します。
```
cd $IMAGENET_HOME \
nohup wget https://image-net.org/data/ILSVRC/2012/ILSVRC2012_img_train.tar
```
URL は変更されている可能性があるため、以前に「Training images (Task 1 & 2)」用に保存した URL に置き換えます。
次のコマンドを使用して、個々のトレーニングディレクトリを $IMAGENET_HOME/train ディレクトリに抽出します。抽出には 1～3 時間かかります。
```
tar xf $IMAGENET_HOME/ILSVRC2012_img_train.tar -C $IMAGENET_HOME/train
```
次のスクリプトに示すように、$IMAGENET_HOME/train ディレクトリにある個々のトレーニング tar ファイルを抽出します。
```
cd `$IMAGENET_HOME/train`

for f in *.tar; do
 d=`basename $f .tar`
 mkdir $d
 tar xf $f -C $d
done
```
抽出した後 tar ファイルを削除して、ディスク容量を解放します。
$IMAGENET_HOME から、保存した URL を使用して「Training images (Task 3)」ファイルをダウンロードします。

「Training images (Task 3)」ファイルは 728 MB で、ダウンロードにかかる時間は数分であるため、Cloud Shell の接続が切断されることを考慮する必要はありません。
```
wget https://image-net.org/data/ILSVRC/2012/ILSVRC2012_img_train_t3.tar
```
URL は変更されている可能性があるため、以前に「Training images (Task 3)」用に保存した URL に置き換えます。
次のコマンドを使用して、個々のトレーニングディレクトリを $IMAGENET_HOME/train ディレクトリに抽出します。
```
tar xf $IMAGENET_HOME/ILSVRC2012_img_train_t3.tar -C $IMAGENET_HOME/train
```
次のスクリプトに示すように、$IMAGENET_HOME/train ディレクトリにある個々のトレーニング tar ファイルを抽出します。
```
cd `$IMAGENET_HOME/train`

for f in *.tar; do
 d=`basename $f .tar`
 mkdir $d
 tar xf $f -C $d
done
```
抽出した後 tar ファイルを削除して、ディスク容量を解放します。
$IMAGENET_HOME から、保存した URL を使用して「Validation images (all tasks)」ファイルをダウンロードします。

"Validation images (all tasks)" ファイルをダウンロードすると、Cloud Shell が切断される可能性があります。nohup または screen を使用すると、Cloud Shell の切断を防ぐことができます。
```
wget https://image-net.org/data/ILSVRC/2012/ILSVRC2012_img_val.tar
```
URL は変更されている可能性があるため、以前に [Validation images (all tasks)] で保存した URL を URL に置き換えます。

このダウンロードには約 30 分かかります。
次のコマンドを使用して、個々の検証ファイルを $IMAGENET_HOME/validation ディレクトリに抽出します。
```
tar xf $IMAGENET_HOME/ILSVRC2012_img_val.tar -C $IMAGENET_HOME/validation
```
検証ファイルをローカルマシンにダウンロードした場合は、ローカルマシン上の $IMAGENET_HOME/validation ディレクトリを VM インスタンスの $IMAGENET_HOME/validation ディレクトリにコピーする必要があります。このコピーオペレーションには約 30 分かかります。
ラベルファイルをダウンロードします。
```
wget -O $IMAGENET_HOME/synset_labels.txt \
https://raw.githubusercontent.com/tensorflow/models/master/research/slim/datasets/imagenet_2012_validation_synset_labels.txt
```
ラベルファイルをローカルマシンにダウンロードした場合は、VM インスタンス上で $IMAGENET_HOME するために、ローカルマシン上の $IMAGENET_HOME ディレクトリにコピーする必要があります。このコピーオペレーションは数秒で完了します。

トレーニングサブディレクトリ名（例: n03062245）は「WordNet ID」（wnid）です。ImageNet API は、synset_labels.txt ファイル内で WordNet ID の関連する検証ラベルへのマッピングを示します。このコンテキストの synset は、視覚的に似たグループの画像です。

Imagenet データセットを処理し、必要に応じて Cloud Storage にアップロードする

GitHub から imagenet_to_gcs.py スクリプトをダウンロードします。

wget https://raw.githubusercontent.com/tensorflow/tpu/master/tools/datasets/imagenet_to_gcs.py

データセットを Cloud Storage にアップロードする場合は、ImageNet データセットをアップロードするストレージバケットのロケーションを指定します。
```
export STORAGE_BUCKET=gs://bucket-name
```
データセットをローカルマシンまたは VM にアップロードする場合は、データセットを保持するデータディレクトリを指定します。
```
(vm)$ export DATA_DIR=$IMAGENET_HOME/dataset-directory
```
次のライブラリをマシンまたは仮想環境にインストールします。
```
pip3 install google-cloud-storage
pip3 install tensorflow
```
スクリプトを実行して、生データセットを TFRecord として前処理し、次のコマンドを使用して Cloud Storage にアップロードします。
注: Cloud Storage にアップロードしない場合は、--nogcs_upload を別のパラメータとして指定し、--project パラメータと --gcs_output_path パラメータをそのままにしておきます。
```
 python3 imagenet_to_gcs.py \
  --project=$PROJECT \
  --gcs_output_path=$STORAGE_BUCKET  \
  --raw_data_dir=$IMAGENET_HOME \
  --local_scratch_dir=$IMAGENET_HOME/tf_records
```

このスクリプトでは、以下の形式の一連のディレクトリ（トレーニングと検証の両方）が生成されます。

${DATA_DIR}/train-00000-of-01024
${DATA_DIR}/train-00001-of-01024
...
${DATA_DIR}/train-01023-of-01024

と

${DATA_DIR}/validation-00000-of-00128
${DATA_DIR}/validation-00001-of-00128
...
${DATA_DIR}/validation-00127-of-00128

Cloud バケットにデータがアップロードされたら、モデルを実行して --data_dir=${DATA_DIR} を設定します。