Qwen3.5-9B-MTP-GGUF 部署完全指南:CUDA、Metal 与 CPU 环境一次配齐
Qwen3.5-9B-MTP-GGUF 部署完全指南:CUDA、Metal 与 CPU 环境一次配齐
本文带你从零开始部署 Qwen3.5-9B-MTP-GGUF——这是 Qwen3.5-9B 大模型的 GGUF 量化系列,内置 MTP(Multi-Token Prediction)多词元预测能力,生成速度可提升约 1.5~2 倍。指南覆盖 CUDA 显卡、Mac Metal 与纯 CPU 三种环境的完整配置步骤,并附量化版本选型表与常见报错解决方案。
一、这个仓库里有什么?
README.md 中官方给出的核心卖点很直接:MTP 投机解码让生成提速约 1.5~2 倍。仓库提供 21 种量化文件 + 3 个视觉投影文件,按体积从大到小排列如下:
| 文件 | 体积(约) | 适用场景 |
|---|---|---|
| Qwen3.5-9B-BF16.gguf | 18.4 GB | 24GB+ 显存,精度优先 |
| Qwen3.5-9B-Q8_0.gguf | 9.8 GB | 12GB+ 显存 |
| Qwen3.5-9B-UD-Q8_K_XL.gguf | 13.2 GB | Unsloth 动态量化,高精度 |
| Qwen3.5-9B-Q6_K.gguf / UD-Q6_K_XL | 7.7 / 9.0 GB | 12GB 显存主力档 |
| Qwen3.5-9B-Q5_K_M.gguf / UD-Q5_K_XL | 6.7 / 6.9 GB | 8~12GB 显存 |
| Qwen3.5-9B-Q4_K_M.gguf / UD-Q4_K_XL | 5.9 / 6.1 GB | 推荐起步档,8GB 显存可跑 |
| Qwen3.5-9B-Q4_K_S.gguf / IQ4_XS / IQ4_NL | 5.3~5.6 GB | 8GB 显存紧凑方案 |
| Qwen3.5-9B-Q3_K_M.gguf / UD-Q3_K_XL / UD-IQ3_XXS | 4.3~5.0 GB | 6GB 显存 / 低配机器 |
| Qwen3.5-9B-UD-Q2_K_XL.gguf / UD-IQ2_M | 4.0~4.4 GB | CPU / 4GB 显存极限方案 |
💡 UD 前缀是 Unsloth Dynamic 2.0 动态量化,官方称其精度优于同级常规量化(见 README.md),同档位下优先选 UD 系列。
另外三个文件值得注意:
- mmproj-BF16.gguf、mmproj-F16.gguf、mmproj-F32.gguf:视觉编码器投影文件,供多模态推理使用;
- imatrix_unsloth.gguf_file:量化时使用的 imatrix 统计文件,一般无需手动处理。
二、获取模型文件
推荐方式:克隆本仓库(注意文件走 Git LFS,克隆后需拉取实际权重):
git lfs install
git clone https://gitcode.com/hf_mirrors/unsloth/Qwen3.5-9B-MTP-GGUF
cd Qwen3.5-9B-MTP-GGUF
git lfs pull
⚠️ 克隆后可检查文件大小:若文件只有几百字节,说明仍是 LFS 指针未拉取,重新执行 git lfs pull 即可。
如果你的机器能直连 Hugging Face,也可以跳过克隆,在 llama-server 中直接用 -hf unsloth/Qwen3.5-9B-MTP-GGUF:UD-Q4_K_XL 在线拉取(官方命令见 README.md)。
三、编译 llama.cpp:CUDA、Metal、CPU 通用
MTP 功能于 2026-05-16 正式并入 llama.cpp 主分支,因此直接编译最新版即可,无需再切分支。
apt-get update
apt-get install pciutils build-essential cmake curl libcurl4-openssl-dev -y
# 克隆 llama.cpp 最新源码,然后按硬件类型编译:
三种环境只差一个编译开关:
| 环境 | CMake 配置 |
|---|---|
| NVIDIA CUDA | -DGGML_CUDA=ON |
| Mac Metal / CPU | -DGGML_CUDA=OFF |
cmake llama.cpp -B llama.cpp/build \
-DBUILD_SHARED_LIBS=OFF -DGGML_CUDA=ON # Metal/CPU 请改为 OFF
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 官方构建流程一致。
四、启动服务:一条命令配齐 MTP 加速
以 CUDA 环境 + UD-Q4_K_XL 量化为例:
./llama.cpp/llama-server \
-m Qwen3.5-9B-UD-Q4_K_XL.gguf \
-ngl 99 -c 8192 -fa on -np 1 \
--spec-type draft-mtp --spec-draft-n-max 6
参数逐个拆解(官方示例见 README.md):
| 参数 | 作用 | 说明 |
|---|---|---|
-m |
模型文件路径 | 也可用 -hf 仓库名:量化 在线加载 |
-ngl 99 |
卸载层数到加速器 | 99 表示尽量全部卸载;CPU 环境删除该参数 |
-c 8192 |
上下文长度 | 显存不足时调小 |
-fa on |
开启 Flash Attention | 省显存 |
-np 1 |
并行批次 | ⚠️ MTP 模式下目前只支持 1 |
--spec-type draft-mtp |
启用 MTP 投机解码 | 旧写法 --spec-type mtp 已于 2026-05-13 更名,见 README.md |
--spec-draft-n-max 6 |
每步最大草稿词元数 | 官方推荐值 |
服务启动后,浏览器访问 http://localhost:8080 即可使用内置 WebUI 对话。
各环境差异速查
- NVIDIA 显卡:按上面命令执行即可,MTP 加速效果最佳;
- Mac(Metal):编译时用
-DGGML_CUDA=OFF,启动命令不变,-ngl 99会自动走 Metal 后端; - 纯 CPU:编译和启动都去掉 GPU 相关参数(不加
-ngl),建议选 UD-Q3_K_XL 或更小的量化以控制内存占用,MTP 草稿步同样可生效。
五、采样参数推荐
README.md 给出的官方建议值:
| 模式 | 参数组合 |
|---|---|
| 思考模式(通用任务) | temperature=1.0, top_p=0.95, top_k=20, presence_penalty=1.5 |
| 思考模式(精密编码) | temperature=0.6, top_p=0.95, top_k=20, presence_penalty=0.0 |
| 指令模式(通用) | temperature=0.7, top_p=0.8, top_k=20, presence_penalty=1.5 |
另外两点实用建议:
- 模型默认处于思考模式,回复前会先输出
think推理内容(见 README.md);如需直接回答,在请求中传入chat_template_kwargs: {"enable_thinking": false}; - 上下文若出现 OOM 报错,优先调小
-c;复杂推理任务建议至少保留 128K 上下文以维持思考能力。
六、常见问题排查
Q1:为什么我不能一边开 MTP 一边传图片?
目前 MTP 模式与 --mmproj(视觉投影)以及 -np > 1 尚不兼容(README.md)。需要多模态时,去掉 --spec-type draft-mtp 相关参数,改为:
./llama.cpp/llama-server -m Qwen3.5-9B-UD-Q4_K_XL.gguf \
-mmproj mmproj-F16.gguf -ngl 99 -c 8192 -fa on
Q2:速度提升明显吗? 官方数据为约 1.5~2 倍的生成提速(README.md),长回复、代码生成场景收益最直观。
Q3:显存不够装不下选中的量化怎么办?
按"权重体积 + 上下文缓存 ≈ 总占用"估算:8GB 显存选 4~5GB 档的 Q4/Q3 量化,把 -c 控制在 8K~16K;再小就选 UD-Q2_K_XL。
Q4:下载下来的文件打不开、提示格式错误?
十有八九是 LFS 指针未拉取(真实文件只有约 136 字节),执行 git lfs pull 重新拉取即可。
七、小结
| 你的硬件 | 推荐配置 |
|---|---|
| NVIDIA 12GB+ | UD-Q6_K_XL + -ngl 99 + MTP |
| NVIDIA / Mac 8GB | UD-Q4_K_XL + -ngl 99 + MTP |
| 低显存 / 纯 CPU | UD-Q3_K_XL 或更小量化,去掉 -ngl |
三步走:克隆仓库拉 LFS → 按硬件编译 llama.cpp(-DGGML_CUDA 开关)→ llama-server 加 --spec-type draft-mtp 启动。配齐之后,你得到的就是一个带 MTP 加速、可在三种计算平台间自由切换的 Qwen3.5-9B 本地服务 ✅