Qwen2.5-VL SCC 视觉 Token 压缩使用说明
本文档介绍如何在 vllm-ascend v0.18.0 中应用 SCC 视觉 token 压缩补丁、启动 Qwen2.5-VL 服务,并完成基础功能验证和 VideoMME 性能评估。
SCC 实现介绍
SCC(Semantic Connected Components)用于压缩 Qwen2.5-VL 的视觉 token,目标是在尽量保持模型效果的前提下降低视觉 token 数量,从而提升多模态推理吞吐。
该补丁的核心改动包括:
- 在
vllm_ascend/ops/scc_compressor.py中新增 SCC 压缩算法,对视觉 embedding 按语义相似度构建连通分量,并将每个分量聚合为代表 token。 - 在 Processor 侧按
K = ceil(N * ratio)缩短 image/video placeholder 数量,确保 prompt 中的视觉占位符数量与压缩后的视觉 embedding 数量一致。 - 在 Model 侧包装 Qwen2.5-VL 的
_process_image_input和_process_video_input,对 ViT 输出做 SCC 压缩。 - 适配 Qwen2.5-VL 的 mROPE 位置计算,避免压缩后视觉 embedding 数量和位置数量不一致。
- 在 EngineCore/worker 子进程中重新应用 monkey patch,确保服务端推理链路中 SCC 生效。
SCC 完全在服务端执行,客户端请求格式无需修改。
前置准备
1、 准备配备昇腾 NPU 的硬件服务器,例如 Atlas 800 A2 系列。
2、 准备可正常工作的 vllm-ascend v0.18.0 环境。安装方法可参考 vllm-ascend 安装指南,建议使用官方 Docker 镜像:
# 宿主机执行
docker pull quay.io/ascend/vllm-ascend:v0.18.0
3、 下载 Qwen2.5-VL 模型权重,例如 Qwen2.5-VL-7B-Instruct。可参考 Qwen2.5-VL-7B-Instruct ModelScope。
4、 如需进行 VideoMME 性能评估,准备 lmms-eval 测试框架:
# 容器内执行;如需在独立环境评估,也可在对应评估环境中执行
git clone https://github.com/EvolvingLMMs-Lab/lmms-eval.git
cd lmms-eval
pip install qwen_vl_utils accelerate decord2 sacrebleu evaluate pytz tenacity pytablewriter pytest
lmms-eval 默认会从 Hugging Face 下载数据集。离线或网络受限环境可提前下载 VideoMME 数据集 ModelScope。
快速开始
1. 启动容器
以下示例在宿主机执行,用于启动 vllm-ascend v0.18.0 官方容器。请根据实际环境调整 NPU 设备、模型目录和代码目录挂载路径。
# 宿主机执行
export IMAGE=quay.io/ascend/vllm-ascend:v0.18.0
docker run -itd --name vllm-ascend-scc \
--net=host \
--privileged \
--device /dev/davinci_manager \
--device /dev/devmm_svm \
--device /dev/hisi_hdc \
-v /usr/local/dcmi:/usr/local/dcmi \
-v /usr/local/Ascend/driver/tools/hccn_tool:/usr/local/Ascend/driver/tools/hccn_tool \
-v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
-v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \
-v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \
-v /etc/ascend_install.info:/etc/ascend_install.info \
-v /root/.cache:/root/.cache \
-v /path/to/workspace:/workspace \
-v /path/to/Qwen2.5-VL-7B-Instruct:/models/Qwen2.5-VL-7B-Instruct \
$IMAGE bash
其中:
/path/to/workspace是宿主机上的工作目录,建议其中包含MultimodalSDK仓库,容器内对应路径为/workspace/MultimodalSDK。/path/to/Qwen2.5-VL-7B-Instruct是宿主机上的模型权重目录,容器内对应路径为/models/Qwen2.5-VL-7B-Instruct。- 如果环境不允许使用
--privileged,可按实际 NPU 设备列表改为显式挂载--device /dev/davinci0。
容器启动后执行docker exec -it vllm-ascend-scc bash会进入容器内的 bash。后续快速开始、功能验证和性能验证中的命令,除明确标注“宿主机执行”外,均默认在该容器内执行。
2. 应用补丁
SCC 补丁已按目标文件拆分到 examples/SCC/patches 目录下,文件名中的两位数字表示推荐应用顺序。请在 vllm-ascend 仓库根目录按顺序应用这些 patch。
下面命令在进入容器后执行。/vllm-workspace/vllm-ascend 指 vllm-ascend 源码仓库根目录,并以开发模式(pip install -e)安装过,无需重新安装;/path/to/MultimodalSDK 指当前 MultimodalSDK 仓库在容器内的路径,若使用上面的挂载示例则为 /workspace/MultimodalSDK。
# 容器内vLLM 和 vLLM Ascend 代码位于 /vllm-workspace 目录
cd /vllm-workspace/vllm-ascend
# 若没有MultimodalSDK仓库,先clone
git clone https://github.com/ModelScope/MultimodalSDK.git /workspace/MultimodalSDK
git apply --check /workspace/MultimodalSDK/examples/SCC/patches/*.patch
git apply /workspace/MultimodalSDK/examples/SCC/patches/*.patch
如果曾经用循环方式应用过并出现失败,请先在 vllm-ascend 仓库中恢复到应用补丁前的干净状态,再重新执行上面的 git apply --check 和 git apply。否则已经应用成功的前半部分 patch 会导致重复应用或上下文不匹配。
3. 配置 SCC 参数
SCC 通过环境变量控制,需在启动 vLLM 服务前设置。
| 变量 | vllm-ascend 默认值 | 范围 | 描述 |
|---|---|---|---|
VLLM_ASCEND_ENABLE_SCC |
0 |
0 或 1 |
SCC 主开关,1 表示启用。 |
VLLM_ASCEND_SCC_RATIO |
0.3 |
(0, 1] |
保留的视觉 token 比例,K = ceil(N * ratio)。 |
VLLM_ASCEND_SCC_TAU |
0.95 |
(0, 1] |
余弦相似度阈值,值越高,聚类越稀疏。 |
VLLM_ASCEND_SCC_EPSILON |
0.05 |
(0, 1) |
CPU fallback 近似连通分量采样误差容限,值越小越精确但越慢。 |
VLLM_ASCEND_SCC_MAX_TOKENS_PER_ITEM |
8192 |
>= 0 |
单个图片或视频项目超过该 token 数时跳过压缩,0 表示不限制。 |
示例:
# 容器内执行,先进入 vllm-ascend 仓库
cd /vllm-workspace/vllm-ascend
# 启用 SCC,使用 vllm-ascend 默认压缩参数
export VLLM_ASCEND_ENABLE_SCC=1
# 如需自定义压缩参数,可继续设置:
export VLLM_ASCEND_SCC_RATIO=0.5
export VLLM_ASCEND_SCC_TAU=0.98
export VLLM_ASCEND_SCC_EPSILON=0.05
完成以上配置后,再进入下一步启动服务。也可以不提前 export,在启动服务命令前以内联环境变量的方式传入参数。
4. 启动服务
补丁会新增 start_vllm_server.sh。启动前请确认脚本中的 MODEL_PATH 指向容器内可用的 Qwen2.5-VL 模型目录,也可以通过环境变量覆盖。若需要启用 SCC,请先按上一节配置 SCC 参数。
基线模式默认关闭 SCC:
# 容器内执行
cd /vllm-workspace/vllm-ascend
MODEL_PATH=/models/Qwen2.5-VL-7B-Instruct bash start_vllm_server.sh
启用 SCC:
# 容器内执行
cd /path/to/vllm-ascend
MODEL_PATH=/models/Qwen2.5-VL-7B-Instruct \
VLLM_ASCEND_ENABLE_SCC=1 \
VLLM_ASCEND_SCC_RATIO=0.5 \
VLLM_ASCEND_SCC_TAU=0.98 \
VLLM_ASCEND_SCC_EPSILON=0.05 \
bash start_vllm_server.sh
服务启动日志中会打印 SCC 状态:
=== Starting vLLM server ===
Model: /models/Qwen2.5-VL-7B-Instruct
Endpoint: http://0.0.0.0:8000/v1
TP size: 2
HF_HOME: /root/.cache/huggingface
SCC: ON (ratio=0.5, tau=0.98, epsilon=0.05)
============================
start_vllm_server.sh 默认在 http://0.0.0.0:8000/v1 暴露 OpenAI 兼容 API,并使用 --tensor-parallel-size 2。如需调整 HOST、PORT、TP_SIZE,可通过环境变量覆盖。
功能验证
本章命令默认在已进入的 vllm-ascend 容器内执行。
1. 单元测试
单元测试用于验证 SCC 算法和 patch 辅助逻辑,不依赖真实模型推理。
# 容器内执行
cd /vllm-workspace/vllm-ascend
# SCC 算法
pytest tests/ut/ops/test_scc_compressor.py
# SCC patch 辅助逻辑
pytest tests/ut/patch/platform/test_patch_engine_core_scc.py
2. 分层冒烟测试
补丁中新增了 tests/scc 目录,用于验证 SCC 集成链路。
# 容器内执行
cd /vllm-workspace/vllm-ascend
# Layer 1:仅验证算法,CPU 可运行,无需启动 vLLM 服务
python tests/scc/test_layer1_algorithm.py
# Layer 2:验证补丁注册和启用路径
VLLM_ASCEND_ENABLE_SCC=1 python tests/scc/test_layer2_patch.py
# Layer 2:验证补丁禁用路径
VLLM_ASCEND_ENABLE_SCC=0 python tests/scc/test_layer2_patch.py
端到端冒烟测试需要先启动服务,再发送请求:
# 容器内终端 1:启动带 SCC 的服务
cd /vllm-workspace/vllm-ascend
VLLM_ASCEND_ENABLE_SCC=1 bash start_vllm_server.sh
# 容器内终端 2:发送测试请求
cd /vllm-workspace/vllm-ascend
bash tests/scc/curl_smoke.sh
请求完成后,检查客户端日志中出现以下日志,则表示用例通过:
=== Request completed. Now check the server log for [SCC] lines. ===
3. 简单 OpenAI API 请求
可以使用如下脚本验证 vLLM 服务是否可正常响应。该脚本只验证服务可用性;SCC 是否生效仍以服务端 [SCC] 日志为准。
import json
import urllib.request
BASE_URL = "http://localhost:8000"
MODEL = "/path/to/Qwen2.5-VL-7B-Instruct"
messages = [
{
"role": "user",
"content": "请用三句话介绍量子计算",
}
]
payload = json.dumps({
"model": MODEL,
"messages": messages,
"max_tokens": 128,
}).encode("utf-8")
req = urllib.request.Request(
f"{BASE_URL}/v1/chat/completions",
data=payload,
headers={"Content-Type": "application/json"},
)
with urllib.request.urlopen(req, timeout=120) as resp:
result = json.loads(resp.read())
print(result["choices"][0]["message"]["content"])
print(result.get("usage", {}))
性能验证
性能评估建议使用同一套模型、同一份数据集,分别在基线模式和 SCC 模式下运行 lmms-eval,对比 value 和 avg_speed。
本章命令默认在已进入的 vllm-ascend 容器内执行。
1. 启动服务端
基线模式:
# 容器内执行
cd /vllm-workspace/vllm-ascend
MODEL_PATH=/models/Qwen2.5-VL-7B-Instruct bash start_vllm_server.sh
SCC 模式:
# 容器内执行
cd /vllm-workspace/vllm-ascend
MODEL_PATH=/models/Qwen2.5-VL-7B-Instruct \
VLLM_ASCEND_ENABLE_SCC=1 \
VLLM_ASCEND_SCC_RATIO=0.5 \
VLLM_ASCEND_SCC_TAU=0.98 \
VLLM_ASCEND_SCC_EPSILON=0.05 \
bash start_vllm_server.sh
2. 运行 lmms-eval
在 lmms-eval 仓库中创建 qwen25vl_vllm.sh:
#!/bin/bash
set -euo pipefail
TASK=videomme
MODEL_NAME=/path/to/Qwen2.5-VL-7B-Instruct
VLLM_HOST=localhost
VLLM_PORT=8000
RUN_TAG="${RUN_TAG:-baseline}"
LIMIT="${LIMIT:-200}"
export HF_HOME="${HF_HOME:-${HOME}/.cache/huggingface}"
export DECORD_NUM_THREADS=1
export OMP_NUM_THREADS=2
export OPENBLAS_NUM_THREADS=2
export MKL_NUM_THREADS=2
export TOKENIZERS_PARALLELISM=false
OUTPUT_DIR=./logs/qwen25vl_vllm_${TASK}_${RUN_TAG}
python3 -m lmms_eval \
--model openai \
--model_args=model_version=${MODEL_NAME},base_url=http://${VLLM_HOST}:${VLLM_PORT}/v1,api_key=EMPTY,max_frames_num=16,timeout=300,num_concurrent=1 \
--tasks ${TASK} \
--batch_size 1 \
--limit ${LIMIT} \
--log_samples \
--output_path ${OUTPUT_DIR}
运行:
# 容器内执行
cd /path/to/lmms-eval
# 基线结果
RUN_TAG=baseline bash qwen25vl_vllm.sh
# SCC 结果
RUN_TAG=scc_ratio0.5_tau0.98_eps0.05 bash qwen25vl_vllm.sh
建议多轮运行后取平均值。通常关注:
value:精度指标,建议确认相对基线无明显下降。avg_speed:速度指标,观察 SCC 启用后的提升幅度。
3. 离线数据集说明
如果无法在线下载 VideoMME,可先下载数据集到本地,并通过环境变量指定本地路径:
# 容器内执行
export LMMS_LOCAL_DATASET_PATH=/path/to/Video-MME
export LMMS_LOCAL_VIDEOMME_PATH=/path/to/Video-MME
export HF_HUB_OFFLINE=1
export TRANSFORMERS_OFFLINE=1
不同版本的 lmms-eval 对本地数据集路径的支持可能不同。如果环境变量无法生效,需要按当前 lmms-eval 版本调整 lmms_eval/api/task.py 的数据集加载逻辑,使其从本地 parquet 或缓存目录加载 VideoMME,以下给个修改示例:
vim lmms-eval/lmms_eval/api/task.py
# 第一处,找到以下代码:
dataset_kwargs["From_YouTube"] = True
cache_path = snapshot_download(repo_id=self.DATASET_PATH, repo_type="dataset") # download_parquet
# 修改成:
dataset_kwargs["From_YouTube"] = True
local_dataset_path = os.environ.get("LMMS_LOCAL_DATASET_PATH")
if local_dataset_path:
cache_path = local_dataset_path
print(f"[LMMS] Use local dataset YouTube cache path: {local_dataset_path}")
else:
cache_path = snapshot_download(repo_id=self.DATASET_PATH, repo_type="dataset") # download_parquet
# 第二处,找到以下代码:
if not os.path.exists(cache_dir) or (create_link and os.path.islink(cache_dir)):
cache_path = snapshot_download(repo_id=self.DATASET_PATH, revision=revision, repo_type="dataset", force_download=force_download, etag_timeout=60)
# 修改成:
if not os.path.exists(cache_dir) or (create_link and os.path.islink(cache_dir)):
local_dataset_path = os.environ.get("LMMS_LOCAL_DATASET_PATH")
if local_dataset_path:
cache_path = local_dataset_path
print(f"[LMMS] Use local dataset cache path: {local_dataset_path}")
else:
cache_path = snapshot_download(repo_id=self.DATASET_PATH, revision=revision, repo_type="dataset", force_download=force_download, etag_timeout=60)
# 第三处,找到以下代码:
load_dataset_cache_dir = load_dataset_kwargs.pop("cache_dir", resolved_dataset_cache_dir)
self.dataset = datasets.load_dataset(
path=self.DATASET_PATH,
name=self.DATASET_NAME,
cache_dir=load_dataset_cache_dir,
download_mode=datasets.DownloadMode.REUSE_DATASET_IF_EXISTS,
download_config=download_config,
num_proc=1,
**load_dataset_kwargs,
)
# 修改成:
load_dataset_cache_dir = load_dataset_kwargs.pop("cache_dir", resolved_dataset_cache_dir)
local_videomme_path = os.environ.get("LMMS_LOCAL_VIDEOMME_PATH")
if local_videomme_path and self.DATASET_PATH == "lmms-lab/Video-MME":
parquet_file = os.path.join(
local_videomme_path,
"videomme",
"test-00000-of-00001.parquet",
)
print(f"[LMMS] Loading local Video-MME parquet: {parquet_file}")
self.dataset = datasets.load_dataset(
"parquet",
data_files={"test": parquet_file},
)
else:
self.dataset = datasets.load_dataset(
path=self.DATASET_PATH,
name=self.DATASET_NAME,
cache_dir=load_dataset_cache_dir,
download_mode=datasets.DownloadMode.REUSE_DATASET_IF_EXISTS,
download_config=download_config,
num_proc=1,
**load_dataset_kwargs,
)
常见问题
看不到任何 [SCC] 日志
通常说明 SCC patch 没有加载。请确认:
- 补丁已成功应用。
- 启动服务时设置了
VLLM_ASCEND_ENABLE_SCC=1。 - 服务端日志中出现了 SCC 启动 banner。
只看到 SCC 启动日志,看不到压缩日志
通常说明请求没有触发图片或视频路径。请使用 tests/scc/curl_smoke.sh 或包含 image_url 的请求进行验证。
服务启动时内存压力过大
start_vllm_server.sh 已限制 OMP/BLAS/tokenizer 线程数,并设置了 --max-num-seqs 1、--max-model-len 12288、--limit-mm-per-prompt '{"image":16,"video":0}'。如果仍然 OOM,可继续降低 TP_SIZE、max_model_len 或并发设置。