# zzzhhzzz/ground-r1 architecture

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

- Interactive diagram: https://gitdiagram.com/zzzhhzzz/ground-r1
- Repository: https://github.com/zzzhhzzz/ground-r1

## Overview

##### Project type and purpose
- This is a machine-learning research codebase implementing “Ground-R1,” a reinforcement-learning framework for grounded visual reasoning with large vision-language models (LVLMs).
- It provides:
– A reinforcement learning (RL) training pipeline that generates evidence regions and answers.
– A supervised fine-tuning (SFT) pipeline for comparison.
– Evaluation scripts across multiple vision-language benchmarks (VisCoT, MME, RefCOCO, etc.).

##### File structure
Top level directories and their roles:
- asset: static images for README visualization
- eval: evaluation scripts & datasets specifically for VisCoT and RefCOCO
- eval_general_dataset: evaluation across general LVLM benchmarks (MME, SEED-Bench…)
- qwen-vl-finetune: supervised fine-tuning module (data prep, training code)
- r1-v: core RL training code, configurations, model implementation
- train_data: scripts and raw data for initial dataset preparation
- scripts, setup.sh: orchestration scripts for end-to-end runs

Key subcomponents:
– r1-v/src/open_r1: Python implementation of RL environment, reward functions, trainers
– r1-v/configs: YAML files driving hyperparameters for different runs (zero2, zero3, qwen2vl_sft)
– qwen-vl-finetune/qwenvl/train: SFT trainer, argument parsing, training loops
– eval & eval_general_dataset: multiple .sh drivers invoking Python scripts for metrics calculation

##### README for additional insights
- Describes two phases: grounding (evidence region rollout) and answering (reward-guided responses).
- Lists dependencies (Conda, Python 3.10, external datasets on Hugging Face).
- Details training & inference commands, plus evaluation across benchmarks.

