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：Critic モデルを使った PPO

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

GRPO との主な違い

• 独立した critic モデルが必要です
• 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

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	1 つを除外したベースライン
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 のメモリ不足が発生する

解決方法：

# 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 トレーニング

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 など）
• コミュニティ: Slack の verl-project

エージェントの作業手順

1. 環境を確認します。 GPU の種類、メモリ、ドライバー／CUDA のバージョン（nvidia-smi）、フレームワークのバージョン、データセットの場所とサイズを確認します。
2. 入力を確定します。 データまたはユーザーからフォーマット、識別子、パラメーターを確認します。結果に影響する値は推測せず、質問してください。
3. まず小規模に実行します。 スモークテストとして、小さなモデルまたはサブセットを使い、少ないステップ数で実行して、損失が減少し、チェックポイントが保存されることを確認します。
4. 上記の手順と参考情報を使って、タスク全体を実行します。
5. 結果を検証します。 保留データでメトリクスを追跡し、ベースラインと比較して、シード、設定、ハードウェアを記録します。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した項目、未確認の事項を明記します。

発生した問題	対応方法
CUDA のメモリ不足	バッチサイズを小さくする、勾配累積／チェックポインティングまたは混合精度を有効にする、あるいはモデルをシャーディングします。
損失が NaN になる、または発散する	学習率を下げ、データに無効な値がないか確認し、勾配クリッピングを有効にします。
これらの手順に記載された関数、フラグ、エンドポイントがインストール済みバージョンに存在しない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認して適宜対応し、ユーザーに伝えます。API を捏造してはいけません。
必須の入力、識別子、パラメーターが曖昧	ユーザーに質問するか、実行前に仮定を明示します。

誠実性に関するルール

• 結果、パラメーター、識別子、引用、統計情報を決して捏造しないでください。実行または検証できない場合は、その旨を明確に伝えてください。
• ログなしに学習結果を主張してはいけません。大規模なジョブを開始する前に、計算コストを見積もってください。
• ここに記載されているバージョン固有の詳細は古くなっている可能性があるため、インストール済みバージョンの公式ドキュメントで確認してください。
• 費用が発生する、共有 GPU やクラウドのクォータを消費する、個人データまたは患者データに触れる、または取り消せない操作を行う前に、許可を求めてください。

関連スキル

• fine-tuning-with-trl: TRL を使って強化学習で LLM をファインチューニングします。指示チューニング用の SFT、選好アラインメント用の DPO、報酬最適化用の PPO／GRPO…
• slime-rl-training: Megatron+SGLang フレームワークの slime を使った、LLM の RL によるポストトレーニングのガイダンスを提供します。
• openrlhf-training: Ray+vLLM アクセラレーションを備えた高性能な RLHF フレームワークです。