Entraîner RetinaNet sur Cloud TPU

Ce document décrit une mise en œuvre du modèle de détection d'objets RetinaNet. Le code est disponible sur GitHub.

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.

Attention : Ce tutoriel utilise un ensemble de données tiers. Google ne formule aucune déclaration ni garantie quant à la validité ou à tout autre aspect de cet ensemble de données.

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

Cette section fournit des informations sur la configuration du bucket Cloud Storage et d'une VM Compute Engine.

Important : Configurez votre VM Compute Engine, votre nœud Cloud TPU et votre bucket Cloud Storage dans la même région pour réduire la latence et les coûts du réseau.

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 bucket Cloud Storage à l'aide de la commande suivante :

   Remarque : Dans la commande suivante, remplacez bucket-name par le nom que vous souhaitez attribuer à votre bucket.

   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.

5. Lancez une VM Compute Engine à l'aide de la commande ctpu up.

   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
   

   Remarque : Si vous avez plusieurs projets, vous devez spécifier un nom de projet à l'aide de --project. Si --name n'est pas spécifié, les noms par défaut des TPU et des VM correspondront à votre nom d'utilisateur.

6. La configuration que vous avez spécifiée apparaît. Saisissez y pour approuver ou n pour annuler.

7. 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.

   Remarque : Lors de la première exécution de ctpu up sur un projet, plusieurs minutes peuvent être nécessaires pour effectuer des tâches de démarrage telles que la propagation SSH et l'activation de l'API. Un message d'erreur apparaît parfois, lors de la propagation de la clé SSH (ERROR: (gcloud.compute.ssh) [/usr/bin/ssh] exited with return code [255]). Dans ce cas, exécutez la commande suivante pour résoudre le problème.

   gcloud compute ssh retinanet-tutorial --zone=europe-west4-a
   

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

   Lorsque la commande ctpu lance une machine virtuelle (VM) Compute Engine, elle place automatiquement les fichiers de modèle RetinaNet de la branche TensorFlow dans le répertoire /usr/share/tpu/models/official/detection/.

8. Utilisez la commande export pour définir ces variables d'environnement.

   Remarque : Dans les commandes suivantes, remplacez bucket-name par le nom de votre bucket.

   (vm)$ export STORAGE_BUCKET=gs://bucket-name
   

   (vm)$ export TPU_NAME=retinanet-tutorial
   (vm)$ export DATA_DIR=${STORAGE_BUCKET}/coco
   

