Creare un'applicazione di addestramento Python per un container predefinito

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

Nota: Agent Platform 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 alla creazione di una distribuzione di origine

Questa guida illustra come creare manualmente una distribuzione di origine e caricarla su Cloud Storage. Prima di seguire la guida, considera i seguenti flussi di lavoro alternativi, che potrebbero essere più convenienti in alcuni casi:

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

  Per utilizzare il pacchettizzazione automatica, devi installare Docker sul tuo computer locale. Questa opzione consente di creare solo una risorsa CustomJob, non una risorsa TrainingPipeline o HyperparameterTuningJob. (Scopri le differenze tra le risorse di addestramento serverless.)

• Per personalizzare ulteriormente l'immagine container ed eseguire il codice in un container localmente prima di eseguirlo su Agent Platform, puoi utilizzare il comando local-run di gcloud CLI per containerizzare il codice ed eseguirlo localmente. Poi puoi eseguire il push dell'immagine in Artifact Registry manualmente.

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

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

• Per la massima flessibilità, puoi creare manualmente un'immagine container personalizzata ed eseguirne il push ad Artifact 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 codice sorgente, segui il resto di questa guida.

Prima di iniziare

Prima di preparare l'applicazione di addestramento per l'esecuzione nel cloud, completa i seguenti 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 Agent Platform. Assicurati che l'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 in una sezione successiva di questo documento.

2. Crea un bucket Cloud Storage nello stesso progetto Google Cloud in cui prevedi di utilizzare la piattaforma dell'agente. In questo bucket archivierai la tua applicazione di addestramento. (Sebbene sia possibile utilizzare un bucket in un bucketGoogle Cloud diverso, questa operazione richiede una configurazione aggiuntiva al di fuori dell'ambito di questa guida.)

   Per ottenere prestazioni ottimali, assicurati che il bucket Cloud Storage si trovi nella località in cui prevedi di utilizzare Agent Platform.

3. Conosci tutte le librerie Python da cui dipende la tua applicazione di addestramento, indipendentemente dal fatto che si tratti di dipendenze personalizzate o disponibili senza costi tramite PyPI.

Struttura dell'applicazione

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

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

  Se utilizzi l'API Agent Platform per avviare l'addestramento serverless, specifica questi valori 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 Agent Platform 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 di origine Python organizzando il codice nella seguente struttura (che viene spesso utilizzata negli esempi di Agent Platform):

• Utilizza una directory di progetto principale contenente il file setup.py. Per indicazioni sui contenuti di questo file, consulta la sezione seguente.

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

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

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

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

Il resto 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 esula ampiamente dall'ambito di questa documentazione. Per comodità, questa sezione fornisce una panoramica dell'utilizzo di Setuptools per creare una distribuzione di origine da utilizzare con Agent Platform. Esistono altre librerie che puoi utilizzare per fare la stessa cosa.

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

   • Importa gli estratti conto per setuptools.find_packages e setuptools.setup.

   • Una chiamata a setuptools.setup con (almeno) i seguenti 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 dalla tua applicazione, con requisiti di versione, ad esempio 'docutils>=0.3'.

     • packages impostato su find_packages(). In questo modo, Setuptools include come pacchetti tutte le sottodirectory della directory principale 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 delle applicazioni Python

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

Per ogni replica nel job di addestramento serverless, 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 quelle non ancora installate. Devi completare i seguenti passaggi solo per le dipendenze che non sono già installate nel container predefinito.

Esistono due tipi di dipendenze che potresti dover aggiungere:

• Dipendenze standard, ovvero pacchetti di distribuzione comuni disponibili su PyPI
• Dipendenze personalizzate, come i pacchetti che hai sviluppato tu o quelli interni a un'organizzazione.

Le sezioni seguenti descrivono la procedura per ogni tipo.

Dipendenze standard (PyPI)

Puoi specificare le dipendenze standard della tua applicazione nello script setup.py. Agent Platform utilizza pip per installare l'applicazione di addestramento sulle repliche che alloca per il job. Il comando pip install cerca le dipendenze configurate e le installa.

L'esempio seguente mostra un setup.py simile a quello di una sezione precedente. Tuttavia, questo setup.py indica ad Agent Platform 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 della tua applicazione passando i relativi percorsi come parte della configurazione del job. Devi avere l'URI della distribuzione di origine di ogni dipendenza. Le dipendenze personalizzate devono trovarsi in una località Cloud Storage. Agent Platform utilizza pip install per installare dipendenze personalizzate, in modo che possano avere le proprie dipendenze standard negli script setup.py.

Ogni URI che includi è il percorso di una distribuzione di origine, formattata come file tar (.tar.gz) o come wheel (.whl). Agent Platform installa ogni dipendenza utilizzando pip install su ogni replica che alloca per il job di addestramento.

Se utilizzi l'API Agent Platform per avviare l'addestramento serverless, specifica gli URI Cloud Storage di queste dipendenze insieme alla tua applicazione di addestramento nel campo packageUris.

Moduli Python

La tua applicazione può contenere più moduli (file Python). Devi identificare il modulo che contiene l'entry point dell'applicazione. Il servizio di addestramento esegue il modulo richiamando Python, proprio come faresti in locale.

Ad esempio, se segui la struttura consigliata in una 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 utilizzi l'API Agent Platform per avviare l'addestramento personalizzato, imposta il campo moduleName su trainer.task.

Per saperne di più sui moduli, consulta la guida di Python ai pacchetti.

Carica la distribuzione di origine su Cloud Storage

Puoi utilizzare gcloud CLI per caricare la distribuzione del codice sorgente e le eventuali dipendenze personalizzate in un bucket Cloud Storage. Ad esempio:

gcloud storage 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 il tuo progettoGoogle Cloud può accedere.

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

Esegui la migrazione da python_package_spec a container_spec

La configurazione PythonPackageSpec (executorImageUri) accetta solo container di addestramento predefiniti supportati ufficialmente. Se il tuo framework o runtime ha raggiunto la fine della disponibilità (EOA), ad esempio scikit-learn o XGBoost, o se hai bisogno di versioni più recenti di Python (ad esempio Python 3.11 e versioni successive) e di librerie di sistema esterne, esegui la migrazione del workload di addestramento per utilizzare ContainerSpec.

A differenza di python_package_spec, ContainerSpec non ha campi package_uris o python_module.

Per eseguire la migrazione del workload a container_spec, scegli uno dei seguenti approcci:

• Mantieni i pacchetti su Cloud Storage: passa l'URI del pacchetto tramite args o env a uno script entrypoint nel container che scarica il pacchetto, lo installa con pip ed esegue python -m <module>.

  Ad esempio, nello script entrypoint del container:

  #!/usr/bin/env bash
  set -e
  
  PACKAGE_URI="$1"
  MODULE_NAME="$2"
  shift 2
  
  gcloud storage cp "${PACKAGE_URI}" ./package.tar.gz
  pip install --no-cache-dir ./package.tar.gz
  python -m "${MODULE_NAME}" "$@"
  

• Crea il codice nell'immagine: in alternativa, copia i file e le dipendenze dell'applicazione di addestramento direttamente nell'immagine Docker al momento della creazione (ad esempio, con COPY e pip install nel tuo Dockerfile) e imposta l'entrypoint direttamente nell'immagine.

Passaggi successivi

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