本指南說明如何在代管訓練叢集上使用 NVIDIA NeMo 生態系統,進行端對端生成式 AI 模型開發。本指南提供下列不同但相關的工作流程逐步操作說明,每個工作流程都有專屬章節:
- NVIDIA NeMo:如要開發基礎模型,請按照這些操作說明執行大規模預先訓練、持續預先訓練 (CPT) 和監督式微調 (SFT)。
- NVIDIA NeMo-RL:如要調整模型和偏好設定,請使用本節套用強化學習 (RL) 等進階技術,根據人類指令和偏好調整模型。
無論是從頭建構模型,還是調整現有模型,這份文件都能引導您設定環境、管理容器化工作,以及在叢集上啟動訓練指令碼。
NVIDIA NeMo
NVIDIA NeMo 框架是端對端平台,可用於建構、自訂及部署生成式 AI 模型。本節專為開發人員和研究人員設計,著重於模型開發的基礎階段。本指南提供逐步操作說明,說明如何使用 NeMo 在代管訓練叢集上執行大規模預先訓練、持續預先訓練 (CPT) 和監督式微調 (SFT)。
本訓練叢集指南提供使用 NeMo 架構執行訓練工作的完整工作流程。這項程序主要分為兩個部分:初始一次性設定環境,以及啟動工作的週期性步驟。
設定環境
啟動工作前,請先準備環境,確保您有容器映像檔和必要的訓練指令碼。
安裝 NeMo-Run
pip install git+https://github.com/NVIDIA/NeMo-Run.git
準備容器映像檔
容器映像檔有兩種選項:使用預先建構的映像檔 (建議),或建構自訂映像檔。
使用預先建立的映像檔 (建議做法)
預先建構的容器映像檔會以 .squashfs 格式提供。將適合您所在區域的映像檔複製到目前使用的目錄。
# Example for the US region
gcloud storage cp gs://vmds-containers-us/vmds_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 指令列存取,必須先產生驗證憑證。
產生驗證憑證。
前往下列網址,然後按照畫面上的指示操作。 這會設定本機環境,以便向存放區進行驗證。https://www.googlesource.com/new-password
複製存放區。
憑證通過驗證後,請執行下列指令下載食譜。
git clone -b release-allowlist-ga https://vertex-model-garden.googlesource.com/vertex-oss-training
啟動訓練工作
設定好環境後,即可啟動訓練工作。
步驟 1:設定環境變數
工作可能需要下列環境變數:
- 必須提供
HF_TOKEN,才能從 Hugging Face 下載模型和資料集。 - 必須有
WANDB_API_KEY,才能使用 Weights & Biases 進行實驗分析。
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>/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
啟動參數
--slurm-type是根據叢集類型設定 (例如hcc-a3m、hcc-a3u、hcc-a4)。--partition必須設為可用的分區。您可以使用sinfo指令查看分區名稱。run.py指令碼會自動將多個目錄掛接至 Docker 容器,包括--log-dir、--cache-dir和--data-dir(如有設定)。
監控工作狀態和記錄
啟動工作後,系統會顯示狀態區塊:
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 | 節點 | 狀態 | NODELIST |
|---|---|---|---|---|---|
| a3u* | 向上鍵 | 無限 | 2 | idle~ | alice-a3u-[2-3] |
| a3u* | 向上鍵 | 無限 | 2 | 閒置 | alice-a3u-[0-1] |
Tokenizer 下載錯誤
指令碼嘗試下載 GPT2 權杖化工具時,您可能會遇到與跨裝置連結相關的 OSError:
OSError: [Errno 18] Invalid cross-device link: 'gpt2-vocab.json' -> '/root/.cache/torch/megatron/megatron-gpt-345m_vocab'
解決方法:
解決這個問題的方法有兩種:
- 方法 1:重新執行工作。這通常是暫時性錯誤。使用相同的
--cache-dir重新執行工作,或許能解決問題。 - 方法 2:
手動下載 tokenizer 檔案。如果重新執行工作失敗,請按照下列步驟操作:
- 下載下列兩個檔案:
gpt2-vocab.jsongpt2-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 Cloud 控制台的「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>/vmds_nemo_rl_squashfs/nemo_rl-h20260302.sqsh
如要將圖片下載到叢集的 Lustre 儲存空間,請使用下列指令:
gs://vmds-containers-<region>/vmds_nemo_rl_squashfs/nemo_rl-h20260302.sqsh DESTINATION
下載程式碼
如要透過 git CLI 存取訓練配方,請前往 https://www.googlesource.com/new-password。您可以使用下列指令下載配方:
cd $HOME
git clone -b release-allowlist-ga https://vertex-model-garden.googlesource.com/vertex-oss-training
啟動工作
步驟 1:設定環境變數。
如要從 Hugging Face 提取模型和資料,可能需要設定 HF_TOKEN。如要使用 Weights & Biases 進行實驗分析,必須設定 WANDB_API_KEY。請在下列檔案中更新這些變數:
要更新的檔案:$HOME/vertex-oss-training/nemo_rl/configs/auth.sh
如果不想使用 Weights & Biases,請在啟動指令碼中將 logger.wandb_enabled 設為 False。
步驟 2:將容器檔案下載或複製到啟動資料夾。
以下是幾個例子。
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`
步驟 3:準備或複製 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
- A3-Mega:
- 請據此設定
--partition,並使用sinfo檢查 slurm 分區。
工作啟動後,系統會在您目前的位置建立新目錄,並以 SLURM 工作 ID 命名。您可以在其中找到屬於這項工作的所有記錄和檢查點。更精確地說,您會在其中找到下列目錄和檔案:
checkpoints/→ 這個目錄會掛接在 NeMo-RL 容器中,包含訓練的所有檢查點。ray-logs/→ 這個目錄包含 Ray head 和 Ray worker 的記錄。nemo_rl_output.log→ 這個檔案包含提交工作的 Slurm 記錄。attach.sh(僅限互動式工作) → 這是 Bash 指令碼,可讓您附加至互動式工作。如果工作成功啟動,系統可能需要幾分鐘才能建立這個檔案。
使用 NeMo-RL 開發
互動式設定
NeMo-RL 提供兩種快速互動式開發選項。
nemorlinteractive
這個指令可讓您從叢集選擇 GPU 節點 (例如節點 5),然後前往所選節點中執行 NeMo-RL 的容器。這個指令適用於單一節點工作流程。
如要使用 nemorlinteractive,請先完成下列步驟:
- 在
configs/auth.sh檔案中,提供要載入工作的所有驗證權杖 (例如 HF 和 WandB)。 請按照下列規範設定
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在 Bash 終端機中,透過
bash_utils.sh來源匯入nemorlinteractive:source bash_utils.sh請執行
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 head 和 worker 的啟動進度。連線至互動式工作。即使連線中斷,這個指令碼也能讓你重新連線:
bash <job_id>/attach.sh
後續步驟
執行預先建構的工作負載,驗證叢集的運作狀態。下一步是執行自訂訓練應用程式。
- 執行自己的自訂工作負載:將訓練程式碼封裝至容器,並將容器提交為
CustomJob至訓練叢集。這項程序包括為分散式環境設定工作。 - 監控訓練工作:使用 Google Cloud 控制台或 Cloud Logging,有效追蹤叢集上執行工作的進度、資源使用率和記錄。
- 查看叢集:執行測試後,請檢查叢集及其個別節點的狀態。
- 管理叢集:更新叢集設定,或刪除叢集以管理費用。
- 使用 Gemini Enterprise Agent Platform 管道自動調度管理工作:手動執行工作後,建立管道來自動調度管理訓練工作流程,將程序自動化。