Qwen3.5-9B-AWQ避坑清单:flashinfer缓存报错、CUDA 12.8与transformers补丁修复全记录
Qwen3.5-9B-AWQ避坑清单:flashinfer缓存报错、CUDA 12.8与transformers补丁修复全记录
Qwen3.5-9B-AWQ 是 Qwen3.5-9B 多模态模型的 4-bit AWQ 量化版,约 12GiB 单卡即可用 vLLM 部署。本文完整记录部署中三大高频坑:flashinfer 缓存报错(ninja 编译失败)、CUDA 12.8 环境要求、以及 transformers 补丁修复(partial_rotary_factor 校验 bug),并附上可直接复制的启动命令与参数说明,帮新手一次跑通。
一、模型速览:AWQ 量化版省了多少空间
AWQ(Activation-aware Weight Quantization)是一种无需数据的权重量化技术。该仓库将 9B 模型的 FFN 层权重压缩到 4 bit,视觉编码器、线性注意力层、首层和 MTP 头则保持原精度,避免精度损伤敏感模块:
| 配置项 | 值 | 说明 |
|---|---|---|
| 量化方式 | awq / 4 bit / group_size 128 |
见 config.json 的 quantization_config |
| 不量化模块 | visual、linear_attn、self_attn、第 0 层、mtp |
敏感层保留精度 |
| 权重总大小 | 约 12GiB(分 5 个 safetensors 分片) | 单张主流消费级显卡可承载 |
| 上下文长度 | 原生 262,144 tokens,YaRN 可扩展至 ~1M | max_position_embeddings: 262144 |
模型采用混合架构:32 层按 8 × (3 × Gated DeltaNet 线性注意力 → 1 × 门控注意力) 排布,并内置 MTP(多 token 预测)模块,可配合推测解码加速。权重分片索引见 model.safetensors.index.json,分片文件为 model-00001-of-00005.safetensors 至 model-00005-of-00005.safetensors。
💡 量化版与全精度版的主要差别就是显存占用更低,适合单卡部署场景;采样参数建议参考 generation_config.json。
二、坑一:flashinfer 缓存报错,ninja 编译失败怎么办
在较老的容器环境里,首次启动 vLLM 时常见如下报错:
subprocess.CalledProcessError:
Command '['ninja', '-v', '-C', '/root/.cache/flashinfer/0.6.3/90a/cached_ops/trtllm_comm',
'-f', '/root/.cache/flashinfer/0.6.3/90a/cached_ops/trtllm_comm/build.ninja']'
returned non-zero exit status 1.
原因:~/.cache/flashinfer 里残留了旧版本编译产物,与新版 vLLM 依赖的 flashinfer 不匹配,增量编译直接失败。
修复方法(一行命令清缓存,启动时会自动重新编译):
rm -rf ~/.cache/flashinfer
这是 README 官方提示的第一步,见 README.md。新环境没有该缓存,则不会触发此坑。
三、坑二:环境要求——CUDA 12.8 + Python 3.12 + 新版 vLLM
截至 2026-02-25,官方要求系统已安装 CUDA 12.8,且依赖版本较新:
vllm >= 0.16.0rc2.dev447(需要 nightly 轮子源)transformers >= 5.3.0.dev0
建议用全新的 Python 3.12 虚拟环境,避免依赖污染:
# 1. 从 nightly 源安装最新 vllm
pip install -U vllm --pre \
--index-url https://pypi.org/simple \
--extra-index-url https://wheels.vllm.ai/nightly
# 2. 清掉旧 flashinfer 缓存(老容器必做,见坑一)
rm -rf ~/.cache/flashinfer
⚠️ 跳过
--extra-index-url https://wheels.vllm.ai/nightly会装到旧版 vLLM,后续qwen3_next_mtp推测解码等特性直接不可用。
四、坑三:transformers 补丁修复(partial_rotary_factor 校验 bug)
这一步有两个目的:修复工具调用(tool call)执行 + 修掉 RoPE 校验的一个小 bug。
Qwen3.5 的 rope_parameters 中带有 partial_rotary_factor: 0.25(见 config.json)。旧版 transformers 的 RoPE 参数校验逻辑不认识这个新字段,加载模型时会校验失败。修复方式是:
# 1. 升级 transformers 到指定提交 f2ba019(修复工具调用)
pip install -U "transformers @ git+https://github.com/huggingface/transformers.git@f2ba019"
# 2. 定位 modeling_rope_utils.py 的 651 行做单行补丁
TF_FILE="$(python -m pip show transformers | awk -F': ' '/^Location:/{print $2}')/transformers/modeling_rope_utils.py"
echo "$TF_FILE"
NEW_LINE=' ignore_keys_at_rope_validation = set(ignore_keys_at_rope_validation) | {"partial_rotary_factor"}' \
perl -i.bak -pe 'if ($. == 651) { $_ = $ENV{NEW_LINE} . "\n" }' "$TF_FILE"
补丁本质只有一句话:把 partial_rotary_factor 加入 ignore_keys_at_rope_validation 忽略集合,即"这个字段不参与校验"。perl -i.bak 会自动保留 .bak 备份文件,改坏了可以随时回滚。
五、vLLM 启动命令与关键参数说明
环境就绪后,按 README.md 启动服务:
export OMP_NUM_THREADS=4
vllm serve \
__YOUR_PATH__/Qwen3.5-9B-AWQ \
--served-model-name MY_MODEL \
--swap-space 4 \
--max-num-seqs 8 \
--max-model-len 262144 \
--gpu-memory-utilization 0.9 \
--tensor-parallel-size 1 \
--enable-auto-tool-choice \
--tool-call-parser qwen3_coder \
--reasoning-parser qwen3 \
--speculative-config '{"method":"qwen3_next_mtp","num_speculative_tokens":2}' \
--trust-remote-code \
--host 0.0.0.0 \
--port 8000
| 参数 | 作用 | 新手提示 |
|---|---|---|
--served-model-name MY_MODEL |
对外的模型名 | 调用 API 时 model 字段填这个 |
--max-model-len 262144 |
最大上下文 256K | 显存吃紧可先调小,但官方建议至少保留 128K 以保持思考能力 |
--max-num-seqs 8 |
并发序列上限 | 按显存调节,越大越吃 KV cache |
--gpu-memory-utilization 0.9 |
GPU 显存利用率上限 | 与主机共存时可适当调低 |
--enable-auto-tool-choice + --tool-call-parser qwen3_coder |
自动工具调用 | 依赖坑三的 transformers 升级 |
--reasoning-parser qwen3 |
解析思维链内容 | 默认思考模式,think 标签由解析器剥离 |
--speculative-config ... qwen3_next_mtp |
开启 MTP 推测解码 | 利用模型自带 MTP 头,num_speculative_tokens: 2 |
启动成功后,服务暴露在 http://<host>:8000/v1,可用任意 OpenAI 兼容客户端接入;纯文本场景可加 --language-model-only 跳过视觉编码器、省出显存给 KV cache。
六、常见报错速查表
| 报错 / 现象 | 大概率原因 | 解决方案 |
|---|---|---|
ninja ... returned non-zero exit status 1 |
flashinfer 旧缓存与新版不兼容 | rm -rf ~/.cache/flashinfer 后重启 |
RoPE 参数校验失败(提及 partial_rotary_factor) |
transformers 版本过旧 | 升级到 f2ba019 提交并打 651 行补丁 |
| 工具调用(tool call)解析异常 | transformers 缺少对应修复 | 同上,先升级 transformers |
| OOM / 显存不足 | 256K 上下文 KV cache 较大 | 调小 --max-model-len,或加 --language-model-only |
装不上 qwen3_next_mtp 相关特性 |
vLLM 版本过旧 | 用 nightly 源重装,确认 vllm --version ≥ 0.16.0rc2 |
七、仓库文件一览
| 文件 | 用途 |
|---|---|
| config.json | 模型结构与 AWQ 量化配置(quantization_config、rope_parameters) |
| generation_config.json | 推荐采样参数:temperature=1.0、top_p=0.8、presence_penalty=1.5 |
| chat_template.jinja | 对话模板,支持图文/视频多模态输入 |
| tokenizer.json / vocab.json / merges.txt | 分词器(词表大小 248,320) |
| preprocessor_config.json / video_preprocessor_config.json | 图像 / 视频预处理配置 |
| model-00001-of-00005.safetensors 等 5 个分片 | 约 12GiB 的 AWQ 量化权重 |
| model.safetensors.index.json | 权重分片索引(total_size 约 12.4GB) |
| LICENSE | Apache-2.0 许可 |
八、总结:三行命令避开三个大坑
- 清缓存:
rm -rf ~/.cache/flashinfer,专治 ninja 编译失败; - 对版本:CUDA 12.8 + Python 3.12 新环境,vLLM 从 nightly 源装 ≥ 0.16.0rc2;
- 打补丁:transformers 升到 f2ba019 提交,并在
modeling_rope_utils.py第 651 行忽略partial_rotary_factor校验。
按 README.md 顺序走完这三步,再配合第五节的启动命令,单卡即可稳定跑起 Qwen3.5-9B-AWQ 的 OpenAI 兼容服务,工具调用、思考模式解析与 MTP 加速全部可用。