Qwen3.5-2B-MTP-GGUF 部署排错手册:-np 并行与 mmproj 为何不能和 MTP 同用?

原创2026-11-11 20:08:281,860 阅读

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 > 1 and --mmproj are 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 秒排错清单

  1. 🔑 启动失败先查参数名:MTP 必须写 --spec-type draft-mtp(不是 mtp)。
  2. 🔑 带 -np > 1 或 --mmproj 报错:删掉二者之一——要 MTP 加速就 -np 1 且不加 --mmproj;要图文理解就去掉投机解码参数。
  3. 🔑 无独显 / Mac 用户:编译时改 -DGGML_CUDA=OFF,-ngl 相应调低。
  4. 🔑 显存 OOM:优先调小 -c(上下文)和 --spec-draft-n-max,再换更低的量化档位。

按这份手册操作后,绝大多数 Qwen3.5-2B MTP GGUF 的本地部署报错都能快速定位解决。🚀

登录后查看全文
Qwen3.5-2B-MTP-GGUF