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
Что это?UniVR — сквозной фреймворк обучения SFT и обучения с подкреплением (GRPO), созданный специально для серии унифицированных генеративных моделей Emu3.5: задачи визуального рассуждения можно обучать, подставив свой загрузчик данных и функцию вознаграждения.
Это готовая модель или фреймворк для обучения?Это фреймворк для обучения, а не самостоятельная модель: UniVRSFT отвечает за мультинодовое контролируемое дообучение (LoRA или по всем параметрам), а UniVRRL — за обучение с подкреплением GRPO; оба построены вокруг бэкбона Emu3.5.
Как его запустить?Установите зафиксированный стек зависимостей, примените прилагаемые патчи исходников vLLM для Emu3.5, затем используйте quick-start-скрипты из UniVRSFT/README.md или UniVRRL/README.md, чтобы запустить обучение SFT или RL.
Нужны ли узлы с несколькими GPU для обучения?Да — примеры quick-start исходят из 2 узлов x 8 GPU для LoRA SFT или 4 узлов x 8 GPU для SFT по всем параметрам, плюс кастомный движок rollout vLLM/verl для стадии RL.
Можно ли подключить любую базовую модель, или всё привязано к Emu3.5?Он жёстко связан с бэкбоном Emu3.5 (34B) — патчи vLLM, HybridEngine и цикл обучения созданы именно под него; заменяются только загрузчик данных (SFT) и функция вознаграждения (RL).
Что такое VR-GRPO?VR-GRPO — парадигма RL, которую использует UniVR: она объединяет вознаграждение за формат, глобальное вознаграждение за ответ, оцениваемое VLM, и пошагово-фокусное вознаграждение, нацеленное на самые неопределённые подшаги (они находятся через дисперсию CLIP-признаков), в виде Rreason = Rg - lambda|Rg - Rs|.
Что такое бенчмарк VR-X?VR-X — бенчмарк, лежащий в основе UniVR: 1.5 млн сырых сэмплов из 16 разных источников, охватывающих манипуляции, пространственные головоломки и физические рассуждения; 310 тыс. сэмплов идут на SFT cold-start и 3 тыс. отобранных — на RL.
Зачем репозиторию кастомный vLLM?В репозитории лежат патчи исходников vLLM, включающие быстрый параллельный инференс без CFG для Emu3.5 во время RL rollout — примерно вдвое выше пропускная способность по сравнению со стандартным режимом CFG, — плюс поддержка LoRA для Emu3.5 в vLLM.
Нужны ли модели текстовые метки для каждого шага рассуждения?Нет — она учится визуальному рассуждению прямо на последовательностях изображений, без плотных пар изображение-текст, генерируя будущие кадры авторегрессивно вместо промежуточной текстовой цепочки.
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