跳到主要内容

MT-veRL 入门

版本

相关能力依赖 Verl 0.9.1、megatron-musa-titan 0.1.0、Megatron-LM、Megatron Bridge、SGLang-MUSA、Ray 和 MUSA 软件栈,使用前请在容器内核对实际版本。

1. MT-veRL 是什么​

veRL 是面向大语言模型的强化学习后训练框架,可组合 actor、rollout、reference、critic 和 reward 等角色,并支持 Megatron、FSDP、SGLang 等训练与推理后端。

MT-veRL 是 veRL 在摩尔线程 MUSA 集群中的适配实践。v2.2.0 采用两层结构:

  1. verl-hardware-plugin 通过 veRL 插件接口注册 MUSA 平台、设备资源和训练引擎。
  2. musa_titan.rl.verl_musa 在启动时安装运行时 patch,为 veRL、Megatron 和 SGLang 补充 MUSA 兼容能力。

用户无需直接修改 veRL 源码。插件层负责识别 MUSA,Titan patch 层负责处理 Torch-MUSA、Megatron 和 SGLang 的兼容细节。

2. 硬件插件​

2.1 插件加载​

verl-hardware-plugin 通过 Python entry point 向 veRL 注册:

[project.entry-points."verl.plugins"]
hardware = "verl_hardware_plugin"

Ray Job 的 runtime_env.yaml 显式指定外部插件和平台:

VERL_USE_EXTERNAL_MODULES: "verl_hardware_plugin"
VERL_PLATFORM: "musa"
ACCELERATOR_BACKEND: "musa"

VERL_PLATFORM=musa 指定 veRL 使用 MUSA 平台,ACCELERATOR_BACKEND=musa 选择加速器初始化路径。

2.2 PlatformMUSA​

能力MUSA 实现
设备名称musa
厂商标识moore_threads
PyTorch 设备模块torch.musa
集合通信后端MCCL
设备可见性变量MUSA_VISIBLE_DEVICES
Ray 调度资源GPU
Ray 不自动设置变量RAY_EXPERIMENTAL_NOSET_MUSA_VISIBLE_DEVICES
进程间通信支持

当前 Ray 使用 GPU 资源调度 MUSA 设备,但不会按 CUDA 规则重写 MUSA_VISIBLE_DEVICES。因此需要设置:

RAY_EXPERIMENTAL_NOSET_MUSA_VISIBLE_DEVICES: "1"

2.3 训练引擎​

插件为 device=musa、vendor=moore_threads 注册:

  • FSDP/FSDP2 语言模型引擎;
  • FSDP/FSDP2 价值模型引擎;
  • Megatron 语言模型引擎;
  • Megatron 价值模型引擎。

训练脚本通过以下参数选择 MUSA 后端:

model_engine=megatron
trainer.device=musa
+actor_rollout_ref.rollout.engine_kwargs.sglang.device=musa

3. 环境检查与通过标准​

以下检查用于确认宿主机、容器、源码和 Ray 集群满足 MT-veRL v2.2.0 的运行要求。尚未创建 set_env.sh 时,先按第 5 节完成路径配置,再返回本节执行检查。

3.1 宿主机驱动与 GPU​

在每台宿主机执行:

mthreads-gmi

v2.2.0 当前环境的参考基线为:

  • Linux Driver 版本为 3.3.10;
  • 设备状态正常,没有掉卡或通信错误;
  • 每节点可见的 MUSA GPU 数量与 hostfile 和训练脚本一致。

mthreads-gmi 用于检查驱动和设备状态,不能替代 MUSA SDK、torch_musa 或 Runtime 的版本检查。

3.2 MUSA SDK、Python 与训练软件​

在容器内先检查 MUSA SDK:

musa_version_query
cat /usr/local/musa/version.json

musa_version_query 中的 musa_toolkits、mcc 和 musa_runtime 应与当前 TrainingSuite 镜像的 SDK 版本一致。随后检查 Python 和训练软件:

python3 - <<'PY'
import importlib.metadata
import os
import platform

import ray
import torch
import torch_musa

print("Python:", platform.python_version())
print("PyTorch:", torch.__version__)
print("torch_musa:", torch_musa.__version__)
print("Ray:", ray.__version__)
print("MUSA available:", torch.musa.is_available())
print("MUSA device count:", torch.musa.device_count())
print("MUSA_VISIBLE_DEVICES:", os.getenv("MUSA_VISIBLE_DEVICES"))

for package in ("sglang", "megatron-core", "transformer-engine"):
try:
print(f"{package}:", importlib.metadata.version(package))
except importlib.metadata.PackageNotFoundError:
print(f"{package}: not installed as a distribution")
PY

v2.2.0 的参考标准如下:

