# tulerfeng/video-r1 architecture

> Architecture diagram of the GitHub repository tulerfeng/video-r1, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tulerfeng/video-r1
- Repository: https://github.com/tulerfeng/video-r1

## Overview

##### Main Components Identification
- Data & Dataset Layer:
- Input datasets include two primary JSON files (Video-R1-260k for RL training and Video-R1-COT-165k for the SFT cold start).
- Data preparation utilities like unzip.py (for uncompressing the dataset) and scripts or instructions for placing data into the proper folder (src/r1-v/Video-R1-data).

- Utility & Preprocessing Layer:
- “qwen-vl-utils”: Contains utility scripts (e.g., vision_process.py) that likely handle video extraction, frame processing (using decord), and other pre-processing activities.
- This module is crucial for converting raw video and image data into the format needed for the training pipelines.

- Model Training Module (Core Compute Engine):
- “r1-v”: Contains the main training pipelines including configurations, trainers, and scripts for both SFT and RL training.
- Inside r1-v, different configurations (ddp.yaml, qwen2vl_sft_config.yaml, etc.) and local scripts (for both SFT and RL) indicate that this component handles the training setup, hyperparameter configurations, and execution commands.
- Distinguish between SFT (using the run_sft_video.sh script) and RL training (using run_grpo_video.sh and run_grpo_vllm_qwen25vl.sh). Clearly indicate that SFT is the initial phase (coarse tuning) and RL (T-GRPO extension) is applied afterwards.

- Evaluation & Inference Module:
- Located in the “eval” folder, with additional evaluation scripts and JSONL prompts.
- Includes scripts (like eval_bench.sh) for running inference on various evaluation benchmarks and for processing evaluation video data.
- The eval component communicates with the trained model and utilizes external benchmark data.

- Auxiliary Components:
- “scripts” present in both the src folder and previous_version subdirectories that tie together various training and evaluation commands.
- Configuration and dependency management files (setup.sh, requirements files, pyproject.toml) that aid in environment setup and reproducibility.
- “previous_version” folder which shows an earlier iteration of the project – a useful reference for understanding the development evolution.

##### Relationships & Interactions
- Data flows from the dataset depot (raw JSON and video/image data) through preprocessing (qwen-vl-utils) where videos are extracted and prepared.
- Preprocessed data is then fed into the training pipeline under r1-v:
- The SFT component uses the prepared “Video-R1-COT-165k” data to fine-tune an initial model (via run_sft_video.sh).
- Following SFT, RL training is carried out on “Video-R1-260k” with temporal reasoning extensions (T-GRPO), where the model’s performance is validated with specialized scripts.
- The trained model is then evaluated using the eval scripts and benchmark JSON configurations.
- External dependencies such as the specific versions of Transformers, vLLM, and trl libraries are also key; include them as dependencies feeding into both training and inference.

##### Architectural Patterns & Design Principles
- Layered Architecture: Separate modules for data ingestion, preprocessing, training, and evaluation.
- Pipeline Orchestration: The sequential flow from dataset processing to supervised training and then reinforcement learning demonstrates a clear pipeline design.
- Modularity & Extensibility: With distinct directories for “qwen-vl-utils” and “r1-v”, the project is modular; each can be updated or replaced without completely disrupting the system.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data & Dataset Layer
    subgraph "Data & Dataset Layer"
        DS1["Raw Data (Video, JSON)"]:::data
        DS2["Data Preparation (unzip.py)"]:::data
    end
    click DS2 "https://github.com/tulerfeng/video-r1/blob/main/src/unzip.py"
    
    %% Utility & Preprocessing Layer
    subgraph "Utility & Preprocessing Layer"
        UT1["Utility Module (qwen-vl-utils)"]:::preprocessing
        UT2["Video Processing (vision_process.py)"]:::preprocessing
    end
    click UT1 "https://github.com/tulerfeng/video-r1/tree/main/src/qwen-vl-utils"
    click UT2 "https://github.com/tulerfeng/video-r1/blob/main/src/qwen-vl-utils/src/qwen_vl_utils/vision_process.py"
    
    %% Model Training Module
    subgraph "Model Training Module"
        MT1["Core Model Training (r1-v)"]:::training
        MT2["SFT Training (run_sft_video.sh)"]:::training
        MT3["RL Training (run_grpo_video.sh)"]:::training
        MT4["RL Acceleration (run_grpo_vllm_qwen25vl.sh)"]:::training
        MT5["Training Configurations (configs)"]:::training
        MT6["Core Training Code (open_r1)"]:::training
    end
    click MT1 "https://github.com/tulerfeng/video-r1/tree/main/src/r1-v"
    click MT2 "https://github.com/tulerfeng/video-r1/blob/main/src/scripts/run_sft_video.sh"
    click MT3 "https://github.com/tulerfeng/video-r1/blob/main/src/scripts/run_grpo_video.sh"
    click MT4 "https://github.com/tulerfeng/video-r1/blob/main/src/scripts/run_grpo_vllm_qwen25vl.sh"
    click MT5 "https://github.com/tulerfeng/video-r1/tree/main/src/r1-v/configs"
    click MT6 "https://github.com/tulerfeng/video-r1/tree/main/src/r1-v/src/open_r1"
    
    %% Evaluation & Inference Module
    subgraph "Evaluation & Inference Module"
        EV1["Evaluation Script (eval_bench.py)"]:::evaluation
        EV2["Evaluation Script (eval_bench.sh)"]:::evaluation
    end
    click EV1 "https://github.com/tulerfeng/video-r1/blob/main/src/eval_bench.py"
    click EV2 "https://github.com/tulerfeng/video-r1/blob/main/src/eval_bench.sh"
    
    %% Auxiliary Components
    subgraph "Auxiliary Components"
        AX1["Support Scripts (scripts)"]:::auxiliary
        AX2["Previous Version Reference"]:::auxiliary
    end
    click AX1 "https://github.com/tulerfeng/video-r1/tree/main/src/scripts"
    click AX2 "https://github.com/tulerfeng/video-r1/tree/main/previous_version/Video-R1-main-previous"
    
    %% External Dependencies
    subgraph "External Dependencies"
        EX1["Dependencies (Transformers, vLLM, trl)"]:::external
    end

    %% Data Flow Connections
    DS1 --> DS2
    DS2 --> UT1
    UT1 --> UT2
    UT2 --> MT1
    EX1 --> UT1
    EX1 --> MT1

    MT1 --> MT2
    MT1 --> MT3
    MT1 --> MT4
    MT5 --> MT6
    MT2 --> MT6
    MT3 --> MT6
    MT4 --> MT6
    MT6 --> EV1
    MT6 --> EV2
    
    EV1 -.-> MT1
    EV2 -.-> MT1

    AX1 --> MT2
    AX1 --> MT3
    AX1 --> EV1

    %% Styles
    classDef data fill:#AED6F1,stroke:#1B4F72,color:#1B4F72;
    classDef preprocessing fill:#F9E79F,stroke:#B9770E,color:#B9770E;
    classDef training fill:#A3E4D7,stroke:#1ABC9C,color:#1ABC9C;
    classDef evaluation fill:#F5B7B1,stroke:#C0392B,color:#C0392B;
    classDef auxiliary fill:#D2B4DE,stroke:#8E44AD,color:#8E44AD;
    classDef external fill:#F0B27A,stroke:#D35400,color:#D35400;
```
