Esegui carichi di lavoro predefiniti

Se ti interessa Vertex AI Managed Training, contatta il tuo rappresentante di vendita per accedere.

Questa guida mostra come utilizzare l'ecosistema NVIDIA NeMo su un cluster di addestramento gestito per lo sviluppo di modelli di AI generativa end-to-end. Fornisce istruzioni passo passo per i seguenti flussi di lavoro distinti ma correlati, ognuno trattato in una sezione dedicata:

  • NVIDIA NeMo: per lo sviluppo di modelli di base, segui queste istruzioni per eseguire il pre-addestramento su larga scala, il pre-addestramento continuo (CPT) e il fine-tuning supervisionato (SFT).
  • NVIDIA NeMo-RL: per l'allineamento del modello e l'ottimizzazione delle preferenze, utilizza questa sezione per applicare tecniche avanzate come l'apprendimento per rinforzo (RL) per allineare il tuo modello alle istruzioni e alle preferenze umane.

Che tu stia creando un modello da zero o perfezionandone uno esistente, questo documento ti guida nella configurazione dell'ambiente, nella gestione dei job containerizzati e nell'avvio degli script di addestramento sul cluster.

NVIDIA NeMo

Il framework NVIDIA NeMo è una piattaforma end-to-end per creare, personalizzare ed eseguire il deployment di modelli di AI generativa. Questa sezione della guida è pensata specificamente per sviluppatori e ricercatori che si concentrano sulle fasi fondamentali dello sviluppo del modello. Fornisce istruzioni passo passo per utilizzare NeMo per eseguire il pre-addestramento su larga scala, il pre-addestramento continuo (CPT) e l'ottimizzazione supervisionata (SFT) su un cluster Managed Training.

Questa guida sui cluster di addestramento fornisce il workflow completo per l'esecuzione di un job di addestramento con il framework NeMo. Il processo è suddiviso in due parti principali: la configurazione iniziale una tantum dell'ambiente e i passaggi ricorrenti per l'avvio di un job.

Configura l'ambiente

Prima di avviare un job, devi preparare l'ambiente assicurandoti di disporre di un'immagine container e degli script di addestramento necessari.

Prepara un'immagine container

Hai due opzioni per l'immagine container: utilizzare un'immagine predefinita (consigliata) o crearne una personalizzata.

Utilizzare un'immagine predefinita (consigliato)

Le immagini container predefinite sono fornite nel formato .squashfs. Copia l'immagine appropriata per la tua regione nella directory di lavoro.

# Example for the US region
gcloud storage cp gs://vmds-containers-us/nemo_squashfs/nemo-20250721.sqsh .
Crea un container personalizzato (avanzato)

Segui questi passaggi solo se i contenitori predefiniti non soddisfano le tue esigenze. Questa procedura ti guida nella conversione di un'immagine container personalizzata nel formato .squashfs utilizzando enroot.

Passaggio 1: esegui l'autenticazione con Google Cloud.

Utilizza i seguenti comandi per assicurarti che sia il tuo Google Cloud account utente sia il registro Docker in cui è ospitata l'immagine siano autenticati:

gcloud auth login
gcloud auth configure-docker us-docker.pkg.dev

Passaggio 2: crea lo script di conversione.

Crea un file denominato enroot-convert.sh e aggiungi i seguenti contenuti dello script. Prima di eseguire questo script, devi aggiornare le variabili REMOTE_IMG e LOCAL_IMG in modo che puntino all'immagine del container e al percorso di output scelto.

#!/bin/bash

#SBATCH --gpus-per-node=8
#SBATCH --exclusive
#SBATCH --mem=0
#SBATCH --ntasks-per-node=1

# Run this script on the slurm login node:
# sbatch -N 1 enroot-convert.sh

set -x
set -e

# The remote docker image URI.
REMOTE_IMG="docker://us-docker.pkg.dev/{YOUR_CONTAINER_IMG_URI}:{YOUR_CONTAINER_IMAGE_TAG}"

# The local path to the to be imported enroot squash file.
LOCAL_IMG="${HOME}/my_nemo.sqsh"

# The path to the enroot config file.
TMP_ENROOT_CONFIG_PATH="/tmp/\$(id -u --name)/config/enroot"

# Download the docker image to each node.
srun -l -N "${SLURM_NNODES}" \
bash -c "
mkdir -p ${TMP_ENROOT_CONFIG_PATH};
echo 'machine us-docker.pkg.dev login oauth2accesstoken password $(gcloud auth print-access-token)' > ${TMP_ENROOT_CONFIG_PATH}/.credentials;
rm -f ${LOCAL_IMG};
ENROOT_CONFIG_PATH=${TMP_ENROOT_CONFIG_PATH} ENROOT_MAX_PROCESSORS=$(( $(nproc) / 2 )) enroot import -o ${LOCAL_IMG} ${REMOTE_IMG};
"

