EasyR1: GRPO-Training für Vision-Language-Modelle auf Basis von veRL

Welche Lücke der Fork schließt

Reinforcement Learning auf Sprachmodellen ist mit veRL bereits möglich. Der Upstream konzentriert sich jedoch auf Text. EasyR1 beschreibt sich selbst als sauberen Fork des veRL-Projekts mit dem Ziel, Vision-Language-Modelle zu unterstützen. Der Unterschied liegt damit nicht in einem neuen Algorithmus, sondern in der Datenpipeline: Bilder müssen durch Rollout, Reward-Berechnung und Training geschleust werden, ohne dass die Padding-Logik der Textpfade bricht. Das README nennt als unterstützte Modelle Llama3, Qwen2, Qwen2.5 und Qwen3 für Text sowie Qwen2-VL, Qwen2.5-VL und Qwen3-VL für den multimodalen Fall, dazu DeepSeek-R1-Distill-Modelle. Zielgruppe sind damit Forschende und kleinere Trainings-Teams, die Reasoning-Verhalten auf Bild-Text-Aufgaben wie Geometry3K oder Counting-Aufgaben verstärken wollen und dafür keinen eigenen Trainer schreiben möchten. Wer ausschließlich Textmodelle trainiert, gewinnt durch den Fork wenig.

HybridEngine, vLLM-SPMD und der Rollout-Pfad

Das README führt die Effizienz auf zwei Bausteine zurück: das Design der HybridEngine, verlinkt auf arXiv 2409.19256, und den SPMD-Modus der vLLM-Bibliothek. Aus dem Repository selbst lässt sich ablesen, dass die Generierung der Rollouts über vLLM läuft, während das Training über FSDP im Actor-Pfad erfolgt. Die Konfigurationsschlüssel bestätigen diese Aufteilung: worker.actor.fsdp.torch_dtype und worker.actor.optim.strategy sind Parameter des Trainingspfads, nicht der Inferenz. Der Datenfluss ist damit der klassische RLHF-Zyklus: Prompts und Bilder gehen an vLLM, die erzeugten Antworten werden gegen ein Reward bewertet, und die resultierenden Advantages landen im FSDP-Trainingsschritt. EasyR1 setzt dabei auf vLLM ab Version 0.8.3. Wer eine ältere vLLM-Version im Cluster betreibt, muss diese zuerst anheben, denn das README nennt die Mindestversion explizit. Die Padding-freie Trainingsvariante ist als Trick aufgeführt, was nahelegt, dass Sequenzen unterschiedlicher Länge ohne Auffüllen durch die Batches laufen.

Installation und der Drei-Schritte-Lauf

Der dokumentierte Weg beginnt mit git clone https://github.com/hiyouga/EasyR1.git, gefolgt von cd EasyR1 und pip install -e . Für Umgebungen ohne Docker empfiehlt das README das vorgebaute Image hiyouga/verl:ngc-th2.8.0-cu12.9-vllm0.11.0, abrufbar per docker pull und gestartet mit den Flags --ipc=host und --gpus=all. Alternativ nennt das README Apptainer mit apptainer pull easyr1.sif docker://hiyouga/verl:ngc-th2.8.0-cu12.9-vllm0.11.0 und dem Shell-Aufruf mit --nv und --cleanenv. Der eigentliche Trainingslauf ist dann ein einziges Skript: bash examples/qwen2_5_vl_7b_geo3k_grpo.sh für volles Fine-Tuning oder bash examples/qwen3_vl_4b_geo3k_grpo_lora.sh für den LoRA-Pfad. Nach dem Lauf konvertiert python3 scripts/model_merger.py --local_dir checkpoints/easy_r1/exp_name/global_step_1/actor den verteilten Checkpoint zurück in das Hugging-Face-Format. Für Multi-Node-Betrieb dokumentiert das README Ray: ray start --head --port=6379 --dashboard-host=0.0.0.0 auf dem Kopfknoten, ray start --address=<head_node_ip>:6379 auf den Workern, Kontrolle über ray status, und das Trainingsskript läuft nur auf dem Kopfknoten. Ein Umgebungsdetail am Rand: USE_MODELSCOPE_HUB=1 lenkt den Modelldownload auf ModelScope um, HF_ENDPOINT=https://hf-mirror.com auf einen Hugging-Face-Spiegel.

