Prepara il codice di addestramento

Esegui l'addestramento personalizzato su Vertex AI per eseguire il tuo codice di addestramento di machine learning (ML) nel cloud, anziché utilizzare AutoML. Questo documento descrive le best practice da considerare durante la scrittura del codice di addestramento.

Scegli una struttura di codice di addestramento

Per prima cosa, determina la struttura che vuoi che assuma il codice di addestramento ML. Puoi fornire il codice di addestramento a Vertex AI in uno dei seguenti formati:

  • Uno script Python da utilizzare con un container predefinito. Usa l'SDK Vertex AI per creare un job personalizzato. Questo metodo consente di fornire l'applicazione di addestramento come singolo script Python.

  • Un'applicazione di addestramento Python da utilizzare con un container predefinito. Crea una distribuzione di origine Python con codice che addestra un modello ML e lo esporta in Cloud Storage. Questa applicazione di addestramento può utilizzare qualsiasi dipendenza inclusa nel container predefinito con cui prevedi di utilizzarla.

    Utilizza questa opzione se uno dei container predefiniti per l'addestramento di Vertex AI include tutte le dipendenze necessarie per l'addestramento. Ad esempio, se vuoi eseguire l'addestramento con PyTorch, scikit-learn, TensorFlow o XGBoost, probabilmente questa è l'opzione migliore.

    Per conoscere le best practice specifiche per questa opzione, leggi la guida alla creazione di un'applicazione di addestramento Python.

  • Un'immagine container personalizzata. Crea un'immagine container Docker con codice che addestra un modello ML e lo esporta in Cloud Storage. Includi nell'immagine del container le eventuali dipendenze richieste dal tuo codice.

    Utilizza questa opzione se vuoi usare dipendenze non incluse in uno dei container predefiniti per l'addestramento di Vertex AI. Ad esempio, se vuoi addestrarlo utilizzando un framework ML Python non disponibile in un container predefinito, o se vuoi eseguire l'addestramento utilizzando un linguaggio di programmazione diverso da Python, questa è l'opzione migliore.

    Per conoscere le best practice specifiche per questa opzione, leggi la guida alla creazione di un'immagine container personalizzata.

Il resto del documento descrive le best practice pertinenti per entrambe le strutture del codice di addestramento.

Best practice per tutto il codice di addestramento personalizzato

Quando scrivi codice di addestramento personalizzato per Vertex AI, tieni presente che il codice verrà eseguito su una o più istanze di macchine virtuali (VM) gestite da Google Cloud. Questa sezione descrive le best practice applicabili a tutto il codice di addestramento personalizzato.

Accedi ai servizi Google Cloud nel tuo codice

In molte delle sezioni seguenti viene descritto l'accesso ad altri servizi Google Cloud dal codice. Per accedere ai servizi Google Cloud, scrivi il tuo codice di addestramento per utilizzare le Credenziali predefinite dell'applicazione (ADC). Molte librerie client di Google Cloud autenticano con ADC per impostazione predefinita. Non è necessario configurare alcuna variabile di ambiente; Vertex AI configura automaticamente ADC per l'autenticazione come agente di servizio codice personalizzato Vertex AI per il progetto (per impostazione predefinita) o come account di servizio personalizzato (se ne hai configurato uno).

Tuttavia, quando utilizzi una libreria client di Google Cloud nel codice, Vertex AI potrebbe non connettersi sempre al progetto Google Cloud corretto per impostazione predefinita. Se si verificano errori di autorizzazione, il problema potrebbe essere la connessione al progetto sbagliato.

Questo problema si verifica perché Vertex AI non esegue il codice direttamente nel progetto Google Cloud. Vertex AI esegue invece il codice in uno dei vari progetti separati gestiti da Google. Vertex AI utilizza questi progetti esclusivamente per le operazioni relative al progetto. Non provare quindi a dedurre un ID progetto dall'ambiente nel tuo codice di addestramento o previsione; specifica gli ID progetto in modo esplicito.

