Addestramento di RetinaNet su Cloud TPU (TF 2.x)

Questo documento descrive un'implementazione del modello di rilevamento degli oggetti RetinaNet. Il codice è disponibile su GitHub.

Le istruzioni riportate di seguito presuppongono che tu abbia già familiarità con l'esecuzione di un modello su Cloud TPU. Se non hai mai utilizzato Cloud TPU, puoi consultare la guida rapida per un'introduzione di base.

Se prevedi di eseguire l'addestramento su una sezione di pod di TPU, consulta la pagina di addestramento sui pod TPU per comprendere le modifiche dei parametri necessarie per le sezioni di pod.

Obiettivi

prepara il set di dati COCO
Crea un bucket Cloud Storage in cui conservare il set di dati e l'output del modello
Configura le risorse TPU per l'addestramento e la valutazione
Esegui addestramento e valutazione su una singola Cloud TPU o un pod di Cloud TPU

Costi

In questo documento vengono utilizzati i seguenti componenti fatturabili di Google Cloud:

Compute Engine
Cloud TPU
Cloud Storage

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il Calcolatore prezzi. I nuovi utenti di Google Cloud possono essere idonei a una prova senza costi aggiuntivi.

Prima di iniziare

Prima di iniziare questo tutorial, verifica che il tuo progetto Google Cloud sia configurato correttamente.

Accedi al tuo account Google Cloud. Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti gratuiti per l'esecuzione, il test e il deployment dei carichi di lavoro.

Nella pagina del selettore di progetti della console Google Cloud, seleziona o crea un progetto Google Cloud.

Vai al selettore progetti

Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.

Nella pagina del selettore di progetti della console Google Cloud, seleziona o crea un progetto Google Cloud.

Vai al selettore progetti

Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.

Questa procedura dettagliata utilizza i componenti fatturabili di Google Cloud. Consulta la pagina dei prezzi di Cloud TPU per stimare i costi. Assicurati di pulire le risorse che hai creato quando hai finito di utilizzarle per evitare addebiti inutili.

prepara il set di dati COCO

Questo tutorial utilizza il set di dati COCO. Il set di dati deve essere nel formato TFRecord su un bucket Cloud Storage per essere utilizzato per l'addestramento.

Se hai già preparato un set di dati COCO su un bucket Cloud Storage situato nella zona che utilizzerai per addestrare il modello, puoi andare direttamente all'addestramento di un singolo dispositivo. In caso contrario, segui questi passaggi per preparare il set di dati.

Apri una finestra di Cloud Shell.

Apri Cloud Shell

In Cloud Shell, configura gcloud con il tuo ID progetto.

export PROJECT_ID=project-id
gcloud config set project ${PROJECT_ID}

In Cloud Shell, crea un bucket Cloud Storage utilizzando questo comando:

Nota: nel comando seguente, sostituisci bucket-name con il nome che vuoi assegnare al bucket.
```
gsutil mb -p ${PROJECT_ID} -c standard -l europe-west4 gs://bucket-name
```
Avviare un'istanza VM di Compute Engine.

Questa istanza VM verrà utilizzata solo per scaricare e pre-elaborare il set di dati COCO. Inserisci un nome a tua scelta nel campo 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.12.0
```
Descrizioni flag comando

vm-only

Crea solo una VM. Per impostazione predefinita, il comando gcloud compute tpus execution-groups crea una VM e una Cloud TPU.

name

Il nome della Cloud TPU da creare.

zone

La zona in cui prevedi di creare la Cloud TPU.

disk-size

Le dimensioni del disco rigido in GB della VM creata dal comando gcloud compute tpus execution-groups.

machine-type

Il tipo di macchina della VM di Compute Engine da creare.

tf-version

La versione di Tensorflow gcloud compute tpus execution-groups viene installata sulla VM.
Se non hai eseguito automaticamente l'accesso all'istanza di Compute Engine, accedi eseguendo il comando ssh riportato di seguito. Quando hai eseguito l'accesso alla VM, il prompt della shell cambia da username@projectname a username@vm-name:
```
  $ gcloud compute ssh instance-name --zone=europe-west4-a
  
