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 tenere presenti durante la scrittura del codice di addestramento.

di Google.

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, consulta la guida alla creazione di un'applicazione di addestramento in 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 contenitore personalizzata.

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

Diverse delle sezioni seguenti descrivono l'accesso ad altri servizi Google Cloud dal 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 di Google Cloud si autenticano con le credenziali predefinite dell'applicazione per impostazione predefinita. Non è necessario configurare alcuna variabile di ambiente. Vertex AI configura automaticamente l'ADC per eseguire l'autenticazione come agente di servizio del 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 Google Cloud nel codice, per impostazione predefinita Vertex AI potrebbe non connettersi sempre al progetto Google Cloud corretto. Se riscontri 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, invece, esegue il codice in uno dei diversi progetti distinti gestiti da Google. Vertex AI utilizza questi progetti esclusivamente per le operazioni relative al tuo progetto. Pertanto, non tentare di dedurre un ID progetto dall'ambiente nel codice di addestramento o di previsione, ma specifica gli ID progetto in modo esplicito.

Se non vuoi codificare 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 del progetto del progetto in cui hai avviato l'addestramento personalizzato. Molti strumenti Google Cloud possono accettare un numero di progetto ovunque venga richiesto 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 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 dopo aver configurato il codice in questo modo riscontri errori di autorizzazione, consulta la sezione seguente sulle risorse a cui può accedere il codice per modificare le autorizzazioni disponibili per il codice di addestramento.

Le risorse a cui può accedere il 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 progetto. Puoi concedere all'amministratore dei dati dei clienti e, di conseguenza, alla tua applicazione di addestramento, 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 formazione richiede più dell'accesso a livello di lettura alle risorse Google Cloud non elencate in quella pagina, deve acquisire un token di accesso OAuth 2.0 con l'ambito https://www.googleapis.com/auth/cloud-platform, che può essere ottenuto solo utilizzando un account di servizio personalizzato.

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 i bucket a cui può accedere un determinato job 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'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 che si trovi nella regione in cui stai eseguendo l'addestramento personalizzato. Per scoprire come archiviare i dati in Cloud Storage, consulta Creare bucket di archiviazione e Caricare oggetti.

Per scoprire da quali bucket Cloud Storage puoi caricare i dati, consulta 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à FUSE di Cloud Storage descritta nella sezione precedente o qualsiasi libreria che supporti l'ADC. Non è necessario fornire esplicitamente le credenziali di autenticazione nel codice.

Ad esempio, puoi utilizzare una delle librerie client mostrate nella guida di Cloud Storage al download degli oggetti. Il client Python per Cloud Storage, in particolare, è incluso nei container predefiniti. Anche la tf.io.gfile.GFile class di TensorFlow supporta l'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 puoi trasmettere in streaming 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.

Esportare 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 predizioni.

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 generare 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 elementi del modello per la previsione.

Variabili di ambiente per directory Cloud Storage speciali

Se specifichi il campo APIbaseOutputDirectory, 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 la regolazione degli iperparametri. Per saperne di più, consulta il riferimento all'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 consente di salvare gli elementi del modello e i checkpoint in posizioni diverse semplicemente modificando il campo dell'API baseOutputDirectory. Tuttavia, non è obbligatorio utilizzare le variabili di ambiente nel codice se non vuoi. Ad esempio, in alternativa puoi impostare in modo hardcode le posizioni per salvare i checkpoint ed esportare gli elementi del modello.

Inoltre, se utilizzi un TrainingPipeline per l'addestramento personalizzato e non specifichi il modelToUpload.artifactUri campo, then 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 AIP_MODEL_DIR dell'ambiente della prova migliore.

Garantire la resilienza ai riavvii

Le VM che eseguono il codice di addestramento si riavviano di tanto in tanto. Ad esempio, Google Cloud potrebbe dover riavviare una VM per motivi di manutenzione. Quando una VM si riavvia, Vertex AI riavvia l'esecuzione del 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 se le VM vengono riavviate.

  • All'inizio del codice di addestramento, controlla se esistono già progressi nell'addestramento nella posizione di esportazione. In questo caso, carica lo stato dell'addestramento salvato invece di avviare l'addestramento da zero.

