Qwen3.5-2B-MTP-GGUF 部署排错手册:-np 并行与 mmproj 为何不能和 MTP 同用?
Qwen3.5-2B-MTP-GGUF 部署排错手册:-np 并行与 mmproj 为何不能和 MTP 同用?
Qwen3.5-2B-MTP-GGUF 是 Unsloth 提供的 Qwen3.5-2B 多 Token 预测(MTP)版 GGUF 量化模型仓库,可直接用 llama.cpp 本地部署。本手册专为新手解答两个高频报错点:为什么 -np 并行和 --mmproj 视觉投影不能与 MTP 同时开启,并附完整参数排错清单与量化版本选择指南。
快速上手:MTP 模式下唯一正确的启动命令
MTP(Multi-Token Prediction,多 Token 预测)是 Qwen3.5 的"内置草稿模型",在生成时让主模型一次校验多个草稿 Token,官方宣称可将生成速度提升 1.5~2 倍。
先编译支持 MTP 的 llama.cpp(CPU/Metal 用户请设置 -DGGML_CUDA=OFF):
apt-get install pciutils build-essential cmake curl libcurl4-openssl-dev -y
git clone https://github.com/ggml-org/llama.cpp
cmake llama.cpp -B llama.cpp/build -DBUILD_SHARED_LIBS=OFF -DGGML_CUDA=ON
cmake --build llama.cpp/build --config Release -j --clean-first \
--target llama-cli llama-mtmd-cli llama-server llama-gguf-split
cp llama.cpp/build/bin/llama-* llama.cpp
然后启动服务(来自 README.md):
export LLAMA_CACHE="unsloth/Qwen3.5-2B-MTP-GGUF"
./llama.cpp/llama-server \
-hf unsloth/Qwen3.5-2B-MTP-GGUF:UD-Q4_K_XL \
-ngl 99 -c 8192 -fa on -np 1 \
--spec-type draft-mtp --spec-draft-n-max 6
✅ 关键记忆点:MTP 模式下必须写 -np 1,且不要加 --mmproj。下面逐一解释原因。
排错一:为什么 -np 并行不能和 MTP 同用?
报错现象
如果你把并行会话数调大(例如 -np 4),启动时会失败或生成结果异常。README 中明确写道:
-np > 1and--mmprojare not yet supported with MTP. (-np > 1和--mmproj目前尚不支持与 MTP 同时使用。)
原因解释(通俗版)
- MTP 是"逐会话"的投机解码:每个会话都要维护自己的草稿 Token 状态和校验队列。
-np是多会话并行批处理:llama.cpp 会把多个会话的 Token 拼成一批计算,与 MTP 的单会话草稿校验流程存在冲突。- 两者叠加时,llama.cpp 尚无法保证草稿与校验的对应关系正确,因此官方直接禁用该组合,而不是"性能差一点"。
多用户并发怎么办?
| 方案 | 做法 | 适用场景 |
|---|---|---|
| 单进程单会话 | -np 1(推荐,保住 MTP 加速) |
个人使用、单 Agent 调用 |
| 多进程实例 | 启动多个 llama-server,各自 -np 1 且端口不同 |
需要并发又想要 MTP 加速 |
| 服务端框架 | 用 SGLang / vLLM 等框架服务,框架层做并发调度 | 生产级多用户 |
💡 简单说:想要 MTP 加速就接受"单会话",想要多会话就放弃 MTP,二者暂时不可兼得。
排错二:为什么 mmproj 视觉投影不能和 MTP 同用?
仓库里的视觉文件
本仓库包含三种精度的视觉投影文件,供开启图文/视频理解时使用:
| 文件 | 精度 | 说明 |
|---|---|---|
| mmproj-BF16.gguf | BF16 | 推荐,精度与体积平衡 |
| mmproj-F16.gguf | F16 | 半精度 |
| mmproj-F32.gguf | F32 | 全精度,体积最大 |
冲突原因
--mmproj 会加载视觉编码器,把图像/视频 Token 混入主模型输入序列。而 MTP 的草稿-校验机制目前只针对纯文本 Token 流实现,视觉 Token 会打乱草稿的上下文对齐,因此同样被官方禁用。
两种取舍,按需选择
路线 A:要速度(纯文本场景)
./llama.cpp/llama-server \
-hf unsloth/Qwen3.5-2B-MTP-GGUF:UD-Q4_K_XL \
-ngl 99 -c 8192 -fa on -np 1 \
--spec-type draft-mtp --spec-draft-n-max 6
路线 B:要视觉(图文/视频理解场景)
./llama.cpp/llama-server \
-hf unsloth/Qwen3.5-2B-MTP-GGUF:UD-Q4_K_XL \
-ngl 99 -c 8192 -fa on -np 1 \
--mmproj mmproj-BF16.gguf
(去掉 --spec-type,用 llama-mtmd-cli 或 server 的多模态接口即可)
⚠️ 注意:Qwen3.5 本身是统一视觉-语言架构,不带 mmproj 并非不能看图,只是 MTP 加速路径当前不支持带视觉输入。
参数速查:MTP 部署常见坑位
| 参数 | 作用 | 排错要点 |
|---|---|---|
-np |
并行会话数 | MTP 下固定 1,超过 1 报错 |
--mmproj |
加载视觉投影文件 | MTP 下不可用,二选一 |
--spec-type |
投机解码类型 | 旧参数 mtp 已于 2026-05-13 改名为 draft-mtp,用旧值会启动失败 |
--spec-draft-n-max |
单步最大草稿 Token 数 | 官方示例为 6,显存紧张可调小 |
-ngl |
GPU 卸载层数 | 99 表示尽量全部上 GPU;显存不足时降低或改用 CPU 混合 |
-c |
上下文长度 | Qwen3.5 原生支持 262,144,但 OOM 时先调小 |
-fa on |
Flash Attention | 开启可省显存,建议保留 |
-DGGML_CUDA |
编译开关 | 无 NVIDIA 显卡 / Apple Metal 时设为 OFF |
量化版本怎么选:UD 动态量化优先
仓库提供了 20 个量化档位(含 Unsloth 动态量化 UD 系列,精度优于传统固定量化)。按显存/内存选择:
| 文件 | 定位 |
|---|---|
| Qwen3.5-2B-UD-Q4_K_XL.gguf | ⭐ 默认推荐,README 示例同款 |
| Qwen3.5-2B-UD-Q2_K_XL.gguf / Qwen3.5-2B-UD-IQ2_M.gguf | 极限低内存(笔记本、树莓派级) |
| Qwen3.5-2B-UD-Q5_K_XL.gguf / Q6_K.gguf / Q8_0.gguf | 显存充足时追求更高保真 |
| Qwen3.5-2B-IQ4_XS.gguf / IQ4_NL.gguf / Q4_K_M.gguf | 经典 4-bit 档位,兼容性最好 |
| Qwen3.5-2B-BF16.gguf | 原始精度(约 4 GB 起步),仅调试基准用 |
其余档位(Q3/Q5 等)在仓库根目录均有,命名规则一致:Q数字 = 平均位宽,UD = Unsloth 动态混合量化,XL = 大文件分片友好版本。
总结:30 秒排错清单
- 🔑 启动失败先查参数名:MTP 必须写
--spec-type draft-mtp(不是mtp)。 - 🔑 带
-np > 1或--mmproj报错:删掉二者之一——要 MTP 加速就-np 1且不加--mmproj;要图文理解就去掉投机解码参数。 - 🔑 无独显 / Mac 用户:编译时改
-DGGML_CUDA=OFF,-ngl相应调低。 - 🔑 显存 OOM:优先调小
-c(上下文)和--spec-draft-n-max,再换更低的量化档位。
按这份手册操作后,绝大多数 Qwen3.5-2B MTP GGUF 的本地部署报错都能快速定位解决。🚀