Speicherbedarf und die LoRA-Ausnahme

Das README liefert eine Hardwaretabelle, die ausdrücklich als Schätzung markiert ist. Für GRPO mit vollem Fine-Tuning in AMP nennt sie 2 mal 24 GB für 1,5B, 4 mal 40 GB für 3B, 8 mal 40 GB für 7B, 16 mal 80 GB für 32B und 32 mal 80 GB für 72B. In BF16 halbieren sich die Werte ungefähr: 1 mal 24 GB für 1,5B, 4 mal 40 GB für 7B, 16 mal 80 GB für 72B. Die LoRA-Variante ist deutlich genügsamer und kommt bei 7B mit 2 mal 32 GB aus, bei 72B mit 4 mal 80 GB. Diese Zahlen sind der praktisch relevanteste Teil des README, weil sie die Einstiegshürde definieren. Ein 7B-Modell mit vollem Fine-Tuning in BF16 verlangt vier 40-GB-Karten, was auf einer einzelnen Workstation mit zwei GPUs nicht läuft. Die Umstellung auf BF16 erfolgt über zwei explizite Konfigurationsschlüssel, worker.actor.fsdp.torch_dtype=bf16 und worker.actor.optim.strategy=adamw_bf16, die das README in einer Notiz nennt. Wer diese Schlüssel nicht setzt, trainiert im AMP-Pfad und braucht die doppelte Speichermenge.

Datensätze: Schema statt Format

EasyR1 definiert kein eigenes Dateiformat. Das README verweist für eigene Daten auf Beispieldatensätze und listet vier Kategorien: Text bei hiyouga/math12k, Bild-Text bei hiyouga/geometry3k, Multi-Bild-Text bei hiyouga/journeybench-multi-image-vqa und gemischte Text-Bild-Daten bei hiyouga/rl-mixed-dataset. Das ist eine bewusste Entscheidung, die Flexibilität bringt, aber auch eine Falle enthält: Wer sein Schema von einem der Beispiele ableitet, muss selbst prüfen, ob die Feldnamen zu dem passen, was der Rollout-Pfad erwartet. Eine formale Spezifikation der Felder findet sich im vorliegenden Material nicht. Für Teams mit heterogenen Datenquellen bedeutet das zusätzlichen Aufwand beim Aufbereiten, und Fehler zeigen sich erst zur Laufzeit im Reward-Pfad, nicht beim Laden.

Was der Fork nicht löst

Die größte Einschränkung steht in der Selbstbeschreibung: EasyR1 ist ein Fork von veRL. Damit erbt es nicht nur die Architektur, sondern auch deren Abhängigkeiten. Ray ist für Multi-Node-Betrieb zwingend, vLLM ab 0.8.3 ebenfalls, und flash-attn ab 2.4.3 kommt hinzu. In Umgebungen, in denen diese drei Bibliotheken nicht in kompatiblen Versionen installiert werden können, ist EasyR1 das falsche Werkzeug, unabhängig davon, wie gut die Algorithmusabdeckung ist. Ein zweiter Punkt betrifft die Dokumentation selbst: Das README verlinkt für die Multi-Node-Details auf die offizielle veRL-Dokumentation, das heißt, ein Teil des Betriebswissens liegt außerhalb dieses Repositories. Wer den Fork einsetzt, muss also zwei Dokumentationsstände verfolgen. Und schließlich die Hardwaretabelle: Sie ist als Schätzung gekennzeichnet, nicht als gemessene Untergrenze. Teams, die knapp kalkulieren, sollten mit Reserve planen, weil die tatsächliche Auslastung von Sequenzlänge, Batchgröße und Bildauflösung abhängt, die in der Tabelle nicht auftauchen.

