MOSS-VL KV Cache量化实战指南:从HQQ INT8到SGLang部署的三步走
MOSS-VL KV Cache量化实战指南:从HQQ INT8到SGLang部署的三步走
MOSS-VL 是面向长视频与实时视频理解的开源 11B 参数模型系列。本文带你完成 MOSS-VL KV Cache 量化的完整流程:先用 FP8-Dynamic 做权重量化,再通过 HQQ INT8(Transformers)或 FP8 KV dtype(SGLang)压缩随视频流不断增长的 KV Cache,最后用 SGLang 三步起服,让长视频推理在单卡上跑得动、跑得起。
为什么长视频推理必须量化 KV Cache 🤔
MOSS-VL 的核心卖点是实时视频流交互:模型一边接收带时间戳的连续帧,一边生成回答,支持随时打断、主动沉默、动态纠错。
问题在于:视频流越长,KV Cache 占用的显存越大。11B 模型在 BF16 下,权重本身已要 22GB+,长视频场景下 KV Cache 还会随流式输入线性膨胀。因此官方量化方案分两层:
| 量化对象 | 作用 | 典型收益 |
|---|---|---|
| 权重(Weight) | 降低模型本体显存 | BF16 → FP8 约省一半 |
| KV Cache | 抑制长视频/长会话显存增长 | 8-bit KV 显存约为 BF16 的一半 |
官方已发布 24GB 量化 checkpoint(FP8 与 NF4 两种),可在单张 24GB 显卡上运行。
第一步:FP8-Dynamic 权重量化(一份 checkpoint 双引擎兼容)
MOSS-VL 的 48 层语言模型中,第 2, 6, 10, …, 46 层(每 4 层一次)是 cross-attention 视觉层,其余 36 层为纯语言 self-attention 层。
FP8-Dynamic 方案的量化策略很克制:
- 量化范围:仅 36 个纯语言层的
q/k/v/o_proj与gate/up/down_proj,共 252 个 Linear 算子 - 保留 BF16:视觉塔、全部 cross-attention 层、embedding、norm、
lm_head - 实现方式:权重
float8_e4m3fnchannel-wise 静态量化,输入激活 FP8 per-token 动态量化(compressed-tensorsFP8_DYNAMIC)
它基于 LLM Compressor 的 oneshot 调用实现,脚本还会自动把 SGLang 需要的 packed_modules_mapping(qkv_proj、gate_up_proj 融合映射)和 ignore 正则写进 config.json——这是它能被 SGLang 直接加载的关键。
pip install -i https://pypi.org/simple --no-deps llmcompressor==0.10.0
python quantization/quantize_fp8_dynamic.py \
--source /path/to/your-checkpoint --output ./my-model-fp8
不想自己量化?可直接使用官方发布的
MOSS-VL-Instruct-0708-FP8、MOSS-VL-Realtime-FP8。另有一个显存更低的 NF4 W4 方案(quantize_nf4_keep_ends.py),首尾各 4 层保留全精度,但仅支持 Transformers。
第二步:KV Cache 量化,HQQ INT8 与 FP8 各走一边
这是本文的重点:两个推理引擎的 KV 量化路径完全不同,需要分别处理。
路径 A:Transformers + HQQ INT8(打包进 checkpoint)
用官方脚本 package_kv8_hqq.py 一键打包:
python quantization/package_kv8_hqq.py \
--source ./my-model-fp8 --output ./my-model-fp8-kv8 \
--weight-quantization fp8-dynamic
它做三件事:
- 硬链接复制 checkpoint(省磁盘空间)
- 写入 KV8 配置到
generation_config.json:
"cache_implementation": "quantized",
"cache_config": {
"backend": "hqq", "nbits": 8,
"axis_key": 0, "axis_value": 0,
"q_group_size": 64, "residual_length": 128
}
- 自动打补丁修复 cross-attention 的 KV 读取路径。原因是 Transformers 的
QuantizedCache把较早的 KV 存在_quantized_keys/_quantized_values中,keys/values只保留一段 128 token 的 BF16 residual 尾部;而 MOSS-VL 的 cross-attention 层直接读keys/values,脚本会把读取逻辑改成"先反量化历史 KV,再拼接 residual 尾部"。
⚠️ 需要额外安装
hqq包(见 quantization/requirements.txt,锁定hqq==0.2.8.post1)。
路径 B:SGLang + 引擎原生 FP8 KV(免打包)
SGLang 不走 HQQ,而是使用引擎自身的 KV dtype 参数,无需修改任何文件:
--kv-cache-dtype fp8_e4m3
package_kv8_hqq.py 生成的 mossvl_kv8_report.json 报告中也明确记录了这一点:SGLang FP8 E4M3 和 Transformers HQQ INT8 是两套各自独立的 KV8 原生实现。所以如果最终目标是 SGLang 部署,第二步可以完全跳过,只需准备 FP8 权重的 checkpoint 即可。
第三步:SGLang 三步起服 🚀
按官方 SGLang 部署文档 third_party/sglang/README.md,环境 → 依赖 → 起服:
conda create -n sglang-moss-vl python=3.12 -y
pip install -e "python" && pip install nvidia-cudnn-cu12==9.16.0.29 joblib
启动服务(以 FP8 量化模型为例):
python3 -m sglang.launch_server \
--model-path /path/to/your-model-fp8 \
--host 0.0.0.0 --port 30000 \
--tp 1 --mem-fraction-static 0.7 \
--kv-cache-dtype fp8_e4m3 \
--trust-remote-code \
--attention-backend flashinfer
三个易踩的坑:
- 必须用
flashinfer作为 prefill 后端——MOSS-VL 使用自定义 cross-attention mask;也可只--prefill-attention-backend flashinfer --decode-attention-backend fa3 --mem-fraction-static建议从 0.7 起调,长视频 KV 吃紧时适当调高- 新部署建议直接用最新官方 SGLang 版本,third_party/sglang/ 目录是历史代码快照
起服后即可通过 inference/offline/ 的批处理查询做离线验证,流式推理参考 inference/realtime/。若要做多视频流并发生产服务,官方推荐专用的 SGLang-Omni 后端(动态多会话调度 + 数据并行副本),完整全栈 demo 在 third_party/realtime-demo/。
常见问题速查 💡
| 问题 | 原因与解法 |
|---|---|
| SGLang 加载 FP8 checkpoint 报错 | 确认用官方脚本量化(会自动写 packed_modules_mapping),或直接用官方 FP8 checkpoint |
| Transformers 开 KV8 后 cross-attention 输出异常 | 必须使用打补丁后的 checkpoint(含 mossvl_kv8_report.json 即已修补) |
| 量化后精度担心 | 首尾语言层、cross-attention 与视觉塔均保留 BF16,官方验证过精度稳定 |
| 想省更多显存 | 换 NF4 W4(显存最低)或直接用官方 24GB checkpoint |
参考资料
- 官方量化教程:quantization/README_zh.md / quantization/README.md
- 脚本与依赖:quantization/
- SGLang 部署:third_party/sglang/README.md
- 推理示例:inference/README.md
总结:三步走即「FP8-Dynamic 量化权重 → 按需打包 HQQ INT8 KV8(仅 Transformers 需要)→ SGLang 带 --kv-cache-dtype fp8_e4m3 起服」。掌握后,你自己的 SFT 微调版本也同样适用——所有方案均为训练后量化,无需校准数据和重训。



