Containerizzazione ed esecuzione del codice di addestramento a livello locale

Puoi utilizzare il comando gcloud ai custom-jobs local-run per creare un'immagine container Docker basata sul codice di addestramento, per poi eseguirla come container sul computer locale. Questa funzionalità offre vari vantaggi:

  • Consente di creare un'immagine container con poche conoscenze di Docker. Non devi scrivere personalmente il Dockerfile. Puoi eseguire il push dell'immagine in un secondo momento in Artifact Registry e usarla per l'addestramento personalizzato del container.

    Per casi d'uso avanzati, potrebbe comunque essere utile scrivere personalmente il Dockerfile.

  • L'immagine container può eseguire un'applicazione di addestramento Python o uno script Bash.

    Puoi usare uno script Bash per eseguire codice di addestramento scritto in un altro linguaggio di programmazione, ma devi specificare anche un'immagine container di base che supporti l'altro linguaggio.

  • L'esecuzione in locale di un container permette di eseguire il codice di addestramento in modo simile a come viene fatto su Vertex AI.

    L'esecuzione in locale del codice è utile per eseguire il debug dei problemi del codice prima di eseguire l'addestramento personalizzato in Vertex AI.

Prima di iniziare

  1. Configura l'ambiente di sviluppo Vertex AI.

  2. Installa Docker Engine.

  3. Se utilizzi Linux, configura Docker in modo da poterlo eseguire senzasudo.

    Il comando local-run richiede questa configurazione per utilizzare Docker.

Utilizza il comando local-run

Esegui il comando in basso per creare un'immagine container basata sul codice di addestramento ed eseguire un container in locale:

gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME

Sostituisci quanto segue:

  • BASE_IMAGE_URI: l'URI di un'immagine Docker da utilizzare come base del container. Scegli un'immagine di base che includa le dipendenze necessarie per il codice di addestramento.

    Puoi utilizzare l'URI di un'immagine container di addestramento predefinito o qualsiasi altro valore valido per un'istruzione FROM di Dockerfile. Ad esempio, un'immagine Docker disponibile pubblicamente o un'immagine Docker in Artifact Registry a cui hai accesso.

  • WORKING_DIRECTORY: la directory di livello più basso nel file system che contiene tutto il codice di addestramento e le dipendenze locali da utilizzare per l'addestramento.

    Per impostazione predefinita, il comando copia solo la directory principale del file specificato dal flag --script (vedi la voce di elenco seguente) nell'immagine Docker risultante. L'immagine Docker non include necessariamente tutti i file all'interno di WORKING_DIRECTORY. Per personalizzare i file da includere, consulta la sezione di questo documento dedicata all'inclusione delle dipendenze.

    Se ometti il flag --local-package-path (e questo segnaposto), il comando local-run utilizza la directory di lavoro attuale per questo valore.

  • SCRIPT_PATH: il percorso relativo a WORKING_DIRECTORY nel file system locale e in cui si trova lo script che funge da punto di ingresso per il codice di addestramento. Può essere uno script Python (che termina con .py) o uno script Bash.

    Ad esempio, se vuoi eseguire /hello-world/trainer/task.py e WORKING_DIRECTORY è /hello-world, usa trainer/task.py per questo valore.

    Se specifichi uno script Python, nell'immagine di base deve essere installato Python, mentre se specifichi uno script Bash, nell'immagine di base deve essere installato Bash. Tutti i container di addestramento predefiniti e molte altre immagini Docker disponibili pubblicamente includono entrambe le dipendenze.

    Utilizza --python-module anziché --script

    Se ometti il flag --script (e SCRIPT_PATH), devi invece utilizzare il flag --python-module per specificare il nome di un modulo Python in WORKING_DIRECTORY da eseguire come punto di contatto per l'addestramento. Ad esempio, anziché --script=trainer/task.py, puoi specificare --python-module=trainer.task.

    In questo caso, il container Docker risultante carica il codice come modulo piuttosto che come script. Ti consigliamo di utilizzare questa opzione se lo script del punto di ingresso importa altri moduli Python in WORKING_DIRECTORY.

  • OUTPUT_IMAGE_NAME: un nome per l'immagine Docker risultante creata dal comando. Puoi utilizzare qualsiasi valore accettato dal -t docker build.

    Se prevedi di eseguire in un secondo momento il push dell'immagine ad Artifact Registry, ti conviene usare un nome immagine che soddisfi i requisiti di Artifact Registry. In alternativa, puoi contrassegnare l'immagine con nomi aggiuntivi in un secondo momento.

    Se ometti il flag --output-image-uri (e questo segnaposto), il comando local-run contrassegna l'immagine con un nome basato sull'ora attuale e sul nome file dello script del punto di ingresso.

