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

Questo documento mostra come eseguire il modello ShapeMask utilizzando Cloud TPU con il set di dati COCO.

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.

Addestramento su singolo dispositivo Cloud TPU

Questa sezione fornisce informazioni sulla configurazione delle risorse Cloud Storage, VM e Cloud TPU per l'addestramento di singoli dispositivi.

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

In Cloud Shell, crea una variabile per l'ID del tuo 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

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.

La località del bucket deve trovarsi nella stessa regione della macchina virtuale (VM) e del nodo TPU. Le VM e i nodi TPU si trovano in zone specifiche, che sono suddivisioni all'interno di una regione.

Il bucket Cloud Storage archivia i dati che utilizzi per addestrare il modello e i risultati dell'addestramento. Lo strumento gcloud compute tpus execution-groups 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.

Se hai già preparato un set di dati COCO su un bucket Cloud Storage situato nella zona che utilizzerai per addestrare il modello, puoi avviare le risorse TPU e preparare Cloud TPU per l'addestramento. In caso contrario, segui questi passaggi per preparare il set di dati.

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

avvia le risorse TPU e addestra il modello

Usa il comando gcloud per avviare le risorse TPU. Il comando da utilizzare dipende dall'utilizzo di VM TPU o nodi TPU. Per saperne di più sull'architettura delle due VM, consulta Architettura di sistema.
VM TPU
```
$ gcloud compute tpus tpu-vm create shapemask-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=shapemask-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.

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.

disk-size

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

tf-version

La versione di Tensorflow gcloud viene installata 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 shapemask-tutorial --zone=europe-west4-a
```
Nodo TPU
```
gcloud compute ssh shapemask-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 i requisiti di TensorFlow.

VM TPU

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

Nodo TPU

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

Lo script di addestramento richiede un pacchetto aggiuntivo. Installalo ora:

VM TPU

(vm)$ pip3 install --user tensorflow-model-optimization>=0.1.3

Nodo TPU

(vm)$ pip3 install --user tensorflow-model-optimization>=0.1.3

Imposta la variabile del nome del bucket di archiviazione. Sostituisci bucket-name con il nome del tuo bucket di archiviazione:
```
(vm)$ export STORAGE_BUCKET=gs://bucket-name
```

Imposta la variabile del nome di Cloud TPU.

VM TPU

(vm)$ export TPU_NAME=local

Nodo TPU

(vm)$ export TPU_NAME=shapemask-tutorial

Imposta la variabile di ambiente PYTHONPATH:

VM TPU

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

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

Aggiungi alcune variabili di ambiente obbligatorie:

(vm)$ export RESNET_CHECKPOINT=gs://cloud-tpu-checkpoints/retinanet/resnet50-checkpoint-2018-02-07
(vm)$ export DATA_DIR=${STORAGE_BUCKET}/coco
(vm)$ export TRAIN_FILE_PATTERN=${DATA_DIR}/train-*
(vm)$ export EVAL_FILE_PATTERN=${DATA_DIR}/val-*
(vm)$ export VAL_JSON_FILE=${DATA_DIR}/instances_val2017.json
(vm)$ export SHAPE_PRIOR_PATH=gs://cloud-tpu-checkpoints/shapemask/kmeans_class_priors_91x20x32x32.npy
(vm)$ export MODEL_DIR=${STORAGE_BUCKET}/shapemask

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

Addestra il modello ShapeMask:

Lo script seguente esegue un addestramento di esempio che viene addestrato per soli 100 passi e richiede circa 10 minuti su una TPU v3-8. L'addestramento per la convergenza richiede circa 22.500 passaggi e circa 6 ore su una TPU v3-8.

(vm)$ python3 main.py \
  --strategy_type=tpu \
  --tpu=${TPU_NAME} \
  --model_dir=${MODEL_DIR} \
  --mode=train \
  --model=shapemask \
  --params_override="{train: {total_steps: 100, learning_rate: {init_learning_rate: 0.08, learning_rate_levels: [0.008, 0.0008], learning_rate_steps: [15000, 20000], }, checkpoint: { path: ${RESNET_CHECKPOINT},prefix: resnet50}, train_file_pattern: ${TRAIN_FILE_PATTERN}}, shapemask_head: {use_category_for_mask: true, shape_prior_path: ${SHAPE_PRIOR_PATH}}, shapemask_parser: {output_size: [640, 640]}}"

Descrizioni flag comando

strategy_type: Per addestrare il modello Shapemask 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: La directory in cui vengono archiviati i checkpoint e i riepiloghi durante l'addestramento del modello. Se la cartella non è presente, 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 ulteriori checkpoint, a condizione che questi siano stati creati utilizzando una Cloud TPU delle stesse dimensioni e della stessa 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.

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

Train Step: 100/100  / loss = {'total_loss': 10.815635681152344,
'loss': 10.815635681152344, 'retinanet_cls_loss': 1.4915691614151,
'l2_regularization_loss': 4.483549118041992,
'retinanet_box_loss': 0.013074751943349838,
'shapemask_prior_loss': 0.17314358055591583,
'shapemask_coarse_mask_loss': 1.953366756439209,
'shapemask_fine_mask_loss': 2.216097831726074, 'model_loss': 6.332086086273193,
'learning_rate': 0.021359999} / training metric = {'total_loss': 10.815635681152344,
'loss': 10.815635681152344, 'retinanet_cls_loss': 1.4915691614151,
'l2_regularization_loss': 4.483549118041992,
'retinanet_box_loss': 0.013074751943349838,
'shapemask_prior_loss': 0.17314358055591583,
'shapemask_coarse_mask_loss': 1.953366756439209,
'shapemask_fine_mask_loss': 2.216097831726074,
'model_loss': 6.332086086273193, 'learning_rate': 0.021359999}

Esegui lo script per valutare il modello ShapeMask. Questa operazione richiede circa 10 minuti su una TPU v3-8:

(vm)$ python3 main.py \
    --strategy_type=tpu \
    --tpu=${TPU_NAME} \
    --model_dir=${MODEL_DIR} \
    --checkpoint_path=${MODEL_DIR} \
    --mode=eval_once \
    --model=shapemask \
    --params_override="{eval: { val_json_file: ${VAL_JSON_FILE}, eval_file_pattern: ${EVAL_FILE_PATTERN}, eval_samples: 5000 }, shapemask_head: {use_category_for_mask: true, shape_prior_path: ${SHAPE_PRIOR_PATH}}, shapemask_parser: {output_size: [640, 640]}}"

Descrizioni flag comando

strategy_type: Per addestrare il modello Shapemask 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: La directory in cui vengono archiviati i checkpoint e i riepiloghi durante l'addestramento del modello. Se la cartella non è presente, 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 ulteriori checkpoint, a condizione che questi siano stati creati utilizzando una Cloud TPU delle stesse dimensioni e della stessa 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.

Al termine della valutazione, viene visualizzato un messaggio simile al seguente:

DONE (t=5.47s).
 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 shapemask-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 shapemask-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 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 Platform.
```
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.
```
gsutil mb -p ${PROJECT_ID} -c standard -l europe-west4 gs://bucket-name
```
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 ora e torna qui per configurare l'addestramento del pod.
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.
```
$ gcloud compute tpus tpu-vm create shapemask-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, ci vogliono circa 5 minuti per eseguire attività di avvio come la propagazione della chiave SSH e l'attivazione delle API.
Nodo TPU
```
$ gcloud compute tpus execution-groups create  \
 --zone=europe-west4-a \
 --name=shapemask-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.

