verl-rl-training

verl：用于 LLM 的 Volcano Engine 强化学习

verl 是 ByteDance Seed 团队为大语言模型打造的灵活、高效且可用于生产环境的 RL 训练库。它实现了 HybridFlow 框架（EuroSys 2025），并为 Doubao-1.5-pro 等模型提供支持，使其在数学基准测试中达到 O1 级别的表现。

何时使用 verl

在以下情况下选择 verl：

• 需要可用于生产环境的大规模 RL 训练（已测试至 671B 参数）
• 需要灵活切换后端（FSDP ↔ Megatron-LM ↔ vLLM ↔ SGLang）
• 需要支持多种 RL 算法（PPO、GRPO、RLOO、REINFORCE++、DAPO）
• 需要为 Agent 工作流提供带工具调用的多轮 rollout
• 需要进行视觉语言模型 RL 训练

以下情况可考虑其他方案：

• 需要原生 Megatron 训练 → 使用 slime 或 miles
• 希望使用基于 Monarch 的 PyTorch 原生抽象 → 使用 torchforge
• 只需要简单的 SFT/DPO → 使用 TRL 或 Axolotl

主要功能

• 训练后端：FSDP、FSDP2、Megatron-LM
• Rollout 引擎：vLLM、SGLang、HuggingFace Transformers
• 算法：PPO、GRPO、DAPO、RLOO、ReMax、REINFORCE++、SPIN、SPPO
• 模型：Qwen-3、Llama-3.1、DeepSeek、Gemma-2（0.5B 至 671B）
• 高级功能：LoRA RL、序列并行、专家并行、多轮工具调用

安装

# Option 1: pip install
pip install verl[vllm]  # or verl[sglang] for SGLang backend

# Option 2: Docker (recommended for production)
docker pull verlai/verl:vllm011.latest

# Option 3: From source
git clone https://github.com/volcengine/verl.git
cd verl && pip install -e .[vllm,math]

快速开始：GRPO 训练

python3 -m verl.trainer.main_ppo \
    algorithm.adv_estimator=grpo \
    data.train_files=~/data/gsm8k/train.parquet \
    actor_rollout_ref.model.path=Qwen/Qwen2.5-7B \
    actor_rollout_ref.rollout.n=8 \
    actor_rollout_ref.actor.use_kl_loss=True \
    trainer.n_gpus_per_node=8

核心架构

verl 使用 HybridFlow 编程模型，将控制流与计算分离：

┌─────────────────────────────────────────────────────────┐
│ Single-Process Controller (Ray)                         │
│ - Orchestrates: rollout → reward → train → sync        │
└─────────────────────┬───────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────┐
│ Multi-Process Workers                                   │
│ ├── ActorRolloutRefWorker (policy + generation)        │
│ ├── CriticWorker (value estimation, PPO only)          │
│ └── RewardManager (model-based or rule-based rewards)  │
└─────────────────────────────────────────────────────────┘

---

工作流 1：使用 GRPO 进行数学推理训练

在 GSM8K 或 MATH 等数学任务上训练推理模型时，使用此工作流。

前置条件清单

• 配备 8 张或更多 GPU 的集群（推荐 H100）
• parquet 格式的数据集，包含 prompt 和 reward_model 列
• 来自 HuggingFace Hub 的基础模型

步骤 1：准备数据集

import pandas as pd

data = [
    {
        "prompt": [{"role": "user", "content": "What is 15 + 27?"}],
        "reward_model": {"ground_truth": "42"}
    },
    # ... more examples
]
df = pd.DataFrame(data)
df.to_parquet("train.parquet")

步骤 2：定义奖励函数

# reward_function.py
import re

def compute_reward(responses, ground_truths):
    rewards = []
    for response, gt in zip(responses, ground_truths):
        # Extract answer from response
        match = re.search(r'\\boxed{([^}]+)}', response)
        if match and match.group(1).strip() == gt.strip():
            rewards.append(1.0)
        else:
            rewards.append(0.0)
    return rewards

步骤 3：创建训练配置

