사전 빌드된 워크로드 실행

Vertex AI 관리형 학습에 관심이 있으면 영업 담당자에게 문의하여 액세스 권한을 받으세요.

이 가이드에서는 관리형 학습 클러스터에서 NVIDIA NeMo 생태계를 사용하여 엔드 투 엔드 생성형 AI 모델을 개발하는 방법을 설명합니다. 이 가이드에서는 다음과 같은 구분되지만 관련된 워크플로에 대한 단계별 안내를 제공하며 각 워크플로는 자체 전용 섹션에서 설명됩니다.

  • NVIDIA NeMo: 파운데이션 모델 개발의 경우 다음 안내에 따라 대규모 사전 학습, 지속적 사전 학습(CPT), 지도 미세 조정(SFT)을 수행합니다.
  • NVIDIA NeMo-RL: 모델 정렬 및 선호도 조정을 위해 이 섹션을 사용하여 강화 학습(RL)과 같은 고급 기법을 적용해 모델을 인간의 안내와 선호도에 맞게 정렬합니다.

처음부터 모델을 빌드하거나 기존 모델을 미서 조정하는 여부에 관계없이 이 문서에서는 환경 설정, 컨테이너화된 작업 관리, 클러스터에서 학습 스크립트 실행을 안내합니다.

NVIDIA NeMo

NVIDIA NeMo 프레임워크는 생성형 AI 모델을 빌드, 맞춤설정, 배포하는 엔드 투 엔드 플랫폼입니다. 가이드의 이 섹션은 모델 개발의 기본 단계에 중점을 두는 개발자와 연구자를 대상으로 합니다. NeMo를 사용하여 관리형 학습 클러스터에서 대규모 사전 학습, 지속적 사전 학습(CPT), 지도 미세 조정(SFT)을 수행하는 단계별 안내를 제공합니다.

이 학습 클러스터 가이드에서는 NeMo 프레임워크로 학습 작업을 실행하는 전체 워크플로를 제공합니다. 이 프로세스는 환경의 초기 일회성 설정과 작업 실행을 위한 반복 단계 등 두 가지 주요 부분으로 나뉩니다.

환경 설정

작업을 실행하기 전에 컨테이너 이미지와 필요한 학습 스크립트가 있는지 확인하여 환경을 준비해야 합니다.

컨테이너 이미지 준비

컨테이너 이미지에는 사전 빌드된 이미지 사용(권장)하 또는 커스텀 이미지 빌드 등 두 가지 옵션이 있습니다.

사전 빌드된 이미지 사용(권장)

사전 빌드된 컨테이너 이미지는 .squashfs 형식으로 제공됩니다. 해당 리전에 맞는 이미지를 작업 디렉터리에 복사합니다.

# Example for the US region
gcloud storage cp gs://vmds-containers-us/nemo_squashfs/nemo-20250721.sqsh .
맞춤설정된 컨테이너 빌드(고급)

사전 빌드된 컨테이너가 니즈를 충족하지 않는 경우에만 다음 단계를 수행합니다. 이 절차에서는 enroot를 사용하여 커스텀 컨테이너 이미지를 .squashfs 형식으로 변환하는 방법을 안내합니다.

1단계: Google Cloud로 인증합니다.

다음 명령어를 사용하여 Google Cloud 사용자 계정 및 이미지가 호스팅되는 Docker 레지스트리가 모두 인증되었는지 확인합니다.

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

2단계: 전환 스크립트를 만듭니다.

enroot-convert.sh 파일을 만들고 다음 스크립트 콘텐츠를 추가합니다. 이 스크립트를 실행하기 전에 REMOTE_IMG 및 LOCAL_IMG 변수를 업데이트하여 컨테이너 이미지와 선택한 출력 경로를 가리켜야 합니다.

#!/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};
"

3단계: 스크립트를 실행하고 출력을 확인합니다.

Slurm 로그인 노드에서 스크립트를 실행합니다.

sbatch -N 1 enroot-convert.sh

