一键部署verl：高效实现大模型后训练的保姆级教程

一键部署verl：高效实现大模型后训练的保姆级教程

1. 引言

1.1 大模型后训练的挑战与需求

随着大型语言模型（LLMs）在自然语言理解、代码生成、数学推理等任务中展现出强大能力，如何进一步提升其行为对齐性、逻辑一致性与任务表现，已成为工业界和学术界的共同关注点。传统的监督微调（SFT）已难以满足复杂场景下的精细化控制需求，而基于人类反馈的强化学习（RLHF）及其变体（如 RLAIF、GRPO）则成为主流的后训练范式。

然而，RLHF 类训练流程复杂，涉及多个阶段：策略采样（rollout）、奖励计算、优势估计、策略更新等，且各阶段对计算资源的需求差异巨大——推理阶段需要高吞吐的生成引擎，训练阶段则依赖高效的分布式训练框架。这种异构性导致传统系统在执行效率、资源利用率和扩展性方面面临严峻挑战。

1.2 verl 的定位与核心价值

verl是由字节跳动火山引擎团队开源的一款专为 LLM 后训练设计的强化学习框架，是其HybridFlow 论文的官方实现。它旨在解决 RLHF 流程中的两大核心问题：

• 灵活性：支持灵活定义复杂的 RL 数据流（DataFlow），便于实现 PPO、GRPO、OPO 等多种算法。
• 高效性：通过与 vLLM、SGLang、FSDP、Megatron-LM 等 SOTA 推理与训练框架深度集成，结合创新的3D-HybridEngine技术，在多 GPU 集群上实现极高的训练吞吐。

据官方论文实验表明，verl 在多种 RLHF 算法上相较现有系统可实现1.53×–20.57× 的吞吐提升，显著降低训练成本，具备良好的生产环境适用性。

本教程将带你从零开始，手把手完成 verl 框架的一键部署，并以 GRPO 算法为例，完整走通一次大模型后训练流程，涵盖环境准备、配置解析、训练执行与结果验证等关键环节。

2. verl 核心架构与技术原理

2.1 整体架构概览

verl 采用分层解耦的设计思想，将整个 RL 训练流程划分为多个独立但协同工作的模块，形成清晰的技术栈结构：

[Configs/Launcher] │ ▼ [Trainer 主循环] ── 调 Ray & HybridFlow → 安排任务图 │ ├── 用 [Rollout Engine: vLLM/SGLang] 生成轨迹 ├── 调 [Reward] 计算奖励 ├── 调 [Algorithms] 做优势/损失（PPO/GRPO…） └── 用 [Training Engine: FSDP/Megatron] 反向更新

该架构实现了“算法逻辑”与“分布式执行”的分离，用户只需关注数据流的构建，底层调度由 Ray 和 HybridFlow 自动完成。

2.2 核心设计一：HybridFlow 编程范式

HybridFlow 是 verl 的编程模型基础，融合了单控制器（flexibility）与多控制器（efficiency）的优点：

• 单控制器模式：用于高层任务编排，允许用户像写脚本一样灵活定义 RL 步骤顺序。
• 多控制器模式：在底层并行执行单元中启用，确保高并发下的执行效率。

通过这种混合控制方式，verl 既能支持复杂的条件分支、循环结构，又能保证在大规模集群上的高性能执行。

2.3 核心设计二：3D-HybridEngine

这是 verl 实现高性能的关键所在。在 RL 训练过程中，actor 模型需在“生成”与“训练”两个阶段间频繁切换，传统做法会导致显存冗余和大量通信开销。

3D-HybridEngine通过以下机制优化这一过程：

• 动态重分片（Resharding）：根据当前阶段自动调整模型的并行策略（如 Tensor Parallelism、Data Parallelism），避免不必要的参数复制。
• 显存复用：在阶段切换时复用已有缓存，减少内存分配与释放开销。
• 通信优化：利用预通信（pre-communication）和流水线技术，隐藏部分通信延迟。

实验证明，该机制可显著降低 actor 模型在 rollout 与 training 之间的切换延迟，提升整体吞吐。

2.4 支持的算法与后端引擎

此外，verl 还支持 Agentic RL 场景下的多轮对话、工具调用与异步 rollout，适用于更复杂的智能体训练任务。

3. 环境准备与一键部署

3.1 部署方式选择

verl 提供两种主要部署方式：

• Docker 镜像部署（推荐）：使用预构建镜像，省去依赖安装烦恼，适合快速验证。
• 源码安装：适用于定制化开发或特定环境适配。

本文推荐使用 Docker 方式进行一键部署。

3.2 使用 Docker 镜像启动 verl 环境

官方提供了基于 NGC（NVIDIA GPU Cloud）优化的 Docker 镜像，集成了 verl 及其依赖组件（包括 vLLM、FlashInfer 等）。

拉取镜像命令：

docker pull hiyouga/verl:ngc-th2.6.0-cu126-vllm0.8.4-flashinfer0.2.2-cxx11abi0

启动容器：

nvidia-docker run -it --shm-size=1g \ -v $HOME/data:/root/data \ -v $HOME/output:/root/output \ hiyouga/verl:ngc-th2.6.0-cu126-vllm0.8.4-flashinfer0.2.2-cxx11abi0 /bin/bash

说明：

• --shm-size=1g：防止 Ray 因共享内存不足报错。
• -v参数挂载本地数据与输出目录，便于持久化训练结果。

3.3 验证安装是否成功

进入容器后，执行以下 Python 命令验证 verl 是否正确安装：

