EasyR1：高效、可扩展的多模态强化学习训练框架

被 亚马逊云科技 使用

本项目是对原 veRL 项目的干净分叉，以支持视觉语言模型。我们感谢所有作者提供了如此高性能的强化学习训练框架。

EasyR1 因 HybirdEngine 的设计以及最新发布的 vLLM 的 SPMD 模式而具备高效性和可扩展性。

特性

• 支持的模型

  • Llama3/Qwen2/Qwen2.5/Qwen3 语言模型
  • Qwen2-VL/Qwen2.5-VL/Qwen3-VL 视觉语言模型
  • DeepSeek-R1 提炼模型

• 支持的算法

  • GRPO
  • DAPO
  • Reinforce++
  • ReMax
  • RLOO
  • GSPO
  • CISPO

• 支持的数据集

  • 任何符合 特定格式 的文本或视觉-文本数据集

• 支持的技巧

  • 无填充训练
  • LoRA 训练
  • 从最新/最佳检查点恢复
  • Wandb、SwanLab、Mlflow 和 TensorBoard 追踪

需求

软件需求

• Python 3.9+
• transformers>=4.54.0
• flash-attn>=2.4.3
• vllm>=0.8.3

我们提供了一个 Dockerfile，方便构建环境。

我们推荐在 EasyR1 中使用 预构建的 Docker 镜像：

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

使用 USE_MODELSCOPE_HUB=1 可从 ModelScope 仓库下载模型。

硬件需求

* 估算

方法	位数	1.5B	3B	7B	32B	72B
GRPO 全量微调	AMP	2*24GB	4*40GB	8*40GB	16*80GB	32*80GB
GRPO 全量微调	BF16	1*24GB	1*40GB	4*40GB	8*80GB	16*80GB
GRPO LoRA 微调	AMP	1*12GB	1*24GB	2*32GB	2*80GB	4*80GB

[!NOTE] 使用 worker.actor.fsdp.torch_dtype=bf16 和 worker.actor.optim.strategy=adamw_bf16 启用 bf16 训练。

教程：只需 3 步即可在 Geometry3K 数据集上运行 Qwen2.5-VL GRPO

安装

git clone https://github.com/hiyouga/EasyR1.git
cd EasyR1
pip install -e .

GRPO 全量训练

bash examples/qwen2_5_vl_7b_geo3k_grpo.sh

GRPO 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

[!TIP] 如果连接 Hugging Face 时遇到问题，可以尝试使用 export HF_ENDPOINT=https://hf-mirror.com。

如果想使用 SwanLab 日志记录器，可以尝试使用 bash examples/qwen2_5_vl_7b_geo3k_swanlab.sh。

自定义数据集

请参考示例数据集来准备您自己的数据集。

• 文本数据集：https://huggingface.co/datasets/hiyouga/math12k
• 图像-文本数据集：https://huggingface.co/datasets/hiyouga/geometry3k
• 多图像-文本数据集：https://huggingface.co/datasets/hiyouga/journeybench-multi-image-vqa
• 文本-图像混合数据集：https://huggingface.co/datasets/hiyouga/rl-mixed-dataset

如何理解 EasyR1 中的 GRPO

• 要了解 GRPO 算法，可以参考 Hugging Face 博客。

如何在多节点环境中运行 70B+ 模型

1. 启动 Ray 主节点。

ray start --head --port=6379 --dashboard-host=0.0.0.0

2. 启动 Ray 工作节点并连接到主节点。

ray start --address=<head_node_ip>:6379

3. 检查 Ray 资源池。

ray status

4. 仅在 Ray 主节点上运行训练脚本。

bash examples/qwen2_5_vl_7b_geo3k_grpo.sh

有关多节点训练和 Ray 调试器的更多详细信息，请参阅 veRL 官方文档。

其他基线

我们还复现了 R1-V 项目的以下两个基线：

• CLEVR-70k-Counting：在计数问题上训练 Qwen2.5-VL-3B-Instruct 模型。
• GeoQA-8k：在 GeoQA 问题上训练 Qwen2.5-VL-3B-Instruct 模型。

性能基线

请参阅 baselines.md。

使用 EasyR1 的优秀工作