Se non vuoi impostare come hardcoded un ID progetto nel tuo codice di addestramento, puoi fare riferimento alla variabile di ambiente CLOUD_ML_PROJECT_ID: Vertex AI imposta questa variabile di ambiente in ogni container di addestramento personalizzato per contenere il numero di progetto del progetto in cui hai avviato l'addestramento personalizzato. Molti strumenti Google Cloud possono accettare un numero di progetto ovunque prendano un ID progetto.

Ad esempio, se vuoi utilizzare il client Python per Google BigQuery per accedere a una tabella BigQuery nello stesso progetto, non provare a dedurre il progetto nel codice di addestramento:

Selezione implicita del progetto

from google.cloud import bigquery

client = bigquery.Client()

Utilizza invece codice che seleziona esplicitamente un progetto:

Selezione esplicita del progetto

import os

from google.cloud import bigquery

project_number = os.environ["CLOUD_ML_PROJECT_ID"]

client = bigquery.Client(project=project_number)

Se si verificano errori di autorizzazione dopo aver configurato il codice in questo modo, consulta la sezione seguente sulle risorse a cui può accedere il codice per modificare le autorizzazioni disponibili per il codice di addestramento.

A quali risorse può accedere il tuo codice

Per impostazione predefinita, la tua applicazione di addestramento può accedere a qualsiasi risorsa Google Cloud disponibile per l'agente di servizio personalizzato Vertex AI (CCSA) del tuo progetto. Puoi concedere al CCSA e, di conseguenza, alla tua richiesta di addestramento, l'accesso a un numero limitato di altre risorse seguendo le istruzioni in Concedere agli agenti di servizio Vertex AI l'accesso ad altre risorse. Se la tua applicazione di addestramento ha bisogno di un accesso superiore alla lettura alle risorse Google Cloud non elencate nella pagina, deve acquisire un token di accesso OAuth 2.0 con l'ambito https://www.googleapis.com/auth/cloud-platform, operazione che può essere eseguita solo utilizzando un account di servizio personalizzato.

Ad esempio, considera l'accesso del tuo codice di addestramento alle risorse Cloud Storage:

Per impostazione predefinita, Vertex AI può accedere a qualsiasi bucket Cloud Storage nel progetto Google Cloud in cui stai eseguendo l'addestramento personalizzato. Puoi anche concedere a Vertex AI l'accesso ai bucket Cloud Storage in altri progetti oppure personalizzare con precisione i bucket a cui può accedere un job specifico utilizzando un account di servizio personalizzato.

Leggi e scrivi file Cloud Storage con Cloud Storage FUSE

In tutti i job di addestramento personalizzato, Vertex AI monta i bucket Cloud Storage a cui hai accesso nella directory /gcs/ del file system di ciascun nodo di addestramento. Come comoda alternativa all'utilizzo del client Python per Cloud Storage o di un'altra libreria per accedere a Cloud Storage, puoi leggere e scrivere direttamente nel file system locale per leggere i dati da Cloud Storage o scrivere dati in Cloud Storage. Ad esempio, per caricare dati da gs://BUCKET/data.csv, puoi utilizzare il seguente codice Python:

file = open('/gcs/BUCKET/data.csv', 'r')

Vertex AI utilizza Cloud Storage FUSE per montare i bucket di archiviazione. Tieni presente che le directory montate da Cloud Storage FUSE non sono conformi a POSIX.

Le credenziali che usi per l'addestramento personalizzato determinano a quali bucket puoi accedere in questo modo. La sezione precedente sulle risorse a cui può accedere il tuo codice descrive esattamente i bucket a cui puoi accedere per impostazione predefinita e come personalizzare questo accesso.

Carica dati di input

Il codice ML solitamente opera sui dati di addestramento per addestrare un modello. Non archiviare i dati di addestramento insieme al tuo codice, sia che tu crei un'applicazione di addestramento Python sia un'immagine container personalizzata. L'archiviazione dei dati con codice può portare a un progetto mal organizzato, rendere difficile il riutilizzo del codice in set di dati diversi e causare errori per set di dati di grandi dimensioni.

Puoi caricare i dati da un set di dati gestito Vertex AI o scrivere il tuo codice per caricare i dati da un'origine esterna a Vertex AI, come BigQuery o Cloud Storage.