9. Installer les packages supplémentaires

   L'application d'apprentissage RetinaNet nécessite plusieurs packages supplémentaires. Installez-les maintenant :

   (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
   

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 fichiers TFRecord (*.tfrecord), ce qui correspond au 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. Un certain nombre de fichiers *.tfrecord est alors créé dans votre répertoire de données.

   Remarque : L'exécution du script de téléchargement et de conversion COCO dure environ une heure.

2. Après avoir converti les données en TFRecord, copiez-les depuis le stockage local vers votre bucket Cloud Storage à l'aide de la commande gsutil. Vous devez également copier les fichiers d'annotation qui 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 l'environnement d'entraînement

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

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

   Réglage	Description
   --tpu-only	Créez un Cloud TPU uniquement, ne créez pas de VM.
   --tf-version	La version de Tensorflow "ctpu" est installée sur la VM.
   --name	Nom du Cloud TPU.

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. Mettre à jour les valeurs "keepalive" de la connexion à votre VM.

   Dans ce tutoriel, vous devez disposer d'une connexion longue durée à l'instance Compute Engine. Pour vérifier que vous n'êtes pas déconnecté de l'instance, exécutez la commande suivante :

   (vm)$ sudo /sbin/sysctl \
     -w net.ipv4.tcp_keepalive_time=120 \
     net.ipv4.tcp_keepalive_intvl=120 \
     net.ipv4.tcp_keepalive_probes=5
   

4. Vous êtes à présent prêt à exécuter le modèle à partir des données COCO prétraitées. Tout d'abord, ajoutez le dossier racine /models au chemin Python à l'aide de la commande suivante :

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

Pour l'entraînement et l'évaluation, vous devez utiliser TensorFlow version 1.13 ou ultérieure.

Remarque : Si vous souhaitez surveiller les résultats et les performances du modèle, suivez le guide de configuration de TensorBoard

.

Entraînement sur un seul appareil Cloud TPU

Remarque : Ce script effectue un entraînement pour 22 500 pas et son exécution dure environ trois heures sur un Cloud TPU v2-8 et environ 1 heure et demie sur un Cloud TPU v3-8.

1. Configurez les variables d'environnement suivantes :

   (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
   

2. Exécutez le script d'entraînement :

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

   Réglage	Description
   --use_tpu	Entraînez le modèle sur un seul Cloud TPU.
   --tpu	Spécifie le nom du Cloud TPU. Cette valeur est définie en spécifiant la variable d'environnement (TPU_NAME).
   --num_cores	Spécifie le nombre de cœurs sur Cloud TPU.
   --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 Cloud TPU, le chemin model_dir doit être un chemin Cloud Storage (gs://...). Vous pouvez réutiliser un dossier existant pour charger les données de point de contrôle actuelles et stocker des points de contrôle supplémentaires si les points de contrôle précédents ont été créés avec des TPU de même taille et la même version de TensorFlow.
   --mode	Spécifie le mode d'exécution du modèle. Les valeurs valides sont train et eval.

Évaluation sur un seul appareil Cloud TPU

La procédure suivante utilise les données d'évaluation COCO. L'exécution des pas d'évaluation prend environ 10 minutes.

1. Configurez les variables d'environnement suivantes :

   (vm)$ export EVAL_SAMPLES=5000
   

2. Exécutez le script d'évaluation :

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

   Réglage	Description
   --use_tpu	Évaluez le modèle sur un seul Cloud TPU.
   --tpu	Spécifie le nom du Cloud TPU. Cette valeur est définie en spécifiant la variable d'environnement (TPU_NAME).
   --num_cores	Spécifie le nombre de cœurs sur Cloud TPU.
   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 Cloud TPU, le chemin model_dir doit être un chemin Cloud Storage (gs://...). Vous pouvez réutiliser un dossier existant pour charger les données de point de contrôle actuelles et stocker des points de contrôle supplémentaires si les points de contrôle précédents ont été créés avec des TPU de même taille et la même version de TensorFlow.
   --mode	Spécifie le mode d'exécution du modèle. Les valeurs valides sont train et eval.

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 entièrement compatible peut fonctionner avec les tranches de pod suivantes :

• v2-32
• v3-32

Attention : Le scaling vers des tranches de pod plus grandes est expérimentale avec ce modèle. Les scripts d'entraînement utilisés dans ce tutoriel ont été optimisés pour un nœud TPU v3-32. Ils ne seront pas exécutés tels quels dans une configuration v2, car ils nécessitent de la mémoire supplémentaire.

Remarque : Le script s'entraîne pour 2 109 pas. Le processus prend environ 30 minutes sur un type de TPU v3-32 et 10 minutes sur un type de TPU v3-128.

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

   (vm)$ ctpu delete --tpu-only --zone=europe-west4-a --name=retinanet-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=europe-west4-a \
     --tf-version=1.15.3 \
     --name=retinanet-tutorial-pod
    

3. 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.

4. Configurez les variables d'environnement suivantes :

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

5. Exécutez le script d'entraînement de pod sur un nœud TPU v3-32 :

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

   Réglage	Description
   --use_tpu	Entraînez le modèle sur un pod Cloud TPU.
   --tpu	Spécifie le nom du Cloud TPU. Cette valeur est définie en spécifiant la variable d'environnement (TPU_NAME).
   --num_cores	Spécifie le nombre de cœurs sur Cloud TPU.
   --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 Cloud TPU, le chemin model_dir doit être un chemin Cloud Storage (gs://...). Vous pouvez réutiliser un dossier existant pour charger les données de point de contrôle actuelles et stocker des points de contrôle supplémentaires si les points de contrôle précédents ont été créés avec des TPU de même taille et la même version de TensorFlow.
   --mode	Spécifie le mode d'exécution du modèle.
   --eval_after_training	Défini sur True pour évaluer le modèle après l'entraînement.
   --params_override	Remplace les paramètres du modèle par les valeurs spécifiées.

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=europe-west4-a --name=retinanet-tutorial
   

   Important : Si vous avez défini le nom des ressources TPU lors de l'exécution de ctpu up, vous devez spécifier ce nom à l'aide de l'indicateur --name lors de l'exécution de ctpu delete pour arrêter vos ressources TPU.

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=europe-west4-a
   

   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 "europe-west4-a"
   No instances currently exist.
    Compute Engine VM:     --
    Cloud TPU:             --
   

   Attention : Lorsque vous supprimez votre bucket, toutes les données d'entraînement sont perdues. N'effectuez cette opération que lorsque vous avez terminé ce tutoriel.

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

Dans ce tutoriel, vous avez entraîné le modèle RetinaNet à l'aide d'un exemple d'ensemble de données. Les résultats de cet entraînement ne sont pas utilisables pour l'inférence dans la plupart des cas. Afin d'utiliser un modèle pour l'inférence, vous pouvez entraîner les données sur un ensemble de données accessible au public ou sur votre propre ensemble de données. Les modèles entraînés sur des appareils Cloud TPU nécessitent des ensembles de données au format TFRecord.

Vous pouvez utiliser l'exemple d'outil de conversion d'ensemble de données pour convertir un ensemble de données de classification d'images au format TFRecord. Si vous n'utilisez pas de modèle de classification d'images, vous devez convertir vous-même votre ensemble de données au format TFRecord. Pour en savoir plus, consultez la section TFRecord et tf.Example.

Réglages d'hyperparamètres

Pour améliorer les performances du modèle avec votre ensemble de données, vous pouvez régler ses hyperparamètres. Vous trouverez des informations sur les hyperparamètres communs à tous les modèles compatibles avec des TPU sur GitHub. Des informations sur les hyperparamètres spécifiques au modèle sont disponibles dans le code source de chaque modèle. Pour en savoir plus sur ces réglages, consultez les pages Présentation des réglages d'hyperparamètres, Utiliser le service de réglage d'hyperparamètres et Régler les hyperparamètres.

Inférence

Une fois que vous avez entraîné votre modèle, vous pouvez l'utiliser pour l'inférence (également appelée prédiction). AI Platform est une solution basée sur le cloud permettant de développer, d'entraîner et de déployer des modèles de machine learning. Une fois un modèle déployé, vous pouvez utiliser le service AI Platform Prediction.

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 RetinaNet. 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.