작업이 완료되면 slurm-<JOB_ID>.out 파일에서 변환 로그를 찾고 LOCAL_IMG에 지정한 경로에서 최종 컨테이너 이미지를 찾습니다.

학습 레시피 다운로드

학습 레시피는 비공개 googlesource.com 저장소에 저장됩니다. Git 명령줄을 사용하여 학습 레시피에 액세스하려면 먼저 인증 사용자 인증 정보를 생성해야 합니다.

  1. 인증 사용자 인증 정보 생성

    다음 URL로 이동하여 화면에 표시된 안내를 따릅니다. 이렇게 하면 저장소로 인증하도록 로컬 환경이 구성됩니다. https://www.googlesource.com/new-password

  2. 저장소 클론

    사용자 인증 정보가 인증되면 다음 명령어를 실행하여 레시피를 다운로드합니다.

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

학습 작업 실행

환경이 설정되면 학습 작업을 실행할 수 있습니다.

1단계: 환경 변수 설정

작업에 다음 환경 변수가 필요할 수 있습니다.

  • Hugging Face에서 모델과 데이터 세트를 다운로드하려면 HF_TOKEN이 필요합니다.
  • 실험 분석에 가중치와 편향을 사용하려면 WANDB_API_KEY가 필요합니다.
export HF_TOKEN=YOUR_HF_TOKEN
export WANDB_API_KEY=YOUR_WANDB_API_KEY

2단계: 실행 스크립트 실행

작업 디렉터리로 이동하여 run.py 스크립트를 실행해 작업을 시작합니다. 이 예시에서는 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

실행 파라미터

  • --slurm-type은 클러스터 유형(예: hcc-a3m, hcc-a3u, hcc-a4)에 따라 설정됩니다.
  • --partition은 사용 가능한 파티션으로 설정되어야 합니다. sinfo 명령어를 사용하여 파티션 이름을 확인할 수 있습니다.
  • run.py 스크립트는 --log-dir, --cache-dir, --data-dir를 포함한 여러 디렉터리를 Docker 컨테이너에 자동으로 마운트합니다(설정된 경우).

작업 상태 및 로그 모니터링

작업을 실행하면 상태 블록이 표시됩니다.

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

실행 로그는 상태 출력의 Local Directory 필드에 표시된 경로에 작성됩니다. 예를 들어 다음과 유사한 경로에서 로그 파일을 찾을 수 있습니다.

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

일반적인 오류 및 해결 방법

이 섹션에서는 작업 실행 중에 발생할 수 있는 일반적인 문제를 설명하고 이를 해결하기 위한 권장 단계를 제공합니다.

잘못된 파티션 오류

기본적으로 작업은 일반 파티션에서 실행되려고 합니다. 일반 파티션이 없거나 일반 파티션을 사용할 수 없으면 다음 오류가 표시되면서 작업이 실패합니다.

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

솔루션:

실행 명령어에서 --partition 또는 -p 인수를 사용하여 사용 가능한 파티션을 지정합니다. 사용 가능한 파티션 목록을 보려면 Slurm 로그인 노드에서 sinfo 명령어를 실행합니다.

sinfo

출력에 사용 가능한 파티션 이름이 표시됩니다(이 예시에서는 a3u).

PARTITION AVAIL TIMELIMIT NODES STATE NODELIST
a3u* 작동 중 무한 2 유휴 상태~ alice-a3u-[2-3]
a3u* 작동 중 무한 2 유휴 상태 alice-a3u-[0-1]

토크나이저 다운로드 오류

스크립트에서 GPT2 토크나이저를 다운로드하려고 하면 교차 기기 링크와 관련된 OSError가 발생할 수 있습니다.

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

해결책:

