Qwen3.5-9B-MTP-GGUF 部署完全指南:CUDA、Metal 与 CPU 环境一次配齐

原创2026-10-19 15:33:541,915 阅读

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 系列。

另外三个文件值得注意:

二、获取模型文件

推荐方式:克隆本仓库(注意文件走 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 本地服务 ✅

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