Pacchettizzazione di un'applicazione di addestramento

Prima di poter eseguire l'applicazione di addestramento con AI Platform Training, devi caricare il codice e le eventuali dipendenze in un bucket Cloud Storage a cui può accedere il tuo progetto Google Cloud. Questa pagina mostra come impacchettare e eseguire il deployment dell'applicazione nel cloud.

Per ottenere i risultati migliori, ti consigliamo di testare l'applicazione di addestramento localmente prima di caricarla sul cloud. L'addestramento con AI Platform Training comporta addebiti sul tuo account per le risorse utilizzate.

Prima di iniziare

Prima di poter spostare l'applicazione di addestramento sul cloud, devi completare i seguenti passaggi:

  1. Configura l'ambiente di sviluppo, come descritto nella guida introduttiva.

  2. Sviluppare l'applicazione di addestramento con uno dei framework di machine learning ospitati di AI Platform Training: TensorFlow, scikit-learn o XGBoost. In alternativa, crea un container personalizzato per personalizzare l'ambiente della tua applicazione di addestramento. In questo modo, hai la possibilità di utilizzare framework di machine learning diversi da quelli ospitati da AI Platform Training.

    Se vuoi eseguire il deployment del modello addestrato in AI Platform Prediction dopo l'addestramento, leggi la guida all'esportazione del modello per la previsione per assicurarti che il pacchetto di addestramento esegua l'esportazione degli elementi del modello che possono essere utilizzati da AI Platform Prediction.

  3. Segui la guida per configurare un bucket Cloud Storage in cui puoi archiviare i dati e i file della tua applicazione di addestramento.

  4. Conosci tutte le librerie Python di cui dipende la tua applicazione di addestramento, indipendentemente dal fatto che si tratti di pacchetti personalizzati o disponibili gratuitamente tramite PyPI.

Questo documento illustra i seguenti fattori che influiscono sul modo in cui pacchettizzare la tua applicazione e caricarla su Cloud Storage:

  • Utilizzando l'interfaccia a riga di comando gcloud (opzione consigliata) o scrivendo la tua soluzione.
  • Se necessario, crea manualmente il pacchetto.
  • Come includere dipendenze aggiuntive non installate dal runtime di AI Platform Training in uso.

Il modo più semplice per pacchettizzare l'applicazione e caricarla insieme alle sue dipendenze è utilizzare lgcloud CLI. Utilizza un unico comando (gcloud ai-platform jobs submit training) per pacchettizzare e caricare l'applicazione e inviare il tuo primo job di addestramento.

Per comodità, è utile definire i valori di configurazione come variabili di shell:

PACKAGE_PATH='LOCAL_PACKAGE_PATH'
MODULE_NAME='MODULE_NAME'
STAGING_BUCKET='BUCKET_NAME'
JOB_NAME='JOB_NAME'
JOB_DIR='JOB_OUTPUT_PATH'
REGION='REGION'

Sostituisci quanto segue:

  • LOCAL_PACKAGE_PATH: il percorso della directory del pacchetto Python nel tuo ambiente locale
  • MODULE_NAME: il nome completo del modulo di formazione
  • BUCKET_NAME: il nome di un bucket Cloud Storage
  • JOB_NAME: un nome per il job di addestramento
  • JOB_OUTPUT_PATH: l'URI di una directory Cloud Storage dove vuoi che il job di addestramento salvi l'output
  • REGION: la regione in cui vuoi eseguire il job di addestramento

Per ulteriori dettagli sui requisiti per questi valori, consulta l'elenco dopo il seguente comando.

L'esempio seguente mostra un gcloud ai-platform jobs submit training comando che impacchetta un'applicazione e invia il job di addestramento:

