Fix language switch links

78cdbd3 verified 3 days ago

4.44 kB

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
  - bitsandbytes
  - NF4
  - quantized
  - custom_code

English | 中文

MOSS-VL-Realtime W4A16 NF4 + KV8 HQQ

这是 MOSS-VL-Realtime 的 24 GB 显存量化版本，保留了原模型基于时间戳的实时流式推理能力，同时支持标准的离线图片和视频推理接口。

量化方法

模块	格式
大部分语言模型层	bitsandbytes NF4 4-bit 权重，启用 double quantization
首尾语言模型层和多模态模块	BF16
激活与计算	BF16
Transformers KV Cache	HQQ INT8
Attention 后端	FlashAttention 2

模型保留了首尾语言层和多模态模块的 BF16 精度，对主要语言模型层使用 NF4 权重量化，并通过 HQQ 将 KV Cache 压缩为 INT8。量化配置已包含在 checkpoint 中，加载时无需再次传入量化参数。

量化前后性能

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

MOSS-VL 量化前后 benchmark 对比

硬件要求

模型支持单张 24 GB 显存的 NVIDIA 消费级显卡。建议使用 FlashAttention 2，并将实时推理的 frame_queue_size 设为 1。

环境安装

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 \
  bitsandbytes==0.49.2 \
  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
bitsandbytes	0.49.2
HQQ	0.2.8.post1

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

加载模型

import torch
from transformers import AutoModelForCausalLM, AutoProcessor

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

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，请不要使用 BF16 或 dynamic Cache 配置覆盖它。

实时流式推理

应用侧按时间顺序传入 PIL 图片和对应时间戳。24 GB 显存配置建议使用 frame_queue_size=1。

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()

离线视频推理

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)