Entraîner RetinaNet sur Cloud TPU (TF 2.x)

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

Préparer l'ensemble de données COCO
Créer un bucket Cloud Storage pour stocker votre ensemble de données et la sortie du modèle
Configurer des ressources 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é.

Connectez-vous à votre compte Google Cloud. Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits gratuits pour exécuter, tester et déployer des charges de travail.

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

Accéder au sélecteur de projet

Assurez-vous que la facturation est activée pour votre projet Cloud. Découvrez comment vérifier que la facturation est activée pour votre projet.

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

Accéder au sélecteur de projet

Assurez-vous que la facturation est activée pour votre projet Cloud. Découvrez comment vérifier que la facturation est activée pour votre projet.

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.

Préparer l'ensemble de données COCO

Ce tutoriel utilise l'ensemble de données COCO. L'ensemble de données doit être au format TFRecord sur un bucket Cloud Storage à utiliser pour l'entraînement.

Si l'ensemble de données COCO est déjà préparé sur un bucket Cloud Storage situé dansZone pour entraîner le modèle, vous pouvez accéder directement àl'entraînement sur un seul appareil. Sinon, procédez comme suit pour préparer l'ensemble de données.

Ouvrez une fenêtre Cloud Shell.

Ouvrir Cloud Shell
Dans Cloud Shell, 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 gs://bucket-name
```
Lancez une instance de VM Compute Engine.

Cette instance de VM ne sera utilisée que pour télécharger et prétraiter l'ensemble de données COCO. Renseignez le nom de votre choix avec le paramètre instance-name.
```
$ gcloud compute tpus execution-groups create \
 --vm-only \
 --name=instance-name \
 --zone=europe-west4-a \
 --disk-size=300 \
 --machine-type=n1-standard-16 \
 --tf-version=2.6.0
```
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.
Si vous n'êtes pas automatiquement connecté à l'instance Compute Engine, connectez-vous en exécutant la commande ssh suivante. Lorsque vous êtes connecté à la VM, votre invite d'interface système passe de username@projectname à username@vm-name:
```
  $ gcloud compute ssh instance-name --zone=europe-west4-a
  
```
Configurez deux variables, une pour le bucket de stockage que vous avez créé précédemment et une pour le répertoire contenant les données d'entraînement (DATA_dir) sur le bucket de stockage.
```
(vm)$ export STORAGE_BUCKET=gs://bucket-name
```
```
(vm)$ export DATA_DIR=${STORAGE_BUCKET}/coco
```

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"

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)$ git clone https://github.com/tensorflow/tpu.git
(vm)$ sudo bash 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. L'exécution du script de téléchargement et de conversion COCO prend environ une heure.
Copier les données dans votre bucket Cloud Storage

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. 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}
```
Nettoyer les ressources de la VM

Une fois l'ensemble de données COCO converti au format TFRecord et copié dans l'ensemble de données DATA_dir dans votre bucket Cloud Storage, vous pouvez supprimer l'instance Compute Engine.

Déconnectez-vous de l'instance Compute Engine:
```
(vm)$ exit
```
Votre invite devrait maintenant être username@projectname, indiquant que vous êtes dans Cloud Shell.

Supprimez votre instance Compute Engine.

  $ gcloud compute instances delete instance-name
    --zone=europe-west4-a

Entraînement Retinanet sur un TPU unique

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

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 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. La commande gcloud utilisée dans ce tutoriel pour configurer le TPU configure également 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.

Configurer et démarrer Cloud TPU

Lancez une VM Compute Engine et Cloud TPU à l'aide de la commande gcloud. La commande utilisée varie selon que vous utilisez des VM TPU ou des nœuds TPU. Pour en savoir plus sur l'architecture des deux VM, consultez la page Architecture système.
VM TPU
```
$ gcloud alpha compute tpus tpu-vm create retinanet-tutorial \
--zone=europe-west4-a \
--accelerator-type=v3-8 \
--version=v2-alpha
```
Description des options de commande

zone

Zone dans laquelle vous prévoyez de créer votre Cloud TPU.

accelerator-type

Type du Cloud TPU à créer.

version

Version d'exécution de Cloud TPU.
Nœud TPU
```
$ gcloud compute tpus execution-groups create  \
 --zone=europe-west4-a \
 --name=retinanet-tutorial \
 --accelerator-type=v3-8 \
 --machine-type=n1-standard-8 \
 --disk-size=300 \
 --tf-version=2.6.0
```
Description des options de commande

