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.

Scegliere una struttura del codice di addestramento

Innanzitutto, determina quale struttura vuoi che assuma il codice di addestramento ML. Puoi fornire il codice di addestramento a Vertex AI in uno dei seguenti modi:

  • Uno script Python da utilizzare con un container predefinito. Utilizza l'SDK Vertex AI per creare un job personalizzato. Questo metodo ti 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 di Vertex AI per l'addestramento include tutte le dipendenze necessarie per l'addestramento. Ad esempio, se vuoi eseguire l'addestramento con PyTorch, scikit-learn, TensorFlow o XGBoost, questa è probabilmente l'opzione migliore.

    Per scoprire 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 eventuali dipendenze richieste dal codice nell'immagine container.

    Utilizza questa opzione se vuoi usare dipendenze che non sono incluse in uno dei container predefiniti di Vertex AI per l'addestramento. Ad esempio, se vuoi eseguire l'addestramento 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 scoprire le best practice specifiche per questa opzione, leggi la guida alla creazione di un'immagine container personalizzata.

Il resto di questo documento descrive le best practice pertinenti a 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.

Accedere ai servizi Google Cloud nel codice

Molte delle sezioni seguenti descrivono l'accesso ad altri servizi Google Cloud dal tuo codice. Per accedere ai servizi Google Cloud , scrivi il codice di addestramento in modo che utilizzi le credenziali predefinite dell'applicazione (ADC). Molte librerie client Google Cloud si autenticano con ADC per impostazione predefinita. Non devi configurare alcuna variabile di ambiente. Vertex AI configura automaticamente ADC per l'autenticazione come agente di servizio del codice personalizzato Vertex AI per il tuo progetto (per impostazione predefinita) o come account di servizio personalizzato (se ne hai configurato uno).

Tuttavia, quando utilizzi una libreria client nel codice, Vertex AI potrebbe non connettersi sempre al progettoGoogle Cloud corretto per impostazione predefinita. Google Cloud 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 tuo progetto Google Cloud . Vertex AI esegue il codice in uno dei diversi progetti separati gestiti da Google. Vertex AI utilizza questi progetti esclusivamente per le operazioni correlate al tuo progetto. Pertanto, non tentare di dedurre un ID progetto dall'ambiente nel codice di addestramento o inferenza; specifica gli ID progetto in modo esplicito.

Se non vuoi codificare in modo permanente un ID progetto nel codice di addestramento, puoi fare riferimento alla variabile di ambiente CLOUD_ML_PROJECT_ID: Vertex AI imposta questa variabile di ambiente in ogni contenitore di addestramento personalizzato in modo che contenga il numero di progetto del progetto in cui hai avviato l'addestramento personalizzato. Molti Google Cloud strumenti possono accettare un numero di progetto ovunque accettino un ID progetto.

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

Selezione implicita del progetto

from google.cloud import bigquery

client = bigquery.Client()

Utilizza invece un codice che selezioni 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 riscontri errori di autorizzazione dopo aver configurato il codice in questo modo, leggi la sezione seguente su quali risorse può accedere il tuo codice per modificare le autorizzazioni disponibili per il codice di addestramento.

A quali risorse può accedere il tuo codice

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

Ad esempio, considera l'accesso del 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 puoi personalizzare con precisione a quali bucket può accedere un job specifico utilizzando un service account 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'uso del client Python per Cloud Storage o di un'altra libreria per accedere a Cloud Storage, puoi leggere e scrivere direttamente sul file system locale per leggere dati da Cloud Storage o scrivere dati su Cloud Storage. Ad esempio, per caricare i 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 utilizzi per l'addestramento personalizzato determinano a quali bucket puoi accedere in questo modo. La sezione precedente relativa alle risorse a cui può accedere il tuo codice descrive esattamente a quali bucket puoi accedere per impostazione predefinita e come personalizzare questo accesso.

Carica i dati di input

Il codice ML di solito opera sui dati di addestramento per addestrare un modello. Non archiviare i dati di addestramento insieme al codice, indipendentemente dal fatto che tu stia creando un'applicazione di addestramento Python o un'immagine container personalizzata. L'archiviazione dei dati con codice può portare a un progetto disorganizzato, rendere difficile il riutilizzo del codice su set di dati diversi e causare errori per set di dati di grandi dimensioni.