```
Imposta due variabili, una per il bucket di archiviazione creato in precedenza e una per la directory che contiene i dati di addestramento (DATA_DIR) nel bucket di archiviazione.
```
(vm)$ export STORAGE_BUCKET=gs://bucket-name
```
```
(vm)$ export DATA_DIR=${STORAGE_BUCKET}/coco
```

Installa i pacchetti necessari per pre-elaborare i dati.

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

Esegui lo script download_and_preprocess_coco.sh per convertire il set di dati COCO in un set di TFRecord (*.tfrecord) previsto dall'applicazione di addestramento.
```
(vm)$ git clone https://github.com/tensorflow/tpu.git
(vm)$ sudo bash tpu/tools/datasets/download_and_preprocess_coco.sh ./data/dir/coco
```
Questa operazione installa le librerie richieste ed esegue lo script di pre-elaborazione. Restituisce un numero di file *.tfrecord nella directory dei dati locali. Lo script di download e conversione di COCO richiede circa un'ora.
Copia i dati nel bucket Cloud Storage

Dopo aver convertito i dati in TFRecord, copiali dallo spazio di archiviazione locale al bucket Cloud Storage utilizzando il comando gsutil. Devi anche copiare i file delle annotazioni. Questi file consentono di convalidare le prestazioni del modello.
```
(vm)$ gsutil -m cp ./data/dir/coco/*.tfrecord ${DATA_DIR}
(vm)$ gsutil cp ./data/dir/coco/raw-data/annotations/*.json ${DATA_DIR}
```
Esegui la pulizia delle risorse VM

Una volta che il set di dati COCO è stato convertito in TFRecords e copiato in DATA_DIR sul bucket Cloud Storage, puoi eliminare l'istanza di Compute Engine.

Disconnettiti dall'istanza Compute Engine:
```
(vm)$ exit
```
Il prompt ora dovrebbe essere username@projectname, a indicare che ti trovi in Cloud Shell.

Eliminare l'istanza Compute Engine.

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

Addestramento su singolo dispositivo Cloud TPU

Apri una finestra di Cloud Shell.

Apri Cloud Shell
Crea una variabile per l'ID del progetto.
```
export PROJECT_ID=project-id
```
Configura Google Cloud CLI per utilizzare il progetto in cui vuoi creare Cloud TPU.
```
gcloud config set project ${PROJECT_ID}
```
La prima volta che esegui questo comando in una nuova VM Cloud Shell, viene visualizzata una pagina Authorize Cloud Shell. Fai clic su Authorize in fondo alla pagina per consentire a gcloud di effettuare chiamate API Google Cloud con le tue credenziali.

Creare un account di servizio per il progetto Cloud TPU.

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

Il comando restituisce un account di servizio Cloud TPU con il seguente formato:

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

Crea un bucket Cloud Storage utilizzando il comando seguente:

Nota: nel comando seguente, sostituisci bucket-name con il nome che vuoi assegnare al bucket.
```
gsutil mb -p ${PROJECT_ID} -c standard -l europe-west4 gs://bucket-name
```
Questo bucket Cloud Storage archivia i dati utilizzati per addestrare il modello e i risultati dell'addestramento. Il comando gcloud utilizzato in questo tutorial per configurare la TPU configura anche le autorizzazioni predefinite per l'account di servizio Cloud TPU che hai configurato nel passaggio precedente. Se vuoi autorizzazioni più granulari, rivedi le autorizzazioni a livello di accesso.

configura e avvia Cloud TPU

Avvia una VM di Compute Engine e Cloud TPU utilizzando il comando gcloud. Il comando da utilizzare dipende dall'utilizzo di VM TPU o nodi TPU. Per ulteriori informazioni sull'architettura delle due VM, consulta Architettura di sistema.
VM TPU
```
$ gcloud compute tpus tpu-vm create retinanet-tutorial \
--zone=europe-west4-a \
--accelerator-type=v3-8 \
--version=tpu-vm-tf-2.16.1-pjrt
```
Descrizioni flag comando

zone

La zona in cui prevedi di creare la Cloud TPU.

accelerator-type

Il tipo di acceleratore specifica la versione e le dimensioni della Cloud TPU che vuoi creare. Per maggiori informazioni sui tipi di acceleratori supportati per ogni versione di TPU, consulta Versioni TPU.

version

La versione software di Cloud TPU.
Nodo 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.12.0
```
Descrizioni flag comando

zone

La zona in cui prevedi di creare la Cloud TPU.

accelerator-type

Il tipo di Cloud TPU da creare.

machine-type

Il tipo di macchina della VM di Compute Engine da creare.

disk-size

La dimensione del volume radice della VM di Compute Engine (in GB).

tf-version

La versione di TensorFlow gcloud si installa sulla VM.
Nota: se hai più di un progetto, devi specificare l'ID progetto con il flag --project.

Per maggiori informazioni sul comando gcloud, consulta la sezione Riferimento gcloud.

Nota: la prima volta che esegui gcloud compute tpus su un progetto, ci vogliono circa 5 minuti per eseguire attività di avvio come la propagazione della chiave SSH e l'attivazione delle API.
Se non hai eseguito automaticamente l'accesso all'istanza di Compute Engine, accedi eseguendo il comando ssh riportato di seguito. Quando hai eseguito l'accesso alla VM, il prompt della shell cambia da username@projectname a username@vm-name:
VM TPU
```
gcloud compute tpus tpu-vm ssh retinanet-tutorial --zone=europe-west4-a
```
Nodo TPU
```
gcloud compute ssh retinanet-tutorial --zone=europe-west4-a
```
Punto chiave: da questo momento in poi, un prefisso di (vm) $ significa che devi eseguire il comando sull'istanza VM di Compute Engine.

Mentre continui con queste istruzioni, esegui ogni comando che inizia con (vm)$ nella finestra della sessione VM.

Installa pacchetti aggiuntivi

L'applicazione di addestramento RetinaNet richiede diversi pacchetti extra. Installali ora:

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

Installa i requisiti di TensorFlow.

VM TPU

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

Nodo TPU

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

Imposta la variabile del nome di Cloud TPU.

VM TPU

(vm)$ export TPU_NAME=local

Nodo TPU

(vm)$ export TPU_NAME=retinanet-tutorial

Aggiungi variabili di ambiente per le directory dei dati e dei modelli.

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

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

Imposta la variabile di ambiente PYTHONPATH:

VM TPU

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

Nodo TPU

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

Durante la creazione della TPU, se imposti il parametro --version su una versione che termina con -pjrt, imposta le seguenti variabili di ambiente per abilitare il runtime PJRT:
```
  (vm)$ export NEXT_PLUGGABLE_DEVICE_USE_C_API=true
  (vm)$ export TF_PLUGGABLE_DEVICE_LIBRARY_PATH=/lib/libtpu.so
```

Passa alla directory in cui è archiviato il modello:

VM TPU

(vm)$ cd /usr/share/tpu/models/official/legacy/detection

Nodo TPU

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

Addestramento su singolo dispositivo Cloud TPU

I seguenti script di addestramento sono stati eseguiti su una Cloud TPU v3-8. Richiederà più tempo, ma puoi eseguirle anche su Cloud TPU v2-8.

Lo script di esempio riportato di seguito viene addestrato per soli 10 passaggi e richiede meno di 5 minuti per l'esecuzione su un nodo TPU v3-8. Per l'addestramento alla convergenza sono necessari circa 22.500 passaggi e circa 1 ora e mezza su una TPU Cloud TPU v3-8.

Configura le seguenti variabili di ambiente:

(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

Esegui lo script di addestramento:
```
(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 } }"
```
Descrizioni flag comando

strategy_type

Per addestrare il modello RetinaNet su una TPU, devi impostare distribution_strategy su tpu.

tpu

Il nome della Cloud TPU. Viene impostato utilizzando la variabile di ambiente TPU_NAME.

model_dir

Il bucket Cloud Storage in cui vengono archiviati i checkpoint e i riepiloghi durante l'addestramento. Puoi utilizzare una cartella esistente per caricare i checkpoint generati in precedenza creati su una TPU delle stesse dimensioni e versione di TensorFlow.

mode

Impostalo su train per addestrare il modello o su eval per valutarlo.

params_override

Una stringa JSON che sostituisce i parametri di script predefiniti. Per ulteriori informazioni sui parametri dello script, consulta /usr/share/models/official/legacy/detection/main.py.

Il modello verrà addestrato per 10 passaggi in circa 5 minuti su una TPU v3-8. Al termine dell'addestramento, vedrai un output simile al seguente:

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
}

Valutazione di un singolo dispositivo Cloud TPU

La procedura seguente utilizza i dati di valutazione COCO. L'esecuzione dei passaggi di valutazione su una TPU v3-8 richiede circa 10 minuti.

Configura le seguenti variabili di ambiente:
```
(vm)$ export EVAL_SAMPLES=5000
```

Esegui lo script di valutazione:

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

Descrizioni flag comando

strategy_type: La strategia di distribuzione da utilizzare. tpu o multi_worker_gpu.
tpu: Il nome della Cloud TPU. Viene impostato utilizzando la variabile di ambiente TPU_NAME.
model_dir: Il bucket Cloud Storage in cui vengono archiviati i checkpoint e i riepiloghi durante l'addestramento. Puoi utilizzare una cartella esistente per caricare i checkpoint generati in precedenza creati su una TPU delle stesse dimensioni e versione di TensorFlow.
mode: Uno tra train, eval o train_and_eval.
params_override: Una stringa JSON che sostituisce i parametri di script predefiniti. Per maggiori informazioni sui parametri dello script, consulta /usr/share/models/official/legacy/detection/main.py.

Al termine della valutazione, vedrai messaggi simili ai seguenti sulla console:

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

Hai completato l'addestramento e la valutazione su un singolo dispositivo. Segui questi passaggi per eliminare le risorse TPU attuali per un singolo dispositivo.

Disconnettiti dall'istanza Compute Engine:
```
(vm)$ exit
```
Il prompt dovrebbe ora essere username@projectname, a indicare che ti trovi in Cloud Shell.
Elimina la risorsa TPU.
VM TPU
```
$ gcloud compute tpus tpu-vm delete retinanet-tutorial \
--zone=europe-west4-a
```
Descrizioni flag comando

zone

La zona in cui si trovava la tua Cloud TPU.
Nodo TPU
```
$ gcloud compute tpus execution-groups delete retinanet-tutorial \
--tpu-only \
--zone=europe-west4-a
```
Descrizioni flag comando

tpu-only

Elimina solo la Cloud TPU. La VM rimane disponibile.

zone

La zona che contiene la TPU da eliminare.

A questo punto, puoi concludere questo tutorial ed eseguire la pulizia oppure puoi continuare ed esplorare l'esecuzione del modello sui pod di Cloud TPU.

Scala il tuo modello con i pod di Cloud TPU

L'addestramento del modello sui pod di Cloud TPU può richiedere alcune modifiche allo script di addestramento. Per informazioni, consulta Addestramento sui pod TPU.

Addestramento di Retinanet su un pod di TPU

Apri una finestra di Cloud Shell.

Apri Cloud Shell
Crea una variabile per l'ID del progetto.
```
export PROJECT_ID=project-id
```
Configura Google Cloud CLI per utilizzare il progetto in cui vuoi creare Cloud TPU.
```
gcloud config set project ${PROJECT_ID}
```
La prima volta che esegui questo comando in una nuova VM Cloud Shell, viene visualizzata una pagina Authorize Cloud Shell. Fai clic su Authorize in fondo alla pagina per consentire a gcloud di effettuare chiamate API Google Cloud con le tue credenziali.
Creare un account di servizio per il progetto Cloud TPU.

Gli account di servizio consentono al servizio Cloud TPU di accedere ad altri servizi Google Cloud.
```
gcloud beta services identity create --service tpu.googleapis.com --project $PROJECT_ID
```
Il comando restituisce un account di servizio Cloud TPU con il seguente formato:
```
service-PROJECT_NUMBER@cloud-tpu.iam.gserviceaccount.com
```
Crea un bucket Cloud Storage utilizzando il comando seguente o utilizza un bucket che hai creato in precedenza per il tuo progetto.

Importante: configura le risorse Cloud TPU e il tuo bucket Cloud Storage) nella stessa regione/zona per ridurre la latenza di rete e i costi di rete. Le Cloud TPU si trovano in zone specifiche, che sono suddivisioni all'interno di una regione.

Nel comando seguente, sostituisci europe-west4 con il nome della regione che utilizzerai per eseguire l'addestramento. Sostituisci bucket-name con il nome che vuoi assegnare al bucket.
```
gsutil mb -p ${PROJECT_ID} -c standard -l europe-west4 gs://bucket-name
```
Questo bucket Cloud Storage archivia i dati utilizzati per addestrare il modello e i risultati dell'addestramento. Il comando gcloud utilizzato in questo tutorial configura le autorizzazioni predefinite per l'account di servizio Cloud TPU che hai configurato nel passaggio precedente. Se vuoi autorizzazioni più granulari, rivedi le autorizzazioni a livello di accesso.

La località del bucket deve trovarsi nella stessa regione delle risorse TPU.
Se in precedenza hai preparato il set di dati COCO e lo hai spostato nel bucket di archiviazione, puoi utilizzarlo di nuovo per l'addestramento dei pod. Se non hai ancora preparato il set di dati COCO, preparalo subito e torna qui per configurare l'addestramento.
configura e avvia un pod di Cloud TPU

Questo tutorial specifica un pod v3-32. Per altre opzioni relative ai pod, consulta Versioni TPU.
VM TPU
Nota: se al momento non è disponibile capacità sufficiente per creare il pod di TPU, puoi mettere in coda la richiesta utilizzando risorse in coda. Le risorse in coda consentono di ricevere capacità non appena diventa disponibile. Per richiedere le risorse Cloud TPU come risorse in coda, utilizza invece il comando gcloud alpha compute tpus queued-resources create. Per maggiori informazioni, consulta Gestire le risorse in coda.

Avvia un pod di VM TPU utilizzando il comando gcloud compute tpus tpu-vm. Questo tutorial specifica un pod v3-32.
```
$ gcloud compute tpus tpu-vm create retinanet-tutorial \
--zone=europe-west4-a \
--accelerator-type=v3-32 \
--version=tpu-vm-tf-2.16.1-pod-pjrt
```
Descrizioni flag comando

zone

La zona in cui prevedi di creare la Cloud TPU.

accelerator-type

Il tipo di acceleratore specifica la versione e le dimensioni della Cloud TPU che vuoi creare. Per maggiori informazioni sui tipi di acceleratori supportati per ogni versione di TPU, consulta Versioni TPU.

version

La versione software di Cloud TPU.

Nota: la prima volta che esegui gcloud su un progetto, sono necessari circa 5 minuti per eseguire attività di avvio come la propagazione della chiave SSH e l'attivazione delle API.
Nodo TPU
Esegui il comando gcloud compute tpus execution-groups, utilizzando il parametro accelerator-type per specificare la sezione di pod da utilizzare. Ad esempio, il comando seguente utilizza una sezione di 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.12.0 
```
Descrizioni flag comando

zone

La zona in cui prevedi di creare la Cloud TPU.

name

Il nome della TPU. Se non specificato, il valore predefinito è il tuo nome utente.

accelerator-type

Il tipo di Cloud TPU da creare.

machine-type

Il tipo di macchina della VM di Compute Engine da creare.

tf-version

La versione di Tensorflow gcloud viene installata sulla VM.
Se non hai eseguito automaticamente l'accesso all'istanza di Compute Engine, accedi eseguendo il comando ssh riportato di seguito. Quando hai eseguito l'accesso alla VM, il prompt della shell cambia da username@projectname a username@vm-name:
VM TPU
```
gcloud compute tpus tpu-vm ssh retinanet-tutorial --zone=europe-west4-a
```
Nodo TPU
```
gcloud compute ssh retinanet-tutorial --zone=europe-west4-a
```
Punto chiave: da questo momento in poi, un prefisso di (vm) $ significa che devi eseguire il comando sull'istanza VM di Compute Engine.

Imposta la variabile del nome di Cloud TPU.

(vm)$ export TPU_NAME=retinanet-tutorial

Imposta le variabili dei bucket Cloud Storage

Configura le seguenti variabili di ambiente, sostituendo bucket-name con il nome del tuo 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'applicazione di addestramento prevede che i tuoi dati di addestramento siano accessibili in Cloud Storage. L'applicazione di addestramento usa il tuo bucket Cloud Storage per archiviare i checkpoint durante l'addestramento.

Installa pacchetti aggiuntivi

L'applicazione di addestramento RetinaNet richiede diversi pacchetti extra. Installali ora:

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

Installa i requisiti di TensorFlow.

VM TPU

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

Nodo TPU

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

Imposta alcune variabili di ambiente obbligatorie:

(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

Imposta la variabile di ambiente PYTHONPATH:

VM TPU

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

Nodo TPU

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

Passa alla directory in cui è archiviato il modello:

VM TPU

(vm)$ cd /usr/share/tpu/models/official/legacy/detection

Nodo TPU

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

Addestra il modello
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}, } }" 
```
Descrizioni flag comando

tpu

Il nome della tua TPU.

model_dir

Specifica la directory in cui vengono archiviati i checkpoint e i riepiloghi durante l'addestramento del modello. Se la cartella risulta mancante, il programma ne crea una. Quando utilizzi una Cloud TPU, model_dir deve essere un percorso Cloud Storage (gs://...). Puoi riutilizzare una cartella esistente per caricare i dati dei checkpoint attuali e per archiviare checkpoint aggiuntivi, a condizione che questi siano stati creati utilizzando Cloud TPU delle stesse dimensioni e versione di TensorFlow.

params_override

Una stringa JSON che sostituisce i parametri di script predefiniti. Per ulteriori informazioni sui parametri dello script, consulta /usr/share/tpu/models/official/legacy/detection/main.py.

Questa procedura addestra il modello sul set di dati COCO per 5625 passaggi di addestramento. Questo addestramento richiede circa 20 minuti su una Cloud TPU v3-32. Al termine dell'addestramento, appare un messaggio simile al seguente:
Nodo TPU

Il seguente script di addestramento di esempio è stato eseguito su un pod Cloud TPU v3-32. Addestra per soli 10 passi e impiega meno di 5 minuti. L'addestramento alla convergenza richiede 2109 passaggi e circa 50 minuti su un pod di 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 } }" 
```
Descrizioni flag comando

strategy_type

La strategia di distribuzione da utilizzare. tpu o multi_worker_gpu.

tpu

Specifica il nome della Cloud TPU. Questo valore viene impostato utilizzando la variabile di ambiente TPU_NAME.

model_dir

Il bucket Cloud Storage in cui vengono archiviati i checkpoint e i riepiloghi durante l'addestramento. Puoi utilizzare una cartella esistente per caricare i checkpoint generati in precedenza creati su una TPU delle stesse dimensioni e versione di TensorFlow.

mode

Uno tra train, eval o train_and_eval.

params_override

Una stringa JSON che sostituisce i parametri di script predefiniti. Per ulteriori informazioni sui parametri dello script, consulta /usr/share/models/official/legacy/detection/main.py.

Al termine dell'addestramento, viene visualizzato un messaggio simile al seguente:

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}

Nodo 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}

Esegui la pulizia

Per evitare che al tuo Account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo tutorial, elimina il progetto che contiene le risorse oppure mantieni il progetto ed elimina le singole risorse.

Disconnettiti dalla VM di Compute Engine:
```
(vm)$ exit
```
Il prompt dovrebbe ora essere username@projectname, a indicare che ti trovi in Cloud Shell.
Elimina le risorse Cloud TPU e Compute Engine. Il comando da utilizzare per eliminare le risorse dipende dall'utilizzo di VM TPU o nodi TPU. Per ulteriori informazioni, consulta Architettura di sistema.
VM TPU
```
$ gcloud compute tpus tpu-vm delete retinanet-tutorial \
--zone=europe-west4-a
```
Nodo TPU
```
$ gcloud compute tpus execution-groups delete retinanet-tutorial \
--zone=europe-west4-a
```
Verifica che le risorse siano state eliminate eseguendo gcloud compute tpus execution-groups list. L'eliminazione potrebbe richiedere diversi minuti. Una risposta come la seguente indica che le istanze sono state eliminate correttamente.
```
$ gcloud compute tpus execution-groups list --zone=europe-west4-a
```
```
Listed 0 items.
```
Elimina il bucket Cloud Storage utilizzando gsutil, come illustrato di seguito. Sostituisci bucket-name con il nome del tuo bucket Cloud Storage.
```
$ gsutil rm -r gs://bucket-name
```

Passaggi successivi

I tutorial su TensorFlow Cloud TPU in genere addestrano il modello utilizzando un set di dati di esempio. I risultati di questo addestramento non sono utilizzabili per l'inferenza. Per utilizzare un modello per l'inferenza, puoi addestrare i dati su un set di dati disponibile pubblicamente o sul tuo set di dati. I modelli TensorFlow addestrati sulle Cloud TPU in genere richiedono che i set di dati siano in formato TFRecord.

Puoi utilizzare l'esempio dello strumento di conversione del set di dati per convertire un set di dati di classificazione delle immagini nel formato TFRecord. Se non utilizzi un modello di classificazione delle immagini, dovrai convertire manualmente il set di dati nel formato TFRecord. Per ulteriori informazioni, consulta TFRecord e tf.Example.

Ottimizzazione degli iperparametri

Per migliorare le prestazioni del modello con il set di dati, puoi ottimizzare gli iperparametri del modello. Puoi trovare informazioni sugli iperparametri comuni a tutti i modelli supportati da TPU su GitHub. Puoi trovare informazioni sugli iperparametri specifici nel codice sorgente di ciascun modello. Per ulteriori informazioni sull'ottimizzazione degli iperparametri, consulta Panoramica dell'ottimizzazione degli iperparametri e degli iperparametri.

Inferenza

Una volta addestrato il modello, puoi utilizzarlo per l'inferenza (detta anche previsione). Puoi utilizzare lo strumento di conversione di inferenza Cloud TPU per preparare e ottimizzare un modello TensorFlow per l'inferenza su Cloud TPU v5e. Per ulteriori informazioni sull'inferenza su Cloud TPU v5e, consulta l'introduzione all'inferenza di Cloud TPU v5e.

Addestra con immagini di dimensioni diverse

Puoi sperimentare l'utilizzo di una rete backbone più grande (ad esempio, ResNet-101 anziché ResNet-50). Un'immagine di input più grande e una backbone più potente generano un modello più lento ma più preciso.

Usa una base diversa

In alternativa, puoi preaddestrare un modello ResNet sul tuo set di dati e utilizzarlo come base per il tuo modello RetinaNet. Con un po' di lavoro aggiuntivo, puoi anche passare a una rete backbone alternativa al posto di ResNet. Infine, se ti interessa implementare i tuoi modelli di rilevamento degli oggetti, questa rete potrebbe essere una buona base per ulteriori sperimentazioni.