Il comando crea un'immagine container Docker in base alla configurazione. Dopo la creazione dell'immagine, il comando stampa il seguente output:

A training image is built.
Starting to run ...

Il comando utilizza immediatamente questa immagine container per eseguire un container sul computer locale. Quando il contenitore esce, il comando stampa il seguente output:

A local run is finished successfully using custom image: OUTPUT_IMAGE_NAME

Opzioni aggiuntive

Le sezioni seguenti descrivono opzioni aggiuntive che puoi utilizzare per personalizzare il comportamento del comando local-run.

Installa le dipendenze

Il codice di addestramento può basarsi su qualsiasi dipendenza installata nell'immagine di base (ad esempio, le immagini container di addestramento predefinito includono molte librerie Python per il machine learning), nonché eventuali file inclusi nell'immagine Docker creata dal comando local-run.

Se specifichi uno script con il flag --script o --python-module, il comando copia la directory superiore dello script (e le sue sottodirectory) nell'immagine Docker. Ad esempio, se specifichi --local-package-path=/hello-world e --script=trainer/task.py, il comando copia /hello-world/trainer/ nell'immagine Docker.

Puoi anche includere dipendenze Python aggiuntive o file arbitrari dal tuo file system completando i passaggi aggiuntivi descritti in una delle sezioni seguenti:

Installa altre dipendenze Python

Puoi includere dipendenze Python aggiuntive nell'immagine Docker in diversi modi:

Utilizzare un file requirements.txt

Se nella directory di lavoro è presente un file denominato requirements.txt, il comando local-run lo considera un file dei requisiti pip e lo utilizza per installare le dipendenze Python nell'immagine Docker.

Utilizzare un file setup.py

Se nella directory di lavoro è presente un file denominato setup.py, il comando local-run lo considera un file setup.py Python, lo copia nell'immagine Docker ed esegue pip install nella directory dell'immagine Docker che contiene il file.

Ad esempio, puoi aggiungere un argomento install_requires a setup.py per installare le dipendenze Python nell'immagine Docker.

Specifica le singole dipendenze PyPI

Puoi utilizzare il flag --requirements per installare dipendenze specifiche da PyPI nell'immagine Docker. Ad esempio:

gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  --requirements=REQUIREMENTS

Sostituisci REQUIREMENTS con un elenco separato da virgole di specificatori dei requisiti di Python.

Specifica dipendenze Python locali aggiuntive

Puoi utilizzare il flag --extra-packages per installare specifiche dipendenze Python locali. Queste dipendenze Python devono trovarsi nella directory di lavoro e ogni dipendenza deve essere in un formato supportato da pip install, ad esempio un file wheel o una distribuzione di origine Python.

Ad esempio:

gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  --extra-packages=LOCAL_DEPENDENCIES

Sostituisci LOCAL_DEPENDENCIES con un elenco separato da virgole di percorsi file locali relativi alla directory di lavoro.

Includi altri file

Per copiare directory aggiuntive nell'immagine Docker (senza installarle come dipendenze di Python), puoi utilizzare il flag --extra-dirs. Puoi specificare solo le directory all'interno della directory di lavoro. Ad esempio:

gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  --extra-dirs=EXTRA_DIRECTORIES

Sostituisci EXTRA_DIRECTORIES con un elenco separato da virgole di directory locali relative alla directory di lavoro.

Argomenti dell'applicazione di addestramento

