EasyR1 是一个高效、可扩展的多模态强化学习训练框架，基于 veRL 构建。该项目是原始 veRL 项目的干净分支，旨在支持视觉语言模型，感谢所有作者提供了这样一个高性能的强化学习训练框架。
【用途】 EasyR1 主要用于多模态（文本和视觉-文本）强化学习训练，特别针对视觉语言模型（VLM）进行优化。它被 Amazon Web Services 使用。项目还推荐了新的开源项目 PenguinHarness（本地优先的多智能体应用开发平台）。
【主要能力】
- 支持的模型：Llama3/Qwen2/Qwen2.5/Qwen3 语言模型；Qwen2-VL/Qwen2.5-VL/Qwen3-VL 视觉语言模型；DeepSeek-R1 蒸馏模型。
- 支持的算法：GRPO、DAPO、Reinforce++、ReMax、RLOO、GSPO、CISPO。
- 支持的数据集：任何特定格式的文本、视觉-文本数据集。
- 支持的技巧：无填充训练（Padding-free training）、LoRA 训练、从最新/最佳检查点恢复、Wandb & SwanLab & Mlflow & Tensorboard 跟踪。
- 高效可扩展：得益于 HybridEngine 设计和 vLLM 的最新 SPMD 模式。
【使用方式】 软件要求：transformers>=4.54.0，flash-attn>=2.4.3。项目提供 Dockerfile 以方便构建环境，推荐使用预构建的 Docker 镜像。如果环境不支持 Docker，可以考虑使用 Apptainer。使用 USE_MODELSCOPE_HUB=1 从 ModelScope hub 下载模型。硬件要求：使用 worker.actor.fsdp.torch_dtype=bf16 和 worker.actor.optim.strategy=adamw_bf16 启用 bf16 训练。
教程：三步在 Geometry3K 数据集上运行 Qwen2.5-VL GRPO。包括：GRPO 全量训练、GRPO LoRA 训练、合并 Hugging Face 格式检查点。如果连接 Hugging Face 遇到问题，可考虑使用 export HF_ENDPOINT=https://hf-mirror.com。如果想使用 SwanLab logger，可考虑使用 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）。
【如何理解 GRPO】 可参考 Hugging Face 的博客。
【多节点环境运行 70B+ 模型】 启动 Ray head 节点；启动 Ray worker 节点并连接到 head 节点；检查 Ray 资源池；仅在 Ray head 节点上运行训练脚本。更多关于多节点训练和 Ray 调试器的详细信息，请参阅 veRL 官方文档。
【其他基线】 还复现了 R1-V 项目的两个基线：CLEVR-70k-Counting（在计数问题上训练 Qwen2.5-VL-3B-Instruct 模型）和 GeoQA-8k（在 GeoQA 问题上训练 Qwen2.5-VL-3B-Instruct 模型）。性能基线见 baselines.md。
【使用 EasyR1 的优秀工作】 包括 MMR1、Vision-R1、Seg-Zero、MetaSpatial、Temporal-R1、NoisyRollout、GUI-R1、FAST-GRPO、R1-Track、VisionReasoner、MM-UPT、RL-with-Cold-Start、ViGoRL、Revisual-R1、SophiaVL-R1、Vision-Matters、VTool-R1、Long-RL、EditGRPO、ARES、VPPO、IE-Critic-R1、OneThinker、MetaphorStar、CARDEA 等。
【限制与待办】
- 支持 VLMs 的 ulysses 并行（中等优先级）。
- 支持更多 VLM 架构。
- 本项目不提供监督微调和推理脚本，如有需求推荐使用 LlamaFactory。
- 以下功能暂时禁用，计划在未来的更新中逐一修复。
- 视觉语言模型尚不兼容 ulysses 并行。
【讨论组】 欢迎加入微信群。
【常见问题】
- ValueError: Image features and image tokens do not match: tokens: 8192, features 9800 → 增加 data.max_prompt_length 或减少 data.max_pixels。
- RuntimeError: CUDA Error: out of memory at /workspace/csrc/cumem_allocator.cpp:62 → 减少 worker.rollout.gpu_memory_utilization 并启用 worker.actor.offload.offload_params。
- RuntimeError: 0 active drivers ([]). There should only be one. → 从当前 python 环境卸载 deepspeed。
【核心贡献者】 Yaowei Zheng、Junting Lu、Shenzhi Wang、Zhangchi Feng、Dongdong Kuang、Yuwen Xiong 和 Richong Zhang。也感谢 Guangming Sheng 和 Chi Zhang 的有益讨论。建议同时引用原始工作。项目地址：https://github.com/hiyouga/EasyR1。
