Frequently Asked Questions

最后更新：09/24/2025。

Ray 相关

如何为分布式 Ray 添加断点以进行调试？

请查阅 Ray 的官方调试指南： https://docs.ray.io/en/latest/ray-observability/ray-distributed-debugger.html

“Unable to register worker with raylet”

此问题的原因是由于某些系统设置，例如 SLURM 对节点上 CPU 共享方式添加了一些约束。虽然 ray.init() 尝试启动与机器 CPU 核心数量相同的 Worker 进程，但 SLURM 的一些约束限制了 core-workers 看到 raylet 进程，从而导致问题。

要修复此问题，您可以将配置项 ray_init.num_cpus 设置为您系统允许的数值（例如，适当减小 CPU 数量）。

分布式训练

如何使用 Ray 运行多节点后训练？

您可以启动一个 Ray 集群并提交 Ray 作业，按照 Ray 的官方指南操作： https://docs.ray.io/en/latest/ray-core/starting-ray.html

然后，在配置中，将 trainer.nnode 配置设置为作业所需的机器数量。

如何在 Slurm 管理的集群上使用 verl？

Ray 为用户提供了这个官方教程，来在 Slurm 上启动 Ray 集群。我们已经在多节点设置下的 Slurm 集群上验证了 GSM8K 示例，操作步骤如下。

1. [可选] 如果您的集群支持 Apptainer 或 Singularity 并且您希望使用它，可以将 verl 的 Docker 镜像转换为 Apptainer 镜像。或者，使用集群上可用的包管理器设置环境，或使用其他容器运行时（例如通过 Slurm 的 OCI 支持）。

apptainer pull /your/dest/dir/vemlp-th2.4.0-cu124-vllm0.6.3-ray2.10-te1.7-v0.0.3.sif docker://verlai/verl:vemlp-th2.4.0-cu124-vllm0.6.3-ray2.10-te1.7-v0.0.3

按照 GSM8K 示例准备数据集和模型检查点。
使用您集群的自身信息修改 examples/slurm/ray_on_slurm.slurm 文件。
使用 sbatch 向 Slurm 集群提交作业脚本。

请注意，Slurm 集群设置可能因环境而异。如果您遇到问题，请参考 Ray 的 Slurm 用户指南中常见的注意事项。

如果您更改了 Slurm 资源规格，请确保必要时更新作业脚本中的环境变量。

安装相关

NotImplementedError: TensorDict does not support membership checks with the in keyword.

详细错误信息：

NotImplementedError: TensorDict does not support membership checks with the `in` keyword. If you want to check if a particular key is in your TensorDict, please use `key in tensordict.keys()` instead.

问题原因：Linux-arm64 平台没有适合版本的 tensordict 包（TensorDict 库）。确认方法如下：

pip install tensordict==0.6.2

输出示例：

ERROR: Could not find a version that satisfies the requirement tensordict==0.6.2 (from versions: 0.0.1a0, 0.0.1b0, 0.0.1rc0, 0.0.2a0, 0.0.2b0, 0.0.3, 0.1.0, 0.1.1, 0.1.2, 0.8.0, 0.8.1, 0.8.2, 0.8.3)
ERROR: No matching distribution found for tensordict==0.6.2

解决方法 1：: 从源码安装 tensordict：

pip uninstall tensordict
git clone https://github.com/pytorch/tensordict.git
cd tensordict/
git checkout v0.6.2
python setup.py develop
pip install -v -e .

解决方法 2：: 临时修改出错代码：tensordict_var -> tensordict_var.keys()

非法内存访问

如果您在 rollout（推理展开）过程中遇到类似 CUDA error: an illegal memory access was encountered 的错误消息，请查阅 vLLM 文档针对您使用的 vLLM 版本的具体故障排除步骤。

检查点

如果您想将模型检查点转换为 Hugging Face SafeTensor 格式，请参考 verl/model_merger。

Triton `compile_module_from_src` 错误

如果您遇到类似下面堆栈跟踪的 Triton 编译错误，请根据 https://verl.readthedocs.io/en/latest/examples/config.html 设置 use_torch_compile 标志，以禁用融合内核的即时编译（JIT）。

File "/data/lbh/conda_envs/verl/lib/python3.10/site-packages/triton/runtime/jit.py", line 345, in <lambda>
  return lambda *args, **kwargs: self.run(grid=grid, warmup=False, *args, **kwargs)
File "/data/lbh/conda_envs/verl/lib/python3.10/site-packages/triton/runtime/autotuner.py", line 338, in run
  return self.fn.run(*args, **kwargs)