Per ottenere prestazioni ottimali quando carichi i dati da Cloud Storage, utilizza un bucket nella regione in cui esegui l'addestramento personalizzato. Per informazioni su come archiviare i dati in Cloud Storage, leggi Creazione di bucket di archiviazione e Caricamento di oggetti.

Per conoscere i bucket Cloud Storage da cui puoi caricare i dati, leggi la sezione precedente relativa alle risorse a cui può accedere il tuo codice.

Per caricare i dati da Cloud Storage nel tuo codice di addestramento, utilizza la funzionalità FUSE di Cloud Storage descritta nella sezione precedente oppure qualsiasi libreria che supporti ADC. Non è necessario fornire esplicitamente credenziali di autenticazione nel codice.

Ad esempio, puoi utilizzare una delle librerie client illustrate nella guida di Cloud Storage relativa al download di oggetti. In particolare, il client Python per Cloud Storage è incluso nei container predefiniti. Anche la classe tf.io.gfile.GFile di TensorFlow supporta ADC.

Carica un set di dati di grandi dimensioni

A seconda dei tipi di macchine che prevedi di utilizzare durante l'addestramento personalizzato, le tue VM potrebbero non essere in grado di caricare in memoria l'intero set di dati di grandi dimensioni.

Se devi leggere dati di dimensioni eccessive per la memoria, trasmettili in streaming o leggili in modo incrementale. I diversi framework ML hanno best practice diverse per farlo. Ad esempio, la classe tf.data.Dataset di TensorFlow può trasmettere dati TFRecord o di testo da Cloud Storage.

L'addestramento personalizzato su più VM con il parallelismo dei dati è un altro modo per ridurre la quantità di dati caricati da ogni VM in memoria. Consulta la sezione Scrittura di codice per l'addestramento distribuito di questo documento.

Esporta un modello ML addestrato

In genere, il codice ML esporta un modello addestrato al termine dell'addestramento sotto forma di uno o più artefatti del modello. Puoi quindi usare gli artefatti del modello per ottenere previsioni.

Una volta completato l'addestramento personalizzato, non potrai più accedere alle VM che hanno eseguito il tuo codice di addestramento. Di conseguenza, il codice di addestramento deve esportare gli artefatti del modello in una località esterna a Vertex AI.

Ti consigliamo di esportare gli artefatti del modello in un bucket Cloud Storage. Come descritto nella sezione precedente sulle risorse a cui può accedere il codice, Vertex AI può accedere a qualsiasi bucket Cloud Storage nel progetto Google Cloud in cui stai eseguendo l'addestramento personalizzato. Usa una libreria che supporti ADC per esportare gli artefatti del modello. Ad esempio, le API TensorFlow per il salvataggio dei modelli Keras possono esportare gli artefatti direttamente in un percorso di Cloud Storage.

Se vuoi utilizzare il tuo modello addestrato per fornire previsioni su Vertex AI, il codice deve esportare gli artefatti del modello in un formato compatibile con uno dei container predefiniti per la previsione. Scopri di più nella guida all'esportazione degli artefatti del modello per la previsione.

Variabili di ambiente per directory Cloud Storage speciali

Se specifichi il campo API baseOutputDirectory, Vertex AI imposta le seguenti variabili di ambiente quando esegue il codice di addestramento:

I valori di queste variabili di ambiente variano leggermente a seconda che utilizzi l'ottimizzazione degli iperparametri. Per scoprire di più, consulta il riferimento API per baseOutputDirectory.

L'utilizzo di queste variabili di ambiente semplifica il riutilizzo dello stesso codice di addestramento più volte, ad esempio con dati diversi o opzioni di configurazione, e il salvataggio degli artefatti e dei checkpoint del modello in località diverse, semplicemente modificando il campo dell'API baseOutputDirectory. Tuttavia, se non vuoi, non devi necessariamente usare le variabili di ambiente nel codice. Ad esempio, in alternativa puoi impostare come hardcoded le località per salvare i punti di controllo ed esportare gli artefatti del modello.