# config/grpo_math.yaml
algorithm:
  adv_estimator: grpo
  gamma: 1.0
  lam: 1.0

data:
  train_files: /path/to/train.parquet
  val_files: /path/to/val.parquet
  train_batch_size: 256
  max_prompt_length: 512
  max_response_length: 2048

actor_rollout_ref:
  model:
    path: Qwen/Qwen2.5-7B-Instruct
  actor:
    use_kl_loss: true
    kl_loss_coef: 0.001
    ppo_mini_batch_size: 64
  rollout:
    name: vllm
    n: 8  # samples per prompt
    temperature: 0.7
    top_p: 0.95

trainer:
  total_epochs: 3
  n_gpus_per_node: 8
  save_freq: 100

步骤 4：启动训练

python3 -m verl.trainer.main_ppo \
    --config-path config \
    --config-name grpo_math \
    trainer.experiment_name=grpo_math_qwen7b

步骤 5：监控并验证

• 在 WandB/TensorBoard 中检查损失曲线
• 确认奖励随训练步数增加而提升
• 在留出的测试集上运行评估

---

工作流 2：使用 Critic 模型进行 PPO 训练

需要基于价值的优势估计（GAE）时，使用此工作流。

与 GRPO 的主要区别

• 需要单独的 Critic 模型
• 使用广义优势估计（GAE）
• 更适合奖励密集的任务

配置

algorithm:
  adv_estimator: gae  # Use GAE instead of GRPO
  gamma: 0.99
  lam: 0.95

critic:
  model:
    path: Qwen/Qwen2.5-7B-Instruct  # Can be same or different from actor
  ppo_mini_batch_size: 64

actor_rollout_ref:
  actor:
    use_kl_loss: true
    kl_loss_coef: 0.02
    clip_ratio: 0.2  # PPO clipping

使用 Critic 启动训练

python3 -m verl.trainer.main_ppo \
    algorithm.adv_estimator=gae \
    critic.model.path=Qwen/Qwen2.5-7B-Instruct \
    trainer.n_gpus_per_node=8

---

工作流 3：使用 Megatron 进行大规模训练

训练参数量超过 70B 的模型或需要专家并行时，使用此工作流。

前置条件

• 安装 Megatron-LM bridge：pip install mbridge
• 将模型转换为 Megatron 格式
• 使用 NVLink/InfiniBand 的多节点集群

70B 及以上模型的配置

actor_rollout_ref:
  model:
    path: /path/to/megatron/checkpoint
    backend: megatron
  actor:
    strategy: megatron
    tensor_model_parallel_size: 8
    pipeline_model_parallel_size: 2
  rollout:
    name: vllm
    tensor_parallel_size: 8

启动多节点训练

# On head node
ray start --head --port=6379

# On worker nodes
ray start --address='head_ip:6379'

# Launch training
python3 -m verl.trainer.main_ppo \
    trainer.nnodes=4 \
    trainer.n_gpus_per_node=8

---

配置参考

算法选择

算法	adv_estimator	适用场景
GRPO	grpo	无需 Critic，适用于数学/推理任务
PPO/GAE	gae	奖励密集、价值估计
REINFORCE++	reinforce_plus_plus	降低方差
RLOO	rloo	留一法基线
ReMax	remax	最大奖励基线
OPO	opo	最优策略优化

关键参数

# Rollout parameters
actor_rollout_ref.rollout.n: 8              # Samples per prompt
actor_rollout_ref.rollout.temperature: 0.7  # Sampling temperature
actor_rollout_ref.rollout.top_p: 0.95       # Nucleus sampling

# Training parameters
actor_rollout_ref.actor.lr: 1e-6            # Learning rate
actor_rollout_ref.actor.ppo_mini_batch_size: 64
actor_rollout_ref.actor.clip_ratio: 0.2     # PPO clip range

# KL control
actor_rollout_ref.actor.use_kl_loss: true
actor_rollout_ref.actor.kl_loss_coef: 0.001
algorithm.kl_ctrl.target_kl: 0.1            # For adaptive KL control

---

常见问题及解决方案

问题：Rollout 期间发生 OOM