gcloud ai-platform jobs submit training $JOB_NAME \
    --staging-bucket=$STAGING_BUCKET \
    --job-dir=$JOB_DIR  \
    --package-path=$PACKAGE_PATH \
    --module-name=$MODULE_NAME \
    --region=$REGION \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

  • --staging-bucket specifica un bucket Cloud Storage in cui eseguire il commit dei pacchetti di addestramento e delle dipendenze. Il progetto Google Cloud deve avere accesso a questo bucket Cloud Storage, che deve trovarsi nella stessa regione in cui esegui il job. Consulta le regioni disponibili per i servizi AI Platform Training. Se non specifichi un bucket di staging, AI Platform Training esegue lo staging dei pacchetti nella posizione specificata nel parametro job-dir.

  • --job-dir specifica la posizione di Cloud Storage che vuoi utilizzare per i file di output del job di addestramento. Il progetto Google Cloud deve avere accesso a questo bucket Cloud Storage, che deve trovarsi nella stessa regione in cui esegui il job. Consulta le regioni disponibili per i servizi AI Platform Training.

  • --package-path specifica il percorso locale alla directory della tua applicazione. Gcloud CLI crea un pacchetto di distribuzione .tar.gz dal tuo codice in base al file setup.py nella directory principale di quello specificato da --package-path. Poi carica questo file .tar.gz su Cloud Storage e lo utilizza per eseguire il job di addestramento.

    Se non è presente alcun file setup.py nella posizione prevista, l'gcloud CLI crea un semplice setup.py temporaneo e include solo la directory specificata da --package-path nel file .tar.gz che genera.

  • --module-name specifica il nome del modulo principale della tua applicazione, utilizzando la notazione dei punti dello spazio dei nomi del pacchetto. Questo è il file Python che esegui per avviare l'applicazione. Ad esempio, se il modulo principale è .../my_application/trainer/task.py (consulta la struttura del progetto consigliata), il nome del modulo è trainer.task.

  • Se specifichi un'opzione sia nel file di configurazione (config.yaml) sia come flag della riga di comando, il valore nella riga di comando sostituisce il valore nel file di configurazione.
  • Il flag -- vuoto indica la fine dei flag specifici gcloud e l'inizio dei flag USER_ARGS che vuoi passare all'applicazione.
  • I flag specifici per AI Platform Training, ad esempio --module-name, --runtime-version e --job-dir, devono precedere il flag -- vuoto. Il servizio AI Platform Training interpreta questi flag.
  • Il flag --job-dir, se specificato, deve precedere il flag -- vuoto, perché AI Platform Training utilizza il --job-dir per convalidare il percorso.
  • L'applicazione deve gestire anche il flag --job-dir, se specificato. Anche se il flag precede il -- vuoto, --job-dir viene passato anche all'applicazione come flag a riga di comando.
  • Puoi definire tutti i USER_ARGS necessari. AI Platform Training passa --user_first_arg, --user_second_arg e così via alla tua applicazione.

Puoi scoprire di più sugli indicatori di invio dei job nella guida all'esecuzione di un job di addestramento.

Utilizzo delle dipendenze

Le dipendenze sono pacchetti che import nel codice. La tua applicazione potrebbe avere molte dipendenze necessarie per il suo funzionamento.

Quando esegui un job di addestramento su AI Platform Training, il job viene eseguito su istanze di addestramento (macchine virtuali configurate appositamente) su cui sono già installati molti pacchetti Python comuni. Controlla i pacchetti inclusi nella versione del runtime che utilizzi per l'addestramento e prendi nota di eventuali dipendenze non ancora installate.

Potresti dover aggiungere due tipi di dipendenze:

  • Dipendenze standard, ovvero pacchetti Python comuni disponibili su PyPI.
  • Pacchetti personalizzati, ad esempio quelli sviluppati autonomamente o quelli interni a un'organizzazione.

Le sezioni seguenti descrivono la procedura per ciascun tipo.

Aggiunta di dipendenze standard (PyPI)

Puoi specificare le dipendenze standard del pacchetto all'interno dello script setup.py. AI Platform Training utilizza pip per installare il pacchetto sulle istanze di addestramento allocate per il tuo job. Il comando pip install cerca le dipendenze configurate e le installa.

Crea un file denominato setup.py nella directory principale della tua applicazione (una directory sopra la directory trainer se segui il pattern consigliato).

Inserisci il seguente script in setup.py, inserendo i tuoi valori:

from setuptools import find_packages
from setuptools import setup

REQUIRED_PACKAGES = ['some_PyPI_package>=1.0']

setup(
    name='trainer',
    version='0.1',
    install_requires=REQUIRED_PACKAGES,
    packages=find_packages(),
    include_package_data=True,
    description='My training application package.'
)

Se utilizzi Google Cloud CLI per inviare il job di addestramento, il file setup.py viene utilizzato automaticamente per creare il pacchetto.

Se invii il job di addestramento senza utilizzare gcloud, utilizza il seguente comando per eseguire lo script:

python setup.py sdist

Per ulteriori informazioni, consulta la sezione sulla pacchettizzazione manuale dell'applicazione di formazione.

Aggiunta di dipendenze personalizzate

Puoi specificare le dipendenze personalizzate dell'applicazione passando i relativi percorsi come parte della configurazione del job. Devi avere l'URI del pacchetto di ogni dipendenza. Le dipendenze personalizzate devono trovarsi in una posizione Cloud Storage. AI Platform Training utilizza pip install per installare dipendenze personalizzate, in modo da poter avere le proprie dipendenze standard nei propri script setup.py.

