Neste guia, mostramos como usar o ecossistema NVIDIA NeMo em um cluster de treinamento gerenciado para o desenvolvimento de modelos de IA generativa de ponta a ponta. Ele fornece instruções detalhadas para os seguintes fluxos de trabalho distintos, mas relacionados, cada um abordado em uma seção dedicada:
- NVIDIA NeMo: para o desenvolvimento de modelos de fundação, siga estas instruções para realizar pré-treinamento em grande escala, pré-treinamento contínuo (CPT) e ajuste supervisionado (SFT).
- NVIDIA NeMo-RL: para alinhamento de modelos e ajuste de preferências, use esta seção para aplicar técnicas avançadas, como o aprendizado por reforço (RL), para alinhar seu modelo com instruções e preferências humanas.
Seja para criar um modelo do zero ou refinar um já existente, este documento orienta você na configuração do ambiente, no gerenciamento de jobs conteinerizados e na inicialização de scripts de treinamento no cluster.
NVIDIA NeMo
O framework NVIDIA NeMo é uma plataforma completa para criar, personalizar e implantar modelos de IA generativa. Esta seção do guia é voltada especificamente para desenvolvedores e pesquisadores que se concentram nas etapas fundamentais do desenvolvimento de modelos. Ele fornece instruções detalhadas para usar o NeMo para realizar pré-treinamento em grande escala, pré-treinamento contínuo (CPT) e ajuste supervisionado (SFT) em um cluster de treinamento gerenciado.
Este guia de clusters de treinamento fornece o fluxo de trabalho completo para executar um job de treinamento com o framework NeMo. O processo é dividido em duas partes principais: a configuração inicial única do ambiente e as etapas recorrentes para iniciar um job.
Configurar o ambiente
Antes de iniciar um job, prepare o ambiente garantindo que você tenha uma imagem do contêiner e os scripts de treinamento necessários.
Instalar o NeMo-Run
pip install git+https://github.com/NVIDIA/NeMo-Run.git
Preparar uma imagem de contêiner
Há duas opções para a imagem do contêiner: usar uma imagem pré-criada (recomendado) ou criar uma personalizada.
Usar uma imagem pré-criada (recomendado)
As imagens de contêiner pré-criadas são fornecidas no formato .squashfs. Copie a
imagem apropriada para sua região no diretório de trabalho.
# Example for the US region
gcloud storage cp gs://vmds-containers-us/vmds_nemo_squashfs/nemo-20250721.sqsh .
Criar um contêiner personalizado (avançado)
Siga estas etapas somente se os contêineres pré-criados não atenderem às suas necessidades.
Este procedimento orienta você na conversão de uma imagem de contêiner personalizada para o formato .squashfs usando enroot.
Etapa 1: autenticar com o Google Cloud.
Use os comandos a seguir para garantir que sua conta de usuário do Google Cloud e o registro do Docker em que a imagem está hospedada sejam autenticados:
gcloud auth login
gcloud auth configure-docker us-docker.pkg.dev
Etapa 2: criar o script de conversão.
Crie um arquivo chamado enroot-convert.sh e adicione o seguinte conteúdo
de script. Antes de executar esse script, atualize as variáveis REMOTE_IMG e
LOCAL_IMG para que apontem para a imagem do contêiner e o caminho de saída escolhido.
#!/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};
"
Etapa 3: execute o script e verifique a saída.
Execute o script no nó de login do Slurm.
sbatch -N 1 enroot-convert.sh
Depois que o job for concluído, encontre os registros de conversão em um arquivo chamado
slurm-<JOB_ID>.out e a imagem final do contêiner no caminho especificado
para LOCAL_IMG.
Fazer o download das receitas de treinamento
As receitas de treinamento são armazenadas em um repositório particular do googlesource.com.
Para acessá-los com a linha de comando do Git, primeiro é necessário gerar credenciais de autenticação.
Gerar credenciais de autenticação.
Acesse o URL a seguir e siga as instruções na tela. Isso configura o ambiente local para autenticação com o repositório. https://www.googlesource.com/new-password
Clone o repositório.
Depois que as credenciais forem autenticadas, execute o comando a seguir para fazer o download das receitas.
git clone -b release-allowlist-ga https://vertex-model-garden.googlesource.com/vertex-oss-training
Iniciar um job de treinamento
Depois que o ambiente estiver configurado, você poderá iniciar um job de treinamento.
Etapa 1: definir variáveis de ambiente
As seguintes variáveis de ambiente podem ser necessárias para o job:
- O
HF_TOKENé necessário para baixar modelos e conjuntos de dados do Hugging Face. - O
WANDB_API_KEYé necessário para usar o Weights & Biases na análise de experimentos.
export HF_TOKEN=YOUR_HF_TOKEN
export WANDB_API_KEY=YOUR_WANDB_API_KEY
Etapa 2: executar o script de inicialização
Navegue até o diretório de trabalho e execute o script run.py para iniciar um
job. Este exemplo inicia um job de treinamento de demonstração com o 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 inicialização
--slurm-typeé definido com base no tipo de cluster (por exemplo,hcc-a3m,hcc-a3u,hcc-a4).--partitionprecisa ser definido como uma partição disponível. É possível conferir os nomes das partições com o comandosinfo.- O script
run.pymonta automaticamente vários diretórios no contêiner do Docker, incluindo--log-dir,--cache-dire--data-dir, se estiverem definidos.
Como monitorar o status e os registros de jobs
Depois que você inicia o job, um bloco de status é exibido:
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
Os registros de execução são gravados no caminho mostrado no campo Local Directory
da saída de status. Por exemplo, é possível encontrar os arquivos de registro em um caminho
como este:
$NEMORUN_HOME/experiments/nemo-demo-run/nemo-demo-run_1753123402/nemo-demo-run/<JOB_ID>.log
Erros comuns e soluções
Nesta seção, descrevemos problemas comuns que podem surgir durante a execução do job e fornecemos as etapas recomendadas para resolvê-los.
Erro de partição inválida
Por padrão, os jobs tentam ser iniciados na partição geral. Se a partição geral não existir ou não estiver disponível, o job vai falhar com o seguinte erro:
sbatch: error: invalid partition specified: general
sbatch: error: Batch job submission failed: Invalid partition name specified
Solução:
Especifique uma partição disponível usando o argumento --partition ou -p no comando de inicialização.
Para ver uma lista de partições disponíveis, execute o comando sinfo no
nó de login do Slurm.
sinfo
A saída mostra os nomes das partições disponíveis, como a3u neste exemplo:
| PARTITION | AVAIL | TIMELIMIT | NODES | ESTADO | NODELIST |
|---|---|---|---|---|---|
| a3u* | cima | infinite | 2 | idle~ | alice-a3u-[2-3] |
| a3u* | cima | infinite | 2 | inativo | alice-a3u-[0-1] |
Erro de download do tokenizador
Você pode encontrar um OSError relacionado a um link entre dispositivos quando o script tentar fazer o download do tokenizador GPT2:
OSError: [Errno 18] Invalid cross-device link: 'gpt2-vocab.json' -> '/root/.cache/torch/megatron/megatron-gpt-345m_vocab'
Soluções:
Você tem duas opções para resolver esse problema:
- Opção 1:
execute o job novamente. Esse erro costuma ser temporário. Executar o job novamente usando
o mesmo
--cache-dirpode resolver o problema. - Opção 2:
faça o download manual dos arquivos do tokenizador. Se a nova execução do job falhar,
siga estas etapas:
- Faça o download dos dois arquivos a seguir:
gpt2-vocab.jsongpt2-merges.txt
- Mova os arquivos salvos para o subdiretório
torch/megatron/no diretório de cache (por exemplo,<var>YOUR_CACHE_DIR</var>/torch/megatron/). - Renomeie os arquivos da seguinte maneira:
- Renomeie
gpt2-vocab.jsoncomomegatron-gpt-345m_vocab. - Renomeie
gpt2-merges.txtcomomegatron-gpt-345m_merges.
- Renomeie
- Faça o download dos dois arquivos a seguir:
NVIDIA NeMo-RL
O framework NVIDIA NeMo-RL foi projetado para alinhar modelos de linguagem grandes com as preferências e instruções humanas. Nesta seção, mostramos como usar o NeMo-RL em um cluster para realizar tarefas de alinhamento avançadas, incluindo ajuste supervisionado (SFT), ajuste de preferência (como otimização direta de preferência ou DPO) e aprendizado por reforço (RL).
O guia aborda dois fluxos de trabalho principais: executar um job de treinamento em lote padrão e usar o ambiente de desenvolvimento interativo para depuração.
Pré-requisitos
Antes de começar, crie um cluster seguindo as instruções na página Criar cluster ou use um cluster de treinamento gerenciado, se tiver um.
Conectar-se ao nó de login do cluster
Para se conectar ao nó de login do cluster, encontre o comando correto da Google Cloud CLI acessando a página Máquina virtual do Compute Engine no console do Google Cloud e clicando em SSH > Ver comando da Google Cloud CLI. Será semelhante a:
ssh $USER_NAME@machine-addr
Exemplo:
ssh $USER_NAME@nic0.sliua3m1-login-001.europe-north1-c.c.infinipod-shared-dev.internal.gcpnode.com
Usar a imagem Docker pré-criada
Os arquivos .sqsh convertidos são fornecidos para imagens de contêiner pré-criadas. É possível
selecionar um contêiner para sua região e defini-lo diretamente como o parâmetro de imagem
do contêiner ou fazer o download dele para o sistema de arquivos do cluster.
Para defini-lo diretamente como o parâmetro da imagem do contêiner, use um dos caminhos a seguir.
Substitua <region> pela sua região específica
(por exemplo, europe, asia, us):
/gcs/vmds-containers-<region>/vmds_nemo_rl_squashfs/nemo_rl-h20260302.sqsh
Para baixar a imagem no armazenamento Lustre do cluster, use o seguinte comando:
gs://vmds-containers-<region>/vmds_nemo_rl_squashfs/nemo_rl-h20260302.sqsh DESTINATION
Baixar o código
Para acessar a receita de treinamento com a CLI do git, acesse https://www.googlesource.com/new-password. A receita pode ser baixada com o seguinte comando:
cd $HOME
git clone -b release-allowlist-ga https://vertex-model-garden.googlesource.com/vertex-oss-training
Iniciar jobs
Etapa 1: definir variáveis de ambiente.
Para extrair modelos e dados do Hugging Face, talvez seja necessário definir o HF_TOKEN.
Para usar o Weights & Biases na análise de experimentos, é necessário definir o WANDB_API_KEY. Atualize essas variáveis no seguinte arquivo:
Arquivo a ser atualizado: $HOME/vertex-oss-training/nemo_rl/configs/auth.sh
Se você não quiser usar Weights & Biases, defina logger.wandb_enabled como False
no script de inicialização.
Etapa 2: faça o download ou copie o arquivo do contêiner para a pasta de inicialização.
Confira alguns exemplos.
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`
Etapa 3: preparar ou clonar o repositório NeMo-RL.
Crie um clone do código NeMo-RL, se ainda não houver um. Talvez seja necessário usar git submodule update --init --recursive se você já tiver clonado o repositório sem a flag --recursive.
git clone https://github.com/NVIDIA-NeMo/RL --recursive
Etapa 4: iniciar o job de treinamento.
sbatch -N <num_nodes> launch.sh --cluster_type hcc-a3m --job_script algorithms/dpo.sh
Em que:
--cluster-typeé definido com base no tipo de cluster:- A3-Mega:
hcc-a3m - A3-Ultra:
hcc-a3u - A4:
hcc-a4 - A3H:
hcc-a3h
- A3-Mega:
--partitionprecisa ser definido de acordo, em quesinfopode ser usado para verificar as partições do Slurm.
Depois que o job é iniciado, um novo diretório com o nome do código da tarefa do SLURM é criado no local atual. Dentro, você vai encontrar todos os registros e checkpoints pertencentes a esse job. Mais precisamente, dentro dele, você vai encontrar os seguintes diretórios e arquivos:
checkpoints/→ esse diretório é montado dentro do contêiner NeMo-RL e contém todos os checkpoints do treinamento.ray-logs/→ esse diretório contém os registros do nó principal e dos workers do Ray.nemo_rl_output.log→ esse arquivo contém os registros do Slurm do job enviado.attach.sh(somente jobs interativos) → é um script bash que permite que você se conecte a um job interativo. Se o job for iniciado com sucesso, pode levar alguns minutos para que esse arquivo seja criado.
Desenvolvimento com NeMo-RL
Configuração interativa
Há duas opções disponíveis para o desenvolvimento interativo rápido com o NeMo-RL.
nemorlinteractive
Esse é um comando auxiliar simples que permite escolher um nó de GPU do cluster (por exemplo, o nó número 5) e, em seguida, leva você a um contêiner em execução para o NeMo-RL dentro do nó selecionado. Esse comando é útil para fluxos de trabalho de nó único.
Para usar o nemorlinteractive, siga estas etapas de pré-requisito:
- Forneça todos os tokens de autenticação que você quer (por exemplo, HF e WandB) carregados para o
job no arquivo
configs/auth.sh. Defina a variável de ambiente
CLUSTER_TYPEde acordo com a seguinte diretriz: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 clusterImporte
nemorlinteractiveno terminal bash usando obash_utils.sh:source bash_utils.shExecute o comando
nemorlinteractive. Exemplo:# Assuming you want to take the compute node number 5. nemorlinteractive 5
Lançamento interativo
Essa opção permite executar cargas de trabalho de forma interativa em vários nós de computação. Os jobs interativos são mais adequados para casos de uso de depuração e verificação. Essas cargas de trabalho reservam o nó indefinidamente até que o desenvolvedor decida que a depuração foi concluída e queira liberar os recursos.
Siga estas etapas para essa opção:
Forneça todos os tokens de autenticação que você quer (por exemplo, HF e WandB) carregados no job
no arquivo configs/auth.sh.
sbatch -N <num_nodes> launch.sh --cluster_type hcc-a3m --interactive
Aguarde de 2 a 5 minutos para que
<job_id>/attach.shseja criado.Para monitorar o progresso da inicialização, verifique
<job_id>/nemo_rl_output.logpara ver o progresso do script de inicialização e verifique<job_id>/ray_logs/para ver o progresso da inicialização do head e dos workers do Ray.Conecte-se ao job interativo. Esse script permite que você se conecte novamente, mesmo que perca a conexão:
bash <job_id>/attach.sh
A seguir
A execução de uma carga de trabalho pré-criada verifica o status de funcionamento do cluster. A próxima etapa é executar seu próprio aplicativo de treinamento personalizado.
- Executar sua própria carga de trabalho personalizada: empacote o código de treinamento em um contêiner
e envie o contêiner como um
CustomJobpara o cluster de treinamento. Esse processo inclui a configuração do job para um ambiente distribuído. - Monitore seus jobs de treinamento: acompanhe de forma eficaz o progresso, a utilização de recursos e os registros dos jobs em execução no cluster usando o console do Google Cloud ou o Cloud Logging.
- Ver o cluster: depois de executar os testes, verifique o status do cluster e dos nós individuais.
- Gerenciar o cluster: atualize a configuração do cluster ou exclua-o para gerenciar custos.
- Orquestre jobs com os pipelines da Gemini Enterprise Agent Platform: depois de executar jobs manualmente, automatize o processo criando um pipeline para orquestrar seus fluxos de trabalho de treinamento.