• MMR1: 通过方差感知采样和开放资源增强多模态推理。[](https://github.com/LengSicong/MMR1) [](https://arxiv.org/abs/2509.21268)
• Vision-R1: 激励多模态大型语言模型的推理能力。[](https://github.com/Osilly/Vision-R1) [](https://arxiv.org/abs/2503.06749)
• Seg-Zero: 基于认知强化的推理链引导分割。[](https://github.com/dvlab-research/Seg-Zero) [](https://arxiv.org/abs/2503.06520)
• MetaSpatial: 在元宇宙中强化视觉语言模型的3D空间推理能力。[](https://github.com/PzySeere/MetaSpatial) [](https://arxiv.org/abs/2503.18470)
• Temporal-R1: 通过时间一致性奖励将时间推理能力融入多模态大语言模型。[](https://github.com/appletea233/Temporal-R1) [](https://arxiv.org/abs/2506.01908)
• NoisyRollout: 通过数据增强强化视觉推理。[](https://github.com/John-AI-Lab/NoisyRollout) [](https://arxiv.org/pdf/2504.13055)
• GUI-R1: 面向GUI代理的通用R1风格视觉-语言动作模型。[](https://github.com/ritzz-ai/GUI-R1) [](https://arxiv.org/abs/2504.10458)
• FAST-GRPO: 快慢思维框架，可根据问题特征动态调整推理深度。[](https://github.com/Mr-Loevan/FAST) [](https://arxiv.org/abs/2504.18458)
• R1-Track: 通过强化学习将多模态大语言模型直接应用于视觉目标跟踪。[](https://github.com/Wangbiao2/R1-Track)
• VisionReasoner: 通过强化学习实现统一的视觉感知与推理。[](https://github.com/dvlab-research/VisionReasoner) [](https://arxiv.org/abs/2505.12081)
• MM-UPT: 通过GRPO对多模态大语言模型推理进行无监督后训练。[](https://github.com/waltonfuture/MM-UPT) [](https://arxiv.org/pdf/2505.22453)
• RL-with-Cold-Start: 通过冷启动强化学习推进多模态推理。[](https://github.com/waltonfuture/RL-with-Cold-Start) [](https://arxiv.org/pdf/2505.22334)
• ViGoRL: 面向视觉推理的具身强化学习。[](https://github.com/Gabesarch/grounded-rl) [](https://arxiv.org/abs/2505.23678)
• Revisual-R1: 推进多模态推理：从优化的冷启动到分阶段强化学习。[](https://github.com/CSfufu/Revisual-R1) [](https://arxiv.org/abs/2506.04207)
• SophiaVL-R1: 通过思考奖励强化多模态大语言模型的推理能力。[](https://github.com/kxfan2002/SophiaVL-R1) [](https://arxiv.org/abs/2505.17018)
• Vision-Matters: 简单的视觉扰动即可提升多模态数学推理能力。[](https://github.com/YutingLi0606/Vision-Matters) [](https://arxiv.org/abs/2506.09736)
• VTool-R1: 视觉语言模型通过多模态工具使用上的强化学习学会用图像思考。[](https://github.com/VTOOL-R1/vtool-r1) [](https://arxiv.org/abs/2505.19255)
• Long-RL: 将强化学习扩展到长序列。[](https://github.com/NVlabs/Long-RL) [](https://arxiv.org/abs/2507.07966)
• EditGRPO: 通过后回放编辑的强化学习实现临床准确的胸部X光报告生成。[](https://github.com/taokz/EditGRPO)
• ARES: 基于难度感知的令牌级熵塑造实现多模态自适应推理。[](https://github.com/shawn0728/ARES) [](https://arxiv.org/abs/2510.08457)
• VPPO: 多模态强化学习中的令牌感知聚焦。[](https://github.com/huaixuheqing/VPPO-RL) [](https://arxiv.org/abs/2510.09285)
• IE-Critic-R1: 推进文本驱动图像编辑的解释性度量，以实现与人类感知的一致性。[](https://github.com/Coobiw/IE-Critic-R1) [](https://arxiv.org/abs/2511.18055)
• OneThinker: 图像和视频的一体化推理模型。[](https://github.com/tulerfeng/OneThinker) [](https://arxiv.org/abs/2512.03043)
• MetaphorStar: 基于端到端视觉强化学习的图像隐喻理解和推理。[](https://github.com/MING-ZCH/MetaphorStar) [](https://arxiv.org/abs/2602.10575)

待办事项

• 支持 VLM 的 Ulysses 并行策略（中优先级）。
• 支持更多 VLM 架构。

[!注意] 本项目不会提供监督微调和推理的脚本。如果您有此类需求，建议使用 LlamaFactory。

已知问题

这些功能目前暂时禁用，我们计划在未来的更新中逐一修复。

• 视觉语言模型目前尚不兼容 Ulysses 并行策略。

讨论群

👋 加入我们的 微信交流群。

常见问题解答

ValueError: 图像特征与图像标记不匹配：标记数为 8192，特征数为 9800

请增加 data.max_prompt_length 或减少 data.max_pixels。

RuntimeError: CUDA 错误：显存不足，位于 /workspace/csrc/cumem_allocator.cpp:62

请降低 worker.rollout.gpu_memory_utilization，并启用 worker.actor.offload.offload_params。

RuntimeError: 活动驱动程序数量为 0（[]）。应仅有一个。

请从当前 Python 环境中卸载 deepspeed。

引用

核心贡献者：Zheng Yaowei、Lu Junting、Wang Shenzhi、Feng Zhangchi、Kuang Dongdong，以及 Xiong Yuwen 和 Zhang Richong。

我们还要感谢 Sheng Guangming 和 Zhang Chi 提供的有益讨论。

@misc{zheng2025easyr1,
  title        = {EasyR1：高效、可扩展的多模态强化学习训练框架},
  author       = {Zheng Yaowei, Lu Junting, Wang Shenzhi, Feng Zhangchi, Kuang Dongdong, Xiong Yuwen, Zhang Richong},
  howpublished = {\url{https://github.com/hiyouga/EasyR1}},
  year         = {2025}
}

我们也建议同时引用原始工作：

@article{sheng2024hybridflow,
  title   = {HybridFlow：灵活高效的 RLHF 框架},
  author  = {Sheng Guangming, Zhang Chi, Ye Zilingfeng, Wu Xibin, Zhang Wang, Zhang Ru, Peng Yanghua, Lin Haibin, Wu Chuan},
  year    = {2024},
  journal = {arXiv 预印本 arXiv: 2409.19256}
}

EasyR1 快速上手指南

EasyR1 是一个高效、可扩展的多模态强化学习（RL）训练框架，基于 veRL 项目改进，专门支持视觉语言模型（VLM）的 RL 训练。它利用 HybirdEngine 和 vLLM 的 SPMD 模式，实现了高性能的 GRPO、DAPO 等算法训练。

环境准备

系统要求

• Python: 3.9+
• GPU: 支持 CUDA 的 NVIDIA 显卡（显存需求参考下表）
• 操作系统: Linux (推荐)

硬件资源估算

方法	精度	1.5B	3B	7B	32B	72B
GRPO 全量微调	AMP	2*24GB	4*40GB	8*40GB	16*80GB	32*80GB
GRPO 全量微调	BF16	1*24GB	1*40GB	4*40GB	8*80GB	16*80GB
GRPO LoRA 微调	AMP	1*12GB	1*24GB	2*32GB	2*80GB	4*80GB

提示: 启用 BF16 训练可显著降低显存占用，需在配置中设置 worker.actor.fsdp.torch_dtype=bf16 和 worker.actor.optim.strategy=adamw_bf16。

前置依赖

核心依赖包括：

• transformers>=4.54.0
• flash-attn>=2.4.3
• vllm>=0.8.3

安装步骤

推荐使用官方预构建的 Docker 镜像，以避免复杂的环境配置问题。国内用户若连接 Docker Hub 较慢，可配置镜像加速器。

方案一：使用 Docker（推荐）

# 拉取预构建镜像
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 (Singularity) 或手动安装依赖。

方案二：源码安装

若在现有环境中直接安装，请执行以下命令：

# 克隆仓库
git clone https://github.com/hiyouga/EasyR1.git
cd EasyR1

# 安装依赖
pip install -e .

加速提示: 若下载 Hugging Face 模型受阻，请设置环境变量使用镜像源： export HF_ENDPOINT=https://hf-mirror.com

若需从 ModelScope 下载模型，请设置： export USE_MODELSCOPE_HUB=1

基本使用

以下以在 Geometry3K 数据集上使用 GRPO 算法微调 Qwen2.5-VL-7B 模型为例。

1. 全量微调 (Full Fine-Tuning)

运行官方提供的示例脚本即可开始训练：

bash examples/qwen2_5_vl_7b_geo3k_grpo.sh

2. LoRA 微调 (节省显存)

如果显存有限，可以使用 LoRA 进行参数高效微调：

bash examples/qwen3_vl_4b_geo3k_grpo_lora.sh

3. 合并检查点

训练完成后，将 LoRA 权重合并到基础模型中，导出为 Hugging Face 格式：

python3 scripts/model_merger.py --local_dir checkpoints/easy_r1/exp_name/global_step_1/actor

自定义数据集

EasyR1 支持任意格式的文本或图文数据集。您可以参考仓库中的示例数据集格式准备自己的数据：

• 纯文本：math12k
• 图文对：geometry3k
• 多图混合：journeybench-multi-image-vqa