verl-deploy

Verl デプロイ - トレーニングサービスのワンコマンド起動

NPU クラスター上で Verl 分散トレーニングサービスを起動し、アクセラレーション機能を柔軟に設定できます。DAPO/GRPO などの RLHF アルゴリズムに対応しています。

基本原則

1. ユーザー設定を優先：ユーザーによる明示的な指定 > 自動検出 > デフォルト値
2. 設定は必ず検証：パスやイメージなどが有効か実行前に確認し、推測しません
3. ユーザー確認を必須とする：実行前に設定一覧を表示し、確認を待ちます
4. ホストマシンとコンテナ内を厳密に区別：docker cp はホストマシンで実行し、コンテナに入った後は docker プレフィックス付きコマンドを使用しません

---

全体の流れ

1. 环境预检查 → 2. 用户交互 → 3. 配置确认 → 4. 镜像准备+容器拉起 → 5. SwanLab 配置 → 6. 生成双脚本 → 7. 复制+执行 → 8. 验证

---

フェーズ 1：環境の事前チェック

以下の bash コマンドを実行して、マシン環境を自動検出します。

# NPU 信息
npu-smi info
npu-smi info -t board 2>/dev/null

# Docker 和镜像
docker ps -a | grep verl
docker images | grep -E "verl|ascend"

# 模型权重
find /mnt/public /mnt2 /mnt/project -maxdepth 4 -type d -name "Qwen*" 2>/dev/null

# 数据集
find /mnt /mnt2 -name "*.parquet" 2>/dev/null | head -20

# 网卡和 IP
hostname -I

検出結果を記録し、フェーズ 2 で使用します。

---

フェーズ 2：ユーザーとの対話による情報収集

AskUserQuestion を使用し、各ラウンドでフェーズ 1 の検出結果に基づく入力済みの値を提示して情報を収集します。

ラウンド 1：基本設定

• トレーニングモード：単一マシン / 複数マシン
• NPU カード番号（検出結果を入力済みの値として提示。ユーザーは変更可能）
• モデルパス（検出されたモデルを選択肢として表示するか、パスを手動で指定）
• トレーニングデータセットのパス
• テストデータセットのパス
• Checkpoint の保存先パス

ラウンド 2：イメージとコンテナの設定

• コンテナの処理方法：既存のコンテナを使用 / コンテナを新規作成
• 新規作成する場合：
  • イメージの選択：ローカルにある既存の verl イメージを一覧表示 / 手動で入力 / quay.io からプル
  • デフォルトのプル先：quay.io/ascend/verl:verl-8.3.rc1-910b-ubuntu22.04-py3.11-v0.7.0

ラウンド 3：SwanLab の設定

• SwanLab ログを有効にするか（はい / いいえ）

有効にする場合は、項目ごとに質問します（デフォルト値を提示）：

• SwanLab Host：デフォルト値なし、必須（例：http://192.168.1.100:8000）
• SwanLab API Key：デフォルト値なし、必須
• SwanLab Mode：デフォルトは cloud
• SwanLab Workspace：デフォルトは TrainingMaster
• SwanLab Log Dir：デフォルトは /mnt/project/h4380/examples/verl/swanlab_cloud_fsdp_log/
• Project Name：デフォルトは verl_hlm

ラウンド 4：機能の設定

7 桁の 2 進数の機能マスクを入力します。

位[0]位[1]位[2]位[3]位[4]位[5]位[6]
 ↓    ↓    ↓    ↓    ↓    ↓    ↓
RmvPad DynBSZ Offload PfxCache Recompute SwapOpt VPP

デフォルト値：0000000（すべて無効）

機能の説明：

ビット	名前	種類	説明
0	Remove Padding	シンプルな切り替え	無効な padding の計算を削減
1	Dynamic Batch Size	シンプルな切り替え	実際の長さに応じて batch を分割
2	Offload	シンプルな切り替え	パラメーター / 勾配を CPU にオフロード
3	Prefix Cache	行の追加	KV キャッシュのプレフィックスを再利用
4	Recompute	3 行の追加	キャッシュの代わりに再計算を使用
5	Swap Optimizer	行の追加	オプティマイザーの状態をスワップイン / スワップアウト
6	VPP	行の追加	仮想パイプライン並列処理

排他に関する警告：bit5（Swap Optimizer）と bit2（Offload）の optimizer_offload は同時に有効にできません。同時に有効にした場合、スクリプトは optimizer_offload を自動的に False に設定します。

ラウンド 5：トレーニングのハイパーパラメーター