zone

Zone dans laquelle vous prévoyez de créer votre Cloud TPU.

accelerator-type

Type du Cloud TPU à créer.

machine-type
Type de machine de la VM Compute Engine à créer.
disk-size

Taille du volume racine de votre VM Compute Engine (en Go).

tf-version

La version de TensorFlow gcloud s'installe sur la VM.
Remarque :Si vous avez plusieurs projets, vous devez spécifier l'ID du projet avec l'option --project.

Pour en savoir plus sur la commande gcloud, consultez la documentation de référence de gcloud.

Remarque :La première fois que vous exécutez gcloud alpha compute tpus 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. .
Si vous n'êtes pas automatiquement connecté à l'instance Compute Engine, connectez-vous en exécutant la commande ssh suivante. Lorsque vous êtes connecté à la VM, votre invite d'interface système passe de username@projectname à username@vm-name:
VM TPU
```
gcloud alpha compute tpus tpu-vm ssh retinanet-tutorial --zone=europe-west4-a
```
Nœud TPU
```
gcloud compute ssh retinanet-tutorial --zone=europe-west4-a
```
Important :À partir de ce point, le préfixe (vm) $ signifie que vous devez exécuter la commande sur l'instance de VM Compute Engine. .

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

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'

Installez la configuration requise pour TensorFlow.

VM TPU

(vm)$ git clone https://github.com/tensorflow/models.git
(vm)$ pip3 install -r models/official/requirements.txt

Nœud TPU

(vm)$ pip3 install --user -r /usr/share/models/official/requirements.txt

Définissez la variable de nom Cloud TPU.

VM TPU

(vm)$ export TPU_NAME=local

Nœud TPU

(vm)$ export TPU_NAME=retinanet-tutorial

Ajoutez des variables d'environnement pour les répertoires de données et de modèles.

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

(vm)$ export DATA_DIR=${STORAGE_BUCKET}/coco
(vm)$ export MODEL_DIR=${STORAGE_BUCKET}/retinanet-train

Définissez la variable d'environnement PYTHONPATH :

VM TPU

(vm)$ export PYTHONPATH="${PWD}/models:${PYTHONPATH}"

Nœud TPU

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

Accédez au répertoire où le modèle est stocké :

VM TPU

(vm)$ cd ~/models/official/vision/detection

Nœud TPU

(vm)$ cd /usr/share/models/official/vision/detection

Entraînement sur un seul appareil Cloud TPU

Les scripts d'entraînement suivants ont été exécutés sur un Cloud TPU v3-8. Vous pouvez également les exécuter sur un Cloud TPU v2-8, mais cela prendra plus de temps.

L'exemple de script ci-dessous est entraîné pendant 10 étapes et dure moins de 5 minutes sur un nœud TPU v3-8. L'entraînement à la convergence nécessite environ 22 500 étapes et une heure et demie sur un TPU v3-8.

Configurez les variables d'environnement suivantes :

