EasyR1: veRL を視覚言語モデル向けに作り直したフォークの実力と境界
EasyR1: An Efficient, Scalable, Multi-Modality RL Training Framework based on veRL
ひと目でわかる
- これは何？
- EasyR1 は veRL をフォークし、Qwen2-VL 系の視覚言語モデルに対する GRPO/DAPO などの RL 訓練を 1 つの bash スクリプトで回せるようにしたフレームワークである。README から読み取れる範囲で、その仕組み、動かし方、見落としやすい制約を整理する。
- 誰に向いている？
- Qwen2.5-VL や Qwen3-VL のような視覚言語モデルに対して GRPO 系の RL を回したい研究チームには向いている。一方、テキスト専用モデルだけを扱う場合や、上流 veRL の機能追従を最優先する場合は、このフォークを選ぶ理由が薄い。
- 商用利用できる？
- できます。Apache-2.0 は寛容なライセンスで、著作権表示とライセンス表示を残せば、使用・改変・販売が可能です。
- 今もメンテナンスされている？
- されています。最後のコミットは 16 日前です。
- 何の言語で書かれている？
- 主に Python です（GitHub の言語統計による）。
回答はプロジェクトの GitHub データ（最終同期：2026年9月15日）と当サイトの分析に基づくもので、法的助言ではありません。
オープンソース詳細解説
EasyR1 が埋めようとしているのは veRL の視覚言語モデル対応の穴である
EasyR1 は hiyouga 氏による veRL のクリーンフォークで、ライセンスは Apache-2.0。README は冒頭で「a clean fork of the original veRL project to support vision language models」と述べており、目的は汎用の RL 訓練基盤を作ることではなく、veRL が苦手としていた視覚言語モデルの訓練経路を用意することにある。対象読者は、Qwen2-VL や Qwen2.5-VL、Qwen3-VL のようなモデルに対して GRPO 系の報酬最適化をかけたい研究開発者である。テキスト専用モデル（Llama3、Qwen2、Qwen2.5、Qwen3）と DeepSeek-R1 蒸留モデルも対象に含まれるが、フォークの存在理由はむしろ画像入力側にある。テキストだけを訓練するなら上流の veRL を直接使う方が追従コストは低い。EasyR1 を選ぶ判断は、画像とテキストが混在するデータセットを扱うかどうかで分かれる。
HybridEngine と vLLM の SPMD モードが訓練と生成を同じ GPU に載せる
README は効率と拡張性の根拠として HybridEngine（arXiv:2409.19256）と vLLM の SPMD モードを挙げている。RL 訓練では、方策モデルが応答を生成する推論フェーズと、その応答に対する報酬から勾配を計算する訓練フェーズが交互に走る。このとき推論エンジンと訓練エンジンを別々の GPU 群に置くと、重みの転送と待ち時間がそのままオーバーヘッドになる。HybridEngine はこの 2 つを同じデバイス上で切り替える設計で、vLLM の SPMD モードは各プロセスが同一のコードパスを実行しながら役割を分担する形をとる。EasyR1 自身はこの部分を再実装しておらず、上流 veRL の機構をそのまま引き継いでいる点は押さえておきたい。フォークの差分はモデル側の入力処理、具体的には画像トークンの扱いとデータセット形式に集中している。
対応アルゴリズムとデータセット形式の広さが実用上の差になる
README が列挙するアルゴリズムは GRPO、DAPO、Reinforce++、ReMax、RLOO、GSPO、CISPO の 7 つ。バージョン履歴を見ると v0.3.1 が Multi-modal DAPO、v0.3.2 が RL Baselines を掲げており、アルゴリズム追加が継続的に行われていることがわかる。データセットは README の表現では「Any text, vision-text dataset in a specific format」で、テキスト、画像テキスト、複数画像テキスト、テキスト画像混在の 4 種類の例が Hugging Face 上のデータセットとして示されている。訓練テクニックとしては padding-free training、LoRA 訓練、最新または最良チェックポイントからの再開、Wandb・SwanLab・Mlflow・Tensorboard による記録が挙がっている。ここで注意したいのは、LoRA が README 上で新機能として扱われており、後述するように適用範囲が限定されている可能性があることだ。
導入は Docker イメージの取得から始まり、3 ステップで GRPO まで到達する
README は Dockerfile を用意しつつ、事前ビルド済みイメージの利用を推奨している。取得と起動は次の 2 行である。
docker pull hiyouga/verl:ngc-th2.8.0-cu12.9-vllm0.11.0 docker run -it --ipc=host --gpus=all hiyouga/verl:ngc-th2.8.0-cu12.9-vllm0.11.0
Docker が使えない環境向けに Apptainer の手順も示されている。apptainer pull easyr1.sif docker://hiyouga/verl:ngc-th2.8.0-cu12.9-vllm0.11.0 でイメージを取得し、apptainer shell --nv --cleanenv --bind /mnt/your_dir:/mnt/your_dir easyr1.sif でシェルに入る。モデルを ModelScope から取得したい場合は USE_MODELSCOPE_HUB=1 を設定する。
ソースから入れる場合は git clone https://github.com/hiyouga/EasyR1.git の後、cd EasyR1 して pip install -e . を実行する。ソフトウェア要件は Python 3.9 以上、transformers>=4.54.0、flash-attn>=2.4.3、vllm>=0.8.3。
訓練は bash examples/qwen2_5_vl_7b_geo3k_grpo.sh で開始する。LoRA 版は bash examples/qwen3_vl_4b_geo3k_grpo_lora.sh。チェックポイントを Hugging Face 形式に統合するには python3 scripts/model_merger.py --local_dir checkpoints/easy_r1/exp_name/global_step_1/actor を実行する。Hugging Face への接続に問題がある場合は export HF_ENDPOINT=https://hf-mirror.com を設定する。
メモリ要件の表は estimated であり、そのまま見積もりに使うと危ない
README のハードウェア要件表は、見出しの直後に「* *estimated*」と明記されている。つまり実測値ではなく推定である。表によれば GRPO の全パラメータ訓練は 7B モデルで AMP なら 8*40GB、BF16 なら 4*40GB、LoRA 訓練なら 2*32GB。72B では全パラメータ AMP が 32*80GB、BF16 が 16*80GB、LoRA が 4*80GB となる。BF16 を有効にするには worker.actor.fsdp.torch_dtype=bf16 と worker.actor.optim.strategy=adamw_bf16 を設定する、と README は注記している。この表を容量計画の唯一の根拠にするのは避けたい。シーケンス長、画像枚数、バッチ構成、勾配蓄積の設定で必要メモリは動く。導入検討時は、対象モデルと自前データセットで短いステップ数を回し、実測のピークメモリを取るのが順当である。
LoRA 訓練は魅力的だが、その適用範囲は README からは確定できない
LoRA 訓練は 72B クラスで 4*80GB まで要件を下げられるため、計算資源が限られたチームにとって最も現実的な入口に見える。ただし README が LoRA を「![new]」付きで紹介していること、そして LoRA の例として挙げられているのが examples/qwen3_vl_4b_geo3k_grpo_lora.sh という GRPO のスクリプト 1 本だけであることは事実として記録しておく。DAPO や GSPO、CISPO と LoRA を組み合わせた場合の挙動、対応する設定キー、既知の制約については README に記述がない。推測で埋めるべきではない。LoRA 経路を本番の訓練に使うなら、まず GRPO の例を動かしてから、目的のアルゴリズムに切り替えて設定の受理と学習の進行を自分の環境で確かめる必要がある。
マルチノードは Ray に依存し、上流 veRL のドキュメントを読む前提になっている
70B 以上のモデルをマルチノードで動かす手順は README に 4 ステップで示されている。ヘッドノードで ray start --head --port=6379 --dashboard-host=0.0.0.0 を実行し、ワーカーノードで ray start --address=<head_node_ip>:6379 を実行して接続する。ray status でリソースプールを確認したうえで、訓練スクリプトはヘッドノードでのみ bash examples/qwen2_5_vl_7b_geo3k_grpo.sh のように実行する。詳細は veRL 公式ドキュメントの multinode ページを参照せよ、と README は明示している。これは EasyR1 が分散実行の層を自前で持たず、Ray と veRL の設計にそのまま乗っていることを意味する。利点は実績のある仕組みを再利用できること、欠点はトラブルシューティングの情報が EasyR1 のリポジトリ外にあることだ。Ray のダッシュボードやデバッガの使い方も veRL 側の資料を読むことになる。
比較対象としての上流 veRL と、R1-V ベースラインの再現
最も直接的な代替は上流の veRL である。EasyR1 は自らを clean fork と位置づけているので、差分は視覚言語モデル対応に集約されている。テキスト専用モデルだけを訓練するなら、フォークを挟む分だけ上流との差分を追う手間が増える。逆に画像入力を扱うなら、上流に手を入れるより EasyR1 のデータセット形式に合わせる方が速い。もう 1 つの参照点は R1-V で、README はそのベースライン 2 本を EasyR1 上で再現したと述べている。CLEVR-70k-Counting は examples/baselines/qwen2_5_vl_3b_clevr.sh、GeoQA-8k は examples/baselines/qwen2_5_vl_3b_geoqa8k.sh にある。Qwen2.5-VL-3B-Instruct を対象にした小規模な再現で、パイプラインが期待通り動くかを確かめる出発点として使いやすい。性能の比較値は assets/baselines.md に置かれている。
Apache-2.0 のフォークを運用するコストは上流追従にある
ライセンスは Apache-2.0 で、フォーク元の veRL から引き継いでいる。Apache-2.0 は商用利用を含む広い利用を許すが、本記事は法的助言ではない。実務上の関心事はむしろ保守にある。EasyR1 は veRL のクリーンフォークであるため、上流が HybridEngine や vLLM 連携を更新したとき、その変更をそのまま受け取れるとは限らない。リリース履歴を見ると v0.3.0 が 2025-04-15、v0.3.1 が 2025-06-19、v0.3.2 が 2025-09-18 で、およそ 2 か月から 3 か月間隔。この間隔は活発な更新を示す一方、上流 veRL のペースとは独立している。依存も固定されていて、Docker イメージのタグは vllm0.11.0 を指すが、ソースからのインストール要件は vllm>=0.8.3 と幅がある。イメージとソースで vLLM のバージョンが異なる点は、再現性を重視するなら意識しておきたい。
編集部の結論
Qwen2.5-VL や Qwen3-VL のような視覚言語モデルに対して GRPO 系の RL を回したい研究チームには向いている。一方、テキスト専用モデルだけを扱う場合や、上流 veRL の機能追従を最優先する場合は、このフォークを選ぶ理由が薄い。導入前に確認すべきは 3 点で、第一に README のメモリ表が estimated と明記されている以上、手元の GPU で examples/qwen2_5_vl_7b_geo3k_grpo.sh を短いステップ数で流して実測すること。第二に LoRA 経路が GRPO 以外のアルゴリズムと組み合わせられるかどうか。第三に Apache-2.0 のフォークであり、上流 veRL の変更をどの程度取り込んでいるかをリリース間隔から判断すること。
コミュニティノート