다음의 두 가지 옵션으로 문제를 해결할 수 있습니다.

  • 옵션 1: 작업을 다시 실행합니다. 이 오류는 일시적인 경우가 많습니다. 같은 --cache-dir를 사용하여 작업을 다시 실행하면 문제가 해결될 수 있습니다.
  • 옵션 2: 토크나이저 파일을 수동으로 다운로드합니다. 작업을 다시 실행해도 실패하면 다음 단계를 수행합니다.
    • 다음 파일 2개를 다운로드합니다.
      • gpt2-vocab.json
      • gpt2-merges.txt
    • 다운로드한 파일을 캐시 디렉터리 내 torch/megatron/ 하위 디렉터리(예: <var>YOUR_CACHE_DIR</var>/torch/megatron/)로 이동합니다.
    • 다음과 같이 파일 이름을 바꿉니다.
      • gpt2-vocab.json 이름을 megatron-gpt-345m_vocab로 바꿉니다.
      • gpt2-merges.txt 이름을 megatron-gpt-345m_merges로 바꿉니다.

NVIDIA NeMo-RL

NVIDIA NeMo-RL 프레임워크는 대규모 언어 모델이 인간의 선호도와 안내에 정렬되도록 설계되었습니다. 이 섹션에서는 클러스터에서 NeMo-RL을 사용하여 지도 미세 조정(SFT), 선호도 조정(예: 직접 선호도 최적화(DPO)), 강화 학습(RL)과 같은 고급 정렬 태스크를 수행하는 방법을 안내합니다.

이 가이드에서는 표준 일괄 학습 작업 실행 및 디버깅에 대화형 개발 환경 사용 등 두 가지 기본 워크플로를 설명합니다.

기본 요건

시작하기 전에 클러스터 만들기 페이지의 안내를 따라 클러스터를 만들거나 기존 관리형 학습 클러스터를 사용합니다(있는 경우).

클러스터 로그인 노드에 연결

클러스터의 로그인 노드에 연결하려면 Google Google Cloud 콘솔에서 Google Compute Engine 가상 머신 페이지로 이동하여 SSH > Google Cloud CLI 명령어 보기를 클릭하여 올바른 Google Cloud CLI 명령어를 찾습니다. 다음과 유사한 형식으로 표시됩니다.

ssh $USER_NAME@machine-addr

예:

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

사전 빌드된 Docker 이미지 사용

변환된 .sqsh 파일은 사전 빌드된 컨테이너 이미지에 제공됩니다. 리전의 컨테이너를 선택하고 컨테이너 이미지 파라미터로 직접 설정하거나 클러스터의 파일 시스템에 다운로드할 수 있습니다.

컨테이너 이미지 파라미터로 직접 설정하려면 다음 경로 중 하나를 사용합니다. <region>을 특정 리전(예: europe, asia, us)으로 바꿔야 합니다.

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

이미지를 클러스터의 Lustre 스토리지에 다운로드하려면 다음 명령어를 사용합니다.

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

코드 다운로드

git CLI로 학습 레시피에 액세스하려면 https://www.googlesource.com/new-password로 이동합니다. 다음 명령어를 사용하여 레시피를 다운로드할 수 있습니다.

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

작업 실행

1단계: 환경 변수를 설정합니다.

Hugging Face에서 모델과 데이터를 가져오려면 HF_TOKEN을 설정해야 할 수 있습니다. 실험 분석에 가중치와 편향을 사용하려면 WANDB_API_KEY를 설정해야 합니다. 다음 파일에서 이러한 변수를 업데이트합니다.

업데이트할 파일: $HOME/vertex-oss-training/nemo_rl/configs/auth.sh

가중치와 편향을 사용하지 않으려면 실행 스크립트에서 logger.wandb_enabled를 False로 설정합니다.

2단계: 컨테이너 파일을 실행 폴더에 다운로드하거나 복사합니다.

