Execute cargas de trabalho pré-criadas

Se tiver interesse no Vertex AI Managed Training, contacte o seu representante de vendas para ter acesso.

Este guia mostra como usar o ecossistema NVIDIA NeMo num cluster de preparação gerido para o desenvolvimento de modelos de IA generativa completos. Fornece instruções passo a passo para os seguintes fluxos de trabalho distintos, mas relacionados, cada um abordado na sua própria secção dedicada:

  • NVIDIA NeMo: para o desenvolvimento de modelos fundamentais, siga estas instruções para realizar a pré-preparação em grande escala, a pré-preparação contínua (CPT) e o ajuste fino supervisionado (SFT).
  • NVIDIA NeMo-RL: para o alinhamento de modelos e o ajuste de preferências, use esta secção para aplicar técnicas avançadas, como a aprendizagem por reforço (RL), para alinhar o seu modelo com instruções e preferências humanas.

Quer esteja a criar um modelo de raiz ou a refinar um existente, este documento explica como configurar o seu ambiente, gerir tarefas em contentores e iniciar scripts de preparação no cluster.

NVIDIA NeMo

A estrutura NVIDIA NeMo é uma plataforma ponto a ponto para criar, personalizar e implementar modelos de IA generativa. Esta secção do guia destina-se especificamente a programadores e investigadores focados nas fases fundamentais do desenvolvimento de modelos. Fornece instruções passo a passo para usar o NeMo para realizar a pré-formação em grande escala, a pré-formação contínua (CPT) e o ajuste fino supervisionado (SFT) num cluster de formação gerido.

Este guia de clusters de preparação fornece o fluxo de trabalho completo para executar uma tarefa de preparação com a framework NeMo. O processo está dividido em duas partes principais: a configuração inicial única do seu ambiente e os passos recorrentes para iniciar uma tarefa.

Configure o seu ambiente

Antes de iniciar uma tarefa, tem de preparar o seu ambiente certificando-se de que tem uma imagem de contentor e os scripts de preparação necessários.

Prepare uma imagem de contentor

Tem duas opções para a imagem do contentor: usar uma imagem pré-criada (recomendado) ou criar uma personalizada.

Usar uma imagem pré-criada (recomendado)

As imagens de contentores pré-criadas são fornecidas no formato .squashfs. Copie a imagem adequada para a sua região para o diretório de trabalho.

# Example for the US region
gcloud storage cp gs://vmds-containers-us/nemo_squashfs/nemo-20250721.sqsh .
Crie um contentor personalizado (avançado)

Siga estes passos apenas se os contentores pré-criados não satisfizerem as suas necessidades. Este procedimento explica como converter uma imagem de contentor personalizada no formato .squashfs usando o enroot.

Passo 1: autentique com o Google Cloud.

Use os seguintes comandos para garantir que a sua Google Cloud conta de utilizador e o registo do Docker onde a sua imagem está alojada estão autenticados:

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

Passo 2: crie o script de conversão.

Crie um ficheiro com o nome enroot-convert.sh e adicione o seguinte conteúdo do script. Antes de executar este script, tem de atualizar as variáveis REMOTE_IMG e LOCAL_IMG para apontarem para a imagem do contentor 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};
"

Passo 3: execute o script e valide o resultado.

Execute o script no nó de início de sessão do Slurm.

sbatch -N 1 enroot-convert.sh

Após a conclusão da tarefa, encontre os registos de conversão num ficheiro denominado slurm-<JOB_ID>.out e a imagem do contentor final no caminho especificado para LOCAL_IMG.

Transfira as receitas de preparação

As receitas de preparação são armazenadas num repositório googlesource.com privado. Para aceder a estes ficheiros com a linha de comandos do Git, tem de gerar primeiro credenciais de autenticação.

  1. Gere credenciais de autenticação.

    Aceda ao seguinte URL e siga as instruções no ecrã. Esta ação configura o seu ambiente local para autenticar com o repositório. https://www.googlesource.com/new-password

  2. Clone o repositório.

    Depois de as credenciais serem autenticadas, execute o seguinte comando para transferir as receitas.

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

Inicie uma tarefa de preparação

Depois de configurar o ambiente, pode iniciar uma tarefa de preparação.

Passo 1: defina as variáveis de ambiente

As seguintes variáveis de ambiente podem ser necessárias para o seu trabalho:

  • O HF_TOKEN é necessário para transferir modelos e conjuntos de dados do Hugging Face.
  • O WANDB_API_KEY é necessário para usar o Weights & Biases para a análise de experiências.
