Ray 分布式调试实战指南在 verl/HybridFlow 训练中定位 Actor 与 Rollout 问题【免费下载链接】verlverl/HybridFlow: A Flexible and Efficient RL Post-Training Framework项目地址: https://gitcode.com/GitHub_Trending/ve/verl本指南基于 verl 仓库的 docs/start/ray_debug_tutorial.rst 编写围绕 verl/HybridFlow 的 Ray 分布式训练场景讲解如何使用 Ray Distributed Debugger VSCode 扩展与 Ray 内置的 legacy debugger 两种方式对ray.remote远程任务进行断点调试。读完本文你将掌握在 verl 的 PPO/GRPO 训练actor、critic、rollout、reward 等远程 Worker中设置断点、附加调试器、处理多个断点以及排查初始化异常的完整方法。调试环境与适用场景verl/HybridFlow 是一个基于 Ray 的分布式 RL 后训练框架训练流程由 driver 进程发起通过ray.remote的TaskRunner驱动再进一步分派到 actor、critic、ref policy、reward model 等 WorkerGroup 上执行。也就是说训练代码的绝大部分逻辑模型前向、rollout 生成、PPO 更新运行在 Ray 管理的远程进程里普通单进程调试器如 IDE 的本地 debug无法触达这些进程。例如 verl/trainer/main_ppo.py 中的run_ppo会先调用ray.init()初始化集群再通过task_runner_class.remote()创建远程 TaskRunner随后ray.get(runner.run.remote(config))等待训练完成。这意味着任何断点若想命中模型训练的关键路径都必须能附加到这些 Ray 管理的进程上——这正是本教程要解决的核心问题。本文介绍两条调试路径推荐路径Ray Distributed Debugger VSCode 扩展Ray 2.39 起由 Anyscale 提供通过 Dashboard 与debugpy实现图形化断点调试兼容路径Ray 内置的 legacy debugger通过RAY_DEBUGlegacy与--ray-debugger-external启动集群再用ray debug命令行附加。下面先从环境准备讲起再依次展开两种方案的完整操作步骤。前置准备集群、版本与变量1. 建立 Ray 集群无论使用哪种调试方式都需要先有一个可用的 Ray 集群。对于单机多卡或多机训练verl 提供了标准的多节点启动方式详见 docs/start/multinode.rst# 在 head 节点启动 Ray--dashboard-host0.0.0.0 允许外部访问 Dashboard ray start --head --dashboard-host0.0.0.0启动后关注两个地址GCS 地址形如head_ip:6379用于 worker 节点连接Dashboard 地址形如head_ip:8265用于在浏览器查看集群状态以及后续作为 Ray Distributed Debugger 扩展的连接入口。worker 节点通过 GCS 地址加入集群ray start --addresshead_ip:6379用ray status确认所有节点都已加入。若需将训练任务提交到集群可使用ray job submit参考 docs/start/multinode.rst 中的--runtime-envverl/trainer/runtime_env.yaml用法该文件位于 verl/trainer/runtime_env.yaml内含working_dir、排除项以及TORCH_NCCL_AVOID_RECORD_STREAMS、CUDA_DEVICE_MAX_CONNECTIONS等分布式环境变量。2. 版本与依赖检查使用 Ray Distributed Debugger VSCode 扩展前请确认以下条件满足详见扩展 READMEVisual Studio Code已安装ray[default] 2.9.1项目运行所需的 Ray 版本下限debugpy 1.8.0调试协议实现VSCode 调试后端依赖它。3. 启用崩溃后调试Post-mortem Debugging在启动 Ray 之前设置环境变量以启用崩溃后调试——即远程任务抛出未捕获异常时自动挂起并进入调试会话export RAY_DEBUG_POST_MORTEM1重要提醒设置该变量的同时务必移除任何遗留的旧式调试标志后再启动 Ray否则新旧机制冲突会导致调试行为异常RAY_DEBUGlegacy--ray-debugger-external从源码看verl 本身并不强制要求这些变量调试相关的环境变量完全由用户在ray start/python job.py之前自行 export。唯一需要留意的是 verl 在ray.init()时会通过get_ppo_ray_runtime_env(config)合并默认 runtime_env见 verl/trainer/main_ppo.py用户传入的ray_kwargs.ray_init.runtime_env会覆盖默认值配置入口见 verl/trainer/config/ppo_trainer.yaml 的ray_kwargs段因此调试变量应在环境层面全局生效而不是依赖 config 传递。方法一Ray Distributed Debugger VSCode 扩展推荐第 1 步安装扩展并添加集群从 Ray 2.39 开始Anyscale 引入了Ray Distributed DebuggerVSCode 扩展。按扩展安装说明完成安装后使用之前拿到的 Dashboard URLhttp://head_ip:8265将你的集群添加到扩展中。扩展会通过该地址发现集群中的 Ray 进程并建立调试通道。第 2 步在远程函数中埋入breakpoint()在代码中插入breakpoint()调用然后向集群提交任务ray.remote def worker_fn(...): # 前向计算或 rollout 生成逻辑 ... breakpoint() # 命中后进程会挂起等待调试器附加 ...任务提交后扩展会检测到活跃断点并在 VSCode 中展示断点信息。注意断点仅支持在ray.remote装饰的远程函数/类方法内生效。这正好覆盖 verl 的训练关键路径——例如 verl/trainer/main_ppo.py 中ray.remote修饰的TaskRunnerV1其run方法内部初始化 trainer、agent loop manager 并执行fit()所有 PPO 数据流都从这里展开同理各角色的 Workeractor_rollout、critic、ref也都是以 Ray 远程 Actor 形式运行的。第 3 步直接从命令行启动任务从命令行直接运行你的训练脚本不要使用launch.jsonpython job.py对应到 verl即python3 -m verl.trainer.main_ppo \ data.train_files/path/to/train.parquet \ data.val_files/path/to/test.parquet \ actor_rollout_ref.model.pathQwen/Qwen2.5-0.5B-Instruct \ trainer.n_gpus_per_node1 \ trainer.nnodes1 \ ...脚本内部会在ray.init()后创建远程 TaskRunnertask_runner_class.remote()进而驱动所有远程 Worker。第 4 步附加调试器到断点当进程首次命中breakpoint()时点击 VSCode 侧边栏的 Ray Distributed Debugger 图标即可附加调试器。此时你可以像本地调试一样查看调用栈、变量值甚至逐步执行远程代码。第 5 步多个breakpoint()的轮换调试如果代码中有多个breakpoint()先断开当前调试会话disconnect再点击扩展图标附加到下一个断点。以此类推逐个处理所有断点。这是分布式调试与单进程调试最大的差异——每个断点都对应一个独立的远程进程实例因此需要反复断开—重连。方法二Ray 内置 Legacy Debugger当无法使用 VSCode 扩展例如 Ray 版本低于 2.39或环境不允许安装扩展时可使用 Ray 自带的 legacy debugger。该调试器允许你调试分布式应用但需要以特定标志启动 Ray 集群。第 1 步以 legacy 模式启动集群# 启动 head 节点 RAY_DEBUGlegacy ray start --head --dashboard-host0.0.0.0 --ray-debugger-external # 启动 worker 节点address 替换为实际的 head GCS 地址 RAY_DEBUGlegacy ray start --address10.124.46.192:6379 --ray-debugger-external两个关键标志RAY_DEBUGlegacy启用 Ray 内置的旧式调试器--ray-debugger-external允许调试器在集群外部即你的开发机附加到远程进程便于从本机发起调试。第 2 步设置断点并运行ray debug在代码中设置breakpoint()后向集群提交任务然后运行ray debug该命令会进入等待状态监听远程进程触发的断点。命中后即可在命令行界面查看调用栈、求值变量进行交互式调试。两种方式如何选择对比维度Ray Distributed Debugger 扩展推荐Legacy Debugger适用 Ray 版本 2.39扩展引入任意版本交互界面VSCode 图形界面命令行交互需要安装VSCode 扩展 debugpy无额外依赖附加方式点击扩展图标ray debug命令环境变量RAY_DEBUG_POST_MORTEM1RAY_DEBUGlegacy--ray-debugger-external结合 verl 源码的调试实操要点在正确的进程层级上设置断点verl 的分布式执行模型参考 docs/workers/ray_trainer.rst大致为driver 进程加载配置、调用ray.init()、创建远程 TaskRunnerTaskRunnerRay Actor承载 trainer调度 PPO 数据流WorkerGroup各角色 Workeractor_rollout、critic、ref policy、reward model各自运行在不同进程或按create_colocated_worker_cls合并。由于断点只支持ray.remote内部调试 actor 更新逻辑时应在TaskRunnerV1.runverl/trainer/main_ppo.py 中ray.remote class TaskRunnerV1内部下断点调试具体某个模型角色时则应在对应 Worker 类的远程方法中下断点。注意driver 进程python -m verl.trainer.main_ppo本体不是 Ray 远程任务不能靠这套机制断点如需调试 driver 侧逻辑可配合传统本地调试。结合 post-mortem 排查训练崩溃RL 训练中常见的远程任务抛异常但日志不完整问题可以用RAY_DEBUG_POST_MORTEM1让崩溃进程自动挂起随后附加调试器检查现场状态如 DataProto 字段缺失、advantage 计算 NaN、reward 分数形状不匹配等。这是定位远程异常的最快路径崩溃点即断点无需预先猜测埋点位置。辅助手段Ray 日志与 Dashboard调试前建议先观察日志缩小范围ray job logs Submission ID --follow持续跟踪任务日志各 actor 的 driver/task 日志位于/tmp/ray/session_latest/logs/driver 日志名为job-driver-raysubmit_Submission ID.log多节点训练时Ray Dashboard 提供了结构化的 job 视图详见 docs/start/multinode.rst。先看日志、再决定在哪个远程函数埋breakpoint()能显著减少无效断点。常见问题排查断点从未命中确认断点位于ray.remote修饰的函数内部确认任务确实提交到了目标集群而不是本地新建了一个集群确认RAY_DEBUG_POST_MORTEM是在ray start/任务启动前导出的。遗留标志干扰若同时设置了RAY_DEBUGlegacy和RAY_DEBUG_POST_MORTEM1先清除 legacy 标志再重启集群。无法附加检查防火墙是否放行 Dashboard 端口8265以及 debugpy 使用的调试端口--dashboard-host0.0.0.0确保外部可达。多断点错乱每个断点对应独立进程实例务必先 disconnect 再 attach 下一个否则会附加到错误的进程。小结本文完整覆盖了 verl/HybridFlow 下两种 Ray 分布式调试方案推荐使用 Ray Distributed Debugger VSCode 扩展安装扩展 → 用 Dashboard URL 添加集群 → 在ray.remote函数内插入breakpoint()→ 命令行运行任务 → 点击扩展图标附加调试器多断点时断开—重连逐个处理备选使用 legacy debugger以RAY_DEBUGlegacy ray start --head --ray-debugger-external启动集群配合ray debug进行命令行交互调试。无论哪种方式关键都在于理解 verl 的进程层级断点要打在ray.remote的 TaskRunner 或各角色 Worker 上driver 进程则需另用本地调试。结合RAY_DEBUG_POST_MORTEM1的崩溃后调试与 Ray 日志/Dashboard 预判即可系统性地定位分布式 RL 训练中的各类问题。【免费下载链接】verlverl/HybridFlow: A Flexible and Efficient RL Post-Training Framework项目地址: https://gitcode.com/GitHub_Trending/ve/verl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考