hiyouga/EasyR1

EasyR1 – 효율적이고 확장 가능한 멀티모달 RL 학습

소개

• veRL 강화학습(RLHF) 프레임워크의 포크 버전으로, 시각 언어 모델(VLM)을 처리할 수 있도록 확장되었습니다.
• HybridEngine(HybridFlow 논문)과 vLLM의 SPMD 모드를 기반으로 구축되어 대규모 LLM 및 VLM에 대해 빠르고 메모리 효율적인 학습을 제공합니다.

주요 기능

• 모델 지원: Llama 3, Qwen 2/2.5/3 (텍스트) 및 시각적 확장 변형 모델, DeepSeek-R1 증류 모델.
• RL 알고리즘: GRPO, DAPO, Reinforce++, ReMax, RLOO, GSPO, CISPO (최신 RL-HF 방법 다수 포함).
• 학습 기법: 패딩 없는 배치, LoRA 스타일의 저랭크 적응, 체크포인트 재개, 주요 실험 추적 도구(Wandb, SwanLab, Mlflow, TensorBoard)와의 통합.
• 확장성: Ray와 FSDP를 통해 단일 GPU에서 다중 GPU/노드에 걸친 70B 파라미터 모델 학습까지 지원하며, AMP/BF16 하드웨어 사용 테이블을 제공합니다.
• 데이터셋 유연성: 지정된 형식을 따르는 모든 텍스트 또는 이미지-텍스트 데이터셋을 지원합니다. 예시로 Math12K, Geometry3K, JourneyBench-multi-image-VQA 및 혼합 RL 데이터셋이 있습니다.

일반적인 워크플로우

1. 설치 – 저장소를 복제하고 pip install -e .를 실행하거나 제공된 Docker 이미지(hiyouga/verl)를 사용합니다.
2. 데이터 준비 – 텍스트 또는 시각-텍스트 데이터를 예상되는 JSON/Parquet 레이아웃에 배치합니다.
3. 스크립트 실행 – 전체 파라미터 GRPO 학습을 위해 bash examples/qwen2_5_vl_7b_geo3k_grpo.sh를 실행하거나, 파라미터 효율적인 미세 조정을 위해 LoRA 변형 스크립트를 사용합니다.
4. 체크포인트 병합 – python scripts/model_merger.py를 사용하여 RL 학습된 체크포인트를 Hugging-Face 호환 모델로 변환합니다.
5. (선택 사항) 다중 노드 – Ray 클러스터를 시작하고 헤드 노드에서 동일한 스크립트를 실행합니다.

빠른 시작

git clone https://github.com/hiyouga/EasyR1.git
cd EasyR1
pip install -e .
# 7B Qwen2.5-VL 모델에 대한 전체 파라미터 학습
bash examples/qwen2_5_vl_7b_geo3k_grpo.sh

저장소에는 LoRA 스크립트, SwanLab 로깅 예시, 재현 가능한 환경을 위한 Dockerfile이 포함되어 있습니다.

사용 대상

• 추론, 도구 사용 또는 시각적 질의응답 능력을 향상시키기 위해 강화학습으로 멀티모달 LLM을 미세 조정하는 연구자.
• 단일 GPU에서 다중 노드 클러스터까지 확장 가능한 프로덕션 수준의 RLHF 파이프라인이 필요한 엔지니어.
• 시각 언어 데이터에서 최신 RL 알고리즘(DAPO, GSPO, CISPO)을 실험하려는 사용자.

제한 사항 / 향후 과제

• 시각 언어 모델은 아직 ulysses 병렬화 기능과 호환되지 않습니다.
• 순수 지도 미세 조정이나 추론용 스크립트는 제공하지 않으며, 해당 작업에는 LlamaFactory 사용을 권장합니다.

커뮤니티 및 지원

• WeChat 그룹을 통한 토론 (README에 링크).
• 일반적인 CUDA/OOM 및 데이터 크기 오류에 대한 FAQ 섹션.
• EasyR1을 인용하는 다운스트림 프로젝트(MMR1, Vision-R1, Seg-Zero 등) 목록이 계속 증가 중.

인용

@misc{zheng2025easyr1,
  title        = {EasyR1: An Efficient, Scalable, Multi-Modality RL Training Framework},
  author       = {Yaowei Zheng and Junting Lu and Shenzhi Wang and Zhangchi Feng and Dongdong Kuang and Yuwen Xiong and Richong Zhang},
  howpublished = {\url{https://github.com/hiyouga/EasyR1}},
  year         = {2025}
}