File "/data/lbh/conda_envs/verl/lib/python3.10/site-packages/triton/runtime/jit.py", line 607, in run
  device = driver.active.get_current_device()
File "/data/lbh/conda_envs/verl/lib/python3.10/site-packages/triton/runtime/driver.py", line 23, in __getattr__
  self._initialize_obj()
File "/data/lbh/conda_envs/verl/lib/python3.10/site-packages/triton/runtime/driver.py", line 20, in _initialize_obj
  self._obj = self._init_fn()
File "/data/lbh/conda_envs/verl/lib/python3.10/site-packages/triton/runtime/driver.py", line 9, in _create_driver
  return actives[0]()
File "/data/lbh/conda_envs/verl/lib/python3.10/site-packages/triton/backends/nvidia/driver.py", line 371, in __init__
  self.utils = CudaUtils()  # TODO: make static
File "/data/lbh/conda_envs/verl/lib/python3.10/site-packages/triton/backends/nvidia/driver.py", line 80, in __init__
  mod = compile_module_from_src(Path(os.path.join(dirname, "driver.c")).read_text(), "cuda_utils")
File "/data/lbh/conda_envs/verl/lib/python3.10/site-packages/triton/backends/nvidia/driver.py", line 57, in compile_module_from_src
  so = _build(name, src_path, tmpdir, library_dirs(), include_dir, libraries)
File "/data/lbh/conda_envs/verl/lib/python3.10/site-packages/triton/runtime/build.py", line 48, in _build
  ret = subprocess.check_call(cc_cmd)
File "/data/lbh/conda_envs/verl/lib/python3.10/subprocess.py", line 369, in check_call
  raise CalledProcessError(retcode, cmd)

训练批大小、迷你批大小和微批大小的含义是什么？

下图展示了不同批大小配置之间的关系。

https://excalidraw.com/#json=pfhkRmiLm1jnnRli9VFhb,Ut4E8peALlgAUpr7E5pPCA

https://github.com/user-attachments/assets/16aebad1-0da6-4eb3-806d-54a74e712c2d

如何生成 Ray 时间线来分析训练作业的性能？

要生成 Ray 时间线文件，您可以将配置项 ray_init.timeline_json_file 设置为一个 JSON 文件路径。例如：

ray_init.timeline_json_file=/tmp/ray_timeline.json

该文件将在训练作业结束时生成于指定路径。您可以使用 Chrome://tracing 或 Perfetto UI 等工具查看 Ray 时间线文件。

下图显示了一个在 1 个节点 4 张 GPU 上运行的训练作业生成的 Ray 时间线文件。

https://github.com/eric-haibin-lin/verl-community/blob/main/docs/ray_timeline.png?raw=true

如何仅为 wandb 设置代理？

如果您需要代理来访问 wandb，您可以在训练作业脚本中添加以下配置。与使用全局 https_proxy 环境变量相比，此方法不会干扰其他 HTTP 请求，例如 ChatCompletionScheduler。

+trainer.wandb_proxy=http://<your proxy and port>

推理与训练序列不匹配（高 actor/grad_norm）

如果您在训练过程中遇到 actor/grad_norm 指标持续增加的问题，这可能是推理引擎和训练之间存在显著精度不匹配导致的。您可以使用以下参数来确认这一点：

actor_rollout_ref.rollout.calculate_log_probs=True

此参数将添加如 training/rollout_probs_diff_mean 之类的指标，可用于验证推理和训练之间是否存在精度差异。

在正常情况下，training/rollout_probs_diff_mean 的值应低于 0.005。如果您观察到此值高于 0.01，则表示推理引擎存在精度问题。精度问题已知在以下条件下发生：

使用非 Hopper 架构 GPU，例如 A100、L20、B200 等。
使用存在问题 22103 的 vLLM 作为推理引擎。
输入和输出文本较长，例如在多轮对话中使用推理模型（如 Qwen3）进行 RL 训练的场景。

如果上述三个条件都满足，并且您观察到 rollout_probs_diff_mean 值过高，建议添加以下参数来解决精度问题：

+actor_rollout_ref.rollout.engine_kwargs.vllm.disable_cascade_attn=True

此问题的根本原因是 vLLM 使用的 Flash Attention 中的一个 bug。虽然它已得到修复，但修复尚未在最新版本的 vLLM (v0.10.2) 中发布。有关此问题的更详细解释，请参考 Fix LSE output error in FA2 kv-split。

在 vLLM 发布包含此修复的新版本之前，建议使用上述配置禁用 cascaded attention（级联注意力）作为临时解决方案。