verl-rl-training

verl: LLM 向けの Volcano Engine 強化学習

verl は、ByteDance の Seed チームによる、大規模言語モデル向けの柔軟で効率的かつ本番環境対応の RL 学習ライブラリです。HybridFlow フレームワーク（EuroSys 2025）を実装しており、数学ベンチマークで O1 レベルの性能を達成した Doubao-1.5-pro などのモデルを支えています。

verl を使うべき場面

verl を選ぶべき場合:

• 大規模な本番環境向けの RL 学習が必要（最大 671B パラメータまでテスト済み）
• バックエンドを柔軟に切り替えたい（FSDP ↔ Megatron-LM ↔ vLLM ↔ SGLang）
• 複数の RL アルゴリズム（PPO、GRPO、RLOO、REINFORCE++、DAPO）をサポートしたい
• エージェント向けワークフローのために、ツール呼び出しを伴うマルチターンのロールアウトが必要
• ビジョン言語モデルの RL 学習を行いたい

代替手段を検討すべき場合:

• Megatron ネイティブの学習が必要 → slime または miles を使用
• Monarch を使った PyTorch ネイティブの抽象化を求める → torchforge を使用
• 単純な SFT/DPO のみが必要 → TRL または Axolotl を使用

主な機能

• 学習バックエンド: FSDP、FSDP2、Megatron-LM
• ロールアウトエンジン: 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 を備えた GPU クラスター（H100 推奨）
• prompt 列と reward_model 列を持つ parquet 形式のデータセット
• 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: クリティックモデルを用いた PPO

価値ベースのアドバンテージ推定（GAE）が必要な場合にこのワークフローを使用します。

GRPO との主な違い

• 別個のクリティックモデルが必要
• Generalized Advantage Estimation（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

クリティックを使った起動

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 ブリッジをインストールする: 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	クリティック不要、数学・推論向け
PPO/GAE	gae	密な報酬、価値推定
REINFORCE++	reinforce_plus_plus	分散の低減
RLOO	rloo	Leave-one-out ベースライン
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

---

よくある問題と解決策

問題: ロールアウト中の OOM

症状: 生成フェーズで CUDA out of memory が発生する

解決策:

# 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

問題: 重み同期の遅延

症状: ロールアウトと学習の間で長い停止が発生する

解決策:

# 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)

---

高度なトピック

マルチターンのツール呼び出し

ツールを使うエージェント向けワークフローについては references/multi-turn.md を参照してください。

ビジョン言語モデル

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

LoRA Training

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

---

Resources

• Documentation: https://verl.readthedocs.io/
• Paper: https://arxiv.org/abs/2409.19256
• GitHub: https://github.com/volcengine/verl
• Recipes: https://github.com/verl-project/verl-recipe (DAPO, GSPO, etc.)
• Community: Slack at verl-project