轉換圖片分類資料集，以便用於 Cloud TPU

本教學課程說明如何使用圖片分類資料轉換器範例指令碼，將原始圖片分類資料集轉換為 TFRecord 格式，用於訓練 Cloud TPU 模型。

與將每張圖片讀取為個別檔案相比，TFRecord 可更有效率地從 Cloud Storage 讀取大型檔案。您可以在使用 tf.data.Dataset 管道的任何位置使用 TFRecord。

如要進一步瞭解如何使用 TFRecord，請參閱下列 TensorFlow 文件：

• TFRecord 和 tf.train.Example
• tf.data.Dataset
• tf.data：建構 TensorFlow 輸入管道
• PyTorch TFRecord 讀取器和寫入器

如果您使用 PyTorch 或 JAX 架構，且未將 Cloud Storage 用於資料集儲存空間，可能無法從 TFRecord 獲得相同優勢。

轉換總覽

GitHub 上資料轉換器存放區中的圖片分類資料夾包含 converter 指令碼、image_classification_data.py 和範例實作 simple_example.py，您可以複製及修改這些內容，自行轉換資料。

圖像分類資料轉換器範例定義了兩個類別：ImageClassificationConfig 和 ImageClassificationBuilder。這些類別定義於 tpu/tools/data_converter/image_classification_data.py 中。

ImageClassificationConfig 是抽象基礎類別，您會將 ImageClassificationConfig 子類別化，定義例項化 ImageClassificationBuilder 所需的設定。

ImageClassificationBuilder 是圖片分類資料集的 TensorFlow 資料集建構工具。這是 tdfs.core.GeneratorBasedBuilder 的子類別。這項工具會從資料集擷取資料範例，並轉換為 TFRecords。TFRecord 會寫入 ImageClassificationBuilder 的 __init__ 方法的 data_dir 參數所指定的路徑。

在 simple_example.py 中，SimpleDatasetConfig 子類別會實作 ImageClassificationConfig，定義支援的模式、圖片類別數量，以及產生器範例，產生器會針對資料集中的每個範例，產生包含圖片資料和圖片類別的字典。

main() 函式會建立隨機產生的圖片資料集，並例項化 SimpleDatasetConfig 物件，指定類別數量和磁碟上資料集的路徑。接著，main() 會例項化 ImageClassificationBuilder 物件，並傳入 SimpleDatasetConfig 例項。最後，main() 會呼叫 download_and_prepare()。呼叫這個方法時，ImageClassificationBuilder 例項會使用 SimpleDatasetConfig 實作的資料範例產生器載入每個範例，並將其儲存至一系列 TFRecord 檔案。

如需更詳細的說明，請參閱分類轉換器筆記本。

修改資料轉換範例，載入資料集

如要將資料集轉換為 TFRecord 格式，請將 ImageClassificationConfig 類別定義為下列屬性的子類別：

• num_labels：傳回圖片類別數量
• supported_modes：傳回資料集支援的模式清單 (例如：測試、訓練和驗證)
• text_label_map：傳回字典，模擬文字類別標籤與整數類別標籤之間的對應關係 (SimpleDatasetConfig 不會使用這個屬性，因為不需要對應關係)
• download_path：下載資料集的路徑 (SimpleDatasetConfig 不會使用這個屬性，example_generator 會從磁碟載入資料)

實作 example_generator 產生器函式。這個方法必須產生字典，其中包含每個範例的圖片資料和圖片類別名稱。ImageClassificationBuilder 會使用 example_generator() 函式擷取每個範例，並以 TFRecord 格式寫入磁碟。

執行資料轉換範例

注意：本節適用於 Cloud TPU API。如果是 Ironwood (TPU7x)，則必須使用 Google Kubernetes Engine (GKE)。詳情請參閱「關於 GKE 中的 TPU」。

1. 請使用下列指令來建立 Cloud Storage 值區：

   注意： 在下列指令中，請將 bucket-name 替換為您要指派給 bucket 的名稱。

   gcloud storage buckets create gs://bucket-name --project=your-project-id --location=us-central2

2. 使用 gcloud 指令啟動 Cloud TPU。

   $ gcloud compute tpus tpu-vm create tpu-name \
       --zone=us-central2-b \
       --accelerator-type=v4-8 \
       --version=tpu-vm-tf-2.17.1-pjrt

   指令旗標說明

   zone

   您要建立 Cloud TPU 的區域。

   accelerator-type

   加速器類型會指定您要建立的 Cloud TPU 版本和大小。 如要進一步瞭解各個 TPU 版本支援的加速器類型，請參閱 TPU 版本。

   version

   Cloud TPU 軟體版本。