Quattro ore è una linea guida, non un limite fisso. Se la resilienza è una priorità, ti consigliamo di aggiungere questi comportamenti al codice anche se non prevedi che venga eseguito per così tanto tempo.

La modalità di attuazione di questi comportamenti dipende dal framework di ML utilizzato. Ad esempio, se utilizzi TensorFlow Keras, scopri come utilizzare il callback ModelCheckpoint per questo scopo.

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

Best practice per le funzionalità facoltative di addestramento personalizzato

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 il codice per l'ottimizzazione degli iperparametri, le GPU, l'addestramento distribuito e Vertex AI TensorBoard.

Scrivi il codice per attivare il logging automatico

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

Scrivi il codice per restituire i log del contenitore

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

Utilizzare 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, chiamati anche dati "strutturati". Viene rilevato e interpretato da Cloud Logging e inserito in jsonPayload. In contrasto, il messaggio di testo semplice viene inserito in textPayload.

Scrittura di log strutturati

Puoi trasmettere i log JSON strutturati in diversi modi. I modi più comuni sono tramite l'libreria di logging di Python o passando 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 nel LogEntry generato, come descritto nella documentazione per i campi speciali.

Ad esempio, se il tuo JSON include una proprietà severity, viene rimossa dal 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 contenitori con un log delle richieste (solo servizi)

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

I log dei container non sono correlati automaticamente ai log delle richieste, a meno che non utilizzi una libreria client di Cloud Logging. Per correlare i log dei contenitori con i 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'X-Cloud-Trace-Context intestazione.

Visualizza i log

Per visualizzare i log del contenitore nella console Google Cloud:

  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.

Scrivi il codice per l'ottimizzazione degli iperparametri

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

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

  • Analizza gli argomenti della riga di comando che rappresentano gli iperparametri da ottimizzare e utilizza 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, ogni volta con argomenti della riga di comando diversi. 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 a riga di comando forniti da Vertex AI.

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

Segnalare la metrica di ottimizzazione degli iperparametri

Il codice di addestramento deve segnalare in modo intermittente la metrica dell'iperparametro che stai tentando di ottimizzare a Vertex AI. Ad esempio, se vuoi massimizzare l'accuratezza del tuo modello, ti consigliamo di registrare questa metrica alla fine di ogni epoca di addestramento. Vertex AI utilizza queste informazioni per decidere quali iperparametri utilizzare per la prova di addestramento successiva. Scopri di più su come selezionare e specificare una metrica di ottimizzazione degli iperparametri.

Utilizza la libreria Python cloudml-hypertune per generare un 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 GitHubcloudml-hypertune o consulta il codelab Vertex AI: ottimizzazione degli iperparametri.

Scrivere codice per le GPU

Puoi selezionare 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 con GPU.

Se vuoi eseguire l'addestramento con le GPU, assicurati che il codice di addestramento possa sfruttarle. A seconda del framework ML utilizzato, questa operazione potrebbe richiedere 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 affatto utilizzare le GPU.

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

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 ML, 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 rendere possibile questo per il tuo framework di ML.

In alternativa, puoi eseguire un container diverso su ciascuno dei vari pool di worker. Un pool di worker è un gruppo di VM che configuri per utilizzare le stesse opzioni di calcolo e lo stesso container. In questo caso, probabilmente ti consigliamo di 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 qualsiasi attività arbitraria. Il modo in cui lo fai dipende dal tuo obiettivo e dal framework ML che utilizzi.

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 la visualizzazione degli esperimenti di machine learning. Con Vertex AI TensorBoard puoi monitorare, visualizzare e confrontare gli esperimenti di ML, per poi condividerli con il tuo team. Puoi anche utilizzare Cloud Profiler per individuare e risolvere i colli di bottiglia delle prestazioni e addestrare i modelli in modo più rapido e conveniente.

Per utilizzare Vertex AI TensorBoard con l'addestramento personalizzato, devi svolgere i seguenti passaggi:

  • 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 in modo da scrivere i log compatibili con TensorBoard su Cloud Storage (vedi Modifiche allo script di addestramento).

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

Passaggi successivi