Pacchettizzazione di un'applicazione di addestramento

Prima di poter eseguire la tua 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 pacchettizzare e organizzare la tua applicazione nel cloud.

Puoi ottenere risultati ottimali testando la tua applicazione di addestramento localmente prima di caricarla nel cloud. L'addestramento con AI Platform Training prevede addebiti sul tuo account per le risorse utilizzate.

Prima di iniziare

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

  1. Configura il tuo ambiente di sviluppo come descritto nella Guida introduttiva.

  2. Sviluppa la tua 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. Questo ti offre la possibilità di utilizzare framework di machine learning diversi da quelli ospitati di 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 e assicurati che il pacchetto di addestramento esporta gli artefatti del modello utilizzabili da AI Platform Prediction.

  3. Segui la guida per la configurazione di un bucket Cloud Storage in cui archiviare i dati e i file dell'applicazione di addestramento.

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

Questo documento illustra i seguenti fattori che influenzano il modo in cui pacchettizzi la tua applicazione e la carichi in Cloud Storage:

  • Utilizzare gcloud CLI (opzione consigliata) o programmare la tua soluzione.
  • Creazione manuale del pacchetto, se necessario.
  • Come includere altre dipendenze 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 gcloud CLI. Puoi utilizzare un singolo comando (gcloud ai-platform jobs submit training) per pacchettizzare e caricare l'applicazione e inviare il tuo primo job di addestramento.

Per praticità, è utile definire i valori di configurazione come variabili 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 in cui vuoi che il job di addestramento salvi l'output
  • REGION: la regione in cui vuoi eseguire il job di addestramento

Ulteriori dettagli sui requisiti per questi valori sono disponibili nell'elenco dopo il comando seguente.

L'esempio seguente mostra un comando gcloud ai-platform jobs submit training che pacchettizza 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 vuoi archiviare i pacchetti di addestramento e dipendenze. Il tuo progetto Google Cloud deve avere accesso a questo bucket Cloud Storage e il bucket deve trovarsi nella stessa regione in cui esegui il job. Consulta le regioni disponibili per i servizi di AI Platform Training. Se non specifichi un bucket gestione temporanea, AI Platform Training include i pacchetti nella località 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 tuo progetto Google Cloud deve avere accesso a questo bucket Cloud Storage e il bucket deve trovarsi nella stessa regione in cui esegui il job. Consulta le regioni disponibili per i servizi di AI Platform Training.

  • --package-path specifica il percorso locale della directory dell'applicazione. gcloud CLI crea un pacchetto di distribuzione .tar.gz dal tuo codice in base al file setup.py nella directory padre di quello specificato da --package-path. Quindi carica il file .tar.gz in Cloud Storage e lo utilizza per eseguire il job di addestramento.

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

  • --module-name specifica il nome del modulo principale dell'applicazione utilizzando la notazione dei punti dello spazio dei nomi del pacchetto. Si tratta del 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 contrassegna la fine dei flag specifici gcloud e l'inizio di USER_ARGS che vuoi passare alla tua applicazione.
  • I flag specifici per AI Platform Training, come --module-name, --runtime-version e --job-dir, devono precedere il flag -- vuoto. Questi flag vengono interpretati dal servizio AI Platform Training.
  • Il flag --job-dir, se specificato, deve precedere il flag -- vuoto, perché AI Platform Training utilizza --job-dir per convalidare il percorso.
  • L'applicazione deve gestire anche il flag --job-dir, se specificato. Anche se il flag precede il carattere -- vuoto, --job-dir viene passato anche all'applicazione sotto forma di flag della riga di comando.
  • Puoi definire tutti gli elementi USER_ARGS di cui hai bisogno. AI Platform Training passa --user_first_arg, --user_second_arg e così via alla tua applicazione.

Per ulteriori informazioni sui flag di invio dei job, consulta la guida all'esecuzione di un job di addestramento.

Utilizzo delle dipendenze

Le dipendenze sono pacchetti che import nel codice. L'applicazione potrebbe avere molte dipendenze necessarie per il funzionamento.

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

Esistono due tipi di dipendenze che potresti dover aggiungere:

  • Dipendenze standard, che sono pacchetti Python comuni disponibili su PyPI.
  • Pacchetti personalizzati, ad esempio quelli sviluppati da te 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 come parte dello script setup.py. AI Platform Training utilizza pip per installare il pacchetto nelle istanze di addestramento allocate per il job. Il comando pip install cerca le dipendenze configurate e le installa.

