如何用Qwen3.5-9B-MTP-GGUF看懂图片与视频?mmproj视觉模型完整实战教程

原创2026-10-19 14:58:061,371 阅读

如何用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 顶部给出了完整指南):

  1. 安装依赖(Linux 示例):apt-get install pciutils build-essential cmake curl libcurl4-openssl-dev -y
  2. 克隆 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
  3. 下载模型文件:从本仓库下载主模型权重(如 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 投机解码则让纯文本场景额外再快一倍——这是一个"大小"兼得的多模态本地部署方案。

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