Se utilizzi lgcloud CLI per eseguire il job di addestramento, puoi specificare le dipendenze sulla tua macchina locale e su Cloud Storage e lo strumento le eseguirà nel cloud per te: quando esegui il comando gcloud ai-platform jobs submit training, imposta il flag --packages per includere le dipendenze in un elenco separato da virgole.

Ogni URI incluso è il percorso di un pacchetto di distribuzione, formattato come tarball (.tar.gz) o wheel (.whl). AI Platform Training installa ogni pacchetto utilizzando pip install su ogni macchina virtuale allocata per il job di addestramento.

L'esempio seguente specifica le dipendenze pacchettizzate denominate dep1.tar.gz e dep2.whl (uno per ogni tipo di pacchetto supportato) insieme a un percorso per le origini dell'applicazione:

gcloud ai-platform jobs submit training $JOB_NAME \
    --staging-bucket $PACKAGE_STAGING_PATH \
    --package-path /Users/mluser/models/faces/trainer \
    --module-name $MODULE_NAME \
    --packages dep1.tar.gz,dep2.whl \
    --region us-central1 \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

Analogamente, l'esempio seguente specifica le dipendenze pacchettizzate denominate dep1.tar.gz e dep2.whl (uno per ogni tipo di pacchetto supportato), ma con un'applicazione di addestramento creata:

gcloud ai-platform jobs submit training $JOB_NAME \
    --staging-bucket $PACKAGE_STAGING_PATH \
    --module-name $MODULE_NAME \
    --packages trainer-0.0.1.tar.gz,dep1.tar.gz,dep2.whl
    --region us-central1 \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

Se esegui job di addestramento utilizzando direttamente l'API AI Platform Training e Prediction, devi eseguire il deployment dei pacchetti delle dipendenze in una posizione Cloud Storage e poi utilizzare i percorsi dei pacchetti in quella posizione.

Generazione manuale del pacchetto

Il packaging del codice Python è un argomento ampio che esula in gran parte dall'ambito di questa documentazione. Per comodità, questa sezione fornisce una panoramica dell'utilizzo di Setuptools per compilare il pacchetto. Esistono altre librerie che puoi utilizzare per fare la stessa cosa.

Per compilare il pacchetto manualmente:

  1. In ogni directory del pacchetto dell'applicazione, includi un file denominato __init__.py, che può essere vuoto o contenere codice che viene eseguito quando viene importato il pacchetto (qualsiasi modulo in quella directory).

  2. Nella directory principale di tutto il codice che vuoi includere nel pacchetto di distribuzione .tar.gz (una directory sopra la directory trainer se segui il pattern consigliato), includere il file Setuptools denominato setup.py che include:

    • Dichiarazioni di importazione per setuptools.find_packages e setuptools.setup.

    • Una chiamata a setuptools.setup con almeno i seguenti parametri impostati:

      • _name_ impostato sul nome dello spazio dei nomi del pacchetto.

      • _version_ impostato sul numero di versione di questa build del pacchetto.

      • _install_requires_ impostato su un elenco di pacchetti richiesti dalla tua applicazione, con i requisiti di versione, ad esempio 'docutils>=0.3'.

      • _packages_ impostato su find_packages(). Questo indica a Setuptools di includere tutte le sottodirectory della directory principale che contengono un file __init__.py come "pacchetti di importazione" (import i moduli da questi in Python con istruzioni come from trainer import util) nel "pacchetto di distribuzione" (il file.tar.gz contenente tutto il codice).

      • _include_package_data_ impostato su True.

  3. Esegui python setup.py sdist per creare il pacchetto di distribuzione .tar.gz.

Struttura del progetto consigliata

Puoi strutturare l'applicazione di addestramento nel modo che preferisci. Tuttavia, la seguente struttura viene comunemente utilizzata nei sample di AI Platform Training e l'organizzazione del progetto simile a quella dei sample può semplificare il loro utilizzo.

  • Utilizza una directory del progetto principale contenente il file setup.py.

    Utilizza la funzione find_packages() di setuptools nel file setup.py per assicurarti che tutte le sottodirectory vengano incluse nel pacchetto di distribuzione .tar.gz che crei.

  • Utilizza una sottodirectory denominata trainer per archiviare il modulo dell'applicazione principale.

  • Assegna un nome al modulo dell'applicazione principale task.py.

  • Crea le altre sottodirectory necessarie per implementare l'applicazione nella directory del progetto principale.

  • Crea un file __init__.py in ogni sottodirectory. Questi file vengono utilizzati da Setuptools per identificare le directory con il codice da pacchettizzare e possono essere vuoti.

Nei Sample di AI Platform Training, la directory trainer in genere contiene i seguenti file di origine:

  • task.py contiene la logica di applicazione che gestisce il job di addestramento.

  • model.py contiene la logica del modello.

  • util.py, se presente, contiene il codice per eseguire l'applicazione di addestramento.