Passaggio 3: esegui lo script e verifica l'output.

Esegui lo script sul nodo di accesso Slurm.

sbatch -N 1 enroot-convert.sh

Al termine del job, trova i log di conversione in un file denominato slurm-<JOB_ID>.out e l'immagine container finale nel percorso specificato per LOCAL_IMG.

Scaricare le ricette di allenamento

Le ricette di addestramento sono archiviate in un repository privato googlesource.com. Per accedervi con la riga di comando Git, devi prima generare le credenziali di autenticazione.

  1. Genera credenziali di autenticazione.

    Visita il seguente URL e segui le istruzioni sullo schermo. In questo modo, l'ambiente locale viene configurato per l'autenticazione con il repository. https://www.googlesource.com/new-password

  2. Clona il repository.

    Una volta autenticate le credenziali, esegui questo comando per scaricare le ricette.

    git clone https://vertex-model-garden.googlesource.com/vertex-oss-training

Avvia un job di addestramento

Una volta configurato l'ambiente, puoi avviare un job di addestramento.

Passaggio 1: imposta le variabili di ambiente

Per il tuo job potrebbero essere necessarie le seguenti variabili di ambiente:

  • HF_TOKEN è necessario per scaricare modelli e set di dati da Hugging Face.
  • WANDB_API_KEY è necessario per utilizzare Weights & Biases per l'analisi degli esperimenti.
export HF_TOKEN=YOUR_HF_TOKEN
export WANDB_API_KEY=YOUR_WANDB_API_KEY

Passaggio 2: esegui lo script di avvio

Vai alla directory di lavoro ed esegui lo script run.py per avviare un job. Questo esempio avvia un job di addestramento demo con Llama 3.1-2b.

# Set the working directory
export WORK_DIR=$HOME/vertex-oss-training/nemo
cd $WORK_DIR

gcloud storage cp
gs://vmds-containers-<region>/nemo_squashfs/nemo-20250721.sqsh nemo-demo.sqsh

# Launch the training job
export NEMORUN_HOME=$WORK_DIR && \
python3 run.py -e slurm --slurm-type hcc-a3m --partition a3m \
  -d $WORK_DIR -i $WORK_DIR/nemo-demo.sqsh \
  -s pretrain/llama3p1_2b_pt.py -n 2 \
  --experiment-name nemo-demo-run

Parametri di avvio

  • --slurm-type è impostato in base al tipo di cluster (ad esempio hcc-a3m, hcc-a3u, hcc-a4).
  • --partition deve essere impostato su una partizione disponibile. Puoi controllare i nomi delle partizioni con il comando sinfo.
  • Lo script run.py monta automaticamente diverse directory nel container Docker, tra cui --log-dir, --cache-dir e --data-dir, se sono impostate.

Monitoraggio dello stato e dei log del job

Dopo aver avviato il job, viene visualizzato un blocco di stato:

Experiment Status for nemo-demo-run_1753123402

Task 0: nemo-demo-run
- Status: RUNNING
- Executor: SlurmExecutor on @localhost
- Job id: 75
- Local Directory: $NEMORUN_HOME/experiments/nemo-demo-run/nemo-demo-run_1753123402/nemo-demo-run

I log di esecuzione vengono scritti nel percorso mostrato nel campo Local Directory dell'output di stato. Ad esempio, puoi trovare i file di log in un percorso simile a questo:

$NEMORUN_HOME/experiments/nemo-demo-run/nemo-demo-run_1753123402/nemo-demo-run/<JOB_ID>.log

Errori comuni e soluzioni

Questa sezione descrive i problemi comuni che possono verificarsi durante l'esecuzione dei job e fornisce i passaggi consigliati per risolverli.

Errore di partizione non valida

Per impostazione predefinita, i job tentano di essere avviati nella partizione generale. Se la partizione generale non esiste o non è disponibile, il job non andrà a buon fine e verrà visualizzato il seguente errore:

sbatch: error: invalid partition specified: general
sbatch: error: Batch job submission failed: Invalid partition name specified

Soluzione:

Specifica una partizione disponibile utilizzando l'argomento --partition o -p nel comando di avvio. Per visualizzare un elenco delle partizioni disponibili, esegui il comando sinfo sul nodo di accesso Slurm.

sinfo

L'output mostra i nomi delle partizioni disponibili, ad esempio a3u in questo esempio:

PARTITION AVAIL TIMELIMIT NODES STATO NODELIST
a3u* Freccia su infinito 2 idle~ alice-a3u-[2-3]
a3u* Freccia su infinito 2 inattivo alice-a3u-[0-1]

