尧图网页设计 
verl 升级指南在 vLLM 0.8 上启用 CUDA Graph 与 V1 引擎进行 RL 后训练【免费下载链接】verlverl/HybridFlow: A Flexible and Efficient RL Post-Training Framework项目地址: https://gitcode.com/GitHub_Trending/ve/verl导读本文以 docs/README_vllm0.8.md 为主体讲解 verlHybridFlow一款灵活高效的 RL 后训练框架如何升级并运行在 vLLM 0.8 上包括环境安装、Docker 镜像导入、开启 CUDA Graph 与 V1 引擎所需的两个关键配置项以及升级过程中常见依赖冲突如ForkingPickler导入失败的排查与修复。读完本文你将能够在 verl vLLM 0.8 组合下完整跑通训练并对相关配置项的底层实现形成源码级认识。1. 升级背景vLLM 0.8 带来了什么vLLM 0.8 系列是 vLLM 引擎的重要迭代版本。在 verl 中vLLM 0.8 默认启用两大特性CUDA Graph将解码阶段的 GPU kernel 执行图预先捕获并复用显著降低 kernel 启动开销提升 rollout 吞吐V1 EnginevLLM 新一代调度引擎重构了批处理与调度路径带来更低的调度延迟与更好的并发表现。需要特别说明的是此版本组合下 verl 采用FSDP 做训练、vLLM 做 rollout采样生成的分工架构即训练与推理由不同组件负责这也是 verl 中常见的 actorFSDP 训练与 rolloutvLLM 推理分离模式。从源码看vLLM 的版本适配逻辑集中在 verl/workers/rollout/vllm_rollout/vllm_async_server.py其开头通过_VLLM_VERSION version.parse(vllm.__version__)第 74 行对 vLLM 版本进行解析并在后续多处按版本分支处理不同 API 行为例如第 356 行判断 vLLM 0.13.0 时改用 CLI 参数方式传递 profiler 配置可见 verl 对 vLLM 各版本保持着细粒度的兼容处理。2. 安装步骤2.1 从源码安装 verl 与 vLLM官方推荐的安装流程如下# 创建 conda 环境Python 3.10 conda create -n verl python3.10 conda activate verl # 克隆并安装 verl git clone https://github.com/verl-project/verl.git cd verl pip3 install -e . # 安装 vLLM 0.8 系列的最新稳定版 pip3 install vllm0.8.3 # 安装 flash-attn注意使用 --no-build-isolation pip3 install flash-attn --no-build-isolation几点说明pip3 install -e .以可编辑模式安装 verl便于开发调试verl 的完整依赖清单见 requirements.txtNPU 场景则使用 requirements-npu.txtvLLM 版本固定为0.8.3这是该文档编写时验证过的稳定版本flash-attn 使用--no-build-isolation是为了让其在已安装的 PyTorch 编译环境中完成构建避免隔离环境导致的编译失败。2.2 使用预构建 Docker 镜像推荐verl 团队提供了 verl vLLM 0.8.3 的预构建镜像可直接导入使用无需手动安装依赖docker pull hiyouga/verl:ngc-th2.6.0-cu126-vllm0.8.3-flashinfer0.2.2-cxx11abi0从镜像 tag 可以看出其组成NGC 基础镜像 PyTorch 2.6.0 CUDA 12.6 vLLM 0.8.3 FlashInfer 0.2.2 CXX11 ABI 0适用于典型 GPU 训练环境。仓库内另有完整的 Docker 构建体系可参考 docker/README.md 以及 docker/verl0.4-cu124-torch2.6-fa2.7.4/Dockerfile.app.vllm.mcore0.12 等应用镜像文件按需构建其他版本的组合镜像。3. 启用 CUDA Graph 与 V1 引擎的关键配置3.1 两行必须添加的配置升级到 vLLM 0.8 后verl 默认启用 CUDA Graph 与 V1 引擎。要在训练脚本中显式开启这两个特性需要在启动命令中追加以下两个参数actor_rollout_ref.rollout.enforce_eagerFalse \ actor_rollout_ref.rollout.free_cache_engineTrue \这两个参数的含义分别如下参数值作用actor_rollout_ref.rollout.enforce_eagerFalse关闭 eager 模式允许 vLLM 使用 CUDA Graph 加速解码actor_rollout_ref.rollout.free_cache_engineTrue在权重同步期间释放推理引擎的 KV Cache训练/推理切换时回收显存3.2 必须移除的环境变量同时如果脚本中原本存在以下环境变量需要删除export VLLM_USE_V11原因在于vLLM 0.8 中 V1 引擎已是默认显式设置该变量不仅多余还可能干扰 verl 对引擎行为的默认管理。仓库中 verl/experimental/fully_async_policy/shell/runtime_env.yaml 等旧配置里仍保留VLLM_USE_V1: 1的写法属于历史遗留而 verl/trainer/main_generation_server.py 等较新入口已不再依赖该变量由 vLLM 版本本身决定引擎行为。3.3 配置项的源码级解析enforce_eagerCUDA Graph 的开关在 verl/trainer/config/rollout/rollout.yaml 中该参数注释为「Whether to disable CUDA graph. Default False to best performance.」即默认False以换取最佳性能。其底层传递逻辑位于 verl/workers/rollout/vllm_rollout/vllm_async_server.py构造 vLLM AsyncEngine 参数时直接将enforce_eager: self.config.enforce_eager传入引擎。当enforce_eagerFalse时vLLM 捕获 CUDA Graph 并复用于解码阶段从而减少 kernel 启动开销。对应的配置类定义在 verl/workers/config/rollout.py其中还包含关联参数cudagraph_capture_sizesCUDA Graph 捕获批大小列表需在enforce_eagerFalse下使用。该参数在 vllm_async_server.py 中被写入compilation_config[cudagraph_capture_sizes]并进一步设置cudagraph_mode为FULL_AND_PIECEWISE当启用解码上下文并行DCP时代码会自动降级为PIECEWISE模式见第 310-318 行以规避 FULL 模式与 DCP 的兼容问题。free_cache_engine训练/推理切换的显存管理该参数默认值为True见 rollout.yaml。它的核心用途是RL 训练中 rollout 引擎与 actor 训练交替进行权重同步update_weights期间需要把显存从 KV Cache 腾给权重更新使用。在 verl/workers/rollout/vllm_rollout/vllm_async_server.py 中可以看到一组配套方法sleep()将引擎休眠、释放 KV Cache 显存第 854-863 行仅在node_rank 0且free_cache_engineTrue时执行release_kv_cache()/resume_kv_cache()分别在权重同步前释放 KV Cache、同步后恢复第 876-893 行同样受该开关控制clear_kv_cache()在权重更新完成后清理前缀缓存保证旧权重下的缓存不会污染新权重第 865-874 行。而在 verl/workers/rollout/vllm_rollout/vllm_rollout.py 中resume()/release()两个方法也会先判断self.config.free_cache_engine再决定是否执行wake_up/sleep从而在同步期间将 GPU 内存让出给权重传输。3.4 真实训练脚本中的用法仓库内大量真实示例脚本都遵循这一配置模式。以 examples/grpo_trainer/run_qwen3_4b_fsdp.sh 为例actor_rollout_ref.rollout.enforce_eagerFalse actor_rollout_ref.rollout.free_cache_engineTrue类似组合还出现在 run_qwen2_5_32b_fsdp.sh、run_glm4_1v_9b_fsdp.sh、run_qwen3_5_27b_fsdp.sh 等脚本中。这些示例的完整启动方式均为python3 -m verl.trainer.main_ppo \ algorithm.adv_estimatorgrpo \ data.train_files... \ actor_rollout_ref.model.path... \ actor_rollout_ref.rollout.namevllm \ actor_rollout_ref.rollout.enforce_eagerFalse \ actor_rollout_ref.rollout.free_cache_engineTrue \ trainer.n_gpus_per_node8 \ ...同时需要注意个别场景的例外例如 run_minicpm_o_2_6_fsdp.sh 中多模态模型将free_cache_engine设为Falserun_deepseek_v3_671b_megatron.sh 中 MoE 大模型将enforce_eager设为True。这说明配置应根据模型类型与显存情况灵活调整多模态或多专家模型对显存/引擎行为有特殊要求时需要关闭 CUDA Graph 或关闭缓存释放。提示vLLM 0.8.2 曾存在 MoE 模型权重加载 bugverl 在 verl/utils/vllm/patch.py 中实现了patch_vllm_moe_model_weight_loader作为 workaround为缺失weight_loader的 MoE 权重补充加载逻辑这也解释了为何示例脚本中对 MoE 模型常需调整引擎配置。4. 升级后常见问题排查4.1 问题现象直接从 vllm0.8 升级到 vllm0.8 后部分依赖包版本可能发生变化从而引入以下运行时报错in module from torch.multiprocessing.reductions import ForkingPickler ImportError: cannot import name ForkingPickler from torch.multiprocessing.reductions (/opt/conda/lib/python3.11/site-packages/torch/multiprocessing/reductions.py)4.2 原因与解决方案该报错说明某个依赖仍在尝试从torch.multiprocessing.reductions导入旧版 torch 中才有的ForkingPickler。vLLM 0.8 升级会连带更新若干依赖包而旧版本的tensordictverl 在数据传输与 rollout 中使用的库与新版 torch 不兼容。解决方案将tensordict升级到 0.6.2。pip install tensordict0.6.2升级后ForkingPickler的导入路径问题即告解决。4.3 进一步定位思路若未来遇到其他依赖不兼容问题可以从以下方向入手查看 requirements.txt、requirements-test.txt 与 uv.lock 中锁定的依赖版本确认与当前 torch/vLLM 组合的兼容性关注 verl/utils/vllm/patch.py 中已有的版本兼容补丁参考其处理模式自行排查在 verl/workers/rollout/vllm_rollout/vllm_async_server.py 中搜索_VLLM_VERSION的版本分支逻辑了解 verl 对 vLLM 各版本差异的处理方式。5. 完整配置速查表将上文涉及的配置汇总如下便于直接对照使用配置项 / 命令推荐值说明python版本3.10conda 环境创建时指定vllm版本0.8.3文档验证过的稳定版flash-attn--no-build-isolation安装在现有 PyTorch 环境内编译actor_rollout_ref.rollout.enforce_eagerFalse启用 CUDA Graph默认即 Falseactor_rollout_ref.rollout.free_cache_engineTrue权重同步期间释放 KV Cache默认即 TrueVLLM_USE_V11移除vLLM 0.8 默认 V1 引擎无需显式设置tensordict0.6.2修复ForkingPickler导入错误6. 总结verl 升级到 vLLM 0.8 的要点可概括为三步装环境按官方流程安装 verlpip3 install -e .与 vLLM 0.8.3或直接使用预构建 Docker 镜像改配置在启动脚本中添加enforce_eagerFalse与free_cache_engineTrue并移除VLLM_USE_V1环境变量以充分发挥 CUDA Graph 与 V1 引擎的性能优势修依赖若遇到ForkingPickler导入错误将tensordict升级到0.6.2。在仓库中这两个配置项从 verl/trainer/config/rollout/rollout.yaml 的定义到 verl/workers/config/rollout.py 的数据类承载再到 verl/workers/rollout/vllm_rollout/vllm_async_server.py 与 vllm_rollout.py 中的实际消费形成了一条完整的配置链路。理解这条链路后你便可以根据模型类型MoE、多模态与显存约束灵活调整 CUDA Graph 与 KV Cache 释放策略在 verl vLLM 0.8 组合上获得稳定且高性能的 RL 后训练体验。【免费下载链接】verlverl/HybridFlow: A Flexible and Efficient RL Post-Training Framework项目地址: https://gitcode.com/GitHub_Trending/ve/verl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 verl 升级指南：在 vLLM 0.8+ 上启用 CUDA Graph 与 V1 引擎进行 RL 后训练
verl 升级指南在 vLLM 0.8 上启用 CUDA Graph 与 V1 引擎进行 RL 后训练【免费下载链接】verlverl/HybridFlow: A Flexible and Efficient RL Post-Training Framework项目地址: https://gitcode.com/GitHub_Trending/ve/verl导读本文以 docs/README_vllm0.8.md 为主体讲解 verlHybridFlow一款灵活高效的 RL 后训练框架如何升级并运行在 vLLM 0.8 上包括环境安装、Docker 镜像导入、开启 CUDA Graph 与 V1 引擎所需的两个关键配置项以及升级过程中常见依赖冲突如ForkingPickler导入失败的排查与修复。读完本文你将能够在 verl vLLM 0.8 组合下完整跑通训练并对相关配置项的底层实现形成源码级认识。1. 升级背景vLLM 0.8 带来了什么vLLM 0.8 系列是 vLLM 引擎的重要迭代版本。在 verl 中vLLM 0.8 默认启用两大特性CUDA Graph将解码阶段的 GPU kernel 执行图预先捕获并复用显著降低 kernel 启动开销提升 rollout 吞吐V1 EnginevLLM 新一代调度引擎重构了批处理与调度路径带来更低的调度延迟与更好的并发表现。需要特别说明的是此版本组合下 verl 采用FSDP 做训练、vLLM 做 rollout采样生成的分工架构即训练与推理由不同组件负责这也是 verl 中常见的 actorFSDP 训练与 rolloutvLLM 推理分离模式。从源码看vLLM 的版本适配逻辑集中在 verl/workers/rollout/vllm_rollout/vllm_async_server.py其开头通过_VLLM_VERSION version.parse(vllm.__version__)第 74 行对 vLLM 版本进行解析并在后续多处按版本分支处理不同 API 行为例如第 356 行判断 vLLM 0.13.0 时改用 CLI 参数方式传递 profiler 配置可见 verl 对 vLLM 各版本保持着细粒度的兼容处理。2. 安装步骤2.1 从源码安装 verl 与 vLLM官方推荐的安装流程如下# 创建 conda 环境Python 3.10 conda create -n verl python3.10 conda activate verl # 克隆并安装 verl git clone https://github.com/verl-project/verl.git cd verl pip3 install -e . # 安装 vLLM 0.8 系列的最新稳定版 pip3 install vllm0.8.3 # 安装 flash-attn注意使用 --no-build-isolation pip3 install flash-attn --no-build-isolation几点说明pip3 install -e .以可编辑模式安装 verl便于开发调试verl 的完整依赖清单见 requirements.txtNPU 场景则使用 requirements-npu.txtvLLM 版本固定为0.8.3这是该文档编写时验证过的稳定版本flash-attn 使用--no-build-isolation是为了让其在已安装的 PyTorch 编译环境中完成构建避免隔离环境导致的编译失败。2.2 使用预构建 Docker 镜像推荐verl 团队提供了 verl vLLM 0.8.3 的预构建镜像可直接导入使用无需手动安装依赖docker pull hiyouga/verl:ngc-th2.6.0-cu126-vllm0.8.3-flashinfer0.2.2-cxx11abi0从镜像 tag 可以看出其组成NGC 基础镜像 PyTorch 2.6.0 CUDA 12.6 vLLM 0.8.3 FlashInfer 0.2.2 CXX11 ABI 0适用于典型 GPU 训练环境。仓库内另有完整的 Docker 构建体系可参考 docker/README.md 以及 docker/verl0.4-cu124-torch2.6-fa2.7.4/Dockerfile.app.vllm.mcore0.12 等应用镜像文件按需构建其他版本的组合镜像。3. 启用 CUDA Graph 与 V1 引擎的关键配置3.1 两行必须添加的配置升级到 vLLM 0.8 后verl 默认启用 CUDA Graph 与 V1 引擎。要在训练脚本中显式开启这两个特性需要在启动命令中追加以下两个参数actor_rollout_ref.rollout.enforce_eagerFalse \ actor_rollout_ref.rollout.free_cache_engineTrue \这两个参数的含义分别如下参数值作用actor_rollout_ref.rollout.enforce_eagerFalse关闭 eager 模式允许 vLLM 使用 CUDA Graph 加速解码actor_rollout_ref.rollout.free_cache_engineTrue在权重同步期间释放推理引擎的 KV Cache训练/推理切换时回收显存3.2 必须移除的环境变量同时如果脚本中原本存在以下环境变量需要删除export VLLM_USE_V11原因在于vLLM 0.8 中 V1 引擎已是默认显式设置该变量不仅多余还可能干扰 verl 对引擎行为的默认管理。仓库中 verl/experimental/fully_async_policy/shell/runtime_env.yaml 等旧配置里仍保留VLLM_USE_V1: 1的写法属于历史遗留而 verl/trainer/main_generation_server.py 等较新入口已不再依赖该变量由 vLLM 版本本身决定引擎行为。3.3 配置项的源码级解析enforce_eagerCUDA Graph 的开关在 verl/trainer/config/rollout/rollout.yaml 中该参数注释为「Whether to disable CUDA graph. Default False to best performance.」即默认False以换取最佳性能。其底层传递逻辑位于 verl/workers/rollout/vllm_rollout/vllm_async_server.py构造 vLLM AsyncEngine 参数时直接将enforce_eager: self.config.enforce_eager传入引擎。当enforce_eagerFalse时vLLM 捕获 CUDA Graph 并复用于解码阶段从而减少 kernel 启动开销。对应的配置类定义在 verl/workers/config/rollout.py其中还包含关联参数cudagraph_capture_sizesCUDA Graph 捕获批大小列表需在enforce_eagerFalse下使用。该参数在 vllm_async_server.py 中被写入compilation_config[cudagraph_capture_sizes]并进一步设置cudagraph_mode为FULL_AND_PIECEWISE当启用解码上下文并行DCP时代码会自动降级为PIECEWISE模式见第 310-318 行以规避 FULL 模式与 DCP 的兼容问题。free_cache_engine训练/推理切换的显存管理该参数默认值为True见 rollout.yaml。它的核心用途是RL 训练中 rollout 引擎与 actor 训练交替进行权重同步update_weights期间需要把显存从 KV Cache 腾给权重更新使用。在 verl/workers/rollout/vllm_rollout/vllm_async_server.py 中可以看到一组配套方法sleep()将引擎休眠、释放 KV Cache 显存第 854-863 行仅在node_rank 0且free_cache_engineTrue时执行release_kv_cache()/resume_kv_cache()分别在权重同步前释放 KV Cache、同步后恢复第 876-893 行同样受该开关控制clear_kv_cache()在权重更新完成后清理前缀缓存保证旧权重下的缓存不会污染新权重第 865-874 行。而在 verl/workers/rollout/vllm_rollout/vllm_rollout.py 中resume()/release()两个方法也会先判断self.config.free_cache_engine再决定是否执行wake_up/sleep从而在同步期间将 GPU 内存让出给权重传输。3.4 真实训练脚本中的用法仓库内大量真实示例脚本都遵循这一配置模式。以 examples/grpo_trainer/run_qwen3_4b_fsdp.sh 为例actor_rollout_ref.rollout.enforce_eagerFalse actor_rollout_ref.rollout.free_cache_engineTrue类似组合还出现在 run_qwen2_5_32b_fsdp.sh、run_glm4_1v_9b_fsdp.sh、run_qwen3_5_27b_fsdp.sh 等脚本中。这些示例的完整启动方式均为python3 -m verl.trainer.main_ppo \ algorithm.adv_estimatorgrpo \ data.train_files... \ actor_rollout_ref.model.path... \ actor_rollout_ref.rollout.namevllm \ actor_rollout_ref.rollout.enforce_eagerFalse \ actor_rollout_ref.rollout.free_cache_engineTrue \ trainer.n_gpus_per_node8 \ ...同时需要注意个别场景的例外例如 run_minicpm_o_2_6_fsdp.sh 中多模态模型将free_cache_engine设为Falserun_deepseek_v3_671b_megatron.sh 中 MoE 大模型将enforce_eager设为True。这说明配置应根据模型类型与显存情况灵活调整多模态或多专家模型对显存/引擎行为有特殊要求时需要关闭 CUDA Graph 或关闭缓存释放。提示vLLM 0.8.2 曾存在 MoE 模型权重加载 bugverl 在 verl/utils/vllm/patch.py 中实现了patch_vllm_moe_model_weight_loader作为 workaround为缺失weight_loader的 MoE 权重补充加载逻辑这也解释了为何示例脚本中对 MoE 模型常需调整引擎配置。4. 升级后常见问题排查4.1 问题现象直接从 vllm0.8 升级到 vllm0.8 后部分依赖包版本可能发生变化从而引入以下运行时报错in module from torch.multiprocessing.reductions import ForkingPickler ImportError: cannot import name ForkingPickler from torch.multiprocessing.reductions (/opt/conda/lib/python3.11/site-packages/torch/multiprocessing/reductions.py)4.2 原因与解决方案该报错说明某个依赖仍在尝试从torch.multiprocessing.reductions导入旧版 torch 中才有的ForkingPickler。vLLM 0.8 升级会连带更新若干依赖包而旧版本的tensordictverl 在数据传输与 rollout 中使用的库与新版 torch 不兼容。解决方案将tensordict升级到 0.6.2。pip install tensordict0.6.2升级后ForkingPickler的导入路径问题即告解决。4.3 进一步定位思路若未来遇到其他依赖不兼容问题可以从以下方向入手查看 requirements.txt、requirements-test.txt 与 uv.lock 中锁定的依赖版本确认与当前 torch/vLLM 组合的兼容性关注 verl/utils/vllm/patch.py 中已有的版本兼容补丁参考其处理模式自行排查在 verl/workers/rollout/vllm_rollout/vllm_async_server.py 中搜索_VLLM_VERSION的版本分支逻辑了解 verl 对 vLLM 各版本差异的处理方式。5. 完整配置速查表将上文涉及的配置汇总如下便于直接对照使用配置项 / 命令推荐值说明python版本3.10conda 环境创建时指定vllm版本0.8.3文档验证过的稳定版flash-attn--no-build-isolation安装在现有 PyTorch 环境内编译actor_rollout_ref.rollout.enforce_eagerFalse启用 CUDA Graph默认即 Falseactor_rollout_ref.rollout.free_cache_engineTrue权重同步期间释放 KV Cache默认即 TrueVLLM_USE_V11移除vLLM 0.8 默认 V1 引擎无需显式设置tensordict0.6.2修复ForkingPickler导入错误6. 总结verl 升级到 vLLM 0.8 的要点可概括为三步装环境按官方流程安装 verlpip3 install -e .与 vLLM 0.8.3或直接使用预构建 Docker 镜像改配置在启动脚本中添加enforce_eagerFalse与free_cache_engineTrue并移除VLLM_USE_V1环境变量以充分发挥 CUDA Graph 与 V1 引擎的性能优势修依赖若遇到ForkingPickler导入错误将tensordict升级到0.6.2。在仓库中这两个配置项从 verl/trainer/config/rollout/rollout.yaml 的定义到 verl/workers/config/rollout.py 的数据类承载再到 verl/workers/rollout/vllm_rollout/vllm_async_server.py 与 vllm_rollout.py 中的实际消费形成了一条完整的配置链路。理解这条链路后你便可以根据模型类型MoE、多模态与显存约束灵活调整 CUDA Graph 与 KV Cache 释放策略在 verl vLLM 0.8 组合上获得稳定且高性能的 RL 后训练体验。【免费下载链接】verlverl/HybridFlow: A Flexible and Efficient RL Post-Training Framework项目地址: https://gitcode.com/GitHub_Trending/ve/verl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考