Puoi caricare i dati da un set di dati gestito da 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 dati da Cloud Storage, utilizza un bucket nella regione in cui stai eseguendo l'addestramento personalizzato. Per scoprire come archiviare i dati in Cloud Storage, leggi Creazione di bucket di archiviazione e Caricamento di oggetti.

Per scoprire da quali bucket Cloud Storage 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 codice di addestramento, utilizza la funzionalità Cloud Storage FUSE descritta nella sezione precedente oppure qualsiasi libreria che supporti ADC. Non è necessario fornire esplicitamente le credenziali di autenticazione nel codice.

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

Carica un set di dati di grandi dimensioni

A seconda dei tipi di macchina 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 hai necessità di leggere dati troppo grandi per essere contenuti nella memoria, invia i dati in modalità flusso o leggili in modo incrementale. Per farlo, le best practice variano a seconda del framework ML. Ad esempio, la tf.data.Dataset classe di TensorFlow può inviare dati di testo o nel formato TFRecord da Cloud Storage.

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

Esporta un modello ML addestrato

Il codice ML in genere esporta un modello addestrato al termine dell'addestramento sotto forma di uno o più artefatti del modello. Dopodiché puoi utilizzare gli artefatti del modello per ottenere inferenze.

Una volta completato l'addestramento personalizzato, non potrai più accedere alle VM che hanno eseguito il codice di addestramento. Pertanto, 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 relativa alle risorse a cui può accedere il tuo codice, Vertex AI può accedere a qualsiasi bucket Cloud Storage nel progetto Google Cloud in cui stai eseguendo l'addestramento personalizzato. Utilizza una libreria che supporta Credenziali predefinite dell'applicazione per esportare gli artefatti del tuo 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 modello addestrato per pubblicare inferenze su Vertex AI, il codice deve esportare gli artefatti del modello in un formato compatibile con uno dei container predefiniti per l'inferenza. Scopri di più nella guida all'esportazione degli artefatti del modello per l'inferenza e la spiegazione.

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 differiscono leggermente a seconda che tu stia utilizzando l'ottimizzazione degli iperparametri. Per saperne 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 o opzioni di configurazione diversi, e il salvataggio di artefatti e checkpoint del modello in posizioni diverse, semplicemente modificando il campo dell'API baseOutputDirectory. Tuttavia, non sei obbligato a utilizzare le variabili di ambiente nel codice se non vuoi. Ad esempio, puoi codificare in modo permanente le posizioni per salvare i checkpoint 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.

Garantire la resilienza ai riavvii

Le VM che eseguono il codice di addestramento vengono riavviate di tanto in tanto. Ad esempio, Google Cloud potrebbe dover riavviare una VM per motivi di manutenzione. Quando una VM viene riavviata, Vertex AI inizia a eseguire di nuovo 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 i progressi dell'addestramento in Cloud Storage, almeno una volta ogni quattro ore, in modo da non perdere i progressi in caso di riavvio delle VM.

  • All'inizio del codice di addestramento, controlla se esiste già un avanzamento dell'addestramento nella posizione di esportazione. In questo caso, carica lo stato di addestramento salvato anziché iniziare l'addestramento da zero.

Quattro ore sono un'indicazione, non un limite rigido. Se garantire la resilienza è una priorità, valuta la possibilità di aggiungere questi comportamenti al tuo codice anche se non prevedi che venga eseguito per così tanto tempo.

Il modo in cui vengono ottenuti questi comportamenti dipende dal framework ML che utilizzi. Ad esempio, se utilizzi TensorFlow Keras, scopri come utilizzare il callback ModelCheckpoint per questo scopo.

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

Best practice per le funzionalità di addestramento personalizzato facoltative

Se vuoi utilizzare delle caratteristiche di addestramento personalizzato facoltative, potrebbe essere necessario apportare ulteriori modifiche al codice di addestramento. Questa sezione descrive le best practice per l'ottimizzazione degli iperparametri, le GPU, l'addestramento distribuito e Vertex AI TensorBoard.

Scrivere codice per attivare la registrazione automatica

Puoi attivare la registrazione automatica utilizzando l'SDK Vertex AI per Python per acquisire automaticamente i parametri e le metriche di rendimento quando invii il job personalizzato. Per maggiori dettagli, consulta Eseguire il job di addestramento con il monitoraggio degli esperimenti.

Scrivi il codice per restituire i log dei container

