Crea un'applicazione di addestramento Python per un container predefinito

Prima di poter eseguire l'addestramento personalizzato con un container predefinito, devi creare una distribuzione di origine Python contenente l'applicazione di addestramento e caricarla in un bucket Cloud Storage a cui può accedere il tuo progetto Google Cloud.

Nota: Vertex AI e la console Google Cloud a volte fanno riferimento a una distribuzione di origine come "pacchetto", che è l'abbreviazione di "pacchetto di distribuzione". Ogni distribuzione di origine può contenere uno o più "pacchetti di importazione". Questo documento utilizza il termine "pacchetto" per fare riferimento ai pacchetti di importazione.

Alternative per la creazione di una distribuzione del codice sorgente

Questa guida illustra la creazione manuale di una distribuzione di origine e il suo caricamento in Cloud Storage. Prima di seguire la guida, prendi in considerazione i seguenti flussi di lavoro alternativi, che in alcuni casi potrebbero essere più pratici:

• Se vuoi eseguire l'addestramento utilizzando il codice sul tuo computer locale e ridurre il più possibile la quantità di pacchettizzazione manuale, ti consigliamo di utilizzare la funzionalità di packaging automatico di Google Cloud CLI. Questa funzionalità consente di creare un'immagine container Docker, eseguirne il push su Container Registry e creare una risorsa CustomJob basata sull'immagine container, il tutto con un singolo comando. Scopri di più nella guida alla creazione di un CustomJob.

  Per utilizzare la pacchettizzazione automatica, devi installare Docker sul tuo computer locale. Questa opzione ti consente solo di creare una risorsa CustomJob, non TrainingPipeline o HyperparameterTuningJob. Scopri di più sulle differenze tra le risorse di addestramento personalizzato.

• Per personalizzare ulteriormente l'immagine container ed eseguire il codice in un container in locale prima di eseguirlo su Vertex AI, puoi utilizzare il comando local-run dell'interfaccia a riga di comando di gcloud per containerizzare il codice ed eseguirlo in locale. Quindi puoi eseguire manualmente il push dell'immagine su Artifact Registry o Container Registry.

  Per utilizzare il comando local-run, devi installare Docker sul tuo computer locale.

• Se puoi scrivere il tuo codice di addestramento in un singolo script Python, puoi utilizzare la classe CustomJob dell'SDK Vertex AI per Python per creare un job personalizzato o una CustomTrainingJob classe per creare un TrainingPipeline personalizzato. Il codice di addestramento viene pacchettizzato automaticamente come distribuzione di origine e caricato in Cloud Storage.

• Per la massima flessibilità, puoi creare manualmente un'immagine container personalizzata ed eseguirne il push su Artifact Registry o Container Registry.

Se nessuna delle opzioni precedenti è adatta al tuo caso d'uso o se preferisci pacchettizzare manualmente la tua applicazione di addestramento come distribuzione di origine, segui il resto di questa guida.

Prima di iniziare

Prima di preparare l'applicazione di addestramento per l'esecuzione nel cloud, completa questi passaggi:

1. Sviluppa la tua applicazione di addestramento utilizzando un framework di machine learning (ML) disponibile in uno dei container predefiniti per l'addestramento di Vertex AI. Assicurati che la tua applicazione di addestramento soddisfi i requisiti del codice di addestramento.

   Se stai scrivendo l'applicazione di addestramento da zero, ti consigliamo di organizzare il codice in base alla struttura dell'applicazione descritta nella seguente sezione del documento.

2. Crea un bucket Cloud Storage nello stesso progetto Google Cloud in cui prevedi di utilizzare Vertex AI. L'applicazione di addestramento verrà archiviata in questo bucket. Sebbene sia possibile utilizzare un bucket in un altro bucket Google Cloud, questa operazione richiede un'ulteriore configurazione che non rientra nell'ambito di questa guida.

   Per ottenere le migliori prestazioni, assicurati che il bucket Cloud Storage si trovi nella località in cui prevedi di utilizzare Vertex AI.

3. Scopri tutte le librerie Python da cui dipende la tua applicazione di addestramento, che si tratti di dipendenze personalizzate o liberamente disponibili tramite PyPI.

Struttura dell'applicazione

Quando esegui l'addestramento personalizzato utilizzando un container predefinito, devi specificare il codice di addestramento in base ai seguenti requisiti:

• Fornisci il codice come una o più distribuzioni di origine Python.

  Se utilizzi l'API Vertex AI per avviare l'addestramento personalizzato, specificali nel campo packageUris.

• Crea un modulo in una di queste distribuzioni di origine che funga da punto di ingresso per l'addestramento.

  Se utilizzi l'API Vertex AI per avviare l'addestramento personalizzato, specificalo nel campo pythonModule.

Se soddisfi questi requisiti, puoi strutturare la tua applicazione di addestramento come preferisci. Tuttavia, ti consigliamo di creare un'unica distribuzione del codice sorgente Python organizzando il codice nella seguente struttura (utilizzata spesso negli esempi di Vertex AI):