3. 使用 SSH 連線至 TPU：

   $ gcloud compute tpus tpu-vm ssh tpu-name --zone=us-central2-b

   連線至 TPU 時，殼層提示會從 username@projectname 變更為 username@vm-name。

4. 安裝必要套件。

   (vm)$ pip3 install opencv-python-headless pillow
   (vm)$ pip3 install tensorflow-datasets

5. 建立指令碼使用的下列環境變數。

   (vm)$ export STORAGE_BUCKET=gs://bucket-name
   (vm)$ export CONVERTED_DIR=$HOME/tfrecords
   (vm)$ export GENERATED_DATA=$HOME/data
   (vm)$ export GCS_CONVERTED=$STORAGE_BUCKET/data_converter/image_classification/tfrecords
   (vm)$ export GCS_RAW=$STORAGE_BUCKET/image_classification/raw
   (vm)$ export PYTHONPATH="$PYTHONPATH:/usr/share/tpu/models"

6. 下載 TensorFlow TPU 存放區。

   (vm)$ cd /usr/share/
   (vm)$ git clone https://github.com/tensorflow/tpu.git
   (vm)$ cd tpu/tools/data_converter

在虛擬資料集上執行資料轉換器

simple_example.py 指令碼位於資料轉換器範例的 image_classification 資料夾中。使用下列參數執行指令碼，即可產生一組偽造圖片，並將其轉換為 TFRecord。

(vm)$ python3 image_classification/simple_example.py \
  --num_classes=1000 \
  --data_path=$GENERATED_DATA \
  --generate=True \
  --num_examples_per_class_low=10 \
  --num_examples_per_class_high=11 \
  --save_dir=$CONVERTED_DIR

對其中一個原始資料集執行資料轉換器

1. 為原始資料的位置建立環境變數。

   (vm)$ export GCS_RAW=gs://cloud-tpu-test-datasets/data_converter/raw_image_classification

2. 執行 simple_example.py 指令碼。

   (vm)$ python3 image_classification/simple_example.py \
   --num_classes=1000 \
   --data_path=$GCS_RAW \
   --generate=False \
   --save_dir=$CONVERTED_DIR

simple_example.py 指令碼會採用下列參數：

• num_classes 是指資料集中的類別數量。我們在此使用 1000 來比對 ImageNet 格式。
• generate 決定是否要產生原始資料。
• data_path 是指資料產生路徑 (如果為 generate=True)，或是原始資料儲存路徑 (如果為 generate=False)。
• num_examples_per_class_low 和 num_examples_per_class_high 會決定每個類別要產生多少範例。指令碼會在這個範圍內產生隨機數量的範例。
• save_dir 是指儲存 TFRecords 的位置。如要在 Cloud TPU 上訓練模型，資料必須儲存在 Cloud Storage。這可以是 Cloud Storage 或 VM 上的檔案。

將 TFRecords 重新命名並移至 Cloud Storage

以下範例使用 ResNet 模型搭配轉換後的資料。

1. 將 TFRecord 重新命名為與 ImageNet TFRecord 相同的格式：

   (vm)$ cd $CONVERTED_DIR/image_classification_builder/Simple/0.1.0/
   (vm)$ sudo apt update
   (vm)$ sudo apt install rename

   (vm)$ rename -v 's/image_classification_builder-(\w+)\.tfrecord/$1/g' *

2. 將 TFRecord 複製到 Cloud Storage：

   (vm)$ gcloud storage cp train* $GCS_CONVERTED
   (vm)$ gcloud storage cp validation* $GCS_CONVERTED

清除所用資源

注意：本節適用於 Cloud TPU API。如果是 Ironwood (TPU7x)，則必須使用 Google Kubernetes Engine (GKE)。詳情請參閱「關於 GKE 中的 TPU」。

1. 如果您尚未中斷與 Cloud TPU 的連線，請中斷連線：

   (vm)$ exit

   系統現在顯示的提示訊息應為 user@projectname，代表您位於 Cloud Shell。

2. 在 Cloud Shell 中執行 gcloud，刪除 VM 資源。

   $ gcloud compute tpus tpu-vm delete tpu-name \
     --zone=us-central2-b

3. 執行 gcloud compute tpus tpu-vm list，確認 VM 是否已刪除。 刪除作業可能需要幾分鐘才能完成。如果畫面中顯示如下回應，則代表已成功刪除執行個體。

   $ gcloud compute tpus tpu-vm list --zone=us-central2-b

   Listed 0 items.
   

4. 執行下列 gcloud CLI 指令，並將 bucket-name 替換為您為這個教學課程建立的 Cloud Storage 值區名稱：

   $ gcloud storage rm gs://bucket-name --recursive