Crea un file denominato setup.py nella directory principale dell'applicazione (una directory più in alto rispetto alla 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, viene utilizzato automaticamente il file setup.py 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 imballaggio manuale dell'applicazione di addestramento.

Aggiunta di dipendenze personalizzate

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

Se utilizzi gcloud CLI per eseguire il job di addestramento, puoi specificare le dipendenze sulla tua macchina locale, oltre che su Cloud Storage, e lo strumento le gestirà automaticamente nel cloud: 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 che includi è il percorso di un pacchetto di distribuzione, formattato come tarball (.tar.gz) o ruota (.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 in pacchetto denominate dep1.tar.gz e dep2.whl (uno dei tipi di pacchetto supportati) insieme a un percorso alle 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

Allo stesso modo, l'esempio seguente specifica le dipendenze in pacchetto denominate dep1.tar.gz e dep2.whl (uno dei tipi di pacchetto supportati), 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 direttamente con l'API AI Platform Training and Prediction, devi archiviare i pacchetti di dipendenze in una località Cloud Storage e poi utilizzare i percorsi dei pacchetti in quella località.

Creazione manuale del pacchetto

La pacchettizzazione del codice Python è un argomento vasto che va ben oltre l'ambito di questa documentazione. Per praticità, questa sezione fornisce una panoramica sull'utilizzo di Setuptools per creare il tuo pacchetto. Esistono altre librerie che puoi usare per fare lo stesso.

Per creare il pacchetto manualmente, procedi nel seguente modo:

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

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

    • Importa istruzioni per setuptools.find_packages e setuptools.setup.

    • Una chiamata a setuptools.setup con almeno questi 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 requisiti di versione, come '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 "importa pacchetti" (import i moduli da questi in Python con istruzioni come from trainer import util) nel tuo "pacchetto di distribuzione" (il file ".tar.gz che contiene tutto il codice).

      • _include_package_data_ impostato su True.

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

Struttura consigliata per il progetto

Puoi strutturare la tua applicazione di addestramento come preferisci. Tuttavia, la seguente struttura è comunemente utilizzata negli esempi di AI Platform Training e rendere l'organizzazione del progetto simile agli esempi può semplificare l'esecuzione degli esempi.

  • 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 principale dell'applicazione.

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

  • Nella directory principale del progetto, crea eventuali altre sottodirectory necessarie per implementare l'applicazione.

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

Negli esempi di AI Platform Training, la directory trainer di solito contiene i seguenti file di origine:

  • task.py contiene la logica dell'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 addestramento

Quando esegui gcloud ai-platform jobs submit training, imposta --package-path su trainer. Questo fa sì che gcloud CLI cerchi un file setup.py nella sezione parent di trainer, la directory principale del progetto.

Moduli Python

Il pacchetto dell'applicazione può contenere più moduli (file Python). Devi identificare il modulo che contiene il punto di ingresso dell'applicazione. Il servizio di addestramento esegue quel modulo richiamando Python, proprio come lo eseguiresti localmente.

Ad esempio, se segui la struttura consigliata della sezione precedente, il modulo principale sarà 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. Quindi, se invii il job con gcloud ai-platform jobs submit training, imposta il flag --module-name su trainer.task.

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

Utilizzo di gcloud CLI per caricare un pacchetto esistente

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

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

  • Imposta il flag --module-name sul nome del modulo principale dell'applicazione, utilizzando la notazione dei punti dello spazio dei nomi del tuo pacchetto. Si tratta del 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 denominato 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

Utilizzo di gcloud CLI per usare un pacchetto esistente già nel cloud

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

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

  • Imposta il flag --module-name sul nome del modulo principale dell'applicazione, utilizzando la notazione dei punti dello spazio dei nomi del tuo pacchetto. Si tratta del 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 puntare alla seguente posizione di Cloud Storage, contenente un pacchetto tarball compresso chiamato 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 necessario, puoi caricare i pacchetti manualmente. Il motivo più comune è chiamare direttamente l'API AI Platform Training and Prediction per avviare il job di addestramento. Il modo più semplice per caricare manualmente il pacchetto e le eventuali dipendenze personalizzate nel bucket Cloud Storage consiste nell'utilizzare lo strumento gsutil:

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

Tuttavia, se puoi utilizzare la riga di comando per questa operazione, devi semplicemente usare gcloud ai-platform jobs submit training per caricare i pacchetti nell'ambito della configurazione di un job di addestramento. Se non riesci a utilizzare la riga di comando, puoi utilizzare la libreria client di Cloud Storage per caricare in modo programmatico.

Passaggi successivi

Avanti
Esecuzione di un job di addestramento