• Utilizza una directory del progetto principale contenente il file setup.py. Consulta la seguente sezione per indicazioni sui contenuti di questo file.

• All'interno della directory principale del progetto, crea una sottodirectory denominata trainer/, che funge da pacchetto principale per il tuo codice di addestramento.

• All'interno di trainer/, crea un modulo denominato task.py che funga da punto di ingresso per il codice di addestramento.

• Per supportare trainer/task.py, crea eventuali moduli Python aggiuntivi che vuoi includere nel pacchetto trainer/ e crea eventuali sottodirectory aggiuntive con il codice aggiuntivo che vuoi inserire nella directory principale del progetto.

• Crea un file __init__.py in ogni sottodirectory per trasformarla in un pacchetto.

La parte rimanente di questa guida presuppone che il codice sia organizzato in base a questa struttura.

Crea una distribuzione di origine

La creazione di distribuzioni di codice sorgente 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 una distribuzione di codice sorgente da utilizzare con Vertex AI. Esistono altre librerie che puoi usare per fare lo stesso.

1. Crea un file setup.py che indichi a setuptools come creare la distribuzione di origine. Un setup.py di base include quanto segue:

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

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

     • name impostato sul nome della distribuzione di origine.

     • version impostato sul numero di versione di questa build della distribuzione di origine.

     • install_requires impostato su un elenco di dipendenze richieste dall'applicazione, con requisiti di versione, come 'docutils>=0.3'.

     • packages impostato su find_packages(). Questo indica a setuptools di includere come pacchetti tutte le sottodirectory della directory padre che contengono un file __init__.py.

     • include_package_data impostato su True.

   L'esempio seguente mostra un file setup.py di base per un'applicazione di addestramento:

   from setuptools import find_packages
   from setuptools import setup
   
   setup(
       name='trainer',
       version='0.1',
       packages=find_packages(),
       include_package_data=True,
       description='My training application.'
   )
   

2. Esegui questo comando per creare una distribuzione di origine, dist/trainer-0.1.tar.gz:

   python setup.py sdist --formats=gztar
   

Dipendenze dell'applicazione Python

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

Per ogni replica nel job di addestramento personalizzato, il codice viene eseguito in un container con molte dipendenze Python comuni già installate. Controlla le dipendenze incluse nel container predefinito che prevedi di utilizzare per l'addestramento e prendi nota di eventuali dipendenze non ancora installate. Devi completare i passaggi seguenti solo per le dipendenze che non sono già installate nel container predefinito.

Esistono due tipi di dipendenze che potresti dover aggiungere:

• Dipendenze standard, che sono pacchetti di distribuzione comuni disponibili su PyPI.
• Dipendenze personalizzate, ad esempio i pacchetti sviluppati da te o quelle interne a un'organizzazione.

Le sezioni seguenti descrivono la procedura per ciascun tipo.

Dipendenze standard (PyPI)

Puoi specificare le dipendenze standard dell'applicazione come parte del relativo script setup.py. Vertex AI utilizza pip per installare l'applicazione di addestramento sulle repliche allocando per il job. Il comando pip install cerca le dipendenze configurate e le installa.

L'esempio seguente mostra un elemento setup.py simile a quello di una sezione precedente. Tuttavia, questo setup.py indica a Vertex AI di installare some_PyPI_package quando installa l'applicazione di addestramento:

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.'
)

Dipendenze personalizzate

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

Ogni URI che includi è il percorso di una distribuzione di origine, formattato come tarball (.tar.gz) o wheel (.whl). Vertex AI installa ogni dipendenza utilizzando pip install su ogni replica allocata per il job di addestramento.

Se utilizzi l'API Vertex AI per avviare l'addestramento personalizzato, specifica gli URI Cloud Storage di queste dipendenze insieme all'applicazione di addestramento nel campo packageUris.

Moduli Python

L'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 di una 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 utilizzi l'API Vertex AI per avviare l'addestramento personalizzato, imposta il campo moduleName su trainer.task.

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

Carica la distribuzione di origine in Cloud Storage

Puoi utilizzare lo strumento gsutil per caricare la tua distribuzione di origine ed eventuali dipendenze personalizzate in un bucket Cloud Storage. Ad esempio:

gsutil cp dist/trainer-0.1.tar.gz CLOUD_STORAGE_DIRECTORY

Sostituisci CLOUD_STORAGE_DIRECTORY con l'URI (che inizia con gs:// e termina con /) di una directory Cloud Storage in un bucket a cui può accedere il tuo progetto Google Cloud.

Per scoprire altri modi per caricare la distribuzione di origine in Cloud Storage, consulta Caricamento di oggetti nella documentazione di Cloud Storage.

Passaggi successivi

• Scopri di più sui requisiti aggiuntivi del codice di addestramento per l'addestramento personalizzato.
• Scopri come creare un job di addestramento personalizzato o una pipeline di addestramento personalizzato che utilizza la tua applicazione di addestramento.