import verl print(verl.__version__)

若输出版本号（如0.1.0），则表示安装成功。

4. GRPO 算法详解与训练实践

4.1 什么是 GRPO？

Group Relative Policy Optimization (GRPO) 是一种无需 critic 网络的强化学习算法，特别适用于数学推理、代码生成等可通过明确规则打分的任务。

传统 PPO 的局限：

• 需要额外训练一个 value network（critic）来估计状态价值。
• critic 训练不稳定，增加调试难度和计算开销。

GRPO 的核心思想：

• 组采样（Group Sampling）：对每个 prompt 并行生成 N 条响应，构成一个“候选组”。
• 相对打分（Relative Scoring）：计算每条响应的奖励得分（如 GSM8K 中的答案正确性）。
• 组内归一（Within-group Normalization）：以组内平均奖励作为基线，优势值 = 个体奖励 - 组平均。
• 策略更新：仅更新 actor 网络，使用 KL 正则防止偏离参考策略。

这种方式省去了 critic 训练，简化了流程，同时保持了稳定的收敛性。

4.2 GRPO 训练脚本详解

以下是一个基于 Qwen3-8B 模型在 GSM8K 数据集上进行 GRPO 训练的完整脚本示例：

set -x python3 -m verl.trainer.main_ppo \ algorithm.adv_estimator=grpo \ data.train_files=$HOME/data/gsm8k/train.parquet \ data.val_files=$HOME/data/gsm8k/test.parquet \ data.train_batch_size=1024 \ data.max_prompt_length=512 \ data.max_response_length=1024 \ data.filter_overlong_prompts=True \ data.truncation='error' \ actor_rollout_ref.model.path=Qwen/Qwen3-8B \ actor_rollout_ref.actor.optim.lr=1e-6 \ actor_rollout_ref.model.use_remove_padding=True \ actor_rollout_ref.actor.ppo_mini_batch_size=256 \ actor_rollout_ref.actor.ppo_micro_batch_size_per_gpu=32 \ actor_rollout_ref.actor.use_kl_loss=True \ actor_rollout_ref.actor.kl_loss_coef=0.001 \ actor_rollout_ref.actor.kl_loss_type=low_var_kl \ actor_rollout_ref.actor.entropy_coeff=0 \ actor_rollout_ref.model.enable_gradient_checkpointing=True \ actor_rollout_ref.actor.fsdp_config.param_offload=False \ actor_rollout_ref.actor.fsdp_config.optimizer_offload=False \ actor_rollout_ref.rollout.log_prob_micro_batch_size_per_gpu=32 \ actor_rollout_ref.rollout.tensor_model_parallel_size=2 \ actor_rollout_ref.rollout.name=vllm \ actor_rollout_ref.rollout.gpu_memory_utilization=0.6 \ actor_rollout_ref.rollout.n=5 \ actor_rollout_ref.ref.log_prob_micro_batch_size_per_gpu=32 \ actor_rollout_ref.ref.fsdp_config.param_offload=True \ algorithm.use_kl_in_reward=False \ trainer.critic_warmup=0 \ trainer.logger='["console","wandb"]' \ trainer.project_name='verl_grpo_example_gsm8k' \ trainer.experiment_name='qwen3_8b_function_rm' \ trainer.n_gpus_per_node=8 \ trainer.nnodes=1 \ trainer.save_freq=20 \ trainer.test_freq=5 \ trainer.total_epochs=15 $@

4.3 关键参数解析

4.4 数据格式要求

verl 要求输入数据为 Parquet 格式，字段如下：

{ "prompt": "What is 2 + 2?", "chosen": "4" }

对于 GRPO，无需提供chosen字段，系统会自动生成多条 response 并打分。

可使用 HuggingFace Datasets 工具转换原始 JSON 数据为 Parquet：

from datasets import Dataset dataset = Dataset.from_json("gsm8k_train.json") dataset.to_parquet("train.parquet")

5. 常见问题与调优建议

5.1 内存溢出（OOM）处理

当出现 OOM 错误时，优先调整以下 micro batch 参数：

• actor_rollout_ref.actor.ppo_micro_batch_size_per_gpu
• actor_rollout_ref.rollout.log_prob_micro_batch_size_per_gpu
• data.max_prompt_length/max_response_length

建议逐步减半，直到运行稳定。

5.2 Ray 启动失败：Socket 监听错误

报错信息示例：

RuntimeError: The server socket has failed to listen on any local network address.port: 20014

解决方案：

• 设置不同的 Ray 临时目录：

  export RAY_TEMP_DIR=/tmp/ray ray stop && ray start --head

• 或修改端口范围：

  ray start --head --port=20015 --node-manager-port=20016

5.3 性能调优建议

6. 总结

verl 作为一款面向生产环境的大模型后训练框架，凭借其HybridFlow 编程模型和3D-HybridEngine 执行引擎，在灵活性与性能之间取得了优异平衡。无论是 PPO 还是 GRPO，都能通过简洁的配置文件快速启动训练任务。

本文详细介绍了 verl 的核心架构、一键部署方法，并以 GRPO 为例展示了完整的训练流程与参数调优技巧。通过 Docker 镜像部署，开发者可在几分钟内搭建起高效的 RL 训练环境，大幅降低入门门槛。

未来，随着 Agentic AI 和复杂任务链路的发展，verl 在多工具调用、长程规划等场景中的应用潜力将进一步释放。建议读者结合自身业务需求，尝试将其应用于实际项目中。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。