disk-size

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

tf-version

La versione di Tensorflow gcloud viene installata sulla VM.

Nota: se hai più di un progetto, devi specificare l'ID progetto con il flag --project.
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 shapemask-tutorial --zone=europe-west4-a
```
Nodo TPU
```
gcloud compute ssh shapemask-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 i requisiti di TensorFlow.

VM TPU

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

Nodo TPU

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

Lo script di addestramento richiede un pacchetto aggiuntivo. Installalo ora:

VM TPU

(vm)$ pip3 install --user tensorflow-model-optimization>=0.1.3

Nodo TPU

(vm)$ pip3 install --user tensorflow-model-optimization>=0.1.3

Configura le seguenti variabili di ambiente, sostituendo bucket-name con il nome del tuo bucket Cloud Storage:
```
(vm)$ export STORAGE_BUCKET=gs://bucket-name
```
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.

Aggiorna le variabili di addestramento richieste.

(vm)$ export MODEL_DIR=${STORAGE_BUCKET}/shapemask-pods
(vm)$ export DATA_DIR=${STORAGE_BUCKET}/coco
(vm)$ export RESNET_CHECKPOINT=gs://cloud-tpu-checkpoints/retinanet/resnet50-checkpoint-2018-02-07
(vm)$ export TRAIN_FILE_PATTERN=${DATA_DIR}/train-*
(vm)$ export EVAL_FILE_PATTERN=${DATA_DIR}/val-*
(vm)$ export VAL_JSON_FILE=${DATA_DIR}/instances_val2017.json
(vm)$ export SHAPE_PRIOR_PATH=gs://cloud-tpu-checkpoints/shapemask/kmeans_class_priors_91x20x32x32.npy