Quando scrivi i log dal tuo servizio o job, questi vengono rilevati automaticamente da Cloud Logging, a condizione che vengano scritti in una delle seguenti 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 posizioni supportate vengono associati automaticamente al servizio di addestramento personalizzato Vertex AI, alla revisione e alla posizione o al job di addestramento personalizzato. Le eccezioni contenute in questi log vengono acquisite e segnalate in Error Reporting.

Utilizza testo semplice anziché JSON strutturato nei log

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

Scrittura di log strutturati

Puoi trasmettere log JSON strutturati in diversi modi. I modi più comuni sono l'utilizzo della libreria Python Logging o il passaggio di 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 rimossi da jsonPayload e scritti nel campo corrispondente della LogEntry generata, come descritto nella documentazione relativa ai campi speciali.

Ad esempio, se il tuo JSON include una proprietà severity, questa viene rimossa da jsonPayload e viene visualizzata come severity della voce di log. La proprietà message viene utilizzata come testo di visualizzazione principale della voce di log, se presente.

Correlare i log dei container con un log di richiesta (solo servizi)

In Esplora log, i log correlati dallo stesso trace sono visualizzabili in formato "padre-figlio": quando fai clic sull'icona a forma di triangolo a sinistra della voce di log della richiesta, i log del contenitore correlati a quella richiesta vengono visualizzati nidificati sotto il log della richiesta.

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

Visualizza i log

Per visualizzare i log dei container nella console Google Cloud :

  1. Nella Google Cloud console, vai alla pagina Job personalizzati di 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.

Scrivi il codice per l'ottimizzazione degli iperparametri

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

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

  • Analizzare gli argomenti della riga di comando che rappresentano gli iperparametri da ottimizzare e utilizzare i valori analizzati per impostare gli iperparametri per l'addestramento.

  • Segnalare in modo intermittente 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 voler 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 in modo intermittente a Vertex AI la metrica degli iperparametri che stai tentando di ottimizzare. Ad esempio, se vuoi massimizzare l'accuratezza del modello, potresti voler generare report su questa metrica alla fine di ogni epoca di addestramento. Vertex AI utilizza queste informazioni per decidere quali iperparametri utilizzare per la successiva prova di addestramento. Scopri di più su come selezionare e specificare una metrica di ottimizzazione degli iperparametri.

Utilizza la libreria Python cloudml-hypertune per segnalare la 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 cloudml-hypertune GitHub o fai riferimento al codelab Vertex AI: ottimizzazione degli iperparametri.

Scrivere codice per le GPU

Puoi selezionare le VM con unità di elaborazione grafica (GPU) per eseguire il codice di addestramento personalizzato. Scopri di più sulla configurazione dell'addestramento personalizzato per l'utilizzo di VM abilitate alla GPU.

Se vuoi eseguire l'addestramento con le GPU, assicurati che il codice di addestramento possa sfruttarle. A seconda del framework ML che utilizzi, potrebbe essere necessario apportare 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 le GPU.

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

Scrivere codice per l'addestramento distribuito

Per addestrare 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 machine learning, come TensorFlow e PyTorch, consentono di eseguire codice di addestramento identico su più macchine che coordinano automaticamente la divisione del lavoro in base alle variabili di ambiente impostate su ciascuna macchina. Scopri se Vertex AI imposta variabili di ambiente per renderlo possibile per il tuo framework ML.

In alternativa, puoi eseguire un container diverso su ciascuno dei vari pool di worker. Un worker pool è un gruppo di VM che configuri per utilizzare le stesse opzioni di calcolo e lo stesso container. In questo caso, probabilmente ti conviene comunque fare affidamento sulle 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 le attività arbitrarie che preferisci. La procedura dipende dal tuo obiettivo e dal framework ML che utilizzi.

Monitorare e visualizzare gli esperimenti di addestramento personalizzato utilizzando Vertex AI TensorBoard

Vertex AI TensorBoard è una versione gestita di TensorBoard, un progetto open source di Google per la visualizzazione di esperimenti di machine learning. Con Vertex AI TensorBoard puoi monitorare, visualizzare e confrontare gli esperimenti di machine learning e poi condividerli con il tuo team. Puoi anche utilizzare Cloud 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 svolgere le seguenti operazioni:

  • Crea un'istanza di Vertex AI TensorBoard nel tuo progetto per archiviare gli esperimenti (vedi 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 (vedi Modifiche allo script di addestramento)

Per una guida passo passo, consulta Utilizzo di Vertex AI TensorBoard con addestramento personalizzato.

Passaggi successivi