a. Main components
1. Data Sources
– Visual-CoT dataset
– LVLM benchmark datasets (MME, SEED-Bench…)
– RefCOCO family datasets
2. Preprocessing
– Data preparation scripts (train_data/prepare_data.py, qwen-vl-finetune/scripts/prepare_SFT_data.sh)
3. Model & Training
– RL Trainer module (r1-v/src/open_r1/trainer)
– Reward functions & environment (format reward, accuracy reward)
– SFT Trainer module (qwen-vl-finetune/qwenvl/train)
4. Configuration Management
– YAML config files (r1-v/configs/*.yaml)
5. Evaluation
– VisCoT & RefCOCO eval scripts (eval/, eval_general_dataset/)
6. Orchestration & Deployment
– Shell scripts (scripts/run_grpo_video.sh, multi_*.sh)
– Environment setup (setup.sh, conda environment)

b. Relationships and data flow
1. Raw datasets → Preprocessing → Formatted data
2. Formatted data + Config → Training module (RL or SFT)
3. Trained model checkpoints → Evaluation scripts → Metrics & plots
4. Optional: Checkpoints & logs stored for analysis

c. Architectural patterns & principles
- Modular ML pipeline: data, training, evaluation isolated in folders
- Config-driven runs: swap YAML files for different experiments
- Two-phase decoupling: evidence grounding vs. answer generation
- Shell orchestration for reproducibility

d. Key technologies & frameworks
- Python 3.10, PyTorch (implied by `trainer.py`)
- vLLM for efficient language model serving (in trainer modules)
- Hugging Face Datasets for data loading
- YAML for configuration (r1-v/configs/)
- Bash scripts for orchestration

##### Elements
- Clear labels: e.g., “Data Prep,” “RL Trainer,” “Reward Functions,” “Eval VisCoT.”
– Data sources (green)
– Processing & training modules (blue)
– Configuration (yellow)
– Evaluation (orange)

##### Final recommendation
– Be exhaustive: represent each directory as a component or subcomponent.
– Capture the two-phase RL pattern visually.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        direction TB
        VC["Visual-CoT Dataset"]:::data
        LVLM["LVLM Benchmark Datasets\n(MME, SEED-Bench…)"]:::data
        RC["RefCOCO Datasets"]:::data
        DP_RL["Data Preparation (RL)"]:::process
        DP_SFT["Data Preparation (SFT)"]:::process
        VC --> DP_RL
        LVLM --> DP_SFT
        RC --> DP_RL
    end

    %% Preprocessing Scripts
    DP_RL --> Formatted_RL["Formatted RL Data"]:::data
    DP_SFT --> Formatted_SFT["Formatted SFT Data"]:::data

    click DP_RL "https://github.com/zzzhhzzz/ground-r1/blob/master/r1-v/train_data/prepare_data.py"
    click DP_SFT "https://github.com/zzzhhzzz/ground-r1/blob/master/qwen-vl-finetune/scripts/prepare_SFT_data.sh"

    %% Configuration Management
    subgraph "Configuration Management"
        direction TB
        RL_Config["RL Config YAMLs"]:::config
    end
    click RL_Config "https://github.com/zzzhhzzz/ground-r1/blob/master/r1-v/configs/zero2.yaml"
    click RL_Config "https://github.com/zzzhhzzz/ground-r1/blob/master/r1-v/configs/zero3.yaml"
    click RL_Config "https://github.com/zzzhhzzz/ground-r1/blob/master/r1-v/configs/ddp.yaml"
    click RL_Config "https://github.com/zzzhhzzz/ground-r1/blob/master/r1-v/configs/qwen2vl_sft_config.yaml"

    %% Training Layer
    subgraph "Training Layer"
        direction TB
        subgraph "RL Training" 
            direction TB
            RL_Core["RL Core Modules"]:::process
            RL_Trainers["RL Trainer Implementations"]:::process
            Reward["Reward Functions"]:::process
            ImgProc["Image Processing Helpers"]:::process
            Grounding["Grounding Phase"]:::process
            Answering["Answering Phase"]:::process

            Formatted_RL --> RL_Core
            RL_Config --> RL_Core
            RL_Core --> RL_Trainers
            RL_Trainers --> Reward
            RL_Trainers --> ImgProc
            RL_Trainers --> Grounding
            RL_Trainers --> Answering
        end

        subgraph "SFT Training"
            direction TB
            SFT_Data_Util["SFT Data Utilities"]:::process
            SFT_Trainer["SFT Trainer Module"]:::process

            Formatted_SFT --> SFT_Data_Util
            RL_Config --> SFT_Trainer
            SFT_Data_Util --> SFT_Trainer
        end
    end

    click RL_Core "https://github.com/zzzhhzzz/ground-r1/blob/master/r1-v/src/open_r1/grpo.py"
    click RL_Core "https://github.com/zzzhhzzz/ground-r1/blob/master/r1-v/src/open_r1/generate.py"
    click RL_Core "https://github.com/zzzhhzzz/ground-r1/blob/master/r1-v/src/open_r1/evaluate.py"
    click RL_Core "https://github.com/zzzhhzzz/ground-r1/blob/master/r1-v/src/open_r1/sft.py"

    click RL_Trainers "https://github.com/zzzhhzzz/ground-r1/blob/master/r1-v/src/open_r1/trainer/grpo_trainer.py"
    click RL_Trainers "https://github.com/zzzhhzzz/ground-r1/blob/master/r1-v/src/open_r1/trainer/vllm_grpo_trainer.py"
    click RL_Trainers "https://github.com/zzzhhzzz/ground-r1/blob/master/r1-v/src/open_r1/trainer/get_input_size.py"

    click Reward "https://github.com/zzzhhzzz/ground-r1/blob/master/r1-v/src/open_r1/accuracy_reward_functions.py"
    click ImgProc "https://github.com/zzzhhzzz/ground-r1/blob/master/r1-v/src/open_r1/trainer/image_pro.py"

    click SFT_Data_Util "https://github.com/zzzhhzzz/ground-r1/blob/master/qwen-vl-finetune/qwenvl/data/data_qwen.py"
    click SFT_Data_Util "https://github.com/zzzhhzzz/ground-r1/blob/master/qwen-vl-finetune/qwenvl/data/rope2d.py"

    click SFT_Trainer "https://github.com/zzzhhzzz/ground-r1/blob/master/qwen-vl-finetune/qwenvl/train/train_qwen.py"
    click SFT_Trainer "https://github.com/zzzhhzzz/ground-r1/blob/master/qwen-vl-finetune/qwenvl/train/trainer.py"
    click SFT_Trainer "https://github.com/zzzhhzzz/ground-r1/blob/master/qwen-vl-finetune/qwenvl/train/argument.py"

    %% Orchestration
    subgraph "Orchestration & Setup"
        direction TB
        RL_Scripts["RL Orchestration Scripts"]:::script
        SFT_Scripts["SFT Orchestration Scripts"]:::script
        Env_Setup["Environment Setup"]:::script

        RL_Scripts --> RL_Core
        SFT_Scripts --> SFT_Trainer
    end

    click RL_Scripts "https://github.com/zzzhhzzz/ground-r1/blob/master/r1-v/run_grpo.sh"
    click RL_Scripts "https://github.com/zzzhhzzz/ground-r1/blob/master/scripts/run_grpo_video.sh"
    click SFT_Scripts "https://github.com/zzzhhzzz/ground-r1/blob/master/qwen-vl-finetune/scripts/Vanilla_SFT.sh"
    click SFT_Scripts "https://github.com/zzzhhzzz/ground-r1/blob/master/qwen-vl-finetune/scripts/Ground_SFT.sh"
    click Env_Setup "https://github.com/zzzhhzzz/ground-r1/blob/master/setup.sh"
    click Env_Setup "https://github.com/zzzhhzzz/ground-r1/blob/master/r1-v/setup.py"
    click Env_Setup "https://github.com/zzzhhzzz/ground-r1/blob/master/r1-v/setup.cfg"

    %% Evaluation Layer
    subgraph "Evaluation Layer"
        direction TB
        Eval_VisCoT["VisCoT & RefCOCO Eval"]:::eval
        Eval_General["General LVLM Benchmark Eval"]:::eval
        Eval_VisCoT --> Metrics["Metrics & Plots"]:::eval
        Eval_General --> Metrics
    end

    click Eval_VisCoT "https://github.com/zzzhhzzz/ground-r1/tree/master/eval/eval_scripts/"
    click Eval_VisCoT "https://github.com/zzzhhzzz/ground-r1/tree/master/eval/eval_dataset/"
    click Eval_VisCoT "https://github.com/zzzhhzzz/ground-r1/blob/master/eval/multi_Ground_R1.sh"
    click Eval_VisCoT "https://github.com/zzzhhzzz/ground-r1/blob/master/eval/multi_RefCOCO.sh"

    click Eval_General "https://github.com/zzzhhzzz/ground-r1/tree/master/eval_general_dataset/scripts/"
    click Eval_General "https://github.com/zzzhhzzz/ground-r1/tree/master/eval_general_dataset/dataset/"
    click Eval_General "https://github.com/zzzhhzzz/ground-r1/blob/master/eval_general_dataset/multi_Ground_R1.sh"
    click Eval_General "https://github.com/zzzhhzzz/ground-r1/blob/master/eval_general_dataset/multi_SFT.sh"

    %% Styles
    classDef data fill:#e0f7fa,stroke:#006064,color:#006064
    classDef process fill:#bbdefb,stroke:#0d47a1,color:#0d47a1
    classDef config fill:#fff9c4,stroke:#f57f17,color:#f57f17
    classDef eval fill:#ffe0b2,stroke:#e65100,color:#e65100
    classDef script fill:#e1bee7,stroke:#4a148c,color:#4a148c
```
