README_zh.md

---
license: apache-2.0
language:
- en
- zh
library_name: transformers
pipeline_tag: video-text-to-text
base_model: OpenMOSS-Team/MOSS-VL-Realtime
tags:
- MOSS-VL
- realtime
- streaming
- video-understanding
- FP8
- compressed-tensors
- HQQ
- quantized
- custom_code
---

<p align="center">
  <img src="assets/logo.png" width="300" alt="MOSS-VL"/>
</p>

<p align="center">
  <a href="https://huggingface.co/OpenMOSS-Team/MOSS-VL-Realtime-FP8/blob/main/README.md">English</a> | 中文
</p>

# MOSS-VL-Realtime FP8 Dynamic + Transformers KV8

这是 [MOSS-VL-Realtime](https://huggingface.co/OpenMOSS-Team/MOSS-VL-Realtime)
的 Transformers FP8 发布版本，保留了按时间戳逐帧输入的视频流式推理接口。
该 checkpoint 不是 SGLang 发布版本。

## 模型架构

<p align="center">
  <img src="assets/architecture.png" alt="MOSS-VL 模型架构" width="100%"/>
</p>

## 量化方法

| 模块 | 格式 |
| --- | --- |
| 36 个非 cross-attention 语言层中的 252 个 self-attention/MLP Linear | compressed-tensors FP8 E4M3 权重，channel-wise 静态 scale，输入激活使用 per-token 动态 FP8 |
| 12 个 cross-attention 语言层 | BF16 |
| 视觉编码器和 merger | BF16 |
| Embedding、norm 和 `lm_head` | BF16 |
| Transformers KV Cache | HQQ INT8，group size 64，BF16 residual length 128 |
| Attention 后端 | FlashAttention 2 |

`generation_config.json` 会自动启用 HQQ KV8。请直接加载 checkpoint，
不要再次传入量化配置，也不要用 BF16 原模型的 generation config 覆盖它。

## 量化 Benchmark

最终测评在各自对应的 benchmark 上对比原始 BF16 模型与四个量化发布配置。
该流式 FP8 checkpoint 的 OVOBench Avg、StreamingBench Avg 和 OmniMMI PA
分别为 70.66、62.93 和 65.50；对应 BF16 分数为 70.86、62.42 和 66.00。

<p align="center">
  <img src="assets/mossvl_quantization_benchmark_comparison_final_v3_zh_4k.png" alt="MOSS-VL 量化配置 benchmark 对比" width="100%"/>
</p>

## 硬件要求

固定 30 帧流式测试的进程峰值显存为 25,522 MiB，GPU 总峰值为
26,249 MiB，其中基线占用 727 MiB。建议使用可用显存超过 26 GiB 的
NVIDIA GPU；多卡环境可通过 `device_map="auto"` 让 Transformers 自动切分。

## 环境安装

```bash
git clone https://github.com/OpenMOSS/MOSS-VL.git
cd MOSS-VL

conda create -n moss_vl_quant python=3.12 pip -y
conda activate moss_vl_quant
pip install -i https://pypi.org/simple --no-build-isolation -r requirements.txt
pip install -i https://pypi.org/simple \
  compressed-tensors==0.14.0.1 \
  hqq==0.2.8.post1
python -m pip check
```

已验证的主要环境版本：

| 依赖 | 版本 |
| --- | --- |
| Python | 3.12.8 |
| PyTorch | 2.8.0 + CUDA 12.8 |
| Transformers | 4.57.1 |
| Accelerate | 1.12.0 |
| FlashAttention | 2.8.1 |
| compressed-tensors | 0.14.0.1 |
| HQQ | 0.2.8.post1 |

视频解码还需要确保 FFmpeg 已加入 `PATH`。

## 加载模型

```python
import torch
from transformers import AutoModelForCausalLM, AutoProcessor

checkpoint = "OpenMOSS-Team/MOSS-VL-Realtime-FP8"

processor = AutoProcessor.from_pretrained(
    checkpoint,
    trust_remote_code=True,
    frame_extract_num_threads=1,
)
model = AutoModelForCausalLM.from_pretrained(
    checkpoint,
    trust_remote_code=True,
    device_map="auto",
    torch_dtype=torch.bfloat16,
    attn_implementation="flash_attention_2",
)
model.eval()
```

## 实时流式推理

应用侧按时间顺序传入 PIL 图片和非递减时间戳。一个模型实例同时支持
一个实时会话。

```python
import time
from PIL import Image

session = model.create_realtime_session(
    processor,
    initial_prompt="持续描述视频中的重要变化，没有明显变化时保持安静。",
    frame_queue_size=1,
    max_tokens_per_turn=12,
    max_new_tokens=4096,
    do_sample=False,
)

frame_paths = [
    "data/frame_0001.jpg",
    "data/frame_0002.jpg",
    "data/frame_0003.jpg",
]

try:
    session.start()
    for index, frame_path in enumerate(frame_paths):
        image = Image.open(frame_path).convert("RGB")
        session.push_frame(image, timestamp=float(index))
        while True:
            chunk = session.poll_output(timeout=0.0)
            if chunk is None:
                break
            print(chunk, end="", flush=True)
        time.sleep(1.0)
finally:
    session.close()
```

模型可能输出 `<|silence|>`、`<|round_start|>` 和 `<|round_end|>` 等
控制 token，应用侧可以按协议过滤或渲染。

## 完整复测命令

固定测试使用新疆航拍视频，以 1 FPS 输入 30 个带时间戳的帧，实际完成
30/30 帧并输出相关的中文导游描述。

```bash
source /inspire/qb-ilm/project/video-understanding/public/train/moss_vl_streaming/8B/quant/venv/bin/activate

/inspire/qb-ilm/project/video-understanding/public/train/moss_vl_streaming/8B/quant/venv/bin/python \
  /inspire/qb-ilm/project/video-understanding/public/train/moss_vl_streaming/8B/quant/benchmark_mossvl_quant.py \
  --label streaming_fp8_reproduce \
  --checkpoint /inspire/qb-ilm/project/video-understanding/public/train/moss_vl_streaming/8B/final_release/quant/MOSS-VL-0708-Streaming-FP8-Dynamic-KV8-HQQ \
  --gpu 0 \
  --frames 30 \
  --attention-backend flash_attention_2 \
  --timeout 300
```

完整输入、命令和原始日志：

```text
/inspire/qb-ilm/project/video-understanding/public/train/moss_vl_streaming/8B/quant/transformers_validation_20260811
```