如何用Qwen3.5-9B-MTP-GGUF看懂图片与视频?mmproj视觉模型完整实战教程
如何用Qwen3.5-9B-MTP-GGUF看懂图片与视频?mmproj视觉模型完整实战教程
Qwen3.5-9B-MTP-GGUF 是 Qwen3.5-9B 原生多模态大模型的 GGUF 量化权重仓库,搭配仓库内的 mmproj 视觉投影器文件,就能在 llama.cpp 等本地推理框架上让 9B 小模型看懂图片与视频。本教程带你从零完成安装、图片识别、视频理解和量化版本选择,全程只需几条命令行。
一、仓库文件速览:哪些文件负责"看懂"图片?
先认识仓库里的核心文件,README.md 中有完整说明:
| 文件 | 作用 | 说明 |
|---|---|---|
| Qwen3.5-9B-UD-Q4_K_XL.gguf | 语言模型主权重 | 9B 参数,官方示例默认推荐此量化 |
| mmproj-F16.gguf | 视觉投影器(推荐) | 约 880MB,把图片/视频特征转成模型能懂的 token |
| mmproj-BF16.gguf | 视觉投影器 | 约 880MB,精度最高 |
| mmproj-F32.gguf | 视觉投影器 | 约 1.7GB,一般无需使用 |
| imatrix_unsloth.gguf_file | 量化校准数据 | Unsloth Dynamic 2.0 量化时用于保精度 |
为什么需要 mmproj 文件?
语言模型本身不直接处理像素。mmproj(multimodal projector)是视觉编码与投影模块,负责把图片、视频帧的特征向量转换成语言模型可以理解的视觉 token,再喂给 9B 语言模型进行推理。Qwen3.5 采用统一视觉-语言架构(early fusion),视觉理解是"原生"训练出来的,官方视觉基准表现亮眼,例如 VideoMME 84.5、MMMU 78.4、OCRBench 89.2。
💡 简单记忆:
Qwen3.5-9B-*.gguf是"大脑",mmproj-*.gguf是"眼睛",两个文件要配套加载。
二、环境准备:安装 llama.cpp 三步走
仓库官方推荐用 llama.cpp 运行(README.md 顶部给出了完整指南):
- 安装依赖(Linux 示例):
apt-get install pciutils build-essential cmake curl libcurl4-openssl-dev -y - 克隆 llama.cpp 源码:从官方仓库克隆后,用 cmake 指定编译目标
llama-cli、llama-mtmd-cli、llama-server、llama-gguf-split。其中 llama-mtmd-cli 就是多模态命令行工具,是本文主角。- NVIDIA 显卡:cmake 参数加
-DGGML_CUDA=ON - CPU / Apple Metal:改为
-DGGML_CUDA=OFF
- NVIDIA 显卡:cmake 参数加
- 下载模型文件:从本仓库下载主模型权重(如 UD-Q4_K_XL)和配套的 mmproj 文件。
⚠️ 若克隆后发现
.gguf文件只有几百字节,说明是 Git LFS 指针文件,执行git lfs pull拉取真实权重即可。
三、图片识别实战:llama-mtmd-cli 一行命令看图
以官方推荐的 Qwen3.5-9B-UD-Q4_K_XL.gguf + mmproj-F16.gguf 为例:
./llama-mtmd-cli \
-m Qwen3.5-9B-UD-Q4_K_XL.gguf \
--mmproj mmproj-F16.gguf \
-ngl 99 -c 8192 \
--image 你的图片.jpg \
-p "请详细描述这张图片的内容"
关键参数速查:
--mmproj:指定视觉投影器文件(图片/视频能力开关)-ngl 99:全部层放入 GPU,显存不足可改小--image:图片路径,支持一次传多张-p:你的提问文本
采样参数与思考模式
Qwen3.5 默认先"思考"再回答(输出 <think>...</think>)。官方推荐参数:
- 思考模式(通用任务):
temperature=1.0, top_p=0.95, top_k=20, presence_penalty=1.5 - 非思考模式(快速直答):
temperature=0.7, top_p=0.8, top_k=20, presence_penalty=1.5,并传chat_template_kwargs中的enable_thinking: false(新版 llama.cpp 可通过--chat-template-kwargs传入)
看图、OCR 提取文字这类任务建议关闭思考模式,响应更快更简洁。
四、视频理解实战:总结视频内容
把 --image 换成 --video 即可分析视频,模型会自动抽帧理解时序内容:
./llama-mtmd-cli \
-m Qwen3.5-9B-UD-Q4_K_XL.gguf \
--mmproj mmproj-F16.gguf \
--video 你的视频.mp4 \
-p "总结这个视频的内容,按时间线列出关键事件"
实用技巧:
- 默认抽帧率约 2fps(官方 API 文档默认
fps=2, do_sample_frames=True),短视频无需调整 - 小时级长视频:官方建议将视频预处理配置中的
longest_edge调大(对应 224k 视频 token),可获得更高采样率和更好的长视频理解效果 - 该模型视频理解能力突出:VideoMME 84.5(带字幕)、MLVU 84.4、LVBench 70.0,均超过更大参数的 Qwen3-VL-30B-A3B
五、llama-server 部署:给应用提供多模态 API
需要图形界面或接入程序时,用 llama-server 起一个 OpenAI 兼容服务:
./llama-server \
-m Qwen3.5-9B-UD-Q4_K_XL.gguf \
--mmproj mmproj-F16.gguf \
-ngl 99 -c 8192
启动后访问 http://localhost:8080 即可在 Web 界面直接上传图片对话;程序调用则请求 /v1/chat/completions,消息体中用 image_url(支持 base64)传入图片。注意官方明确建议:使用 -hf 或本地多模态推理时保持 -np 1。
六、量化版本怎么选?Q2 到 BF16 完整对比
仓库提供了 Qwen3.5-9B-BF16.gguf 到 Qwen3.5-9B-UD-IQ2_M.gguf 共 20+ 种量化,其中带 UD(Unsloth Dynamic) 前缀的版本采用 Unsloth Dynamic 2.0 动态量化,精度优于普通量化:
| 档位 | 代表文件 | 适合场景 |
|---|---|---|
| 极致低显存 | UD-Q2_K_XL、UD-IQ2_M、UD-Q3_K_XL | 显存紧张,可接受一定精度损失 |
| 均衡推荐 ⭐ | UD-Q4_K_XL、UD-Q5_K_XL | 显存适中(16GB 级别可全量上卡),日常看图看视频首选 |
| 高精度 | UD-Q6_K_XL、UD-Q8_K_XL | 显存充足(24GB 级别),追求接近无损 |
| 全精度 | BF16 | 研究/校准基线,约需 20GB+ |
经验法则:先选 UD-Q4_K_XL + mmproj-F16,显存溢出就降一档,追求质量就升一档;同一语言量化可自由搭配三种 mmproj,但建议统一用 F16 控制体积。
七、MTP 加速与视觉模式的兼容注意事项 ⚠️
这个仓库的特色是内置 MTP(Multi-Token Prediction)投机解码:纯文本场景加两个参数即可提速约 1.5–2 倍:
./llama-server -m model.gguf -ngl 99 -fa on -np 1 \
--spec-type draft-mtp --spec-draft-n-max 6
但必须注意官方在 README.md 中的明确提示:MTP 当前尚不支持与 --mmproj(多模态)及 -np > 1 同时使用。也就是说:
- 跑图片/视频 → 去掉
--spec-type、--spec-draft-n-max等投机解码参数 - 纯文本聊天/写作 → 开启 MTP 享受 1.5–2 倍加速
两者按场景切换,不要混用。
八、常见问题排查
| 问题 | 原因与解决 |
|---|---|
| 模型文件只有几百字节 | Git LFS 未拉取,执行 git lfs pull |
| 加载时显存溢出 (OOM) | 减小 -c 上下文、调低 -ngl,或换更低量化(如 Q3_K_XL) |
| 回答前长时间停顿 | 默认思考模式所致,直答类任务关闭 enable_thinking |
| 图片识别不准 | 确认使用配套 mmproj;显存允许时换 mmproj-BF16 |
| MTP 参数加了反而报错 | 视觉模式暂不兼容投机解码,移除 spec 参数 |
总结
用 Qwen3.5-9B-MTP-GGUF 实现本地看图看视频的核心步骤:UD-Q4_K_XL 主模型 + mmproj-F16 视觉投影器 + llama-mtmd-cli 的 --image / --video 参数,三件套齐备即可开工。9B 的体量让它在 16GB 显存甚至 CPU+核显上也能流畅运行视觉理解,而 MTP 投机解码则让纯文本场景额外再快一倍——这是一个"大小"兼得的多模态本地部署方案。