SSD

TL;DR — SSD keeps only the code needed for image sampling, GenEval evaluation, DPG-Bench evaluation, the core HeadH2O method, and a minimal R-KV comparison baseline.

SSD is designed as a practical inference-and-evaluation release rather than a full research code dump. The repository focuses on the exact path needed to:

• sample images with HeadH2O
• evaluate results on GenEval
• evaluate results on DPG-Bench
• compare against H2O-like, StreamingLLM-like, and R-KV settings

• 🚀 [May 27, 2026] Cleaned release repository prepared for public GitHub release.
• ✅ Included: HeadH2O inference, GenEval evaluation, DPG-Bench evaluation, and a GenEval R-KV comparison path.
• 🧹 Release cleanup: Chinese comments translated or removed, public-facing dev v2 naming cleaned up, and scripts/docs normalized for release.

This release intentionally keeps only the core path required to reproduce the main sampling-and-evaluation workflow:

• HeadH2O as the main cache-compression method
• GenEval sampling + scoring
• DPG-Bench sampling + scoring
• R-KV as a lightweight GenEval comparison baseline
• Janus inference code required by the released scripts

This release does not include training code, plotting utilities, unrelated demos, or non-core experimental branches.

head_h2o is the core method in this repository.

Its main idea is to split KV-cache handling by head type:

• spatial heads use a more streaming-style cache
• semantic / heavy-hitter heads use a more H2O-style cache

Head type is determined from precomputed head-importance statistics:

• misc/head_scores/Janus-Pro-1B_head_scores_recent_32.pt
• misc/head_scores/Janus-Pro-7B_head_scores_recent_32.pt

The main control variable is:

• head_sensitivity

This is why the released scripts are organized into:

• *_to_h2o.sh: move HeadH2O toward the H2O side
• *_to_streaming*.sh: move HeadH2O toward the StreamingLLM side
• dpg_headh2o_all_head_sensitive.sh: sweep head_sensitivity
• run_geneval_rkv.sh: run the R-KV baseline

pip install -r requirements.txt
python3 tools/repo_audit.py

This repository assumes a working CUDA / PyTorch environment for Janus inference.

Important dependency notes:

• flash-attn and flashinfer are environment-dependent compiled packages
• mmdet, mmcv, and mmengine are required for GenEval
• modelscope is required for DPG-Bench

This repository does not include model weights.

Typical released models used by the scripts:

• deepseek-ai/Janus-Pro-1B
• deepseek-ai/Janus-Pro-7B

You may also pass a local checkpoint path directly to the Python entrypoints.

GenEval expects a local Mask2Former checkpoint directory:

export MASK2FORMER_MODEL_PATH=/path/to/mask2former_ckpts

DPG evaluation uses a ModelScope VQA checkpoint. By default the released pipeline uses:

xingjianleng/mplug_visual-question-answering_coco_large_en

You can override it with:

export MPLUG_VQA_CKPT=/path/or/modelscope/id

All released scripts live under scripts/head_h2o/.

python3 tools/repo_audit.py

export MASK2FORMER_MODEL_PATH=/path/to/mask2former_ckpts
export CUDA_VISIBLE_DEVICES=0,1,2,3
bash scripts/head_h2o/geneval_headh2o.sh

export MASK2FORMER_MODEL_PATH=/path/to/mask2former_ckpts
export CUDA_VISIBLE_DEVICES=0,1,2,3
bash scripts/head_h2o/run_geneval_rkv.sh

export CUDA_VISIBLE_DEVICES=0,1,2,3
bash scripts/head_h2o/dpg_headh2o.sh

The released sampling/evaluation entrypoints are:

• eval/t2i_geneval_cache_compression.py
• eval/t2i_dpg_bench_cache_compression.py
• eval/t2i_geneval_rkv.py

These are the main Python programs used by the released shell scripts.

All released scripts write to:

${OUTPUT_ROOT:-./outputs}

Typical output structure:

outputs/geneval/Janus-Pro-1B/head_h2o/.../
  00000/
    metadata.jsonl
    samples/
      00000.png
      00001.png
      ...
  results.jsonl

outputs/dpg/Janus-Pro-1B/head_h2o/.../
  0.png
  1.png
  ...
  dpg-bench_xxx_results.txt

all_cache/
├── head_h2o/                       # core HeadH2O / H2O cache implementation
└── utils.py                        # shared cache utilities

configs/
└── test_config_geneval_rkv.sh      # R-KV evaluation configuration

eval/
├── t2i_geneval_cache_compression.py
├── t2i_dpg_bench_cache_compression.py
├── t2i_geneval_rkv.py
├── geneval/                        # GenEval prompts and evaluation code
└── dpg_bench/                      # DPG-Bench prompts and evaluation code

janus/                              # Janus inference code used by the release

misc/
└── head_scores/                    # precomputed head-importance statistics

RKV/
└── HuggingFace/rkv/                # minimal R-KV baseline code path

scripts/
└── head_h2o/                       # released shell entrypoints

tools/
└── repo_audit.py                   # release completeness / consistency checks

This is a core-code-only release.

It intentionally excludes:

• training code
• plotting utilities
• unrelated demos
• old exploratory scripts
• non-core cache variants
• non-core experimental branches

The goal is to keep only the code path needed to reproduce the main sampling + evaluation pipeline.

Before publication, this release was checked for:

• Python syntax validity
• shell script syntax validity
• removal of hard-coded local absolute paths
• validity of internal ROOT / REPO_ROOT references
• presence of the required HeadH2O / Janus / evaluation / R-KV core code

What still depends on your local environment:

• model checkpoints
• CUDA runtime
• compiled attention kernels
• Mask2Former evaluation checkpoint
• ModelScope VQA checkpoint

This release builds on and reorganizes components related to:

• Janus for autoregressive image generation
• HeadH2O / H2O-style cache compression ideas
• StreamingLLM-style cache handling for spatial heads
• R-KV for the comparison baseline
• GenEval and DPG-Bench evaluation pipelines

Please also review upstream repositories, licenses, and model terms when preparing a public release.

This repository now includes software citation files:

• CITATION.cff
• CITATION.bib

If you use this release, please cite the software record and, for exact reproducibility, include the repository URL and commit hash used in your experiments.

If a separate H3Cache / HeadH2O paper is released later, you can additionally cite the paper version in the usual BibTeX format.

See LICENSE.