Inoltre, se utilizzi un TrainingPipeline per l'addestramento personalizzato e non specifichi il campo modelToUpload.artifactUri, Vertex AI utilizza il valore della variabile di ambiente AIP_MODEL_DIR per modelToUpload.artifactUri. (Per l'ottimizzazione degli iperparametri, Vertex AI utilizza il valore della variabile di ambiente AIP_MODEL_DIR della prova migliore.)

Garantisci la resilienza ai riavvii

Le VM che eseguono il codice di addestramento si riavviano occasionalmente. Ad esempio, Google Cloud potrebbe dover riavviare una VM per motivi di manutenzione. Quando una VM viene riavviata, Vertex AI ricomincia a eseguire il codice dall'inizio.

Se prevedi che il codice di addestramento venga eseguito per più di quattro ore, aggiungi diversi comportamenti al codice per renderlo resiliente ai riavvii:

  • Esporta spesso l'avanzamento dell'addestramento in Cloud Storage, almeno una volta ogni quattro ore, in modo da non perdere l'avanzamento al riavvio delle VM.

  • All'inizio del codice di addestramento, verifica se esistono già progressi dell'addestramento nella località di esportazione. In tal caso, carica lo stato di addestramento salvato anziché avviarlo da zero.

Quattro ore sono una linea guida, non un limite fisso. Se garantire la resilienza è una priorità, valuta la possibilità di aggiungere questi comportamenti al tuo codice anche se non prevedi che funzioni per così tanto tempo.

Il modo in cui portare a termine questi comportamenti dipende dal framework ML utilizzato. Ad esempio, se usi TensorFlow Keras, scopri come utilizzare il callback ModelCheckpoint per questo scopo.

Per saperne di più su come Vertex AI gestisce le VM, consulta Comprendere il servizio di addestramento personalizzato.

Best practice per le funzionalità di addestramento personalizzato facoltative

Se vuoi utilizzare determinate funzionalità facoltative di addestramento personalizzato, potresti dover apportare ulteriori modifiche al codice di addestramento. Questa sezione descrive le best practice relative al codice per l'ottimizzazione degli iperparametri, le GPU, l'addestramento distribuito e Vertex AI TensorBoard.

Scrivi il codice per attivare la registrazione automatica

Puoi abilitare l'auotologging utilizzando l'SDK Vertex AI per Python per acquisire automaticamente parametri e metriche sulle prestazioni quando invii il job personalizzato. Per i dettagli, consulta Eseguire un job di addestramento con il monitoraggio dell'esperimento.

Scrivi il codice per restituire i log dei container

Quando scrivi log dal servizio o dal job, questi verranno acquisiti automaticamente da Cloud Logging, purché siano scritti in una di queste posizioni:

La maggior parte degli sviluppatori dovrebbe scrivere i log utilizzando l'output standard e l'errore standard.

I log dei container scritti in queste località supportate vengono automaticamente associati al servizio di addestramento personalizzato, alla revisione e alla località di Vertex AI o al job di addestramento personalizzato. Le eccezioni contenute in questi log vengono acquisite e riportate in Error Reporting.

Utilizza testo semplice e JSON strutturato nei log

Quando scrivi log, puoi inviare una semplice stringa di testo o una singola riga di JSON serializzato, detti anche dati "strutturati". Viene raccolto ed analizzato da Cloud Logging e inserito in jsonPayload. Al contrario, il semplice SMS viene inserito in textPayload.

Scrittura di log strutturati

Puoi trasferire log JSON strutturati in diversi modi. I modi più comuni sono utilizzando la libreria di logging di Python o passando un JSON non elaborato utilizzando print.

Libreria di logging Python

import json
import logging
from pythonjsonlogger import jsonlogger

class CustomJsonFormatter(jsonlogger.JsonFormatter):
 """Formats log lines in JSON."""
  def process_log_record(self, log_record):
    """Modifies fields in the log_record to match Cloud Logging's expectations."""
    log_record['severity'] = log_record['levelname']
    log_record['timestampSeconds'] = int(log_record['created'])
    log_record['timestampNanos'] = int(
        (log_record['created'] % 1) * 1000 * 1000 * 1000)

    return log_record

