Entraîner ShapeMask sur Cloud TPU

Ce document explique comment exécuter le modèle ShapeMask à l'aide de Cloud TPU avec l'ensemble de données COCO.

Les instructions ci-dessous supposent que vous savez comment exécuter un modèle sur Cloud TPU. Si vous débutez avec Cloud TPU, consultez le guide de démarrage rapide pour en savoir plus.

Si vous prévoyez d'effectuer l'entraînement sur une tranche de pod TPU, consultez la section Entraîner sur des pods TPU pour comprendre les modifications de paramètres requises pour les tranches de pods.

Objectifs

  • Créer un bucket Cloud Storage pour stocker votre ensemble de données et la sortie du modèle
  • Préparer l'ensemble de données COCO
  • Configurer une VM Compute Engine et un nœud Cloud TPU pour l'entraînement et l'évaluation
  • Exécuter les tâches d'entraînement et d'évaluation sur un seul Cloud TPU ou sur un pod Cloud TPU

Coûts

Ce tutoriel utilise des composants facturables de Google Cloud, dont :

  • Instance
  • Cloud TPU
  • Cloud Storage

Obtenez une estimation des coûts en fonction de votre utilisation prévue à l'aide du simulateur de coût. Les nouveaux utilisateurs de Google Cloud peuvent bénéficier d'un essai gratuit.

Avant de commencer

Avant de commencer ce tutoriel, vérifiez que votre projet Google Cloud est correctement configuré.

  1. Connectez-vous à votre compte Google.

    Si vous n'en possédez pas déjà un, vous devez en créer un.

  2. Dans Cloud Console, sur la page de sélection du projet, sélectionnez ou créez un projet Cloud.

    Accéder à la page de sélection du projet

  3. Vérifiez que la facturation est activée pour votre projet Google Cloud. Découvrez comment vérifier que la facturation est activée pour votre projet.

  4. Ce tutoriel utilise des composants facturables de Google Cloud. Consultez la grille tarifaire de Cloud TPU pour estimer vos coûts. Veillez à nettoyer les ressources que vous avez créées lorsque vous avez terminé, afin d'éviter des frais inutiles.

Si vous prévoyez d'entraîner un modèle sur une tranche de pod TPU, consultez la section Entraînement sur les pods TPU pour comprendre les modifications de paramètres nécessaires pour les tranches de pods.

Configurer vos ressources

Cette section fournit des informations sur la configuration des ressources Cloud Storage, de VM et Cloud TPU pour ce tutoriel.

  1. Ouvrez une fenêtre Cloud Shell.

    Ouvrir Cloud Shell

  2. Créez une variable pour l'ID de votre projet.

    export PROJECT_ID=project-id
    
  3. Configurez l'outil de ligne de commande gcloud pour utiliser le projet dans lequel vous souhaitez créer Cloud TPU.

    gcloud config set project ${PROJECT_ID}
    
  4. Créez un compte de service pour le projet Cloud TPU.

    gcloud beta services identity create --service tpu.googleapis.com --project $PROJECT_ID
    

    La commande renvoie un compte de service Cloud TPU au format suivant :

    service-PROJECT_NUMBER@cloud-tpu.iam.gserviceaccount.com
    

  5. Créez un bucket Cloud Storage à l'aide de la commande suivante :

    gsutil mb -p ${PROJECT_ID} -c standard -l europe-west4 -b on gs://bucket-name
    

    Ce bucket Cloud Storage stocke les données que vous utilisez pour entraîner votre modèle, ainsi que les résultats de l'entraînement. L'outil ctpu up utilisé dans ce tutoriel définit les autorisations par défaut pour le compte de service Cloud TPU que vous avez configuré à l'étape précédente. Si vous souhaitez utiliser des autorisations plus précises, vérifiez les autorisations de niveau d'accès.

    L'emplacement du bucket doit se trouver dans la même région que votre machine virtuelle (VM) et votre nœud TPU. Les VM et les nœuds TPU sont situés dans des zones spécifiques, qui sont des subdivisions au sein d'une région.

  6. Lancez une instance de VM Compute Engine.

    $ ctpu up --zone=us-central1-a \
     --vm-only \
     --disk-size-gb=300 \
     --machine-type=n1-standard-16 \
     --tf-version=2.3.1 \
     --name=shapemask-tutorial
    
  7. La configuration que vous avez spécifiée apparaît. Saisissez y pour approuver ou n pour annuler.

  8. Une fois l'exécution de la commande ctpu up terminée, vérifiez que l'invite de l'interface système est passée de username@projectname à username@vm-name. Cette modification indique que vous êtes maintenant connecté à votre VM Compute Engine.

    gcloud compute ssh shapemask-tutorial --zone=us-central1-a
    

    À mesure que vous appliquez ces instructions, exécutez chaque commande commençant par (vm)$ dans la fenêtre de session de la VM.

  9. Créez une variable d'environnement pour stocker l'emplacement de votre bucket Cloud Storage.

    (vm)$ export STORAGE_BUCKET=gs://bucket-name
    
  10. Créez une variable d'environnement pour le répertoire de données.

    (vm)$ export DATA_DIR=${STORAGE_BUCKET}/coco
    
  11. Clonez le dépôt tpu.

    (vm)$ git clone -b shapemask https://github.com/tensorflow/tpu/
    
  12. Installez les packages nécessaires au prétraitement des données.

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