检查项通过标准
Python3.12.x
PyTorch2.9.0.post1
torch_musa2.9.0.post1
Linux Driver3.3.10
MUSA SDK / Toolkitsmusa_version_query 中为 4.3.10
MUSA 可用性torch.musa.is_available() 为 True
MUSA 设备数与 MUSA_VISIBLE_DEVICES 和训练脚本中的每节点 GPU 数一致
SGLang0.5.12.post1,实际值应与容器检查结果一致
Verl0.9.1
megatron-musa-titan0.1.0
training-musa-adaptor2.2.0
Ray所有节点版本一致,节点注册和 GPU 资源数正确

如果镜像发布记录已经更新,以该镜像对应的正式发布清单为准。不要只检查 Driver、SDK 或 PyTorch 中的某一个版本,也不能用 mthreads-gmi 报告的工具版本代替 Driver、Runtime 或 SDK 版本。

3.3 源码与插件版本​

进入示例目录并加载环境文件:

cd /path/to/megatron-musa-titan/examples/rl/verl
source set_env.sh

检查运行路径对应的代码提交:

for name in MUSA_TITAN_PATH VERL_PATH MEGATRON_PATH MEGATRON_BRIDGE_PATH; do
path="${!name}"
echo "=== ${name}: ${path}"
git -C "${path}" rev-parse HEAD
git -C "${path}" status --short
done

检查 veRL 是否加载 MUSA 硬件插件:

python3 - <<'PY'
from importlib.metadata import entry_points

plugins = {entry.name: entry.value for entry in entry_points(group="verl.plugins")}
print("verl.plugins:", plugins)
assert plugins.get("hardware") == "verl_hardware_plugin"
PY

通过标准:

  • 所有 Ray 节点的 MUSA_TITAN_PATH、VERL_PATH、MEGATRON_PATH 和 MEGATRON_BRIDGE_PATH 指向相同版本的代码;
  • git rev-parse HEAD 在不同节点输出相同的提交号;
  • git status --short 没有未确认的本地修改和临时调试代码;
  • VERL_PATH 对应 Verl 0.9.1,并使用团队为本次训练固定的提交,避免分支漂移;
  • verl.plugins 中包含 hardware,对应值为 verl_hardware_plugin。

源码未作为 Python distribution 安装时,megatron-core 或 verl 的包元数据可能显示为未安装;此时以 VERL_PATH、MEGATRON_PATH 的代码提交和实际 import 路径为准。

3.4 Ray 版本与资源​

ray --version
RAY_ADDRESS="http://HEAD_IP:8265" ray status

通过标准:

  • 所有节点的 ray --version 输出一致;
  • Ray 中全部节点处于存活状态;
  • Qwen3-30B 示例显示 4 个节点和 32 个 GPU 资源;
  • Qwen3-8B 示例显示 2 个节点和 16 个 GPU 资源;
  • ray job list 和 Job 日志可以正常访问。

以上检查必须在每个 Ray 节点执行,不能只检查启动节点。

4. 运行时 patch​

4.1 启动入口​

Ray Job 的 runtime_env.yaml 设置:

PYTHONPATH: "${RUNTIME_PYTHONPATH}"
VERL_MUSA_PATCH_AT_STARTUP: "1"

RUNTIME_PYTHONPATH 的第一项必须是 MUSA_TITAN_PATH。这样 Ray Driver、Worker 和继承该环境的子进程启动 Python 时,会加载 Titan 根目录中的 sitecustomize.py。

4.2 延迟安装 patch​

sitecustomize.py 先安装两个 import finder,避免 Python 启动时立即加载 Torch-MUSA、veRL 和 Megatron:

  • _VerlBootstrapFinder:监听 verl 和 megatron;
  • _MusaModelRunnerFinder:监听 sglang.srt.model_executor.model_runner。

运行时序如下:

Python 启动
↓
sitecustomize.py 检测 VERL_MUSA_PATCH_AT_STARTUP=1
↓
安装 import finder
↓
导入 verl / megatron
↓
执行 musa_titan.apply_rl_patch()
↓
安装 Megatron 公共 patch 和 veRL 专用 patch

SGLang scheduler 可能不导入 veRL,因此 model_runner 使用独立的导入后钩子。该路径等待 SGLang 定义 LocalSerializedTensor,随后恢复 MUSA capability 并安装 MTP IPC tensor cache。

multiprocessing.resource_tracker 会被排除,避免纯资源跟踪进程加载 Torch-MUSA 和 Megatron。

5. 公共环境配置​

5.1 准备 set_env.sh​

进入示例目录:

cd /path/to/megatron-musa-titan/examples/rl/verl
cp set_env.sh.example set_env.sh

将所有 /path/to 替换为所有 Ray 节点都能访问的路径:

