Puoi usare il comando gcloud ai custom-jobs local-run
per creare un'immagine container Docker basata sul tuo codice di addestramento ed eseguire l'immagine come container sul tuo computer locale. Questa funzionalità offre vari vantaggi:
Consente di creare un'immagine container con poche conoscenze di Docker. Non devi scrivere il tuo Dockerfile. In seguito puoi eseguire il push di questa immagine ad Artifact Registry e utilizzarla per l'addestramento personalizzato dei container.
Per casi d'uso avanzati, potresti comunque voler scrivere il tuo Dockerfile.
L'immagine container può eseguire un'applicazione di addestramento Python o uno script Bash.
Puoi utilizzare uno script Bash per eseguire codice di addestramento scritto in un altro linguaggio di programmazione (purché specifichi anche un'immagine container di base che supporti l'altro linguaggio).
L'esecuzione di un container in locale esegue il codice di addestramento in modo simile a quando viene eseguito su Vertex AI.
L'esecuzione locale del codice consente di eseguire il debug dei problemi prima di eseguire l'addestramento personalizzato su Vertex AI.
Prima di iniziare
Se utilizzi Linux, configura Docker in modo da poterlo eseguire senza
sudo
.Il comando
local-run
richiede questa configurazione per utilizzare Docker.
Usa il comando local-run
Esegui questo comando per creare un'immagine container basata sul tuo 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 per un'immagine container di addestramento predefinito o per qualsiasi altro valore valido per un'istruzione Dockerfile
FROM
, 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 tuo file system che contiene tutto il codice di addestramento e le dipendenze locali necessarie per l'addestramento.
Per impostazione predefinita, il comando copia solo la directory padre del file specificata 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 sull'inclusione delle dipendenze.Se ometti il flag
--local-package-path
(e questo segnaposto), il comandolocal-run
utilizza la directory di lavoro corrente per questo valore.SCRIPT_PATH: il percorso, relativo a WORKING_DIRECTORY nel file system locale, allo script che è il 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
, utilizzatrainer/task.py
per questo valore.Se specifichi uno script Python, nell'immagine di base deve essere installato Python. Se specifichi uno script Bash, sull'immagine di base deve essere installato Bash. Tutti i container di addestramento predefiniti e molte altre immagini Docker disponibili pubblicamente includono entrambe le dipendenze.
Usa
--python-module
anziché--script
Se ometti il flag
--script
(e SCRIPT_PATH), devi invece usare il flag--python-module
per specificare il nome di un modulo Python in WORKING_DIRECTORY da eseguire come punto di ingresso 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 anziché 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 flag
-t
didocker build
.Se intendi eseguire il push dell'immagine in Artifact Registry in un secondo momento, ti consigliamo di utilizzare 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 comandolocal-run
tagga l'immagine con un nome basato sull'ora corrente e il nome file dello script del punto di ingresso.
Il comando crea un'immagine container Docker basata sulla tua configurazione. Dopo aver creato l'immagine, il comando visualizza il seguente output:
A training image is built.
Starting to run ...
Il comando usa immediatamente questa immagine container per eseguire un container sul tuo computer locale. All'uscita del container, il comando visualizza il seguente output:
A local run is finished successfully using custom image: OUTPUT_IMAGE_NAME
Opzioni aggiuntive
Le seguenti sezioni descrivono ulteriori opzioni che puoi utilizzare per personalizzare il comportamento del comando local-run
.
Installa le dipendenze
Il codice di addestramento può basarsi su qualsiasi dipendenza installata sull'immagine di base (ad esempio, le immagini dei container di addestramento predefiniti includono molte librerie Python per il machine learning), nonché qualsiasi file che includi nell'immagine Docker creata con il comando local-run
.
Quando specifichi uno script con il flag --script
o il flag --python-module
, il comando copia la directory padre dello script (e le relative 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 ulteriori dipendenze Python o file arbitrari dal tuo file system completando i passaggi aggiuntivi descritti in una delle seguenti sezioni:
- Utilizzo di un file
requirements.txt
per le dipendenze Python - Utilizzo di un file
setup.py
per le dipendenze Python - Specifica delle singole dipendenze PyPI
- Specifica delle dipendenze Python locali
- Inclusione di altri file
Installa le dipendenze Python aggiuntive
Puoi includere ulteriori dipendenze Python nell'immagine Docker in diversi modi:
Usa un file requirements.txt
Se nella directory di lavoro è presente un file denominato requirements.txt
, il comando local-run
lo considera come un file dei requisiti pip e lo utilizza per installare le dipendenze Python nell'immagine Docker.
Usa un file setup.py
Se nella directory di lavoro è presente un file denominato setup.py
, il comando local-run
lo considera come file setup.py
Python, copia il file 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 usare 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 indicatori dei requisiti Python.
Specifica ulteriori dipendenze Python locali
Puoi usare il flag --extra-packages
per installare dipendenze Python locali specifiche. Queste dipendenze Python devono trovarsi all'interno della 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 dei file locali, espressi in relazione alla directory di lavoro.
Includi altri file
Per copiare directory aggiuntive nell'immagine Docker (senza installarle come dipendenze Python), puoi utilizzare il flag --extra-dirs
. Puoi specificare solo
le directory nella 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, espresse in relazione alla directory di lavoro.
Argomenti dell'applicazione di addestramento
Se lo script del punto di ingresso per l'applicazione di addestramento prevede 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 usi 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 dell'immagine Docker creata dal comando local-run
in Vertex AI e utilizzare le GPU per l'addestramento, assicurati di scrivere un codice di addestramento che sfrutti le GPU e utilizzare un'immagine Docker abilitata per GPU per il valore del flag --executor-image-uri
. Ad esempio, puoi utilizzare una delle immagini del container di addestramento predefinito che supportano 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 viene eseguito un container in locale. Questa operazione è facoltativa, ma può essere utile se vuoi testare il funzionamento del codice di addestramento con le GPU. Segui questi passaggi:
Installa NVIDIA Container Toolkit (
nvidia-docker
) sul tuo computer locale, se non lo hai già fatto.Specifica il flag
--gpu
quando esegui il comandolocal-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 container locale,
monta le credenziali Google Cloud disponibili nel tuo ambiente locale tramite ADC (Application default Credentials) nel container, in modo che il tuo codice di addestramento possa utilizzare ADC per l'autenticazione con le stesse credenziali. In altre parole, le credenziali disponibili da ADC nella tua shell locale sono disponibili anche tramite 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:
Crea o seleziona un account di servizio con le autorizzazioni a cui vuoi che abbia accesso il tuo codice di addestramento.
Scarica una chiave dell'account di servizio per questo account di servizio sul tuo computer locale.
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 tuo file system locale. Deve essere assoluto o relativo alla directory di lavoro corrente della shell, non rispetto alla directory specificata dal flag
--local-package-path
.
Nel container risultante, il tuo 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, Vertex AI utilizza per impostazione predefinita 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 utilizzi il comando local-run
, non puoi autenticarti come agente di servizio del codice personalizzato Vertex AI, ma puoi creare un account di servizio con autorizzazioni simili e utilizzarlo localmente.
Passaggi successivi
Scopri i requisiti per il codice di addestramento.
Scopri come eseguire il push dell'immagine Docker su Artifact Registry e usarla come container personalizzato per l'addestramento su Vertex AI.