UniVR README

The project's README from github.com/FlagOpen/UniVR. As one markdown file: README.md.

UniVR: SFT & RL Training Framework for Emu3.5 Series Unified Models

UniVR Overview


What is This?

UniVR is an end-to-end SFT and Reinforcement Learning (GRPO) training framework specifically built for Emu3.5 series unified generative models. It is designed to be easily adapted for your own tasks — you only need to swap in your own data loader and RL reward function.

Key framework features:


Customizing for Your Own Task

Step 1 — Replace the Data Loader (SFT)

The SFT stage reads training samples in a unified format: [query image, textual instruction, visual reasoning trajectory]. To use your own data, implement a custom PyTorch Dataset that returns samples in this format and plug it into UniVR_SFT/train.py.

No changes to the training loop, DeepSpeed config, or model code are needed.

Step 2 — Replace the Reward Function (RL)

The RL stage calls a reward server via HTTP to score rollout trajectories. To use your own reward:

  1. Implement your reward logic as an HTTP server (see UniVR_RL/verl/ for the existing VLM-based reward server reference).
  2. Set VLLM_PATH in UniVR_RL/examples/emu3_grpo_lora.sh to point to your reward server endpoint.
  3. Optionally adjust worker.rollout.enable_image_decode_for_reward in examples/config_emu3.yaml depending on whether your reward consumes raw image tokens or decoded pixel images.

The GRPO training loop, rollout engine, and Emu3.5 vLLM backend remain unchanged.


Research Context (UniVR)

This framework was developed for UniVR, a system that learns complex visual reasoning, fine-grained physical dynamics, and long-term planning from pure visual demonstrations — without relying on dense image-text pairs or task-specific heuristics.

UniVR uses VR-GRPO, a reinforcement learning paradigm combining:

Training and evaluation use VR-X, a benchmark of 1.5M raw samples from 16 diverse sources spanning manipulation, spatial puzzles, and physical reasoning.


Architecture

UniVR adopts Emu3.5 (34B) as its backbone — a unified generative model that tokenizes images and text into a shared discrete vocabulary via a VQ-VAE-style encoder. The model autoregressively generates visual reasoning traces (future frames) given an image sequence and instruction, with no intermediate text chain.

Training is a two-stage pipeline:

Stage Module Data Description
1. Cold Initialization UniVR_SFT 310k VR-X samples SFT to instill visual reasoning priors
2. Reinforcement Learning UniVR_RL 3k curated samples VR-GRPO with composite reward

Repository Structure

UniVR/
├── install.sh            # One-shot environment setup for both subprojects
├── UniVR_SFT/            # Supervised Fine-Tuning (cold initialization)
│   ├── train.py          # ← Replace dataset here for your task
│   ├── inference.py
│   ├── scripts/
│   │   ├── train_sft_lora.sh
│   │   ├── train_sft_full.sh
│   │   └── inference.sh
│   ├── configs/          # Inference configs
│   └── src/
│       ├── patch/        # vLLM source patches for Emu3.5 (no-CFG + LoRA)
│       └── tokenizer_emu3_ibq/
└── UniVR_RL/             # Reinforcement Learning (VR-GRPO)
    ├── examples/
    │   ├── emu3_grpo_lora.sh  # ← Set your reward server endpoint here
    │   └── config_emu3.yaml
    ├── verl/             # Modified verl framework with Emu3.5 HybridEngine
    └── src/

Installation

bash install.sh

Installs all dependencies (torch==2.8.0, transformers==4.57.3, vllm==0.11.0, flash-attn==2.8.3, deepspeed), applies the vLLM source patches for Emu3.5, and installs the verl-based RL framework.

See UniVR_SFT/README.md and UniVR_RL/README.md for detailed usage of each subproject.


Quick Start

SFT (LoRA, 2 nodes × 8 GPUs)

# Edit scripts/train_sft_lora.sh to set MODEL_PATH, TOKENIZER_PATH, OUTPUT_DIR
cd UniVR_SFT
bash scripts/train_sft_lora.sh

SFT (Full parameter, 4 nodes × 8 GPUs)

bash scripts/train_sft_full.sh

RL (VR-GRPO)

# Edit examples/emu3_grpo_lora.sh to set MODEL_PATH, TOKENIZER_PATH, VQ_MODEL_PATH, VLLM_PATH
cd UniVR_RL
bash examples/emu3_grpo_lora.sh

UniVR (FlagOpen/UniVR)

Searching Database…

178 ·GitHub
What is this?UniVR is an end-to-end SFT and Reinforcement Learning (GRPO) training framework built specifically for Emu3.5 series unified generative models, letting you train visual reasoning tasks by swapping in your own data loader and reward function.
Is this a ready-to-use model or a training framework?It is a training framework, not a standalone model: UniVRSFT handles multi-node supervised fine-tuning (LoRA or full-parameter) and UniVRRL handles GRPO reinforcement learning, both built around the Emu3.5 backbone.
How do I get it running?Install the pinned dependency stack, apply the included vLLM source patches for Emu3.5, then use the UniVRSFT/README.md or UniVRRL/README.md quick-start scripts to launch SFT or RL training.
Do I need multi-GPU nodes to train with this?Yes — the quick-start examples assume 2 nodes x 8 GPUs for LoRA SFT or 4 nodes x 8 GPUs for full-parameter SFT, plus a custom vLLM/verl rollout engine for the RL stage.
Can I plug in any backbone model, or is it tied to Emu3.5?It is tightly coupled to the Emu3.5 (34B) backbone — the vLLM patches, HybridEngine and training loop are built specifically for it; only the data loader (SFT) and reward function (RL) are meant to be swapped out.
What is VR-GRPO?VR-GRPO is the RL paradigm UniVR uses, combining a format reward, a global VLM-judged completion reward, and a step-focal reward that targets the most uncertain sub-steps (found via CLIP-feature variance), combined as Rreason = Rg - lambda|Rg - Rs|.
What is the VR-X benchmark?VR-X is the benchmark behind UniVR: 1.5M raw samples from 16 diverse sources covering manipulation, spatial puzzles and physical reasoning, with 310k samples used for SFT cold-start and 3k curated samples for RL.
Why does the repo need a custom vLLM?It ships vLLM source patches that enable fast no-CFG parallel inference for Emu3.5 during RL rollout, roughly doubling throughput versus standard CFG mode, plus LoRA support for Emu3.5 in vLLM.
Does the model need text labels for each reasoning step?No — it learns visual reasoning directly from image sequences without dense image-text pairs, generating future frames autoregressively instead of an intermediate text chain.
What are similar projects?halo, Intern-Decision, open-r1, OraRL, verl, verl, jeeves, minimind
Creator
FlagOpen
Size
31.7 MB
Stars
178
Updated
CommitJul 25
Age
1mo
Commits · 90 Days