En esta guía, se muestra cómo usar el ecosistema de NVIDIA NeMo en un clúster de entrenamiento administrado para el desarrollo de modelos de IA generativa de extremo a extremo. Se proporcionan instrucciones paso a paso para los siguientes flujos de trabajo distintos, pero relacionados, cada uno de los cuales se trata en su propia sección dedicada:
- NVIDIA NeMo: Para el desarrollo de modelos de base, sigue estas instrucciones para realizar un entrenamiento previo a gran escala, un entrenamiento previo continuo (CPT) y un ajuste supervisado (SFT).
- NVIDIA NeMo-RL: Para la alineación del modelo y el ajuste de preferencias, usa esta sección para aplicar técnicas avanzadas, como el aprendizaje por refuerzo (RL), para alinear tu modelo con las instrucciones y preferencias humanas.
Ya sea que estés creando un modelo desde cero o perfeccionando uno existente, este documento te guiará para configurar tu entorno, administrar trabajos alojados en contenedores y lanzar secuencias de comandos de entrenamiento en el clúster.
NVIDIA NeMo
El framework de NVIDIA NeMo es una plataforma integral para compilar, personalizar e implementar modelos de IA generativa. Esta sección de la guía está dirigida específicamente a desarrolladores e investigadores que se enfocan en las etapas fundamentales del desarrollo de modelos. Proporciona instrucciones paso a paso para usar NeMo con el objetivo de realizar un entrenamiento previo a gran escala, un entrenamiento previo continuo (CPT) y un ajuste supervisado (SFT) en un clúster de entrenamiento administrado.
En esta guía de clústeres de entrenamiento, se proporciona el flujo de trabajo completo para ejecutar un trabajo de entrenamiento con el framework de NeMo. El proceso se divide en dos partes principales: la configuración inicial única de tu entorno y los pasos recurrentes para iniciar un trabajo.
Configura tu entorno
Antes de iniciar un trabajo, debes preparar tu entorno asegurándote de tener una imagen de contenedor y las secuencias de comandos de entrenamiento necesarias.
Instala NeMo-Run
pip install git+https://github.com/NVIDIA/NeMo-Run.git
Prepara una imagen de contenedor
Tienes dos opciones para la imagen de contenedor: usar una imagen compilada previamente (recomendado) o compilar una personalizada.
Usa una imagen precompilada (recomendado)
Las imágenes de contenedor compiladas previamente se proporcionan en el formato .squashfs. Copia la
imagen adecuada para tu región en tu directorio de trabajo.
# Example for the US region
gcloud storage cp gs://vmds-containers-us/vmds_nemo_squashfs/nemo-20250721.sqsh .
Compila un contenedor personalizado (avanzado)
Sigue estos pasos solo si los contenedores compilados previamente no satisfacen tus necesidades.
En este procedimiento, se explica cómo convertir una imagen de contenedor personalizada en el
formato .squashfs con enroot.
Paso 1: Autentícate con Google Cloud.
Usa los siguientes comandos para asegurarte de que tu cuenta de usuario de Google Cloud y el registro de Docker en el que se aloja tu imagen estén autenticados:
gcloud auth login
gcloud auth configure-docker us-docker.pkg.dev
Paso 2: Crea la secuencia de comandos de conversión.
Crea un archivo llamado enroot-convert.sh y agrégale el siguiente contenido
de secuencia de comandos. Antes de ejecutar esta secuencia de comandos, debes actualizar las variables REMOTE_IMG y
LOCAL_IMG para que apunten a tu imagen de contenedor y a la ruta de acceso de salida que elegiste.
#!/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};
"
Paso 3: Ejecuta la secuencia de comandos y verifica el resultado.
Ejecuta la secuencia de comandos en el nodo de acceso de Slurm.
sbatch -N 1 enroot-convert.sh
Una vez que se complete el trabajo, busca los registros de conversión en un archivo llamado
slurm-<JOB_ID>.out y la imagen de contenedor final en la ruta de acceso que especificaste
para LOCAL_IMG.
Descarga las recetas de entrenamiento
Las recetas de entrenamiento se almacenan en un repositorio privado de googlesource.com.
Para acceder a ellos con la línea de comandos de Git, primero debes generar credenciales de
autenticación.
Genera credenciales de autenticación.
Visita la siguiente URL y sigue las instrucciones en pantalla. Esto configura tu entorno local para autenticarte con el repositorio. https://www.googlesource.com/new-password
Clona el repositorio.
Una vez que se autentiquen las credenciales, ejecuta el siguiente comando para descargar las recetas.
git clone -b release-allowlist-ga https://vertex-model-garden.googlesource.com/vertex-oss-training
Inicia un trabajo de entrenamiento
Una vez que se configure tu entorno, podrás iniciar un trabajo de entrenamiento.
Paso 1: Configura las variables de entorno
Es posible que se requieran las siguientes variables de entorno para tu trabajo:
- El
HF_TOKENes necesario para descargar modelos y conjuntos de datos de Hugging Face. - Se requiere
WANDB_API_KEYpara usar Weights & Biases en el análisis de experimentos.
export HF_TOKEN=YOUR_HF_TOKEN
export WANDB_API_KEY=YOUR_WANDB_API_KEY
Paso 2: Ejecuta la secuencia de comandos de inicio
Navega hasta el directorio de trabajo y ejecuta la secuencia de comandos run.py para iniciar un
trabajo. En este ejemplo, se inicia un trabajo de entrenamiento de demostración 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
Parámetros de inicio
--slurm-typese establece según el tipo de clúster (por ejemplo,hcc-a3m,hcc-a3uohcc-a4).--partitiondebe establecerse en una partición disponible. Puedes verificar los nombres de las particiones con el comandosinfo.- La secuencia de comandos
run.pyactiva automáticamente varios directorios en el contenedor de Docker, incluidos--log-dir,--cache-diry--data-dir, si están configurados.
Supervisa el estado y los registros de los trabajos
Después de iniciar el trabajo, se mostrará un bloque de estado:
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
Los registros de ejecución se escriben en la ruta de acceso que se muestra en el campo Local Directory
del resultado del estado. Por ejemplo, puedes encontrar los archivos de registro en una ruta
similar a la siguiente:
$NEMORUN_HOME/experiments/nemo-demo-run/nemo-demo-run_1753123402/nemo-demo-run/<JOB_ID>.log
Errores comunes y soluciones
En esta sección, se describen los problemas comunes que pueden surgir durante la ejecución del trabajo y se proporcionan los pasos recomendados para resolverlos.
Error de partición no válida
De forma predeterminada, los trabajos intentan iniciarse en la partición general. Si la partición general no existe o no está disponible, el trabajo fallará con el siguiente error:
sbatch: error: invalid partition specified: general
sbatch: error: Batch job submission failed: Invalid partition name specified
Solución:
Especifica una partición disponible con el argumento --partition o -p en tu
comando de inicio.
Para ver una lista de las particiones disponibles, ejecuta el comando sinfo en el
nodo de acceso de Slurm.
sinfo
En el resultado, se muestran los nombres de las particiones disponibles, como a3u en este ejemplo:
| PARTITION | AVAIL | TIMELIMIT | NODOS | ESTADO | NODELIST |
|---|---|---|---|---|---|
| a3u* | up | infinito | 2 | idle~ | alice-a3u-[2-3] |
| a3u* | up | infinito | 2 | inactivo | alice-a3u-[0-1] |
Error de descarga del asignador de token
Es posible que encuentres un OSError relacionado con un vínculo entre dispositivos cuando la secuencia de comandos intente descargar el tokenizador de GPT2:
OSError: [Errno 18] Invalid cross-device link: 'gpt2-vocab.json' -> '/root/.cache/torch/megatron/megatron-gpt-345m_vocab'
Soluciones:
Tienes dos opciones para resolver este problema:
- Opción 1:
Vuelve a ejecutar el trabajo. Este error suele ser transitorio. Volver a ejecutar el trabajo con
el mismo
--cache-dirpuede resolver el problema. - Opción 2:
Descarga manualmente los archivos del tokenizador. Si vuelve a fallar la ejecución del trabajo,
sigue estos pasos:
- Descarga los siguientes dos archivos:
gpt2-vocab.jsongpt2-merges.txt
- Mueve los archivos descargados al subdirectorio
torch/megatron/dentro de tu directorio de caché (por ejemplo,<var>YOUR_CACHE_DIR</var>/torch/megatron/). - Cambia el nombre de los archivos de la siguiente manera:
- Cambia el nombre de
gpt2-vocab.jsonamegatron-gpt-345m_vocab. - Cambia el nombre de
gpt2-merges.txtamegatron-gpt-345m_merges.
- Cambia el nombre de
- Descarga los siguientes dos archivos:
NVIDIA NeMo-RL
El framework de NVIDIA NeMo-RL está diseñado para alinear los modelos de lenguaje grandes con las preferencias y las instrucciones de los humanos. En esta sección, se explica cómo usar NeMo-RL en un clúster para realizar tareas de alineación avanzadas, como el ajuste supervisado (SFT), el ajuste de preferencias (como la optimización directa de preferencias o DPO) y el aprendizaje por refuerzo (RL).
En la guía, se abarcan dos flujos de trabajo principales: ejecutar un trabajo de entrenamiento por lotes estándar y usar el entorno de desarrollo interactivo para la depuración.
Requisitos previos
Antes de comenzar, crea un clúster siguiendo las instrucciones de la página Crea un clúster o usa un clúster de entrenamiento administrado existente, si tienes uno.
Conéctate al nodo de acceso del clúster
Para conectarte al nodo de acceso del clúster, navega a la página Máquina virtual de Compute Engine en la consola de Google Cloud y haz clic en SSH > Ver comando de gcloud CLI para encontrar el comando de Google Cloud CLI correcto. Tendrán un aspecto similar a este:
ssh $USER_NAME@machine-addr
Ejemplo:
ssh $USER_NAME@nic0.sliua3m1-login-001.europe-north1-c.c.infinipod-shared-dev.internal.gcpnode.com
Usa la imagen de Docker compilada previamente
Se proporcionan archivos .sqsh convertidos para las imágenes de contenedor compiladas previamente. Puedes
seleccionar un contenedor para tu región y establecerlo directamente como el parámetro de imagen de contenedor
o descargarlo en el sistema de archivos del clúster.
Para configurarla directamente como el parámetro de imagen de contenedor, usa una de las siguientes rutas de acceso.
Ten en cuenta que debes reemplazar <region> por tu región específica
(por ejemplo, europe, asia, us):
/gcs/vmds-containers-<region>/vmds_nemo_rl_squashfs/nemo_rl-h20260302.sqsh
Para descargar la imagen en el almacenamiento de Lustre del clúster, usa el siguiente comando:
gs://vmds-containers-<region>/vmds_nemo_rl_squashfs/nemo_rl-h20260302.sqsh DESTINATION
Descargar el código
Para acceder a la receta de entrenamiento con la CLI de git, visita https://www.googlesource.com/new-password. La receta se puede descargar con el siguiente comando:
cd $HOME
git clone -b release-allowlist-ga https://vertex-model-garden.googlesource.com/vertex-oss-training
Inicia trabajos
Paso 1: Configura las variables de entorno.
Para extraer modelos y datos de Hugging Face, es posible que se deba configurar el HF_TOKEN.
Para usar Weights & Biases en el análisis de experimentos, se debe configurar
WANDB_API_KEY. Actualiza estas variables en el siguiente archivo:
Archivo que se actualizará: $HOME/vertex-oss-training/nemo_rl/configs/auth.sh
Si no quieres usar Weights & Biases, establece logger.wandb_enabled en False
en tu secuencia de comandos de inicio.
Paso 2: Descarga o copia el archivo del contenedor en tu carpeta de inicio.
Aquí tienes algunos ejemplos.
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`
Paso 3: Prepara o clona el repositorio de NeMo-RL.
Crea una clonación del código de NeMo-RL si aún no existe. Ten en cuenta que es posible que
debas usar git submodule update --init --recursive si ya clonaste
el repositorio sin la marca --recursive.
git clone https://github.com/NVIDIA-NeMo/RL --recursive
Paso 4: Inicia el trabajo de entrenamiento.
sbatch -N <num_nodes> launch.sh --cluster_type hcc-a3m --job_script algorithms/dpo.sh
Aquí:
--cluster-typese establece según el tipo de clúster:- A3-Mega:
hcc-a3m - A3-Ultra:
hcc-a3u - A4:
hcc-a4 - A3H:
hcc-a3h
- A3-Mega:
--partitionse debe configurar según corresponda, donde se puede usarsinfopara verificar las particiones de Slurm.
Después de que se inicie el trabajo, se creará un directorio nuevo con el nombre de su ID de trabajo de SLURM en tu ubicación actual. Allí, encontrarás todos los registros y puntos de control que pertenecen a este trabajo. Más precisamente, dentro de ese directorio, encontrarás los siguientes directorios y archivos:
checkpoints/→ Este directorio se activa dentro del contenedor de NeMo-RL y contiene todos los puntos de control del entrenamiento.ray-logs/→ Este directorio contiene los registros de los nodos principales y trabajadores de Ray.nemo_rl_output.log: Este archivo contiene los registros de Slurm del trabajo que enviaste.attach.sh(solo trabajos interactivos): Es una secuencia de comandos de Bash que te permite conectarte a un trabajo interactivo. Si tu trabajo se inicia correctamente, es posible que este archivo tarde unos minutos en crearse.
Desarrollo con NeMo-RL
Configuración interactiva
Hay dos opciones disponibles para el desarrollo interactivo rápido con NeMo-RL.
nemorlinteractive
Este es un comando de ayuda sencillo que te permite elegir un nodo de GPU del clúster (por ejemplo, el nodo número 5) y, luego, te lleva a un contenedor en ejecución para NeMo-RL dentro del nodo seleccionado. Este comando es útil para tus flujos de trabajo de un solo nodo.
Para usar nemorlinteractive, debes seguir estos pasos de requisitos previos:
- Proporciona todos los tokens de autenticación que quieras (por ejemplo, HF y WandB) cargados en el
trabajo en el archivo
configs/auth.sh. Establece la variable de entorno
CLUSTER_TYPEsegún el siguiente lineamiento: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 clusterImporta
nemorlinteractiveen tu terminal de Bash con el comando de origenbash_utils.sh:source bash_utils.shEjecuta el comando
nemorlinteractive. Por ejemplo:# Assuming you want to take the compute node number 5. nemorlinteractive 5
Lanzamiento interactivo
Esta opción te permite ejecutar cargas de trabajo de forma interactiva en varios nodos de procesamiento. Los trabajos interactivos son más adecuados para los casos de uso de depuración y verificación. Estas cargas de trabajo reservan el nodo de forma indefinida hasta que el desarrollador decide que la depuración concluyó y quiere liberar los recursos.
Los siguientes son los pasos que se deben seguir para esta opción:
Proporciona todos los tokens de autenticación que quieras (por ejemplo, HF y WandB) cargados en el trabajo
en el archivo configs/auth.sh.
sbatch -N <num_nodes> launch.sh --cluster_type hcc-a3m --interactive
Espera entre 2 y 5 minutos, y deberías ver que se creó
<job_id>/attach.sh.Para supervisar el progreso del lanzamiento, consulta
<job_id>/nemo_rl_output.logpara ver el progreso de la secuencia de comandos de lanzamiento y consulta<job_id>/ray_logs/para ver el progreso del lanzamiento de los trabajadores y el encabezado de Ray.Conéctate al trabajo interactivo. Esta secuencia de comandos te permite volver a conectarte incluso si pierdes la conexión:
bash <job_id>/attach.sh
¿Qué sigue?
Ejecutar una carga de trabajo compilada previamente verifica el estado operativo del clúster. El siguiente paso es ejecutar tu propia aplicación de entrenamiento personalizada.
- Ejecuta tu propia carga de trabajo personalizada: Empaqueta tu código de entrenamiento en un contenedor
y envíalo como un
CustomJoba tu clúster de entrenamiento. Este proceso incluye configurar el trabajo para un entorno distribuido. - Supervisa tus trabajos de entrenamiento: Realiza un seguimiento eficaz del progreso, el uso de recursos y los registros de los trabajos que se ejecutan en tu clúster con la consola de Google Cloud o Cloud Logging.
- Visualiza tu clúster: Después de ejecutar las pruebas, verifica el estado del clúster y de sus nodos individuales.
- Administra tu clúster: Actualiza la configuración de tu clúster o bórralo para administrar los costos.
- Organiza trabajos con las canalizaciones de Gemini Enterprise Agent Platform: Después de ejecutar trabajos de forma manual, automatiza el proceso creando una canalización para organizar tus flujos de trabajo de entrenamiento.