Errore di download del tokenizzatore

Potresti riscontrare un errore OSError relativo a un collegamento tra dispositivi quando lo script tenta di scaricare il tokenizer GPT2:

OSError: [Errno 18] Invalid cross-device link: 'gpt2-vocab.json' -> '/root/.cache/torch/megatron/megatron-gpt-345m_vocab'

Soluzioni:

Per risolvere il problema, hai due opzioni:

  • Opzione 1: Esegui nuovamente il job. Questo errore è spesso transitorio. Se esegui di nuovo il job utilizzando lo stesso --cache-dir, il problema potrebbe risolversi.
  • Opzione 2: Scarica manualmente i file del tokenizer. Se la riesecuzione del job non va a buon fine, segui questi passaggi:
    • Scarica i due file seguenti:
      • gpt2-vocab.json
      • gpt2-merges.txt
    • Sposta i file scaricati nella sottodirectory torch/megatron/ all'interno della directory della cache (ad esempio, <var>YOUR_CACHE_DIR</var>/torch/megatron/).
    • Rinomina i file come segue:
      • Rinomina gpt2-vocab.json in megatron-gpt-345m_vocab.
      • Rinomina gpt2-merges.txt in megatron-gpt-345m_merges.

NVIDIA NeMo-RL

Il framework NVIDIA NeMo-RL è progettato per allineare i modelli linguistici di grandi dimensioni (LLM) alle preferenze e alle istruzioni umane. Questa sezione ti guida nell'utilizzo di NeMo-RL su un cluster per eseguire attività di allineamento avanzate, tra cui il fine-tuning supervisionato (SFT), l'ottimizzazione delle preferenze (come l'ottimizzazione diretta delle preferenze o DPO) e l'apprendimento per rinforzo (RL).

La guida copre due flussi di lavoro principali: l'esecuzione di un job di addestramento batch standard e l'utilizzo dell'ambiente di sviluppo interattivo per il debug.

Prerequisiti

Prima di iniziare, crea un cluster seguendo le istruzioni riportate nella pagina Crea cluster o utilizza un cluster Managed Training esistente, se ne hai uno.

Connettiti al nodo di accesso del cluster

Per connetterti al nodo di accesso del cluster, trova il comando Google Cloud CLI corretto accedendo alla pagina Macchina virtuale Google Compute Engine nella console Google Google Cloud e facendo clic su SSH > Visualizza comando Google Cloud CLI. che saranno simili a quanto segue:

ssh $USER_NAME@machine-addr

Esempio:

ssh $USER_NAME@nic0.sliua3m1-login-001.europe-north1-c.c.infinipod-shared-dev.internal.gcpnode.com

Utilizza l'immagine Docker predefinita

I file .sqsh convertiti vengono forniti per le immagini container predefinite. Puoi selezionare un container per la tua regione e impostarlo direttamente come parametro dell'immagine container o scaricarlo nel file system del cluster.

Per impostarlo direttamente come parametro dell'immagine container, utilizza uno dei seguenti percorsi. Tieni presente che devi sostituire <region> con la tua regione specifica (ad esempio, europe, asia, us):

/gcs/vmds-containers-<region>/nemo_rl_squashfs/nemo_rl-h20250923.sqsh

Per scaricare l'immagine nell'archivio Lustre del cluster, utilizza il seguente comando:

gs://vmds-containers-<region>/nemo_rl_squashfs/nemo_rl-h20250923.sqsh DESTINATION

Scarica codice

Per accedere alla ricetta di addestramento con la CLI git, visita la pagina https://www.googlesource.com/new-password. La ricetta può essere scaricata con il seguente comando:

cd $HOME
git clone https://vertex-model-garden.googlesource.com/vertex-oss-training

Avviare job

Passaggio 1: imposta le variabili di ambiente.

Per estrarre modelli e dati da Hugging Face, potrebbe essere necessario impostare HF_TOKEN. Per utilizzare Weights & Biases per l'analisi degli esperimenti, è necessario impostare WANDB_API_KEY. Aggiorna queste variabili nel seguente file:

File da aggiornare: $HOME/vertex-oss-training/nemo_rl/configs/auth.sh

Se non vuoi utilizzare Weights & Biases, imposta logger.wandb_enabled su False nello script di avvio.

Passaggio 2: scarica o copia il file del contenitore nella cartella di lancio.

Di seguito sono riportati alcuni esempi.

gcloud storage cp \
  gs://vmds-containers-<region>/vmds_nemo_rl_squashfs/nemo_rl-20250923.sqsh \
  $HOME/vertex-oss-training/nemo_rl/nemo_rl-h20250923.sqsh


# OR

/gcs/vmds-containers-<region>/vmds_nemo_rl_squashfs/nemo_rl-h20250923.sqsh \
  $HOME/vertex-oss-training/nemo_rl/nemo_rl-h20250923.sqsh

cd $HOME/vertex-oss-training/nemo_rl/

# Where region is either `us`, `asia`, or `europe`

Passaggio 3: prepara o clona il repository NeMo-RL.

Crea un clone del codice NeMo-RL se non è già presente. Tieni presente che potresti dover utilizzare git submodule update --init --recursive se hai già clonato il repository senza il flag --recursive.

git clone https://github.com/NVIDIA-NeMo/RL --recursive

Passaggio 4: avvia il job di addestramento.

sbatch -N <num_nodes> launch.sh --cluster_type hcc-a3m --job_script algorithms/dpo.sh

Dove:

  • --cluster-type è impostato in base al tipo di cluster:
    • A3-Mega: hcc-a3m
    • A3-Ultra: hcc-a3u
    • A4: hcc-a4
    • A3H: hcc-a3h
  • --partition deve essere impostato di conseguenza, dove sinfo può essere utilizzato per controllare le partizioni Slurm.

Dopo l'avvio del job, viene creata una nuova directory con il nome dell'ID job SLURM nella posizione corrente. All'interno troverai tutti i log e i checkpoint appartenenti a questo job. Più precisamente, all'interno troverai le seguenti directory e file:

  • checkpoints/ → Questa directory è montata all'interno del container NeMo-RL e contiene tutti i checkpoint dell'addestramento.
  • ray-logs/ → Questa directory contiene i log di ray head e dei worker ray.
  • nemo_rl_output.log → Questo file contiene i log di Slurm del job inviato.
  • attach.sh (solo per i job interattivi) → Questo è uno script bash che ti consente di collegarti a un job interattivo. Se il job viene avviato correttamente, la creazione del file potrebbe richiedere un paio di minuti.

Sviluppo con NeMo-RL

Configurazione interattiva

Sono disponibili due opzioni per lo sviluppo interattivo rapido con NeMo-RL.

nemorlinteractive

Si tratta di un semplice comando helper che ti consente di scegliere un nodo GPU dal cluster (ad esempio il nodo numero 5), quindi ti porta a un container in esecuzione per NeMo-RL all'interno del nodo selezionato. Questo comando è utile per i flussi di lavoro a nodo singolo.

Per utilizzare nemorlinteractive, devi seguire questi passaggi preliminari:

  1. Fornisci tutti i token di autenticazione che vuoi (ad esempio HF e WandB) caricati nel job nel file configs/auth.sh.

  2. Imposta la variabile di ambiente CLUSTER_TYPE in base alle seguenti linee guida:

    export CLUSTER_TYPE="hcc-a3m" # --> if you have A3-Mega cluster
export CLUSTER_TYPE="hcc-a3u" # --> if you have A3-Ultra cluster
export CLUSTER_TYPE="hcc-a4"  # --> If you have A4 cluster
export CLUSTER_TYPE="hcc-a3h" # --> If you have A3H cluster

  3. Importa nemorlinteractive nel terminale bash eseguendo l'origine di bash_utils.sh:

    source bash_utils.sh

  4. Esegui il comando nemorlinteractive. Ad esempio:

    # Assuming you want to take the compute node number 5.
nemorlinteractive 5

Avvio interattivo

Questa opzione ti consente di eseguire i carichi di lavoro in modo interattivo su più nodi di calcolo. I job interattivi sono più adatti per i casi d'uso di debug e verifica. Questi workload riservano il nodo a tempo indeterminato finché lo sviluppatore non decide che il debug è terminato e vuole rilasciare le risorse.

Di seguito sono riportati i passaggi da seguire per questa opzione:

Fornisci tutti i token di autenticazione che vuoi (ad esempio HF e WandB) caricati nel job nel file configs/auth.sh.

sbatch -N <num_nodes> launch.sh --cluster_type hcc-a3m --interactive

  • Attendi 2-5 minuti e dovresti visualizzare <job_id>/attach.sh creato.

  • Per monitorare l'avanzamento del controllo di avvio <job_id>/nemo_rl_output.log, visualizza l'avanzamento dello script di avvio e controlla <job_id>/ray_logs/ per visualizzare l'avanzamento dell'avvio di ray head e dei worker.

  • Connettiti all'attività interattiva. Questo script ti consente di riconnetterti anche se perdi la connessione:

bash <job_id>/attach.sh

Passaggi successivi

L'esecuzione di un carico di lavoro predefinito verifica lo stato operativo del cluster. Il passaggio successivo consiste nell'eseguire la tua applicazione di addestramento personalizzato.