(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 main.py \
     --strategy_type=tpu \
     --tpu=${TPU_NAME} \
     --model_dir=${MODEL_DIR} \
     --mode="train" \
     --params_override="{ type: retinanet, train: { total_steps: 10, 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

strategy_type
Pour entraîner le modèle RetinaNet sur un TPU, vous devez définir distribution_strategy sur tpu.
tpu

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

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
Définissez ce paramètre sur train pour entraîner le modèle ou sur eval pour l'évaluer.
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 modèle effectuera 10 pas en cinq minutes environ sur un TPU v3-8. Une fois l'entraînement terminé, un résultat semblable au suivant s'affiche:

Train Step: 10/10  / loss = {
  'total_loss': 2.4581615924835205,
  'cls_loss': 1.4098565578460693,
  'box_loss': 0.012001709081232548,
  'model_loss': 2.0099422931671143,
  'l2_regularization_loss': 0.44821977615356445,
  'learning_rate': 0.008165999
}
/ training metric = {
  'total_loss': 2.4581615924835205,
  'cls_loss': 1.4098565578460693,
  'box_loss': 0.012001709081232548,
  'model_loss': 2.0099422931671143,
  'l2_regularization_loss': 0.44821977615356445,
 'learning_rate': 0.008165999
}

Évaluation sur un seul appareil Cloud TPU

La procédure suivante utilise les données d'évaluation COCO. L'exécution des étapes d'évaluation sur un TPU v3-8 prend environ 10 minutes.

Configurez les variables d'environnement suivantes :
```
(vm)$ export EVAL_SAMPLES=5000
```

Exécutez le script d'évaluation :

(vm)$ python3 main.py \
      --strategy_type=tpu \
      --tpu=${TPU_NAME} \
      --model_dir=${MODEL_DIR} \
      --checkpoint_path=${MODEL_DIR} \
      --mode=eval_once \
      --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

strategy_type: Stratégie de distribution à utiliser. tpu ou multi_worker_gpu.
tpu: Nom du Cloud TPU. Cette valeur est définie à l'aide de la variable d'environnement TPU_NAME.
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.

À la fin de l'évaluation, vous verrez dans la console des messages semblables à ce qui suit :

Accumulating evaluation results...
DONE (t=7.66s).
 Average Precision  (AP) @[ IoU=0.50:0.95 | area=   all | maxDets=100 ] = 0.000
 Average Precision  (AP) @[ IoU=0.50      | area=   all | maxDets=100 ] = 0.000
 Average Precision  (AP) @[ IoU=0.75      | area=   all | maxDets=100 ] = 0.000
 Average Precision  (AP) @[ IoU=0.50:0.95 | area= small | maxDets=100 ] = 0.000
 Average Precision  (AP) @[ IoU=0.50:0.95 | area=medium | maxDets=100 ] = 0.000
 Average Precision  (AP) @[ IoU=0.50:0.95 | area= large | maxDets=100 ] = 0.000
 Average Recall     (AR) @[ IoU=0.50:0.95 | area=   all | maxDets=  1 ] = 0.000
 Average Recall     (AR) @[ IoU=0.50:0.95 | area=   all | maxDets= 10 ] = 0.000
 Average Recall     (AR) @[ IoU=0.50:0.95 | area=   all | maxDets=100 ] = 0.000
 Average Recall     (AR) @[ IoU=0.50:0.95 | area= small | maxDets=100 ] = 0.000
 Average Recall     (AR) @[ IoU=0.50:0.95 | area=medium | maxDets=100 ] = 0.000
 Average Recall     (AR) @[ IoU=0.50:0.95 | area= large | maxDets=100 ] = 0.000

Vous avez terminé la formation et l'évaluation sur un seul appareil. Suivez la procédure ci-dessous pour supprimer les ressources TPU mono-appareil actuelles.

Déconnectez-vous de l'instance Compute Engine:
```
(vm)$ exit
```
Votre invite devrait maintenant être username@projectname, indiquant que vous êtes dans Cloud Shell.
Supprimez la ressource TPU.
VM TPU
```
$ gcloud alpha compute tpus tpu-vm delete retinanet-tutorial \
--zone=europe-west4-a
```
Description des options de commande

zone

Zone où se trouve votre Cloud TPU.
Nœud TPU
```
$ gcloud compute tpus execution-groups delete retinanet-tutorial \
--tpu-only \
--zone=europe-west4-a
```
Description des options de commande

tpu-only

Supprime uniquement le Cloud TPU. La VM reste disponible.

zone

Zone contenant le TPU à supprimer.

À ce stade, vous pouvez terminer ce tutoriel et nettoyer l'instance, ou vous pouvez continuer à explorer l'exécution du modèle sur les pods Cloud TPU.

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

Entraînement Retinanet sur un pod TPU

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.

Les comptes de service permettent au service Cloud TPU d'accéder à d'autres services Google Cloud Platform.
```
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 ou utilisez un bucket que vous avez créé précédemment pour votre projet.

Important : Configurez vos ressources Cloud TPU et votre bucket Cloud Storage dans la même région/zone pour réduire la latence et les coûts du réseau. Les Cloud TPU sont situés dans des zones spécifiques, qui sont des subdivisions au sein d'une région.

Dans la commande suivante, remplacez europe-west4 par le nom de la région que vous utiliserez pour exécuter l'entraînement. Remplacez bucket-name par le nom que vous souhaitez attribuer au bucket.
```
gsutil mb -p ${PROJECT_ID} -c standard -l europe-west4 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. La commande gcloud utilisée dans ce tutoriel configure 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, consultez la section sur les autorisations de niveau d'accès.

L'emplacement du bucket doit se trouver dans la même région que vos ressources TPU.
Si vous avez déjà préparé l'ensemble de données COCO et l'avez déplacé dans votre bucket de stockage, vous pouvez le réutiliser pour entraîner le pod. Si vous n'avez pas encore préparé l'ensemble de données COCO, préparez-le maintenant et revenez sur cette page pour configurer l'entraînement.
Configurer et lancer un pod Cloud TPU

Ce tutoriel spécifie un pod v3-32. Pour connaître les autres options relatives aux pods, consultez la page Types de TPU disponibles.
VM TPU
Lancez un pod de VM TPU à l'aide de la commande gcloud alpha compute tpus tpu-vm. Ce tutoriel spécifie un pod v3-32. Pour connaître les autres options relatives aux pods, consultez la page Types de TPU disponibles.
```
$ gcloud alpha compute tpus tpu-vm create retinanet-tutorial \
--zone=europe-west4-a \
--accelerator-type=v3-32 \
--version=v2-alpha-pod
```
Description des options de commande

zone

Zone dans laquelle vous prévoyez de créer votre Cloud TPU.

accelerator-type

Type du Cloud TPU à créer.

version

Version d'exécution de Cloud TPU.

Remarque :La première fois que vous exécutez gcloud sur un projet, les tâches de démarrage, telles que la propagation de la clé SSH et l'activation de l'API, prennent environ cinq minutes. .
Nœud TPU
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.
```
$ gcloud compute tpus execution-groups create  \
 --zone=europe-west4-a \
 --name=retinanet-tutorial \
 --accelerator-type=v3-32 \
 --machine-type=n1-standard-8 \
 --disk-size=300 \
 --tf-version=2.6.0 
```
Description des options de commande

zone

Zone dans laquelle vous prévoyez de créer votre Cloud TPU.

name

Nom du TPU. Si aucune valeur n'est spécifiée, le nom d'utilisateur est utilisé par défaut.

accelerator-type

Type du Cloud TPU à créer.

machine-type

Type de machine de la VM Compute Engine à créer.

tf-version

Version de TensorFlow gcloud installée sur la VM.
Si vous n'êtes pas automatiquement connecté à l'instance Compute Engine, connectez-vous en exécutant la commande ssh suivante. Lorsque vous êtes connecté à la VM, votre invite d'interface système passe de username@projectname à username@vm-name:
VM TPU
```
gcloud alpha compute tpus tpu-vm ssh retinanet-tutorial --zone=europe-west4-a
```
Nœud TPU
```
gcloud compute ssh retinanet-tutorial --zone=europe-west4-a
```
Important :À partir de ce point, le préfixe (vm) $ signifie que vous devez exécuter la commande sur l'instance de VM Compute Engine. .

Définissez la variable de nom Cloud TPU.

(vm)$ export TPU_NAME=retinanet-tutorial

Définir des variables de bucket Cloud Storage

Configurez les variables d'environnement suivantes en remplaçant bucket-name par le nom de votre bucket Cloud Storage :
```
(vm)$ export STORAGE_BUCKET=gs://bucket-name
```
```
(vm)$ export MODEL_DIR=${STORAGE_BUCKET}/retinanet-train
(vm)$ export DATA_DIR=${STORAGE_BUCKET}/coco
```
L'application d'entraînement s'attend à ce que vos données d'entraînement soient accessibles dans Cloud Storage. Elle exploite également le bucket Cloud Storage pour stocker des points de contrôle lors de l'entraînement.

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'

Installez la configuration requise pour TensorFlow.

VM TPU

(vm)$ git clone https://github.com/tensorflow/models.git
(vm)$ pip3 install -r models/official/requirements.txt

Nœud TPU

(vm)$ pip3 install --user -r /usr/share/models/official/requirements.txt

Définissez certaines variables d'environnement requises :

(vm)$ export RESNET_PRETRAIN_DIR=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

Définissez la variable d'environnement PYTHONPATH :

VM TPU

(vm)$ export PYTHONPATH="${PWD}/models:${PYTHONPATH}"
(vm)$ export TPU_LOAD_LIBRARY=0

Nœud TPU

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

Accédez au répertoire où le modèle est stocké :

VM TPU

(vm)$ cd ~/models/official/vision/detection

Nœud TPU

(vm)$ cd /usr/share/models/official/vision/detection

Entraîner le modèle
VM TPU
```
(vm)$ python3 main.py \
--strategy_type=tpu \
--tpu=${TPU_NAME} \
--model_dir=${MODEL_DIR} \
--mode=train \
--model=retinanet \
--params_override="{architecture: {use_bfloat16: true}, eval: {batch_size: 40, eval_file_pattern: ${EVAL_FILE_PATTERN}, val_json_file: ${VAL_JSON_FILE}}, postprocess: {pre_nms_num_boxes: 1000}, predict: {batch_size: 40}, train: {batch_size: 256, checkpoint: {path: ${RESNET_PRETRAIN_DIR}, prefix: resnet50/}, iterations_per_loop: 5000, total_steps: 5625, train_file_pattern: ${TRAIN_FILE_PATTERN}, } }" 
```
Description des options de commande

tpu

Nom de votre 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 un Cloud TPU, le champ 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 stocker des points de contrôle supplémentaires tant que les précédents sont créés à l'aide de Cloud TPU de la même taille et de la même version de TensorFlow.

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 ~/models/official/vision/detection/main.py.

Cette procédure entraîne le modèle sur l'ensemble de données COCO pour les étapes d'entraînement 5625. Cet entraînement prend environ 20 minutes sur un Cloud TPU v3-32. Une fois l'entraînement terminé, un message semblable au suivant s'affiche:
Nœud TPU

L'exemple de script d'entraînement suivant a été exécuté sur un pod Cloud TPU v3-32. Il s'exécute en 10 étapes seulement et dure moins de 5 minutes. L'entraînement vers la convergence nécessite 2 109 étapes et prend environ 50 minutes sur un pod TPU v3-32.
```
(vm)$  python3 main.py \
--strategy_type=tpu \
--tpu=${TPU_NAME} \
--model_dir=${MODEL_DIR} \
--mode="train" \
--params_override="{ type: retinanet, train: { total_steps: 10, batch_size: 256, 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

strategy_type

Stratégie de distribution à utiliser. tpu ou multi_worker_gpu.

tpu

Spécifie le nom du Cloud TPU. Ce paramètre est défini à l'aide de la variable d'environnement TPU_NAME.

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.

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.

Une fois l'entraînement terminé, un message semblable au suivant s'affiche:

VM TPU

Train Step: 5625/5625  / loss = {'total_loss': 0.730501651763916,
'cls_loss': 0.3229793608188629, 'box_loss': 0.003082591574639082,
'model_loss': 0.4771089553833008, 'l2_regularization_loss': 0.2533927261829376,
'learning_rate': 0.08} / training metric = {'total_loss': 0.730501651763916,
'cls_loss': 0.3229793608188629, 'box_loss': 0.003082591574639082,
'model_loss': 0.4771089553833008, 'l2_regularization_loss': 0.2533927261829376,
'learning_rate': 0.08}

Nœud TPU

Train Step: 10/10  / loss = {'total_loss': 3.5455241203308105,
'cls_loss': 1.458828330039978, 'box_loss': 0.01220895815640688,
'model_loss': 2.0692763328552246, 'l2_regularization_loss': 1.4762479066848755,
'learning_rate': 0.008165999} / training metric = {'total_loss': 3.5455241203308105,
'cls_loss': 1.458828330039978, 'box_loss': 0.01220895815640688,
'model_loss': 2.0692763328552246, 'l2_regularization_loss': 1.4762479066848755,
'learning_rate': 0.008165999}

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 la VM Compute Engine :
```
(vm)$ exit
```
Votre invite devrait maintenant être username@projectname, indiquant que vous êtes dans Cloud Shell.
Supprimez vos ressources Cloud TPU et Compute Engine. La commande utilisée pour supprimer vos ressources varie selon que vous utilisez des VM TPU ou des nœuds TPU. Pour en savoir plus, consultez la section Architecture système.
VM TPU
```
$ gcloud alpha compute tpus tpu-vm delete retinanet-tutorial \
--zone=europe-west4-a
```
Nœud 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
```
```
Listed 0 items.
```
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 backbone plus étendu (par exemple, ResNet-101 au lieu de ResNet-50). Une image d'entrée plus grande et un réseau backbone plus puissant permettent d'obtenir un modèle plus lent, mais plus précis.

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