def configure_logger():
  """Configures python logger to format logs as JSON."""
  formatter = CustomJsonFormatter(
        '%(name)s|%(levelname)s|%(message)s|%(created)f'
        '|%(lineno)d|%(pathname)s', '%Y-%m-%dT%H:%M:%S')
  root_logger = logging.getLogger()
  handler = logging.StreamHandler()
  handler.setFormatter(formatter)
  root_logger.addHandler(handler)
  root_logger.setLevel(logging.WARNING)

logging.warning("This is a warning log")

JSON non elaborato

import json

def log(severity, message):
  global_extras = {"debug_key": "debug_value"}
  structured_log = {"severity": severity, "message": message, **global_extras}
  print(json.dumps(structured_log))

def main(args):
  log("DEBUG", "Debugging the application.")
  log("INFO", "Info.")
  log("WARNING", "Warning.")
  log("ERROR", "Error.")
  log("CRITICAL", "Critical.")

Campi JSON speciali nei messaggi

Quando fornisci un log strutturato come dizionario JSON, alcuni campi speciali vengono eliminati da jsonPayload e scritti nel campo corrispondente nella LogEntry generata, come descritto nella documentazione relativa ai campi speciali.

Ad esempio, se JSON include una proprietà severity, viene rimossa da jsonPayload e viene visualizzata al suo posto come severity della voce di log. La proprietà message viene utilizzata come testo visualizzato principale della voce di log, se presente.

Correlare i log dei container con un log delle richieste (solo servizi)

In Esplora log, i log correlati allo stesso trace sono visualizzabili nel formato "padre-figlio": quando fai clic sull'icona a forma di triangolo a sinistra della voce di log della richiesta, i log dei container relativi alla richiesta vengono visualizzati nidificati sotto il log delle richieste.

I log dei container non vengono automaticamente correlati ai log delle richieste, a meno che non utilizzi una libreria client di Cloud Logging. Per correlare i log dei container ai log delle richieste senza utilizzare una libreria client, puoi utilizzare una riga di log JSON strutturata contenente un campo logging.googleapis.com/trace con l'identificatore traccia estratto dall'intestazione X-Cloud-Trace-Context.

Visualizza i log

Per visualizzare i log dei container nella console Google Cloud, segui questi passaggi:

  1. Nella console Google Cloud, vai alla pagina Job personalizzati Vertex AI.

    Vai a Job personalizzati

  2. Fai clic sul nome del job personalizzato di cui vuoi visualizzare i log.

  3. Fai clic su Visualizza log.

Scrivere il codice per l'ottimizzazione degli iperparametri

Vertex AI può eseguire l'ottimizzazione degli iperparametri sul codice di addestramento ML. Scopri di più su come funziona l'ottimizzazione degli iperparametri su Vertex AI e su come configurare una HyperparameterTuningJob risorsa.

Se vuoi utilizzare l'ottimizzazione degli iperparametri, il codice di addestramento deve:

  • Analizza gli argomenti della riga di comando che rappresentano gli iperparametri che vuoi ottimizzare e utilizza i valori analizzati per impostare gli iperparametri per l'addestramento.

  • Segnala a intermittenza la metrica di ottimizzazione degli iperparametri a Vertex AI.

Analizza gli argomenti della riga di comando

Per l'ottimizzazione degli iperparametri, Vertex AI esegue il codice di addestramento più volte, con argomenti della riga di comando diversi ogni volta. Il codice di addestramento deve analizzare questi argomenti della riga di comando e utilizzarli come iperparametri per l'addestramento. Ad esempio, per ottimizzare il tasso di apprendimento dell'ottimizzatore, potresti analizzare un argomento della riga di comando denominato --learning_rate. Scopri come configurare gli argomenti della riga di comando forniti da Vertex AI.

Ti consigliamo di utilizzare la libreria argparse di Python per analizzare gli argomenti della riga di comando.

Segnala la metrica di ottimizzazione degli iperparametri

