---
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
---
English | 中文
# MOSS-VL-Realtime FP8 Dynamic + Transformers KV8
这是 [MOSS-VL-Realtime](https://huggingface.co/OpenMOSS-Team/MOSS-VL-Realtime)
的 Transformers FP8 发布版本，保留了按时间戳逐帧输入的视频流式推理接口。
该 checkpoint 不是 SGLang 发布版本。
## 模型架构
## 量化方法
| 模块 | 格式 |
| --- | --- |
| 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。
## 硬件要求
固定 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
```