デフォルト値を提示します。ユーザーは上書きできます。

• トレーニングステップ数（デフォルトは 4）
• Batch Size（デフォルトは 32）
• 学習率（デフォルトは 1e-6）
• TP テンソル並列数（デフォルトは 4）
• PP パイプライン並列数（デフォルトは 2）
• prompt ごとに生成する応答数（デフォルトは 8）

---

フェーズ 3：設定の確認（必須の確認ポイント）

以下を含む設定一覧全体を表示します。

• ハードウェア設定（NPU カード番号、数量）
• コンテナ / イメージ情報
• リソースパス（モデル、データセット、Checkpoint）
• トレーニングのハイパーパラメーター
• 機能マスクと各機能の有効 / 無効状態
• SwanLab の設定（有効にした場合）

ユーザーの確認を待ってから続行します。ユーザーの確認前に変更操作を実行してはいけません。

---

フェーズ 4：イメージの準備 + コンテナの起動

既存のコンテナ

コンテナ名を確認し、状態をチェックします。停止している場合は起動します。

docker ps -a | grep <container_name>
docker start <container_name>  # 如已停止

コンテナの新規作成

1. イメージの確認 / プル：

# 用户选择本地镜像 → 直接使用
# 用户选择拉取 → 执行
docker pull quay.io/ascend/verl:verl-8.3.rc1-910b-ubuntu22.04-py3.11-v0.7.0

2. コンテナの起動：scripts/verl_docker_run.sh を使用します

bash scripts/verl_docker_run.sh <镜像ID> <容器名>

3. コンテナの起動を確認：

docker exec <container_name> bash -c "npu-smi info && python --version"

---

フェーズ 5：SwanLab の設定（有効にした場合）

コンテナに入った後、コンテナ内で操作します（docker プレフィックスは付けません）。

注意：このフェーズでは、先にコンテナに入ってから操作します。後続のフェーズ 7 で初めてコンテナに入る場合は、フェーズ 7 でコンテナに入った後、トレーニングを開始する前に SwanLab を設定することもできます。

手順 1：swanlab を確認してインストール

python -c "import swanlab" 2>/dev/null && echo "swanlab 已安装" || pip install swanlab

手順 2：ログイン

echo '<SWANLAB_API_KEY>' | swanlab login --host <SWANLAB_HOST>

手順 3：ログインを検証

cat ~/.swanlab/config.json

ファイルが存在し、API Key の情報が含まれていれば、ログインは成功です。

---

フェーズ 6：2 つのスクリプトを生成

scripts/generate_training.sh を使用して 2 つのスクリプトを生成します。

生成結果

スクリプト	役割	対応する参考スクリプト
start_verl.sh	上位層：NPU / ネットワーク設定、Ray クラスターの起動、SwanLab 環境変数、下位層の呼び出し	start_flex.sh
run_training.sh	下位層：トレーニングのハイパーパラメーター、機能設定、Hydra の python トレーニングコマンド	test_dapo_qwen3_8b_megatron_flex.sh

呼び出し関係：start_verl.sh → bash run_training.sh

生成コマンド

bash scripts/generate_training.sh \
  --mask <FEATURE_MASK> \
  --output-dir /tmp/verl_scripts/ \
  --model-path <MODEL_PATH> \
  --train-file <TRAIN_FILE> \
  --test-file <TEST_FILE> \
  --ckpts-dir <CKPTS_DIR> \
  --npu-devices "0,1,2,3,4,5,6,7" \
  --master-addr <IP> \
  --socket-ifname <IFNAME> \
  --train-steps <STEPS> \
  --train-tp <TP> \
  --train-pp <PP> \
  --swanlab <yes|no> \
  --swanlab-host <HOST> \
  --swanlab-api-key <KEY> \
  --swanlab-mode <MODE> \
  --swanlab-workspace <WS> \
  --swanlab-log-dir <DIR> \
  --project-name <NAME>

機能の処理方法

Type A（bit0-2）：シンプルな変数置換

テンプレートにプレースホルダーがすでにあるため、sed で直接置換します。

• USE_REMOVE_PADDING_PLACEHOLDER → True/False
• USE_DYNAMIC_BSZ_PLACEHOLDER → True/False
• PARAM_OFFLOAD_PLACEHOLDER / OPTIMIZER_OFFLOAD_PLACEHOLDER / GRAD_OFFLOAD_PLACEHOLDER → それぞれ True/False

Offload と Swap Optimizer は排他的です。同時に有効にした場合、OPTIMIZER_OFFLOAD は自動的に False に設定されます。