export MUSA_TITAN_PATH="/path/to/megatron-musa-titan"
export VERL_PATH="/path/to/verl"
export MEGATRON_PATH="/path/to/Megatron-LM"
export MEGATRON_BRIDGE_PATH="/path/to/megatron-bridge/src"

export MUSA_VISIBLE_DEVICES="${MUSA_VISIBLE_DEVICES:-0,1,2,3,4,5,6,7}"
export MCCL_LIB="${MCCL_LIB:-/usr/local/musa/lib/libmccl.so}"
export GLOO_SOCKET_IFNAME="${GLOO_SOCKET_IFNAME:-eth0}"
export MUSA_LD_LIBRARY_PATH="${MUSA_LD_LIBRARY_PATH:-/usr/lib:/lib64:/usr/lib/x86_64-linux-gnu:/usr/local/musa/lib:/usr/local/lib:/usr/local/mtshmem/lib:/usr/local/openmpi/lib}"
export RUNTIME_PYTHONPATH="${MUSA_TITAN_PATH}:${VERL_PATH}:${MEGATRON_PATH}:${MEGATRON_BRIDGE_PATH}${PYTHONPATH:+:${PYTHONPATH}}"
export RUNTIME_LD_LIBRARY_PATH="${MUSA_LD_LIBRARY_PATH}${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}"

MUSA_TITAN_PATH 必须位于 RUNTIME_PYTHONPATH 首位,否则 Python 可能加载其他目录中的 sitecustomize.py。

5.2 关键运行时变量​

变量作用
VERL_USE_EXTERNAL_MODULES加载 verl_hardware_plugin
VERL_PLATFORM选择 musa 平台
VERL_MUSA_PATCH_AT_STARTUP启用 Titan veRL 自动 patch
RUNTIME_PYTHONPATH同时暴露 Titan、veRL、Megatron 和 Megatron Bridge
MUSA_VISIBLE_DEVICES指定 Worker 可见的 MUSA 设备
RAY_EXPERIMENTAL_NOSET_MUSA_VISIBLE_DEVICES禁止 Ray 按 CUDA 规则重写 MUSA 可见设备
MUSA_LD_LIBRARY_PATH提供 MUSA、共享内存和 OpenMPI 动态库路径

示例脚本会展开 runtime_env.yaml 中的 ${变量}。缺少变量时,脚本直接退出并列出缺失项。

5.3 准备 hostfile​

每行填写一个节点地址,第一行作为 Ray Head:

HEAD_IP
WORKER_IP_1
WORKER_IP_2
WORKER_IP_3

所有节点必须:

  • 可以互相 SSH 访问;
  • 使用一致的 Python、MUSA、MCCL、veRL、Megatron 和 SGLang 环境;
  • 通过相同路径访问模型、数据、checkpoint 和 reward 文件;
  • 已启动 Ray,并可通过 HEAD_IP:8265 访问 Dashboard。

6. 示例脚本​

脚本场景
run_qwen3-30b_grpo_node4_32k.shQwen3-30B-A3B 四机 32K GRPO
run_qwen3-8b_grpo_node2_32k.shQwen3-8B 双机 32K GRPO
run_qwen3-8b_grpo_node2_32k_separate_async_musa.shQwen3-8B 训练与 rollout 分离异步模式
run_ds_v2-lite_chat_grpo_node2.shDeepSeek V2 Lite Chat 双机 GRPO
run_qwen3_5_35b_megatron_ep8pp2cp4.shQwen3.5-35B Megatron EP8/PP2/CP4 示例
run_qwen3_5_122b_megatron_h20.shQwen3.5-122B MUSA 配置示例

实现新的训练配置时,可以参考示例脚本,但仍需保证每个 hostfile 节点拥有相同路径和运行时环境。

7. 常见问题​

7.1 硬件插件未加载​

检查 VERL_USE_EXTERNAL_MODULES、VERL_PLATFORM 和 verl.plugins entry point。只设置 VERL_PLATFORM=musa 不会加载外部插件。

7.2 MUSA patch 未生效​

检查 Ray Worker 中的 PYTHONPATH 和 VERL_MUSA_PATCH_AT_STARTUP。只设置 Driver 环境不足以覆盖远端 Worker,变量必须进入 Ray Job 的运行时配置。

7.3 Ray 看不到正确设备​

检查 MUSA_VISIBLE_DEVICES 和 RAY_EXPERIMENTAL_NOSET_MUSA_VISIBLE_DEVICES。当前适配使用 GPU 作为 Ray 调度资源,但不让 Ray 按 CUDA 规则重写 MUSA 可见设备。

7.4 配置展开提示变量缺失​

在 set_env.sh 或启动命令中补齐错误信息列出的变量,再重新执行脚本。路径必须是所有节点可见的绝对路径。

8. 文档导航​