Imposta alcune variabili di ambiente obbligatorie:

VM TPU

(vm)$ export PYTHONPATH="/usr/share/tpu/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

Avvia l'addestramento dei pod.

L'addestramento di esempio viene eseguito per soli 20 passaggi e richiede circa 10 minuti su un nodo TPU v3-32. Per l'addestramento alla convergenza sono necessari circa 11.250 passaggi e circa 2 ore su un pod di TPU v3-32.
```
(vm)$ python3 main.py \
 --strategy_type=tpu \
 --tpu=${TPU_NAME} \
 --model_dir=${MODEL_DIR} \
 --mode=train \
 --model=shapemask \
 --params_override="{train: { batch_size: 128, iterations_per_loop: 500, total_steps: 20, learning_rate: {'learning_rate_levels': [0.008, 0.0008], 'learning_rate_steps': [10000, 13000] }, checkpoint: { path: ${RESNET_CHECKPOINT}, prefix: resnet50/ }, train_file_pattern: ${TRAIN_FILE_PATTERN} }, eval: { val_json_file: ${VAL_JSON_FILE}, eval_file_pattern: ${EVAL_FILE_PATTERN}}, shapemask_head: {use_category_for_mask: true, shape_prior_path: ${SHAPE_PRIOR_PATH}} }"
```
Descrizioni flag comando

strategy_type

Per addestrare il modello Shapemask 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

La directory in cui vengono archiviati i checkpoint e i riepiloghi durante l'addestramento del modello. Se la cartella non è presente, 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 ulteriori checkpoint, a condizione che questi siano stati creati utilizzando una Cloud TPU delle stesse dimensioni e della stessa 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.

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 dall'istanza di Compute Engine, se non lo hai già fatto:
```
(vm)$ exit
```
Il prompt ora dovrebbe 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 shapemask-tutorial \
--zone=europe-west4-a
```
Nodo TPU
```
$ gcloud compute tpus execution-groups delete shapemask-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. L'output del comando seguente non deve includere nessuna delle risorse TPU create in questo tutorial:
```
$ gcloud compute tpus execution-groups list --zone=europe-west4-a
```
Esegui gsutil come mostrato, sostituendo bucket-name con il nome del bucket Cloud Storage che hai creato per questo tutorial:

Attenzione: se elimini il bucket, tutti i dati di addestramento andranno persi, quindi esegui questo passaggio solo quando hai completato l'esecuzione del tutorial.
```
$ gsutil rm -r gs://bucket-name
```

Passaggi successivi

Addestra con immagini di dimensioni diverse

Puoi sperimentare l'utilizzo di una rete neurale più grande (ad esempio, ResNet-101 anziché ResNet-50). Un'immagine di input più grande e una rete neurale più potente generano un modello più lento ma 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 ShapeMask. Con un po' di lavoro aggiuntivo, puoi anche sostituire ResNet con una rete neurale alternativa. Infine, se ti interessa implementare i tuoi modelli di rilevamento degli oggetti, questa rete potrebbe essere una buona base per ulteriori sperimentazioni.