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-Instruct-0708
tags:
- MOSS-VL
- image-understanding
- video-understanding
- FP8
- compressed-tensors
- quantized
- SGLang
- 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-Instruct-0708-FP8/blob/main/README.md">English</a> | 中文
</p>

# MOSS-VL-Instruct-0708 FP8 Dynamic + Transformers KV8

这是 MOSS-VL-Instruct-0708 的 24 GB 显存量化版本，同一份权重可用于
Transformers 标准推理和 MOSS-VL 原生 SGLang 后端。

## 量化方法

| 模块 | 格式 |
| --- | --- |
| 大部分语言模型层 | FP8 权重 + per-token 动态 FP8 输入激活 |
| Cross-attention、视觉模块和 `lm_head` | BF16 |
| Transformers KV Cache | HQQ INT8 |
| SGLang KV Cache | SGLang 原生 BF16 Cache |

模型保留了对精度更敏感的跨模态与视觉模块，仅对主要语言模型层和
Transformers KV Cache 进行量化。量化配置已随 checkpoint 一起提供，
加载时无需再次传入量化参数。

## 量化前后性能

在所列 benchmark 上，量化模型与未量化 BF16 模型的整体表现接近，
说明量化后模型能力基本保持，没有受到明显影响。

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

## 硬件要求

Transformers 推理支持单张 24 GB 显存的 NVIDIA 消费级显卡。SGLang 的
显存占用取决于服务启动参数和 KV Cache 预留比例。

## 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 \
  hqq==0.2.8.post1
python -m pip check
```

主要环境版本：

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

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

### 加载模型

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

checkpoint = "OpenMOSS-Team/MOSS-VL-Instruct-0708-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()
```

`generation_config.json` 会自动启用 HQQ INT8 KV Cache，请保留该文件，
不要额外传入冲突的 Cache 配置。

### 图片推理

```python
text = model.offline_image_generate(
    processor,
    prompt="请描述这张图片。",
    image="data/example_image.jpg",
    max_new_tokens=256,
    do_sample=False,
    vision_chunked_length=64,
)
print(text)
```

### 视频推理

```python
text = model.offline_video_generate(
    processor,
    prompt="请描述这段视频。",
    video="data/example_video.mp4",
    video_fps=1.0,
    min_frames=1,
    max_frames=256,
    max_new_tokens=256,
    do_sample=False,
    vision_chunked_length=64,
)
print(text)
```

## SGLang 环境

SGLang 建议使用独立环境。当前原生后端对应 Python 3.12.8、SGLang
0.5.11、sglang-kernel 0.4.2、PyTorch 2.11.0 + CUDA 13.0、
Transformers 5.6.0 和 compressed-tensors 0.17.1。

```bash
cd /path/to/mossvl_sglang
conda create -y -n mossvl-sglang-0511 python=3.12.8 pip=24.2
conda activate mossvl-sglang-0511
python -m pip install -r requirements.txt
python -m pip check
```

启动 OpenAI 兼容服务：

```bash
conda activate mossvl-sglang-0511
cd /path/to/mossvl_sglang
GPU_IDS=0 TP_SIZE=1 MEM_FRACTION_STATIC=0.35 \
  ./start_sglang_moss_vl.sh \
  --model-path OpenMOSS-Team/MOSS-VL-Instruct-0708-FP8
```

服务默认监听 `http://127.0.0.1:30000`。SGLang 使用自身的 BF16 KV
Cache，不会读取 Transformers 的 HQQ Cache 配置。