Se lo script del punto di ingresso dell'applicazione di addestramento richiede argomenti della riga di comando, puoi specificarli quando esegui il comando local-run. Questi argomenti non vengono salvati nell'immagine Docker, ma vengono passati come argomenti quando l'immagine viene eseguita come container.

Per trasmettere argomenti allo script del punto di ingresso, passa l'argomento -- seguito dagli argomenti dello script al comando local-run dopo tutti gli altri flag del comando.

Ad esempio, immagina uno script da eseguire localmente con il seguente comando:

python /hello-world/trainer/task.py \
  --learning_rate=0.1 \
  --input_data=gs://BUCKET/small-dataset/

Quando utilizzi il comando local-run, puoi utilizzare i seguenti flag per eseguire lo script nel container con gli stessi argomenti:

gcloud ai custom-jobs local-run \\
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=/hello-world \
  --script=/trainer/task.py \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  -- \
  --learning_rate=0.1 \
  --input_data=gs://BUCKET/small-dataset/

Accelera l'addestramento dei modelli con le GPU

Se alla fine vuoi eseguire il deployment in Vertex AI dell'immagine Docker creata dal comando local-run e utilizzare le GPU per l'addestramento, assicurati di scrivere un codice di addestramento che sfrutti le GPU e di utilizzare un'immagine Docker abilitata per GPU per il valore del flag --executor-image-uri. Ad esempio, puoi utilizzare una delle immagini container di addestramento predefinito che supporta le GPU.

Se il tuo computer locale esegue Linux e dispone di GPU, puoi anche configurare il comando local-run in modo che utilizzi le GPU quando esegue un container in locale. Questa opzione è facoltativa, ma può essere utile se vuoi testare il funzionamento del codice di addestramento con le GPU. Segui questi passaggi:

  1. Se non l'hai ancora fatto, installa NVIDIA Container Toolkit (nvidia-docker) sul tuo computer locale.

  2. Specifica il flag --gpu quando esegui il comando local-run. Ad esempio:

    gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  --gpu

Specifica un account di servizio personalizzato

Per impostazione predefinita, quando il comando local-run esegue il codice di addestramento in un contenitore locale, monta le credenziali Google Cloud disponibili nel tuo ambiente locale tramite le credenziali predefinite dell'applicazione (ADC) nel contenitore, in modo che il codice di addestramento possa utilizzare le credenziali predefinite dell'applicazione per l'autenticazione con le stesse credenziali. In altre parole, le credenziali disponibili da ADC nella shell locale sono disponibili anche da ADC per il tuo codice quando esegui il comando local-run.

Puoi utilizzare il comando gcloud auth application-default login per utilizzare il tuo account utente per ADC oppure puoi impostare una variabile di ambiente nella shell per utilizzare un account di servizio per ADC.

Se vuoi che il container venga eseguito con credenziali Google Cloud diverse da quelle disponibili da ADC nella shell locale, segui questi passaggi:

  1. Crea o seleziona un account di servizio con le autorizzazioni a cui vuoi che abbia accesso il tuo codice di addestramento.

  2. Scarica una chiave dell'account di servizio per questo account di servizio sul tuo computer locale.

  3. Quando esegui il comando local-run, specifica il flag --service-account-key-file. Ad esempio:

    gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  --service-account-key-file=KEY_PATH

    Sostituisci KEY_PATH con il percorso della chiave dell'account di servizio nel file system locale. Deve essere assoluto o relativo alla directory di lavoro corrente della shell, non alla directory specificata dal flag --local-package-path.

Nel container risultante, il codice di addestramento può utilizzare ADC per l'autenticazione con le credenziali dell'account di servizio specificate.

Confronto con l'addestramento su Vertex AI

Quando esegui l'addestramento personalizzato su Vertex AI, per impostazione predefinita Vertex AI utilizza l'agente di servizio del codice personalizzato Vertex AI per il tuo progetto per eseguire il codice. Puoi anche collegare un account di servizio diverso per l'addestramento personalizzato.

Quando usi il comando local-run, non puoi eseguire l'autenticazione come agente di servizio del codice personalizzato Vertex AI, ma puoi creare un account di servizio con autorizzazioni simili e usarlo localmente.

Passaggi successivi