Esegui carichi di lavoro predefiniti

Se ti interessa l'addestramento gestito di Gemini Enterprise Agent Platform, contatta il tuo rappresentante di vendita per l'accesso.

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 workflow distinti ma correlati, ognuno trattato nella propria 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 dei modelli e l'ottimizzazione delle preferenze, utilizza questa sezione per applicare tecniche avanzate come il reinforcement learning (RL) per allineare il 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 la creazione, la personalizzazione e il deployment di modelli di AI generativa. Questa sezione della guida è rivolta in particolare a sviluppatori e ricercatori che si concentrano sulle fasi fondamentali dello sviluppo dei modelli. Fornisce istruzioni passo passo per l'utilizzo di NeMo per eseguire il pre-addestramento su larga scala, il pre-addestramento continuo (CPT) e l'ottimizzazione supervisionata (SFT) su un cluster di addestramento gestito.

Questa guida ai cluster di addestramento fornisce il workflow completo per l'esecuzione di un job di addestramento con il framework NeMo. La procedura è suddivisa 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 avere un'immagine container e gli script di addestramento necessari.

Installa NeMo-Run

pip install git+https://github.com/NVIDIA/NeMo-Run.git

Prepara un'immagine container

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

Utilizza un'immagine predefinita (opzione consigliata)

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/vmds_nemo_squashfs/nemo-20250721.sqsh .
Crea un container personalizzato (avanzato)

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

Passaggio 1: autenticati 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 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.

Scarica le ricette di addestramento

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 le credenziali di autenticazione.

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

  2. Clona il repository.

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

    git clone -b release-allowlist-ga 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 job potrebbero essere necessarie le seguenti variabili di ambiente:

  • HF_TOKEN è necessario per scaricare modelli e set di dati da Hugging Face.
  • Il 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>/vmds_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 dei 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 verrà eseguito 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 tuo 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 STATE NODELIST
a3u* up infinite 2 idle~ alice-a3u-[2-3]
a3u* up infinite 2 idle alice-a3u-[0-1]

Errore di download del tokenizer

Quando lo script tenta di scaricare il tokenizer GPT2, potresti riscontrare un OSError relativo a un link tra dispositivi:

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

Soluzioni:

Hai due opzioni per risolvere questo problema:

  • Opzione 1: esegui di nuovo il job. Questo errore è spesso temporaneo. La riesecuzione del job utilizzando lo stesso --cache-dir potrebbe risolvere il problema.
  • Opzione 2: scarica manualmente i file del tokenizer. Se la riesecuzione del job non riesce, segui questi passaggi:
    • Scarica i seguenti due file:
      • 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 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 l'ottimizzazione supervisionata (SFT), l'ottimizzazione delle preferenze (ad esempio, l'ottimizzazione diretta delle preferenze o DPO) e il reinforcement learning (RL).

La guida tratta due workflow 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 oppure utilizza un cluster di addestramento gestito 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 andando alla pagina Macchina virtuale di 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>/vmds_nemo_rl_squashfs/nemo_rl-h20260302.sqsh

Per scaricare l'immagine nello spazio di archiviazione Lustre del cluster, utilizza il seguente comando:

gs://vmds-containers-<region>/vmds_nemo_rl_squashfs/nemo_rl-h20260302.sqsh DESTINATION

Scarica codice

Per accedere alla ricetta di addestramento con l'interfaccia a riga di comando git, visita https://www.googlesource.com/new-password. La ricetta può essere scaricata con il seguente comando:

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

Avvia i job

Passaggio 1: imposta le variabili di ambiente.

Per eseguire il pull di 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 container nella cartella di avvio.

Di seguito sono riportati alcuni esempi.

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


# OR

/gcs/vmds-containers-<region>/vmds_nemo_rl_squashfs/nemo_rl-h20260302.sqsh \
  $HOME/vertex-oss-training/nemo_rl/nemo_rl-h20260302.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 una copia 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, nella posizione corrente viene creata una nuova directory denominata con l'ID job SLURM. All'interno troverai tutti i log e i checkpoint appartenenti a questo job. Più precisamente, all'interno troverai le seguenti directory e i seguenti 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 ray worker.
  • nemo_rl_output.log → Questo file contiene i log Slurm del job inviato.
  • attach.sh (solo per i job interattivi) → Si tratta di uno script bash che ti consente di collegarti a un job interattivo. Se il job viene avviato correttamente, la creazione di questo file potrebbe richiedere alcuni 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 workflow 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 carichi di lavoro 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 vedere la creazione di <job_id>/attach.sh.

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

  • Connettiti al job interattivo. Questo script ti consente di connetterti di nuovo 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 personalizzata.