export HF_TOKEN=YOUR_HF_TOKEN
export WANDB_API_KEY=YOUR_WANDB_API_KEY

Passo 2: execute o guião de lançamento

Navegue para o diretório de trabalho e execute o script run.py para iniciar uma tarefa. Este exemplo inicia uma tarefa de preparação 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>/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 lançamento

  • --slurm-type é definido com base no tipo de cluster (por exemplo, hcc-a3m, hcc-a3u, hcc-a4).
  • --partition tem de estar definido como uma partição disponível. Pode verificar os nomes das partições com o comando sinfo.
  • O script run.py monta automaticamente vários diretórios no contentor do Docker, incluindo --log-dir, --cache-dir e --data-dir, se estiverem definidos.

Monitorizar o estado e os registos das tarefas

Depois de iniciar a tarefa, é apresentado um bloco 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

Os registos de execução são escritos no caminho apresentado no campo Local Directory do resultado do estado. Por exemplo, pode encontrar os ficheiros de registo num caminho semelhante ao seguinte:

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

Erros comuns e soluções

Esta secção descreve problemas comuns que podem surgir durante a execução de tarefas e fornece passos recomendados para os resolver.

Erro de partição inválida

Por predefinição, as tarefas tentam ser iniciadas na partição geral. Se a partição geral não existir ou não estiver disponível, a tarefa falha 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 através do argumento --partition ou -p no comando de lançamento. Para ver uma lista das partições disponíveis, execute o comando sinfo no nó de início de sessão do Slurm.

sinfo

O resultado mostra os nomes das partições disponíveis, como a3u neste exemplo:

PARTITION AVAIL LIMITE.TEMPO NODES STATE NODELIST
a3u* cima infinito 2 idle~ alice-a3u-[2-3]
a3u* cima infinito 2 inativo alice-a3u-[0-1]

Erro de transferência do tokenizador

Pode encontrar um OSError relacionado com um link entre dispositivos quando o script tenta transferir o tokenizador GPT2:

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

Soluções:

Tem duas opções para resolver este problema:

  • Opção n.º 1: Execute novamente a tarefa. Este erro é frequentemente temporário. Voltar a executar a tarefa com o mesmo --cache-dir pode resolver o problema.
  • Opção n.º 2: Transfira manualmente os ficheiros do tokenizador. Se a nova execução da tarefa falhar, siga estes passos:
    • Transfira os dois ficheiros seguintes:
      • gpt2-vocab.json
      • gpt2-merges.txt
    • Mova os ficheiros transferidos para a subdiretoria torch/megatron/ na diretoria de cache (por exemplo, <var>YOUR_CACHE_DIR</var>/torch/megatron/).
    • Mude o nome dos ficheiros da seguinte forma:
      • Mude o nome de gpt2-vocab.json para megatron-gpt-345m_vocab.
      • Mude o nome de gpt2-merges.txt para megatron-gpt-345m_merges.

NVIDIA NeMo-RL

A framework NVIDIA NeMo-RL foi concebida para alinhar os grandes modelos de linguagem com as preferências e as instruções humanas. Esta secção explica como usar o NeMo-RL num cluster para realizar tarefas de alinhamento avançadas, incluindo o ajuste fino supervisionado (SFT), o ajuste de preferências (como a otimização direta de preferências ou DPO) e a aprendizagem por reforço (RL).

O guia aborda dois fluxos de trabalho principais: executar uma tarefa de preparação 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 preparação gerido existente, se tiver um.

Estabeleça ligação ao nó de início de sessão do cluster

Para estabelecer ligação ao nó de início de sessão do cluster, encontre o comando correto da CLI Google Cloud navegando para a página Máquina virtual do Google Compute Engine na consola Google Google Cloud e clicando em SSH > Ver comando da CLI Google Cloud. Vai ter um aspeto semelhante ao seguinte:

ssh $USER_NAME@machine-addr

Exemplo:

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

Use a imagem Docker pré-criada

São fornecidos .sqsh ficheiros convertidos para imagens de contentores pré-criadas. Pode selecionar um contentor para a sua região e defini-lo diretamente como o parâmetro de imagem do contentor ou transferi-lo para o sistema de ficheiros do cluster.

Para o definir diretamente como o parâmetro de imagem do contentor, use um dos seguintes caminhos. Tenha em atenção que deve substituir <region> pela sua região específica (por exemplo, europe, asia, us):

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

Para transferir a imagem para o armazenamento Lustre do cluster, use o seguinte comando:

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

