easy-r1
Use EasyR1 for multimodal LLM RL post-training, dataset/reward preparation, core API debugging, and checkpoint export workflows.
- License 许可
- Apache-2.0
- 最近更新
- 2026-09-03
- Stars
- ★ 351
- Forks
- 27
01 前言 Front Matter
- name
- easy-r1
- license
- Apache 2.0
- metadata
- { "disco-role": "operating" }
- description
- Use EasyR1 for multimodal LLM RL post-training, dataset/reward preparation, core API debugging, and checkpoint export workflows.
- disable-model-invocation
- true
02 资源文件 4
- 参考文档references/repo-provenance.md2.7 KB
- 参考文档references/repo-routing-metadata.json556 B
- 参考文档references/setup-and-troubleshooting.md5.3 KB
- 脚本scripts/easyr1_env_check.py5.1 KB
03 SKILL.md 正文
EasyR1
Use this repo skill when a task names EasyR1, the verl package from EasyR1, or a multimodal LLM RL/post-training workflow that looks like EasyR1: GRPO/DAPO/Reinforce++/ReMax/RLOO/GSPO/CISPO/SAPO training, Ray + FSDP + vLLM rollout, Qwen/Qwen-VL post-training, EasyR1 reward functions, EasyR1 checkpoint merging, or DataProto debugging.
This skill is self-contained operating guidance distilled from the EasyR1 repository. It does not require reopening the repository checkout. Full training still requires an EasyR1-compatible CUDA runtime with Ray, vLLM, flash-attn, model weights, datasets, and enough GPU memory.
First checks
- Read references/repo-provenance.md before deciding whether this skill is current for a checkout or whether to refresh it.
- Read references/setup-and-troubleshooting.md for install/runtime choices, Docker/container guidance, CUDA/vLLM/flash-attn limits, and common cross-cutting failures.
- Run scripts/easyr1_env_check.py when you need a safe local environment/import/backend check. It does not start Ray, download models, or run training.
Route by task
Training workflows
Load sub-skills/training-workflows/SKILL.md when the task is to configure, lint, explain, or launch python -m verl.trainer.main jobs. It covers EasyR1 config hierarchy, OmegaConf CLI overrides, algorithms and loss types, Ray/FSDP/vLLM runtime assumptions, LoRA, logging, validation, checkpoint save/resume, multi-node setup, and training troubleshooting.
Typical triggers:
- "Run EasyR1 GRPO/DAPO/GSPO/CISPO/SAPO on my dataset."
- "Build or validate an EasyR1 config."
- "Convert an example shell launch to a safer command."
- "Explain
worker.rollout.tensor_parallel_size,algorithm.online_filtering, LoRA, or GPU memory settings."
Data and rewards
Load sub-skills/data-and-rewards/SKILL.md when the task is about dataset rows, prompt templates, image/video columns, reward functions, worker.reward.reward_function, batch/sequential reward modes, DAPO overlong penalties, R1-V/math/Android GUI reward patterns, or validating reward outputs.
Typical triggers:
- "Prepare a custom text/VL dataset for EasyR1."
- "Write an EasyR1 reward function with
overall,accuracy, oraccuracy_normalized." - "Debug image-token mismatch, overlong prompts, or missing reward keys."
Core APIs
Load sub-skills/core-apis/SKILL.md when the task involves EasyR1 support APIs rather than a full job launch: DataProto, tensor/non-tensor batches, padding/unpadding, dynamic sequence-length batching, compute_policy_loss, advantage/KL helpers, logger/tracker helpers, or native CPU API smoke checks.
Typical triggers:
- "Debug a
DataProto.unionor chunk/split error." - "Use EasyR1 core algorithm functions directly."
- "Explain dynamic batching restore order or GRPO grouped rollout assertions."
Checkpoint export
Load sub-skills/checkpoint-export/SKILL.md when the task is to inspect EasyR1 actor checkpoint directories or convert actor shards to Hugging Face format. It covers model_world_size_<N>_rank_<R>.pt shard patterns, the huggingface/ metadata directory, generation config preservation, LoRA merge requirements, upload caveats, and safe preflight inspection.
Typical triggers:
- "Merge an EasyR1 actor checkpoint to Hugging Face format."
- "Preflight a checkpoint before running the model merger."
- "Explain missing rank shards, unsupported DTensor placement, or LoRA base-model errors."
Minimal install/import shape
For users setting up EasyR1 itself, prefer the project-documented CUDA container or an equivalent Python 3.9+ environment with compatible PyTorch, Ray, vLLM, flash-attn, transformers, and model/dataset access. A minimal import check is:
python - <<'PY'
import verl
from verl.protocol import DataProto
from verl.trainer.core_algos import compute_kl
print("verl", getattr(verl, "__version__", "unknown"))
print("DataProto", DataProto.__name__)
print("compute_kl", compute_kl.__name__)
PY
If flash_attn, vllm, CUDA, or Ray imports fail, use the setup/troubleshooting reference before treating EasyR1 training as ready. CPU-safe API checks do not prove the full training runtime.
Boundaries
Do not use this skill as a generic TRL/OpenRLHF/LlamaFactory manual. Use it when EasyR1-specific config keys, scripts, dataset/reward contracts, verl APIs, or checkpoint layout matter. For ordinary supervised fine-tuning or inference workflows that EasyR1 explicitly does not provide, route to a more suitable LLM fine-tuning or serving skill.
04 同仓库更多 Skills
passnet-triton-opt
Make a single PassNet Triton kernel fast AND numerically faithful: performance model (when a replacement can win at all), block/grid/warp tuning, autotune policy, launch overhead, and per-op numeric recipes to pass the dtype baseline tolerances. Use when a pass matches and is correct but speedup below expected, or when correctness fails by small numeric margins.
passnet-solve
END-TO-END playbook for solving one PassNet sample: analyze the computation graphs, decide the optimization strategy (what to fuse, what to replace, what to leave alone), drive the iteration loop, and maximize the sample score. This is the ENTRY skill — invoke it first for any PassNet optimization task; it tells you when to use passnet-pattern-fusion, passnet-triton-opt and passnet-feedback.
passnet-skill
PassNet GPU kernel optimization via compiler passes. Design and implement Triton-based optimization passes, create pass files under ./pass_dir/, self-evaluate with pass_evaluator, and iterate to maximize GPU speedup.
passnet-pattern-fusion
Author PassNet pass files: write patterns that actually MATCH the FX graph, pick fusion regions (which ops to absorb into one Triton kernel), and structure multi-pass submissions with the mandatory shared-dispatch architecture. Use when creating or fixing pattern()/replacement_args()/replacement_func() files, when a pass "failed to match", or when deciding how to fuse multiple kernels/ops.
passnet-orchestrate
Round/batch planning and decision support for PassNet graph optimization. Use for multi-sample triage, worker allocation, eval-budget policy, and post-eval keep/revert decisions. For solving one concrete sample end to end, use passnet-solve as the entry skill; consult this skill only when you need broader planning or a specific decision gate.
passnet-feedback
Fast, deterministic feedback for PassNet work: pre-flight pattern/match verification WITHOUT burning a GPU evaluation, per-node bottleneck analysis of a sample's graphs, and eval-log parsing into per-variant status + estimated score + failure classification. Use BEFORE every GPU evaluation (check_pattern), at the START of a sample (analyze_graph), and AFTER every evaluation (parse_eval_log).