다음은 몇 가지 예입니다.

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`

3단계: NeMo-RL 저장소를 준비하거나 클론합니다.

NeMo-RL 코드가 아직 없으면 NeMo-RL 코드 클론을 만듭니다. --recursive 플래그를 사용하지 않고 저장소를 이미 클론한 경우에는 git submodule update --init --recursive를 사용해야 할 수 있습니다.

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

4단계: 학습 작업을 실행합니다.

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

각 항목의 의미는 다음과 같습니다.

  • --cluster-type은 클러스터 유형에 따라 설정됩니다.
    • A3-Mega: hcc-a3m
    • A3-Ultra: hcc-a3u
    • A4: hcc-a4
    • A3H: hcc-a3h
  • --partition을 적절하게 설정해야 합니다. 여기서 sinfo를 사용하여 Slurm 파티션을 확인할 수 있습니다.

작업이 시작되면 현재 위치에 SLURM 작업 ID를 따라 이름이 지정된 새 디렉터리가 생성됩니다. 내부에는 이 작업에 속하는 모든 로그와 체크포인트가 있습니다. 더 정확히 말하면 다음 디렉터리와 파일이 있습니다.

  • checkpoints/ → 이 디렉터리는 NeMo-RL 컨테이너 내에 마운트되며 학습의 모든 체크포인트를 포함합니다.
  • ray-logs/ → 이 디렉터리에는 Ray 헤드와 Ray 작업자의 로그가 포함됩니다.
  • nemo_rl_output.log → 이 파일에는 제출된 작업의 Slurm 로그가 포함됩니다.
  • attach.sh(대화형 작업만 해당) → 대화형 작업에 연결할 수 있는 Bash 스크립트입니다. 작업이 성공적으로 실행되면 이 파일이 생성되는 데 몇 분 정도 걸릴 수 있습니다.

NeMo-RL을 사용한 개발

대화형 설정

NeMo-RL을 사용한 빠른 대화형 개발에는 두 가지 옵션을 사용할 수 있습니다.

nemorlinteractive

이 명령어는 클러스터에서 GPU 노드(예: 노드 번호 5)를 선택한 후 선택한 노드 내에서 실행 중인 NeMo-RL 컨테이너로 이동할 수 있는 간단한 도우미 명령어입니다. 이 명령어는 단일 노드 워크플로에 유용합니다.

nemorlinteractive를 사용하려면 다음 기본 요건 단계를 수행해야 합니다.

  1. configs/auth.sh 파일에서 작업에 로드할 모든 인증 토큰(예: HF 및 WandB)을 제공합니다.

  2. 다음 가이드라인에 따라 CLUSTER_TYPE 환경 변수를 설정합니다.

    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. bash_utils.sh를 소싱하여 Bash 터미널에서 nemorlinteractive를 가져옵니다.

    source bash_utils.sh

  4. nemorlinteractive 명령어를 실행합니다. 예를 들면 다음과 같습니다.

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

대화형 실행

이 옵션을 사용하면 여러 컴퓨팅 노드에서 대화형으로 워크로드를 실행할 수 있습니다. 대화형 작업은 디버깅 및 검증 사용 사례에 가장 적합합니다. 이러한 워크로드는 개발자가 디버깅이 완료되었으므로 리소스를 해제하겠다고 결정할 때까지 노드를 무기한 예약합니다.

이 옵션에 따라야 하는 단계는 다음과 같습니다.

configs/auth.sh 파일에서 작업에 로드할 모든 인증 토큰(예: HF 및 WandB)을 제공합니다.

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

  • 2~5분 정도 기다립니다. 그러면 <job_id>/attach.sh가 생성됩니다.

  • 실행 진행 상황을 모니터링하려면 <job_id>/nemo_rl_output.log를 확인하여 실행 스크립트 진행 상황을 확인하고 <job_id>/ray_logs/를 확인하여 Ray 헤드와 작업자 실행 진행 상황을 확인하세요.

  • 대화형 작업에 연결합니다. 이 스크립트를 사용하면 연결이 끊겨도 다시 연결할 수 있습니다.

bash <job_id>/attach.sh

다음 단계

사전 빌드된 워크로드를 실행하면 클러스터의 작동 상태를 확인할 수 있습니다. 다음 단계는 자체 커스텀 학습 애플리케이션을 실행하는 것입니다.