MTP 投机解码让生成快 2 倍:Qwen3.5-2B-MTP-GGUF 的 draft-mtp 参数完全指南
MTP 投机解码让生成快 2 倍:Qwen3.5-2B-MTP-GGUF 的 draft-mtp 参数完全指南
本仓库提供了 Qwen3.5-2B 模型的 GGUF 量化权重(由 Unsloth Dynamic 2.0 制作,含多步训练 MTP 草稿权重),配合 llama.cpp 的 --spec-type draft-mtp 投机解码参数,本地生成速度可提升约 1.5~2 倍。本文面向新手,手把手讲清 MTP 投机解码原理、draft-mtp 参数用法与常见坑点。
一、MTP 投机解码是什么?为什么能快 2 倍
大模型生成文本是"逐 token 串行输出"的,速度瓶颈明显。投机解码(Speculative Decoding) 的思路是:
- 先用一个小的"草稿模型"快速猜出后面几个 token;
- 主模型一次性并行验证这些猜测;
- 猜对了就直接采纳,猜错则回退重算。
而 MTP(Multi-Token Prediction,多 token 预测)更妙:Qwen3.5 在训练时就已经内置了 MTP 模块,它和主模型同在一个 GGUF 文件里,相当于"自带草稿模型",无需额外下载。这就是本项目名中 -MTP- 的含义。
🚀 官方实测:启用 MTP 投机解码后,Qwen3.5-2B 的生成速度约提升 1.5~2 倍。
llama.cpp 的 MTP 支持 PR 已于 2026 年 5 月 16 日合并进主线,现在克隆最新 llama.cpp 源码即可使用。
二、仓库文件清单:该下载哪个文件?
仓库核心内容如下(均为相对仓库根目录的路径):
| 文件 | 说明 |
|---|---|
| Qwen3.5-2B-UD-Q4_K_XL.gguf | ⭐ 推荐首选:4-bit Unsloth Dynamic 量化,精度与速度平衡最佳 |
| Qwen3.5-2B-Q4_K_M.gguf | 经典 K-quants 4-bit,兼容性好 |
| Qwen3.5-2B-Q8_0.gguf / Qwen3.5-2B-UD-Q8_K_XL.gguf | 8-bit 高精度档,显存充裕时追求最佳质量 |
| Qwen3.5-2B-BF16.gguf | 未量化全精度版,体积最大 |
| mmproj-F16.gguf | 视觉投影文件(多模态用,注意 MTP 模式下的限制,见下文) |
| imatrix_unsloth.gguf_file | 量化校准用的 imatrix 元数据,一般无需手动使用 |
选型建议:
- 显存 ≤ 6 GB:选 Q4_K_M 或 UD-Q4_K_XL(2B 模型 4-bit 约 1.5 GB 级体积)
- 追求质量:显存宽裕直接上 Q8 档
- 仓库内其余 Q3/Q5/Q6 及 IQ 系列(如 Qwen3.5-2B-IQ4_XS.gguf、Qwen3.5-2B-UD-Q6_K_XL.gguf)可按显存大小自由挑选
完整的量化精度说明与性能对比见 README.md。
三、最快启动步骤(CUDA 版)
1. 构建带 MTP 支持的 llama.cpp
安装编译依赖后,克隆最新 llama.cpp 源码(MTP 功能已合并进主线),启用 CUDA 编译:
apt-get update
apt-get install pciutils build-essential cmake curl libcurl4-openssl-dev -y
git clone https://gitcode.com/hf_mirrors/unsloth/Qwen3.5-2B-MTP-GGUF # 权重仓库(本仓库)
# 另需克隆最新 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
💡 CPU / Metal 平台:把
-DGGML_CUDA=ON改为-DGGML_CUDA=OFF即可。
2. 一行命令开启 draft-mtp 加速
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
启动后 llama-server 会在本地提供 OpenAI 兼容 API,把 base_url 指向它即可用各种客户端对话。
四、draft-mtp 参数速查表
| 参数 | 示例值 | 作用 |
|---|---|---|
--spec-type |
draft-mtp |
开启投机解码并指定使用模型内置 MTP 模块做草稿(核心开关) |
--spec-draft-n-max |
6 |
每轮最多"打草稿"的 token 数,越大加速潜力越大,建议从 4~6 试起 |
-ngl |
99 |
全部层放入 GPU,配合 MTP 发挥完整加速效果 |
-c |
8192 |
上下文长度,显存不足时调小 |
-fa on |
on |
启用 Flash Attention,减少显存占用 |
-np |
1 |
并行请求数;MTP 模式下必须保持 1 |
⚠️ 参数改名提示
llama.cpp 在 2026-05-13 已将旧的 --spec-type mtp 重命名为 --spec-type draft-mtp。如果你参考的是旧教程,请统一替换,否则参数不生效。
五、MTP 当前的限制(务必阅读)
- 不支持并行请求:
-np > 1与 MTP 暂时不兼容,单并发下加速最明显; - 暂不支持视觉投影:MTP 模式下
--mmproj尚未支持,即暂时先跑纯文本;需要图片理解时可去掉 spec 参数配合 mmproj-F16.gguf 单独使用; - 上下文别拉满:模型原生支持 262144 token 上下文,但 KV cache 吃显存,OOM 时优先调小
-c。
六、常见问题排查
| 问题 | 原因与解决 |
|---|---|
提示未知参数 draft-mtp |
llama.cpp 版本太旧,重新克隆最新源码编译 |
| 加速不明显 | 检查 -ngl 是否全量上 GPU;把 --spec-draft-n-max 调到 4~6;避免长上下文吃满显存 |
| 启动报 OOM | 降低 -c、换更低 bit 量化(如 Q4_K_M) |
旧命令 --spec-type mtp 无效 |
已改名,使用 --spec-type draft-mtp |
七、小结
Qwen3.5-2B-MTP-GGUF 把 MTP 草稿权重直接做进了 GGUF 文件,只要最新版 llama.cpp 加两行参数 --spec-type draft-mtp --spec-draft-n-max 6,就能零成本获得约 1.5~2 倍的本地生成提速。记住三件事:用新参数名、-np 1、目前 MTP 与 --mmproj 暂不能同用,你就可以放心上手了。🎯