Struttura consigliata di un progetto di applicazione di formazione

Quando esegui gcloud ai-platform jobs submit training, imposta --package-path su trainer. Di conseguenza, gcloud CLI cercherà un file setup.py nella directory principale di trainer, la directory del progetto principale.

Moduli Python

Il pacchetto dell'applicazione può contenere più moduli (file Python). Devi identificare il modulo che contiene il punto di accesso dell'applicazione. Il servizio di addestramento esegue il modulo chiamando Python, proprio come faresti in locale.

Ad esempio, se segui la struttura consigliata nella sezione precedente, il modulo principale è task.py. Poiché si trova all'interno di un pacchetto di importazione (directory con un file __init__.py) denominato trainer, il nome completo di questo modulo è trainer.task. Pertanto, se invii il job con gcloud ai-platform jobs submit training, imposta il --module-name su trainer.task.

Per ulteriori informazioni sui moduli, consulta la guida di Python ai pacchetti.

Utilizzo di gcloud CLI per caricare un pacchetto esistente

Se crei il pacchetto autonomamente, puoi caricarlo con gcloud CLI. Esegui il comando gcloud ai-platform jobs submit training:

  • Imposta il flag --packages sul percorso dell'applicazione pacchettizzata.

  • Imposta il flag --module-name sul nome del modulo principale della tua applicazione, utilizzando la notazione dei punti dello spazio dei nomi del pacchetto. Questo è il file Python che esegui per avviare l'applicazione. Ad esempio, se il modulo principale è .../my_application/trainer/task.py (consulta la struttura del progetto consigliata), il nome del modulo è trainer.task.

L'esempio seguente mostra come utilizzare un pacchetto tarball compresso (qui chiamato trainer-0.0.1.tar.gz) che si trova nella stessa directory in cui esegui il comando. La funzione principale si trova in un modulo chiamato task.py:

gcloud ai-platform jobs submit training $JOB_NAME \
    --staging-bucket $PACKAGE_STAGING_PATH \
    --job-dir $JOB_DIR \
    --packages trainer-0.0.1.tar.gz \
    --module-name $MODULE_NAME \
    --region us-central1 \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

Utilizzare l'interfaccia a riga di comando gcloud per utilizzare un pacchetto esistente già nel cloud

Se crei il pacchetto autonomamente e lo carichi in una posizione Cloud Storage, puoi caricarlo con gcloud. Esegui il comando gcloud ai-platform jobs submit training:

  • Imposta il flag --packages sul percorso dell'applicazione pacchettizzata.

  • Imposta il flag --module-name sul nome del modulo principale della tua applicazione, utilizzando la notazione dei punti dello spazio dei nomi del pacchetto. Questo è il file Python che esegui per avviare l'applicazione. Ad esempio, se il modulo principale è .../my_application/trainer/task.py (consulta la struttura del progetto consigliata), il nome del modulo è trainer.task.

L'esempio seguente mostra come utilizzare un pacchetto tarball compresso che si trova in un bucket Cloud Storage:

gcloud ai-platform jobs submit training $JOB_NAME \
    --job-dir $JOB_DIR \
    --packages $PATH_TO_PACKAGED_TRAINER \
    --module-name $MODULE_NAME \
    --region us-central1 \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

dove $PATH_TO_PACKAGED_TRAINER è una variabile di ambiente che rappresenta il percorso di un pacchetto esistente già nel cloud. Ad esempio, il percorso potrebbe indicare la seguente posizione Cloud Storage, contenente un pacchetto tarball compresso denominato trainer-0.0.1.tar.gz:

PATH_TO_PACKAGED_TRAINER=gs://$CLOUD_STORAGE_BUCKET_NAME/trainer-0.0.0.tar.gz

Caricamento manuale dei pacchetti

Se hai un motivo, puoi caricare i pacchetti manualmente. Il motivo più comune è che vuoi chiamare direttamente l'API AI Platform Training & Prediction per avviare il job di addestramento. Il modo più semplice per caricare manualmente il pacchetto e eventuali dipendenze personalizzate nel bucket Cloud Storage è utilizzare lo strumento Comandi gcloud storage:

gcloud storage cp /local/path/to/package.tar.gz  gs://bucket/path/

Tuttavia, se puoi utilizzare la riga di comando per questa operazione, devi solo usare gcloud ai-platform jobs submit training per caricare i pacchetti durante la configurazione di un job di addestramento. Se non puoi utilizzare la riga di comando, puoi utilizzare la libreria client di Cloud Storage per eseguire il caricamento tramite programmazione.

Passaggi successivi

Avanti
Esecuzione di un job di addestramento