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:
- Configura il tuo ambiente di sviluppo come descritto nella Guida introduttiva.
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.
Segui la guida per la configurazione di un bucket Cloud Storage in cui archiviare i dati e i file dell'applicazione di addestramento.
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.
Utilizzo di gcloud
per pacchettizzare e caricare la tua applicazione (consigliato)
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 localeMODULE_NAME
: il nome completo del modulo di formazioneBUCKET_NAME
: il nome di un bucket Cloud StorageJOB_NAME
: un nome per il job di addestramentoJOB_OUTPUT_PATH
: l'URI di una directory Cloud Storage in cui vuoi che il job di addestramento salvi l'outputREGION
: 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 parametrojob-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 filesetup.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 semplicesetup.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 specificigcloud
e l'inizio diUSER_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:
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).Nella directory principale di tutto il codice che vuoi includere nel pacchetto di distribuzione
.tar.gz
(una directory dalla directorytrainer
se segui il pattern consigliato), includi il file Setuptools denominatosetup.py
, che include:Importa istruzioni per
setuptools.find_packages
esetuptools.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 sufind_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 comefrom trainer import util
) nel tuo "pacchetto di distribuzione" (il file ".tar.gz che contiene tutto il codice)._include_package_data
_ impostato suTrue
.
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()
disetuptools
nel filesetup.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.
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
- Configura ed esegui un job di addestramento.
- Monitora il job di addestramento durante l'esecuzione.
- Scopri di più su come funziona la formazione.