Type B（bit3-6）：コメントの制御

テンプレート内の Type B 機能の行は、デフォルトで # によってコメントアウトされています。ビットに応じてコメントを解除します。

# bit3: Prefix Cache
[ "$bit3" = "1" ] && sed -i 's/^# \(actor_rollout_ref.rollout.enable_prefix_caching=True\)/\1/' "$script"

# bit4: Recompute（3 行）
if [ "$bit4" = "1" ]; then
    sed -i 's|^# \(+actor_rollout_ref.actor.megatron.override_transformer_config.recompute_granularity=full\)|\1|' "$script"
    sed -i 's|^# \(+actor_rollout_ref.actor.megatron.override_transformer_config.recompute_method=block\)|\1|' "$script"
    sed -i 's|^# \(+actor_rollout_ref.actor.megatron.override_transformer_config.recompute_num_layers=8\)|\1|' "$script"
fi

# bit5: Swap Optimizer
[ "$bit5" = "1" ] && sed -i 's|^# \(+actor_rollout_ref.actor.megatron.override_transformer_config.swap_optimizer=True\)|\1|' "$script"

# bit6: VPP
[ "$bit6" = "1" ] && sed -i 's|^# \(actor_rollout_ref.actor.megatron.virtual_pipeline_model_parallel_size=2\)|\1|' "$script"

# 清理未启用的注释行
sed -i '/^#.*\(+\?actor_rollout_ref\|enable_prefix_caching\)/d' "$script"

SwanLab の処理

テンプレートのデフォルトは trainer.logger='["console","swanlab"]' です。SwanLab を有効にしない場合：

sed -i "s|trainer.logger='\[\"console\",\"swanlab\"\]'|trainer.logger='[\"console\"]'|g" "$script"

---

フェーズ 7：スクリプトをコンテナにコピーして実行

手順 1（ホストマシン）：docker cp

重要：docker cp は必ずホストマシン環境で実行します。現在コンテナ内にいないことを確認してください。

docker cp /tmp/verl_scripts/start_verl.sh <container_name>:/verl/start_verl.sh
docker cp /tmp/verl_scripts/run_training.sh <container_name>:/verl/run_training.sh

手順 2：コンテナに入る

docker exec -it <container_name> bash

手順 3（コンテナ内）：SwanLab の設定 + トレーニングの開始

コンテナに入った後、コンテナ内で実行します（docker プレフィックスは付けません）。

# 激活环境
source /usr/local/Ascend/cann/ascend-toolkit/set_env.sh
source /usr/local/Ascend/cann/nnal/atb/set_env.sh

# （如开启 SwanLab）注入环境变量 + 安装登录
export SWANLAB_HOST="<用户提供的地址>"
export SWANLAB_API_KEY="<用户提供的 API Key>"
export SWANLAB_MODE="<cloud 或 local>"
export SWANLAB_WORKSPACE="<工作空间>"
export SWANLAB_LOG_DIR="<日志目录>"
export PROJECT_NAME="<项目名>"

python -c "import swanlab" 2>/dev/null || pip install swanlab
echo "$SWANLAB_API_KEY" | swanlab login --host "$SWANLAB_HOST"
cat ~/.swanlab/config.json  # 验证

# 启动训练
cd /verl
bash start_verl.sh

start_verl.sh が自動的に Ray クラスターを起動し、run_training.sh を呼び出してトレーニングを開始します。

---

フェーズ 8：トレーニングの開始を検証

コンテナ内で確認します。

ps aux | grep main_dapo
tail -20 logs/verl_qwen3_8b_*.log

---

並列処理の制約

制約	説明
gen_tp == train_tp	推論とトレーニングのテンソル並列数は等しくなければなりません
(train_tp x train_pp) % NPU_PER_NODE == 0	tp x pp は、各ノードの NPU 数で割り切れなければなりません

---

使用可能なスクリプト

スクリプト	用途
scripts/generate_training.sh	パラメーターに基づいて 2 つのスクリプトを生成
scripts/feature_mask.sh	7 桁の 2 進数の機能マスクを解析
scripts/pre_check.sh	環境の事前チェック
scripts/verl_docker_run.sh	コンテナの起動

参考ドキュメント

• references/feature-guide.md — 7 つのアクセラレーション機能の詳細
• references/troubleshooting.md — よくある問題と解決策（Q1-Q13）
• references/ops-commands.md — よく使う運用コマンド（Docker/NPU/Ray/ログ）