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 集群上验证了 :doc:`GSM8K 示例<../examples/gsm8k_example>`， 操作步骤如下。 1. [可选] 如果您的集群支持 `Apptainer 或 Singularity `_ 并且您希望使用它， 可以将 verl 的 Docker 镜像转换为 Apptainer 镜像。或者，使用集群上可用的包管理器设置环境，或使用其他容器运行时（例如通过 `Slurm 的 OCI 支持 `_）。 .. code:: bash 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 2. 按照 :doc:`GSM8K 示例<../examples/gsm8k_example>` 准备数据集和模型检查点。 3. 使用您集群的自身信息修改 `examples/slurm/ray_on_slurm.slurm `_ 文件。 4. 使用 `sbatch` 向 Slurm 集群提交作业脚本。 请注意，Slurm 集群设置可能因环境而异。如果您遇到问题，请参考 Ray 的 `Slurm 用户指南 `_ 中常见的注意事项。 如果您更改了 Slurm 资源规格，请确保必要时更新作业脚本中的环境变量。 安装相关 ------------------------ NotImplementedError: TensorDict does not support membership checks with the `in` keyword. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 详细错误信息： .. code:: bash 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 库）。确认方法如下： .. code:: bash pip install tensordict==0.6.2 输出示例： .. code:: bash 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： .. code:: bash 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）。 .. code:: bash File "/data/lbh/conda_envs/verl/lib/python3.10/site-packages/triton/runtime/jit.py", line 345, in 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 .. image:: https://github.com/user-attachments/assets/16aebad1-0da6-4eb3-806d-54a74e712c2d 如何生成 Ray 时间线来分析训练作业的性能？ ------------------------------------------------------------------------------------------ 要生成 Ray 时间线文件，您可以将配置项 ``ray_init.timeline_json_file`` 设置为一个 JSON 文件路径。 例如： .. code:: bash ray_init.timeline_json_file=/tmp/ray_timeline.json 该文件将在训练作业结束时生成于指定路径。 您可以使用 Chrome://tracing 或 Perfetto UI 等工具查看 Ray 时间线文件。 下图显示了一个在 1 个节点 4 张 GPU 上运行的训练作业生成的 Ray 时间线文件。 .. image:: https://github.com/eric-haibin-lin/verl-community/blob/main/docs/ray_timeline.png?raw=true 如何仅为 wandb 设置代理？ ------------------------------------------------------------------------------------------ 如果您需要代理来访问 wandb，您可以在训练作业脚本中添加以下配置。 与使用全局 https_proxy 环境变量相比，此方法不会干扰其他 HTTP 请求，例如 ChatCompletionScheduler。 .. code:: bash +trainer.wandb_proxy=http:// 推理与训练序列不匹配（高 actor/grad_norm） ------------------------------------------------------------------------------------------ 如果您在训练过程中遇到 actor/grad_norm 指标持续增加的问题，这可能是推理引擎和训练之间存在显著精度不匹配导致的。您可以使用以下参数来确认这一点： .. code:: bash actor_rollout_ref.rollout.calculate_log_probs=True 此参数将添加如 training/rollout_probs_diff_mean 之类的指标，可用于验证推理和训练之间是否存在精度差异。 在正常情况下，training/rollout_probs_diff_mean 的值应低于 0.005。如果您观察到此值高于 0.01，则表示推理引擎存在精度问题。 精度问题已知在以下条件下发生： 1. 使用非 Hopper 架构 GPU，例如 A100、L20、B200 等。 2. 使用存在 `问题 22103 `_ 的 vLLM 作为推理引擎。 3. 输入和输出文本较长，例如在多轮对话中使用推理模型（如 Qwen3）进行 RL 训练的场景。 如果上述三个条件都满足，并且您观察到 rollout_probs_diff_mean 值过高，建议添加以下参数来解决精度问题： .. code:: bash +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（级联注意力）作为临时解决方案。