Transferir código

Para aceder à receita de formação com a CLI git, visite https://www.googlesource.com/new-password. Pode transferir a receita com o seguinte comando:

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

Inicie tarefas

Passo 1: defina as variáveis de ambiente.

Para extrair modelos e dados do Hugging Face, pode ter de definir o HF_TOKEN. Para usar o Weights & Biases para a análise de experiências, tem de definir o WANDB_API_KEY. Atualize estas variáveis no seguinte ficheiro:

Ficheiro a atualizar: $HOME/vertex-oss-training/nemo_rl/configs/auth.sh

Se não quiser usar o Weights & Biases, defina logger.wandb_enabled como False no seu script de lançamento.

Passo 2: transfira ou copie o ficheiro do contentor para a pasta de lançamento.

Eis alguns exemplos.

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`

Passo 3: prepare ou clone o repositório NeMo-RL.

Crie um clone do código NeMo-RL, se ainda não estiver presente. Tenha em atenção que pode ter de usar git submodule update --init --recursive se já tiver clonado o repositório sem a flag --recursive.

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

Passo 4: inicie a tarefa de preparação.

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

Onde:

  • --cluster-type é definido com base no tipo de cluster:
    • A3-Mega: hcc-a3m
    • A3-Ultra: hcc-a3u
    • A4: hcc-a4
    • A3H: hcc-a3h
  • --partition deve ser definido em conformidade, onde sinfo pode ser usado para verificar as partições do SLURM.

Após o início da tarefa, é criado um novo diretório com o nome do ID da tarefa SLURM na sua localização atual. No interior, encontra todos os registos e pontos de verificação relativos a esta tarefa. Mais precisamente, dentro dessa pasta, encontra os seguintes diretórios e ficheiros:

  • checkpoints/ → Este diretório está montado no contentor do NeMo-RL e contém todos os pontos de verificação da preparação.
  • ray-logs/ → Este diretório contém os registos do cabeçalho do raio e dos trabalhadores do raio.
  • nemo_rl_output.log → Este ficheiro contém os registos do Slurm da tarefa enviada.
  • attach.sh (Apenas para tarefas interativas) → Este é um script bash que lhe permite anexar a uma tarefa interativa. Se a tarefa for iniciada com êxito, a criação deste ficheiro pode demorar alguns minutos.

Programação com o NeMo-RL

Configuração interativa

Estão disponíveis duas opções para o desenvolvimento interativo rápido com o NeMo-RL.

nemorlinteractive

Este é um comando auxiliar simples que lhe permite escolher um nó de GPU no cluster (por exemplo, o nó número 5) e, em seguida, acede a um contentor em execução para o NeMo-RL no nó selecionado. Este comando é útil para os fluxos de trabalho de nó único.

Para usar nemorlinteractive, tem de seguir estes passos pré-requisitos:

  1. Forneça todos os tokens de autorização que quer (por exemplo, HF e WandB) carregados para a tarefa no ficheiro configs/auth.sh.

  2. Defina a variável de ambiente CLUSTER_TYPE de 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 cluster

  3. Importe nemorlinteractive no seu terminal bash ao obter o ficheiro bash_utils.sh:

    source bash_utils.sh

  4. Execute o comando nemorlinteractive. Por exemplo:

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

Início interativo

Esta opção permite-lhe executar cargas de trabalho de forma interativa em vários nós de computação. As tarefas interativas são mais adequadas para exemplos de utilização de depuração e validação. Estes cargas de trabalho reservam o nó indefinidamente até o programador decidir que a depuração terminou e que quer libertar os recursos.

Seguem-se os passos que têm de ser seguidos para esta opção:

Forneça todos os tokens de autorização que quer (por exemplo, HF e WandB) carregados para a tarefa no ficheiro configs/auth.sh.

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

  • Aguarde 2 a 5 minutos e deve ver o ícone <job_id>/attach.sh criado.

  • Para monitorizar o progresso da verificação de lançamento, selecione <job_id>/nemo_rl_output.log para ver o progresso do script de lançamento e selecione <job_id>/ray_logs/ para ver o progresso do lançamento do raio principal e dos trabalhadores.

  • Estabeleça ligação ao trabalho interativo. Este script permite-lhe estabelecer ligação novamente, mesmo que perca a ligação:

bash <job_id>/attach.sh

O que se segue?

A execução de uma carga de trabalho pré-criada valida o estado operacional do cluster. O passo seguinte é executar a sua própria aplicação de preparação personalizada.