Il codice di addestramento deve segnalare a intermittenza la metrica dell'iperparametro che stai cercando di ottimizzare in Vertex AI. Ad esempio, per massimizzare l'accuratezza del modello, conviene registrare questa metrica alla fine di ogni periodo di addestramento. Vertex AI usa queste informazioni per decidere quali iperparametri usare per la prova di addestramento successiva. Scopri di più sulla selezione e sulla specifica di una metrica di ottimizzazione degli iperparametri.

Utilizza la libreria Python cloudml-hypertune per generare report sulla metrica di ottimizzazione degli iperparametri. Questa libreria è inclusa in tutti i container predefiniti per l'addestramento e puoi utilizzare pip per installarla in un container personalizzato.

Per scoprire come installare e utilizzare questa libreria, consulta il repository GitHub di cloudml-hypertune o consulta il codelab di Vertex AI: ottimizzazione degli iperparametri.

Scrittura del codice per le GPU

Puoi selezionare VM con GPU (Graphics Processing Unit) per eseguire il tuo codice di addestramento personalizzato. Scopri di più sulla configurazione dell'addestramento personalizzato per l'utilizzo di VM abilitate per GPU.

Se vuoi eseguire l'addestramento con GPU, assicurati che il tuo codice di addestramento possa sfruttarle. A seconda del framework ML utilizzato, potrebbero essere necessarie modifiche al codice. Ad esempio, se utilizzi TensorFlow Keras, devi modificare il codice solo se vuoi utilizzare più di una GPU. Alcuni framework ML non possono utilizzare affatto le GPU.

Inoltre, assicurati che il container supporti le GPU: seleziona un container predefinito per l'addestramento che supporti le GPU oppure installa il Toolkit NVIDIA CUDA e NVIDIA cuDNN nel container personalizzato. Un modo per farlo è utilizzare un'immagine di base del repository Docker nvidia/cuda; un altro modo è utilizzare un'istanza di Deep Learning Containers come immagine di base.

Scrivere il codice per l'addestramento distribuito

Per l'addestramento su set di dati di grandi dimensioni, puoi eseguire il codice su più VM in un cluster distribuito gestito da Vertex AI. Scopri come configurare più VM per l'addestramento.

Alcuni framework di ML, come TensorFlow e PyTorch, consentono di eseguire codice di addestramento identico su più macchine coordinando automaticamente la suddivisione del lavoro in base alle variabili di ambiente impostate su ogni macchina. Scopri se Vertex AI imposta le variabili di ambiente per rendere tutto ciò possibile per il tuo framework ML.

In alternativa, puoi eseguire un container diverso su ciascuno dei vari pool di worker. Un pool di worker è un gruppo di VM da configurare per l'utilizzo delle stesse opzioni di calcolo e dello stesso container. In questo caso, devi comunque affidarti alle variabili di ambiente impostate da Vertex AI per coordinare la comunicazione tra le VM. Puoi personalizzare il codice di addestramento di ogni pool di worker per eseguire qualsiasi attività arbitraria. Il modo in cui esegui questa operazione dipende dall'obiettivo e dal framework ML utilizzato.

Monitora e visualizza gli esperimenti di addestramento personalizzato utilizzando Vertex AI TensorBoard

Vertex AI TensorBoard è una versione gestita di TensorBoard, un progetto open source di Google per visualizzare gli esperimenti di machine learning. Con Vertex AI TensorBoard puoi monitorare, visualizzare e confrontare gli esperimenti ML, per poi condividerli con il team. Puoi anche utilizzare TensorBoard Profiler per individuare e risolvere i colli di bottiglia delle prestazioni per addestrare i modelli in modo più rapido ed economico.

Per utilizzare Vertex AI TensorBoard con l'addestramento personalizzato, devi:

  • Crea un'istanza di Vertex AI TensorBoard nel tuo progetto per archiviare gli esperimenti (consulta Creare un'istanza di TensorBoard).

  • Configura un account di servizio per eseguire il job di addestramento personalizzato con le autorizzazioni appropriate.

  • Modifica il codice di addestramento personalizzato per scrivere log compatibili con TensorBoard in Cloud Storage (consulta Modifiche allo script di addestramento)

Per una guida passo passo, consulta Utilizzare Vertex AI TensorBoard con l'addestramento personalizzato.

Passaggi successivi