症状：生成阶段出现 CUDA 内存不足

解决方案：

# Reduce batch size
actor_rollout_ref.rollout.log_prob_micro_batch_size: 4

# Enable gradient checkpointing
actor_rollout_ref.model.enable_gradient_checkpointing: true

# Use FSDP2 with CPU offloading
actor_rollout_ref.actor.strategy: fsdp2
actor_rollout_ref.actor.fsdp_config.offload_policy: true

问题：训练不稳定

症状：损失激增、奖励崩溃

解决方案：

# Reduce learning rate
actor_rollout_ref.actor.lr: 5e-7

# Increase KL penalty
actor_rollout_ref.actor.kl_loss_coef: 0.01

# Enable gradient clipping
actor_rollout_ref.actor.max_grad_norm: 1.0

问题：权重同步缓慢

症状：Rollout 与训练之间暂停时间过长

解决方案：

# Use FSDP2 for faster resharding
actor_rollout_ref.actor.strategy=fsdp2

# Enable async weight transfer
trainer.async_weight_update=true

问题：vLLM 版本不匹配

症状：导入错误或生成失败

解决方案：使用兼容版本：

pip install vllm>=0.8.5,<=0.12.0
# Avoid vLLM 0.7.x (known bugs)

---

高级主题

多轮工具调用

有关使用工具的 Agent 工作流，请参阅 references/multi-turn.md。

视觉语言模型

actor_rollout_ref:
  model:
    path: Qwen/Qwen2.5-VL-7B-Instruct
  rollout:
    name: vllm
    enable_vision: true

LoRA 训练

actor_rollout_ref:
  actor:
    lora:
      enabled: true
      r: 16
      alpha: 32
      target_modules: ["q_proj", "v_proj"]

---

资源

• 文档：https://verl.readthedocs.io/
• 论文：https://arxiv.org/abs/2409.19256
• GitHub：https://github.com/volcengine/verl
• 方案：https://github.com/verl-project/verl-recipe（DAPO、GSPO 等）
• 社区：verl-project 的 Slack

Agent 操作流程

1. 检查环境。 检查 GPU 类型、内存和驱动/CUDA 版本（nvidia-smi）、框架版本，以及数据集的位置和大小。
2. 明确输入。 根据数据或用户提供的信息确认格式、标识符和参数。对于任何会影响结果的值，不要猜测，应先询问。
3. 先运行小规模版本。 进行冒烟测试：使用小型模型或子集，运行少量步骤，并确认损失下降且检查点已保存。
4. 按照上述说明和参考资料执行完整任务。
5. 验证结果。 在留出数据上跟踪指标，与基线比较，并记录随机种子、配置和硬件。
6. 报告。 说明运行了什么（版本、命令、参数）、检查了什么，以及还有哪些不确定之处。

如果出现这种情况	请这样做
CUDA 显存不足	减小批次大小、启用梯度累积/检查点或混合精度，或者对模型进行分片。
损失为 NaN 或发散	降低学习率，检查数据是否含有无效值，并启用梯度裁剪。
当前安装版本中缺少这些说明里提到的函数、标志或端点	查阅已安装版本自己的文档（help()、--help、官方文档），调整做法，并告知用户。切勿编造 API。
必需的输入、标识符或参数不明确	询问用户，或在运行前明确说明所作的假设。

诚信准则

• 切勿编造结果、参数、标识符、引文或统计数据。如果无法运行或验证某项内容，请如实说明。
• 没有日志时，切勿声称取得了训练结果；启动大型任务前应估算计算成本。
• 此处与版本相关的细节可能已经过时：请对照已安装版本的官方文档进行确认。
• 对于会产生费用、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，必须先征得同意。

相关技能

• fine-tuning-with-trl：使用 TRL 通过强化学习微调大模型——用于指令微调的 SFT、用于偏好对齐的 DPO、用于奖励优化的 PPO/GRPO…
• slime-rl-training：提供使用 slime（一个 Megatron+SGLang 框架）进行大模型 RL 后训练的指导。
• openrlhf-training：高性能 RLHF 框架，使用 Ray+vLLM 加速。