Alternativen und der konkrete Unterschied

Die naheliegende Alternative ist veRL selbst, das Upstream-Projekt von Volcengine. Der Unterschied liegt nicht in der Algorithmusliste, denn GRPO und die verwandten Verfahren stammen von dort, sondern im multimodalen Pfad: EasyR1 fügt die Unterstützung für Qwen-VL-Modelle und Bild-Text-Datensätze hinzu, die im Upstream nach der Beschreibung des Forks nicht im Mittelpunkt steht. Ein Team, das ausschließlich Textmodelle mit GRPO trainiert, hat daher keinen Grund, den Fork zu wählen, und sollte direkt beim Upstream bleiben, weil es dann nur eine Dokumentationsquelle pflegen muss. Umgekehrt gilt: Wer Bilder in den Rollout einbeziehen will, findet in EasyR1 fertige Beispielskripte für Geometry3K und für die beiden R1-V-Baselines CLEVR-70k-Counting und GeoQA-8k, die im Verzeichnis examples/baselines liegen. Diese Skripte sind der eigentliche Mehrwert gegenüber dem Upstream, weil sie einen funktionierenden Ausgangspunkt für den multimodalen Fall darstellen.

Wartung, Lizenz und was vor dem ersten Lauf zu prüfen ist

EasyR1 steht unter Apache-2.0. Diese Lizenz erlaubt kommerzielle Nutzung und Modifikation, verlangt aber, dass Änderungen an den Lizenz- und Urheberrechtshinweisen kenntlich gemacht werden. Da es sich um einen Fork handelt, ist zusätzlich die Lizenz von veRL zu prüfen, weil abgeleiteter Code deren Bedingungen weiterhin unterliegt. Das ist keine Rechtsberatung, sondern ein Hinweis auf den Prüfpunkt. Zur Wartung: Die Release-Historie umfasst v0.3.0 vom April 2025, v0.3.1 vom Juni 2025 mit dem Titel Multi-modal DAPO und v0.3.2 vom September 2025 mit dem Titel RL Baselines. Der Abstand zwischen den Releases liegt also bei etwa zwei bis drei Monaten. Der Fork folgt damit dem Upstream nicht kontinuierlich, sondern in Sprüngen. Wer auf eine bestimmte veRL-Version angewiesen ist, muss prüfen, ob der Fork sie bereits nachgezogen hat. Konkret vor dem ersten Lauf zu klären sind drei Dinge: ob die eigene vLLM-Version mindestens 0.8.3 ist, ob die GPU-Anzahl zur Zeile in der Hardwaretabelle passt, die dem gewählten Modell und Präzisionsmodus entspricht, und ob der eigene Datensatz dem Schema eines der vier genannten Beispieldatensätze folgt. Erst danach lohnt es sich, das Beispielskript auf die eigene Konfiguration umzuschreiben.

Redaktionelles Fazit

EasyR1 passt zu Teams, die bereits Ray- und vLLM-Infrastruktur betreiben und GRPO oder DAPO auf Qwen-VL-Modellen reproduzieren wollen, ohne die veRL-Konfiguration von Hand zusammenzusetzen. Wer nur einen einzelnen 7B-Textlauf auf einer Maschine braucht, ist mit dem Upstream veRL oder mit einer Bibliothek ohne Ray-Abhängigkeit besser bedient. Vor dem ersten produktiven Lauf sollte man die Hardwaretabelle im README gegen die eigene GPU-Ausstattung prüfen und die im Repository hinterlegten Beispieldatensätze als Formatvorlage nehmen, weil EasyR1 kein eigenes Datenformat definiert, sondern nur ein erwartetes Schema dokumentiert.

Offizielle Quellen

1. hiyouga/EasyR1 on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases