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.

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.

Ouvrez une fenêtre Cloud Shell.

Ouvrir Cloud Shell
Créez une variable pour l'ID de votre projet.
```
export PROJECT_ID=project-id
```
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}
```
La première fois que vous exécutez cette commande dans une nouvelle VM Cloud Shell, une page Authorize Cloud Shell s'affiche. Cliquez sur Authorize en bas de la page pour permettre à gcloud d'effectuer des appels d'API GCP avec vos identifiants.

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

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. L'outil gcloud compute tpus execution-groups utilisé dans ce tutoriel définit les autorisations par défaut pour le compte de service Cloud TPU. 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.
Lancez une VM Compute Engine et Cloud TPU à l'aide de la commande gcloud.

Remarque :Ce tutoriel utilise TensorFlow 1.15.5, qui est basé sur l'image Debian 10 et utilise par défaut la version Python 3.6. Les versions antérieures de TensorFlow 1.15.x étaient basées sur Debian 9 et utilisaient par défaut Python 3.5.
```
$ gcloud compute tpus execution-groups create \
 --vm-only \
 --name=retinanet-tutorial \
 --zone=europe-west4-a \
 --disk-size=300 \
 --machine-type=n1-standard-8 \
 --tf-version=1.15.5
```
Description des options de commande

vm-only

Pour créer une VM uniquement. Par défaut, la commande gcloud compute tpus execution-groups crée une VM et un Cloud TPU.

name
Nom de la ressource Cloud TPU à créer.
zone
Zone dans laquelle vous prévoyez de créer votre Cloud TPU.
disk-size
Taille du disque dur en Go de la VM créée par la commande gcloud compute tpus execution-groups.
machine-type
Type de machine de la VM Compute Engine à créer.
tf-version
La version de Tensorflow que gcloud compute tpus execution-groups installe sur la VM.

Pour en savoir plus sur la commande gcloud, consultez la documentation de référence de gcloud.
La configuration que vous avez spécifiée apparaît. Saisissez y pour approuver ou n pour annuler.

Remarque : La première fois que vous exécutez gcloud compute tpus execution-groups sur un projet, les tâches de démarrage telles que la propagation de clé SSH et l'activation de l'API prennent environ cinq minutes.

Une fois l'exécution de la commande gcloud compute tpus execution-groups 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 : Si vous n'êtes pas connecté à l'instance Compute Engine, vous pouvez vous connecter en exécutant la commande suivante :
```
gcloud compute ssh retinanet-tutorial --zone=europe-west4-a
```
À mesure que vous appliquez ces instructions, exécutez chaque commande commençant par (vm)$ dans votre instance Compute Engine.

Lorsque la commande gcloud lance une machine virtuelle 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/. (Installation de Python groupée).
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
```

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

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

Exécutez la commande suivante pour créer un Cloud TPU.
```
(vm)$ gcloud compute tpus execution-groups create \
 --tpu-only \
 --name=retinanet-tutorial \
 --zone=europe-west4-a \
 --tf-version=1.15.5
```
Description des options de commande

tpu-only

Crée le Cloud TPU sans créer de VM. Par défaut, la commande gcloud compute tpus execution-groups crée une VM et un Cloud TPU.

name
Nom de la ressource Cloud TPU à créer.
zone
Zone dans laquelle vous prévoyez de créer votre Cloud TPU.
tf-version

Version de TensorFlow gcloud compute tpus execution-groups installée sur la VM.
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.
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
```
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.

Entraînement sur un seul appareil Cloud TPU

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

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 } }"
```
Description des options de commande

use_tpu

Entraînez le modèle avec un seul Cloud TPU.

tpu

Nom du Cloud TPU. Cette valeur est définie à l'aide de la variable d'environnement TPU_NAME.

num_cores

Nombre de cœurs Cloud TPU à utiliser lors de l'entraînement.

model_dir

Bucket Cloud Storage où les points de contrôle et les résumés sont stockés pendant l'entraînement. Vous pouvez utiliser un dossier existant pour charger des points de contrôle précédemment créés sur un TPU de la même taille et de la même version TensorFlow.

mode

train, eval ou train_and_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.

Configurez les variables d'environnement suivantes :
```
(vm)$ export EVAL_SAMPLES=5000
```
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} } }"
```
Description des options de commande

use_tpu

Définissez cet attribut sur true pour effectuer l'entraînement sur un Cloud TPU.

tpu

Nom du Cloud TPU utilisé pour exécuter l'entraînement ou l'évaluation.

num_cores

Nombre de cœurs Cloud TPU à utiliser lors de l'entraînement.

model_dir

Bucket Cloud Storage où les points de contrôle et les résumés sont stockés pendant l'entraînement. Vous pouvez utiliser un dossier existant pour charger des points de contrôle précédemment créés sur un TPU de la même taille et de la même version TensorFlow.

mode
Spécifiez l'un des types suivants : train, eval ou train_and_eval.
params_override

Chaîne JSON qui remplace les paramètres de script par défaut. Pour en savoir plus sur les paramètres de script, consultez /usr/share/models/official/vision/detection/main.py.

Le script d'évaluation affiche le résultat suivant:
```
Eval result: {
  'AP': 0.3371653,
  'ARl': 0.6749888,
  'ARmax100': 0.4848119,
  'APl': 0.48918217,
  'ARmax10': 0.45885247,
  'APs': 0.14764188,
  'ARm': 0.545395,
  'ARs': 0.24094534,
  'AP75': 0.3606217,
  'AP50': 0.51819533,
  'APm': 0.38223606,
  'ARmax1': 0.29476196
}
```
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

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

(vm)$ gcloud compute tpus execution-groups delete retinanet-tutorial \
  --zone=europe-west4-a \
  --tpu-only

Exécutez la commande gcloud compute tpus execution-groups à l'aide du paramètre accelerator-type pour spécifier la tranche de pod que vous souhaitez utiliser. Par exemple, la commande suivante utilise une tranche de pod v3-32.
```
(vm)$ gcloud compute tpus execution-groups create --name=retinanet-tutorial \
  --accelerator-type=v3-32  \
  --zone=europe-west4-a \
  --tf-version=1.15.5 \
  --tpu-only
```
Description des options de commande

name
Nom de la ressource Cloud TPU à créer.
accelerator-type
Type du Cloud TPU à créer.
zone
Zone dans laquelle vous prévoyez de créer votre Cloud TPU.
tf-version
La version de Tensorflow que gcloud installe sur la VM.
tpu-only

Crée un Cloud TPU uniquement. Par défaut, la commande gcloud crée une VM et un Cloud TPU.

Configurez les variables d'environnement suivantes :

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

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 }} }"
```
Description des options de commande

use_tpu

Définissez cet attribut sur true pour effectuer l'entraînement sur un Cloud TPU.

tpu

Nom du Cloud TPU. S'il n'est pas spécifié lors de la configuration de la VM Compute Engine et du Cloud TPU, votre nom d'utilisateur est utilisé par défaut.

num_cores

Nombre de cœurs Cloud TPU à utiliser pour l'entraînement.

model_dir

Bucket Cloud Storage où les points de contrôle et les résumés sont stockés pendant l'entraînement. Vous pouvez utiliser un dossier existant pour charger des points de contrôle précédemment créés sur un TPU de la même taille et de la même version TensorFlow.

mode

Une des valeurs suivantes : train, eval, train_and_eval ou predict.

eval_after_training

Défini sur true pour évaluer le modèle après l'entraînement.

params_override

Chaîne JSON qui remplace les paramètres de script par défaut. Pour en savoir plus sur les paramètres de script, consultez la section /usr/share/models/official/vision/detection/main.py.

Le résultat du script d'entraînement doit contenir du texte semblable à celui-ci:

INFO:tensorflow:Loss for final step: 0.96952075.
I1125 21:47:10.729412 140023184553728 estimator.py:371] Loss for final step: 0.96952075.
INFO:tensorflow:training_loop marked as finished
I1125 21:47:10.730288 140023184553728 error_handling.py:101] training_loop marked as finished

Effectuer un nettoyage

Pour éviter que les ressources utilisées lors de ce tutoriel soient facturées sur votre compte Google Cloud, supprimez le projet contenant les ressources, ou conservez le projet et supprimez les ressources individuelles.

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.
Dans Cloud Shell, utilisez la commande suivante pour supprimer la VM Compute Engine et votre ressource Cloud TPU :
```
$ gcloud compute tpus execution-groups delete retinanet-tutorial \
  --zone=europe-west4-a
```
Vérifiez que les ressources ont été supprimées en exécutant gcloud compute tpus execution-groups list. La suppression peut prendre plusieurs minutes. Une réponse semblable à celle ci-dessous indique que vos instances ont bien été supprimées.
```
$ gcloud compute tpus execution-groups list \
 --zone=europe-west4-a
```
Vous devriez voir une liste vide de TPU comme ci-dessous:
```
   NAME             STATUS
```
Supprimez votre bucket Cloud Storage à l'aide de gsutil, comme indiqué ci-dessous. Remplacez bucket-name par le nom de votre bucket Cloud Storage.
```
$ 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 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.

Entraîner RetinaNet sur Cloud TPU

Objectifs

Coûts

Avant de commencer

Description des options de commande

Préparer l'ensemble de données COCO

Configurer l'environnement d'entraînement

Description des options de commande

Entraînement sur un seul appareil Cloud TPU

Description des options de commande

Évaluation sur un seul appareil Cloud TPU

Description des options de commande

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

Description des options de commande

Description des options de commande

Effectuer un nettoyage

Étape suivante

Réglages d'hyperparamètres

Inférence

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

Utilisez une base différente