Préparer l'ensemble de données COCO

  1. Exécutez le script download_and_preprocess_coco.sh pour convertir l'ensemble de données COCO en un ensemble d'enregistrements TFRecord (*.tfrecord), format attendu par l'application d'entraînement.

    (vm)$ sudo bash /usr/share/tpu/tools/datasets/download_and_preprocess_coco.sh ./data/dir/coco
    

    Cela installe les bibliothèques requises et exécute le script de prétraitement. Il génère un certain nombre de fichiers *.tfrecord dans votre répertoire de données local.

  2. Après avoir converti les données en enregistrements TFRecord, copiez-les depuis l'espace de stockage local vers votre bucket Cloud Storage à l'aide de la commande gsutil. Vous devez également copier les fichiers d'annotation. Ces fichiers vous aident à valider les performances du modèle :

    (vm)$ gsutil -m cp ./data/dir/coco/*.tfrecord ${DATA_DIR}
    (vm)$ gsutil cp ./data/dir/coco/raw-data/annotations/*.json ${DATA_DIR}
    
    .

Configurer et démarrer Cloud TPU

  1. Lancez une ressource Cloud TPU.

    Exécutez la commande suivante pour créer un Cloud TPU.

    (vm)$ ctpu up --tpu-only \
     --tf-version=2.3.1 \
     --tpu-size=v3-8 \
     --name=shapemask-tutorial
    
  2. La configuration que vous avez spécifiée apparaît. Saisissez y pour approuver ou n pour annuler.

    Le message suivant s'affiche : Operation success; not ssh-ing to Compute Engine VM due to --tpu-only flag. Vous pouvez ignorer ce message puisque vous avez déjà effectué la propagation de clé SSH.

  3. Ajoutez une variable d'environnement pour le nom du Cloud TPU.

    (vm)$ export TPU_NAME=shapemask-tutorial
    

Configurer et démarrer l'entraînement de Cloud TPU

  1. Exécutez la commande suivante pour créer un Cloud TPU.

    (vm)$ ctpu up --tpu-only \
      --tpu-size=v3-8 \
      --zone=us-central1-a \
      --name=shapemask-tutorial \
      --tf-version=2.3.1
    Réglage Description
    tpu-size Spécifie la taille du Cloud TPU. Ce tutoriel utilise un TPU v3-8 pour les tâches d'entraînement et d'évaluation d'un appareil unique.
    zone Zone dans laquelle vous prévoyez de créer votre Cloud TPU. Il doit s'agir de la même zone que celle utilisée pour la VM Compute Engine. Par exemple : us-central1-a
    tf-version La version de Tensorflow "ctpu" est installée sur la VM.
  2. La configuration que vous avez spécifiée apparaît. Saisissez y pour approuver ou n pour annuler.

    Le message suivant s'affiche : Operation success; not ssh-ing to Compute Engine VM due to --tpu-only flag. Vous pouvez ignorer ce message puisque vous avez déjà effectué la propagation de clé SSH.

  3. Ajoutez une variable d'environnement pour le nom du Cloud TPU.

    (vm)$ export TPU_NAME=shapemask-tutorial
    

Exécuter l'entraînement et l'évaluation

Le script suivant exécute un exemple d'entraînement de 100 étapes seulement et dure environ six minutes sur un TPU v3-8. L'entraînement à la conversion nécessite environ 22 500 étapes et environ 6 heures sur un TPU v3-8.

  1. Ajoutez des variables d'environnement obligatoires :

    (vm)$ export PYTHONPATH="${PYTHONPATH}:/usr/share/models"
    (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
    (vm)$ export MODEL_DIR=${STORAGE_BUCKET}/shapemask
    
  2. Exécutez la commande suivante pour entraîner le modèle ShapeMask :

    (vm)$ python3 /usr/share/models/official/vision/detection/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}},  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]}}"
    
    Réglage Description
    tpu Spécifie le nom du Cloud TPU. Cette valeur est définie en spécifiant la variable d'environnement (TPU_NAME).
    model_dir Spécifie le répertoire dans lequel sont stockés les points de contrôle et les résumés lors de l'entraînement du modèle. Si ce dossier est absent, le programme le crée. Lorsque vous utilisez un Cloud TPU, le paramètre model_dir doit être un chemin d'accès à Cloud Storage (`gs://...`). Vous pouvez réutiliser un dossier existant pour charger les données de point de contrôle actuelles et pour stocker des points de contrôle supplémentaires tant que les précédents ont été créés à l'aide d'un TPU de la même taille et de la même version de TensorFlow.
    RESNET_CHECKPOINT Spécifie un point de contrôle pré-entraîné. ShapeMask nécessite un modèle de classification d'images pré-entraîné (tel que ResNet) en tant que réseau backbone. Cet exemple utilise un point de contrôle pré-entraîné créé à l'aide du modèle de démonstration ResNet. Si vous le souhaitez, vous pouvez également entraîner votre propre modèle ResNet et spécifier un point de contrôle à partir du répertoire de celui-ci.
  3. Exécutez l'évaluation :

    (vm)$ python3 /usr/share/models/official/vision/detection/main.py \
    --strategy_type=tpu \
    --tpu=${TPU_NAME} \
    --model_dir=${MODEL_DIR} \
    --mode=eval \
    --model=shapemask \
    --params_override="{eval: { val_json_file: ${VAL_JSON_FILE}, eval_file_pattern: ${EVAL_FILE_PATTERN}, eval_samples: 5000 } }"
    
    Réglage Description
    tpu Spécifie le nom du Cloud TPU. Cette valeur est définie en spécifiant la variable d'environnement (TPU_NAME).
    model_dir Spécifie le répertoire dans lequel sont stockés les points de contrôle et les résumés lors de l'entraînement du modèle. Si ce dossier est absent, le programme le crée. Lorsque vous utilisez un Cloud TPU, le paramètre model_dir doit être un chemin d'accès à Cloud Storage (`gs://...`). Vous pouvez réutiliser un dossier existant pour charger les données de point de contrôle actuelles et pour stocker des points de contrôle supplémentaires tant que les précédents ont été créés à l'aide d'un TPU de la même taille et de la même version de TensorFlow.

Vous pouvez maintenant terminer ce tutoriel et nettoyer vos ressources GCP. Vous pouvez également choisir d'explorer plus avant l'exécution du modèle dans un pod Cloud TPU.

Mise à l'échelle de votre modèle avec les pods Cloud TPU

Vous pouvez obtenir des résultats plus rapidement en adaptant votre modèle aux pods Cloud TPU. Le modèle Mask RCNN est totalement compatible et peut fonctionner avec les tranches de pod suivantes :

  • v2-32
  • v3-32

Lorsque vous utilisez des pods TPU Cloud, vous devez d'abord entraîner le modèle à l'aide d'un pod, puis utiliser un seul appareil Cloud TPU pour évaluer le modèle.

Entraîner avec les pods Cloud TPU

Si vous avez déjà supprimé votre instance Compute Engine, créez-en une nouvelle en suivant les étapes décrites dans la section Configurer vos ressources.

L'exemple d'entraînement ci-dessous ne nécessite que 20 étapes et dure environ 10 minutes sur un nœud TPU v3-32. L'entraînement à la conversion nécessite environ 11 250 étapes et environ 2 heures sur un pod TPU v3-32.

  1. Supprimez la ressource Cloud TPU que vous avez créée pour entraîner le modèle sur un appareil Cloud TPU unique.

    (vm)$ ctpu delete --tpu-only --zone=us-central1-a --name=shapemask-tutorial
  2. Exécutez la commande ctpu up à l'aide du paramètre tpu-size pour spécifier la tranche de pod que vous souhaitez utiliser. Par exemple, la commande suivante utilise une tranche de pod v3-32.

    (vm)$ ctpu up --tpu-only \
      --tpu-size=v3-32  \
      --zone=us-central1-a \
      --name=shapemask-tutorial \
      --tf-version=2.3.1 
  3. Mettez à jour les variables d'environnement TPU_NAME et MODEL_DIR.

    (vm)$ export TPU_NAME=shapemask-tutorial
    (vm)$ export MODEL_DIR=${STORAGE_BUCKET}/shapemask-pods
    
  4. Commencez le script d'entraînement.

    (vm)$ python3 /usr/share/models/official/vision/detection/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}} }"
    
    Réglage Description
    tpu Spécifie le nom du Cloud TPU. Cette valeur est définie en spécifiant la variable d'environnement (TPU_NAME).
    model_dir Spécifie le répertoire dans lequel sont stockés les points de contrôle et les résumés lors de l'entraînement du modèle. Si ce dossier est absent, le programme le crée. Lorsque vous utilisez un Cloud TPU, le paramètre model_dir doit être un chemin d'accès à Cloud Storage (`gs://...`). Vous pouvez réutiliser un dossier existant pour charger les données de point de contrôle actuelles et pour stocker des points de contrôle supplémentaires tant que les précédents ont été créés à l'aide d'un TPU de la même taille et de la même version de TensorFlow.
    RESNET_CHECKPOINT Spécifie un point de contrôle pré-entraîné. ShapeMask nécessite un modèle de classification d'images pré-entraîné (tel que ResNet) en tant que réseau backbone. Cet exemple utilise un point de contrôle pré-entraîné créé à l'aide du modèle de démonstration ResNet. Si vous le souhaitez, vous pouvez également entraîner votre propre modèle ResNet et spécifier un point de contrôle à partir du répertoire de celui-ci.

Évaluer le modèle

Au cours de cette étape, vous utilisez un seul nœud Cloud TPU pour évaluer le modèle entraîné ci-dessus par rapport à l'ensemble de données COCO. L'évaluation dure environ 10 minutes.

  1. Supprimez la ressource Cloud TPU que vous avez créée pour entraîner le modèle sur un pod.

    (vm)$ ctpu delete --tpu-only \
     --zone=us-central1-a \
     --name=shapemask-tutorial
  2. Lancez un nouvel appareil TPU pour exécuter la tâche d'évaluation.

    (vm)$ ctpu up --tpu-only \
      --tpu-size=v3-8 \
      --zone=us-central1-a \
      --tf-version=2.3.1 \
      --name=shapemask-tutorial
    
  3. Mettez à jour la variable d'environnement "TPU_NAME".

    (vm)$ export TPU_NAME=shapemask-tutorial
    
  4. Commencez l'évaluation.

    (vm)$ python3 /usr/share/models/official/vision/detection/main.py \
    --strategy_type=tpu \
    --tpu=shapemask-tutorial \
    --model_dir=${MODEL_DIR} \
    --mode=eval \
    --model=shapemask \
    --params_override="{eval: { val_json_file: ${VAL_JSON_FILE}, eval_file_pattern: ${EVAL_FILE_PATTERN}, eval_samples: 5000 } }"
    

Nettoyer

Pour éviter que les ressources utilisées dans ce tutoriel soient facturées sur votre compte Google Cloud Platform :

  1. Déconnectez-vous de l'instance Compute Engine, si vous ne l'avez pas déjà fait :

    (vm)$ exit
    

    Votre invite devrait maintenant être username@projectname, indiquant que vous êtes dans Cloud Shell.

  2. Dans Cloud Shell, exécutez la commande ctpu delete avec l'option --zone utilisée lors de votre configuration Cloud TPU pour supprimer votre VM Compute Engine et votre Cloud TPU :

    $ ctpu delete --zone=us-central1-a \
     --name=shapemask-tutorial
    
  3. Exécutez la commande suivante pour vérifier que la VM Compute Engine et Cloud TPU ont été arrêtés :

    $ ctpu status --zone=us-central1-a \
      --name=shapemask-tutorial
    

    La suppression peut prendre plusieurs minutes. Si vous n'avez plus d'instances allouées, une réponse de ce type s'affiche :

    2018/04/28 16:16:23 WARNING: Setting zone to "us-central1-a"
    No instances currently exist.
       Compute Engine VM:     --
       Cloud TPU:             --
    
  4. Exécutez gsutil comme indiqué, en remplaçant bucket-name par le nom du bucket Cloud Storage que vous avez créé pour ce tutoriel :

    $ gsutil rm -r gs://bucket-name
    

Étape suivante

Entraînez le modèle à l'aide d'autres tailles d'images

Vous pouvez essayer d'utiliser un réseau de neurones plus étendu (par exemple, ResNet-101 au lieu de ResNet-50). Une image d'entrée plus grande et un réseau de neurones plus puissant permettent d'obtenir un modèle plus précis, mais plus lent.

Utilisez une base différente

Vous pouvez pré-entraîner un modèle ResNet à l'aide de votre propre ensemble de données et l'utiliser comme base pour votre modèle ShapeMask. Vous pouvez également exploiter un autre réseau de neurones que ResNet, ce qui requiert quelques étapes de configuration supplémentaires. Enfin, si vous souhaitez mettre en œuvre vos propres modèles de détection d'objets, ce réseau peut constituer une bonne base pour vos tests.