MOSS-VL KV Cache量化实战指南:从HQQ INT8到SGLang部署的三步走

原创2026-10-27 19:22:341,651 阅读

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 三步起服,让长视频推理在单卡上跑得动、跑得起。

MOSS-VL 实时视频理解演示画面

为什么长视频推理必须量化 KV Cache 🤔

MOSS-VL 的核心卖点是实时视频流交互:模型一边接收带时间戳的连续帧,一边生成回答,支持随时打断、主动沉默、动态纠错。

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 层。

MOSS-VL 模型框架:Gated-XAttention 层与 Self-Attention 层交替堆叠

FP8-Dynamic 方案的量化策略很克制:

  • 量化范围:仅 36 个纯语言层的 q/k/v/o_proj 与 gate/up/down_proj,共 252 个 Linear 算子
  • 保留 BF16:视觉塔、全部 cross-attention 层、embedding、norm、lm_head
  • 实现方式:权重 float8_e4m3fn channel-wise 静态量化,输入激活 FP8 per-token 动态量化(compressed-tensors FP8_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

它做三件事:

  1. 硬链接复制 checkpoint(省磁盘空间)
  2. 写入 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
}
  1. 自动打补丁修复 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)。

MOSS-VL 整体架构:Vision Encoder 与 LLM Decoder 的 Gated-XAttention 结构

路径 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

参考资料

总结:三步走即「FP8-Dynamic 量化权重 → 按需打包 HQQ INT8 KV8(仅 Transformers 需要)→ SGLang 带 --kv-cache-dtype fp8_e4m3 起服」。掌握后,你自己的 SFT 微调版本也同样适用——所有方案均为训练后量化,无需校准数据和重训。

登录后查看全文
MOSS-VL