让大模型看懂图片:Mistral-Small-4-119B-2603-GGUF 加载 mmproj 多模态视觉完整指南(F16/F32/BF16 对比)
让大模型看懂图片:Mistral-Small-4-119B-2603-GGUF 加载 mmproj 多模态视觉完整指南(F16/F32/BF16 对比)
Mistral-Small-4-119B-2603-GGUF 是 Mistral Small 4 大模型的 GGUF 量化版仓库,内含 Unsloth Dynamic 2.0 全系列量化分片与 mmproj 视觉投影文件(F16 / F32 / BF16 三种精度),搭配 llama.cpp 即可让本地大模型"看懂图片",支持文档解析、图像问答与视觉推理。
mmproj 是什么?为什么大模型需要它才能"看见"图片 🖼️
Mistral Small 4 本身是多模态模型:接受文本和图片输入,输出文本(见 README.md 中的 Key Features)。但 GGUF 格式里,文本主干与视觉模块是分家存放的:
- 主模型 GGUF 分片:负责语言理解和推理(如 UD-Q4_K_M/ 下的 3 个分片)
- mmproj 文件:视觉投影矩阵(Multi-Modal Projector),把图片编码后的特征"翻译"成主模型能理解的词向量
简单类比:主模型是"大脑",mmproj 是"眼睛和视神经"。只加载主模型不加载 mmproj,模型只能处理纯文本;加上 --mmproj 参数,才真正拥有看图能力。
仓库文件清单:主模型量化版本与 mmproj 视觉文件
本仓库提供 16 种主模型量化 + 3 种精度的 mmproj 文件,常用文件与大小如下:
| 文件(相对路径) | 类型 | 大小 | 说明 |
|---|---|---|---|
| BF16/ | 主模型 | 约 221 GiB | 原始精度,质量最高,显存需求极大 |
| Q8_0/ | 主模型 | 约 117 GiB | 8-bit 量化,质量/体积均衡 |
| UD-Q6_K_XL/ | 主模型 | 约 100 GiB | Unsloth 动态 6-bit |
| UD-Q5_K_XL/ | 主模型 | 约 83 GiB | Unsloth 动态 5-bit |
| UD-Q4_K_XL/ | 主模型 | 约 69 GiB | Unsloth 动态 4-bit |
| UD-Q4_K_M/ | 主模型 | 约 69 GiB | 主流选择,4-bit 中等配置 |
| UD-IQ4_XS/ | 主模型 | 约 54 GiB | 4-bit 小体积 |
| MXFP4_MOE/ | 主模型 | 约 67 GiB | 仅对 MoE 专家用 4-bit |
| mmproj-F16.gguf | 视觉投影 | 817 MiB | 默认推荐 |
| mmproj-BF16.gguf | 视觉投影 | 826 MiB | 与 F16 体积接近,数值范围更宽 |
| mmproj-F32.gguf | 视觉投影 | 1634 MiB | 32 位全精度,体积翻倍 |
| imatrix_unsloth.gguf_file | 量化数据 | 118 MiB | Unsloth 动态量化使用的 imatrix 校准数据 |
💡 所有大文件均通过 Git LFS 存储,本地克隆后如果看到文件只有几百字节,执行
git lfs pull即可拉取完整数据。
mmproj 三精度对比:F16 / F32 / BF16 怎么选?
mmproj 体积不大(0.8 ~ 1.6 GiB),但精度选择直接影响视觉解析效果:
| 精度 | 位数 | 文件大小 | 精度表现 | 适用场景 |
|---|---|---|---|---|
| F16 | 16 位浮点 | 817 MiB | 视觉特征损失极小,llama.cpp 生态默认选择 | 绝大多数用户的默认推荐 ✅ |
| BF16 | 16 位浮点(8 位指数) | 826 MiB | 动态范围更大,数值稳定性好,适合硬件原生支持 bf16 的设备 | 与 F16 二选一,差异通常不可感知 |
| F32 | 32 位浮点 | 1634 MiB | 精度最高,但体积是 F16 的 2 倍 | 对 OCR、图表数字识别等精度要求苛刻的场景 |
选择建议(由快到慢的排查思路):
- 先用 mmproj-F16.gguf 跑通整个流程;
- 如果同一张图识别结果不理想,换 mmproj-F32.gguf 对比,排除视觉模块精度瓶颈;
- F16 与 BF16 体积几乎一致,可按你的 GPU 对 bf16 的硬件支持程度任选其一。
快速启用图片识别:llama.cpp 加载 mmproj 三步走 🚀
本仓库为 llama.cpp 适配了 Unsloth chat template 修复,运行时需要加 --jinja 参数(详见 README.md 顶部提示)。
第 1 步:克隆仓库
git clone https://gitcode.com/hf_mirrors/unsloth/Mistral-Small-4-119B-2603-GGUF
第 2 步:命令行对话(llama-cli)
分片模型只需指定第一个分片,其余会自动加载:
llama-cli \
-m UD-Q4_K_M/Mistral-Small-4-119B-2603-UD-Q4_K_M-00001-of-00003.gguf \
--mmproj mmproj-F16.gguf \
--jinja \
-cnv
进入对话后使用 /read 图片路径 即可发送图片让模型描述。
第 3 步:启动 OpenAI 兼容 API 服务(llama-server)
llama-server \
-m UD-Q4_K_M/Mistral-Small-4-119B-2603-UD-Q4_K_M-00001-of-00003.gguf \
--mmproj mmproj-F16.gguf \
--jinja \
--port 8080
之后用任意 OpenAI SDK 向 http://localhost:8080/v1 发送消息,content 里混合 text 与 image_url(base64 数据或本地图片路径)即可进行图文混合问答。
主模型量化版本怎么选:显存需求速查表
mmproj 只是"眼睛",整体显存/内存消耗大头仍是主模型。以单分片总大小估算最低内存需求(加上约 10~20% 的 KV Cache 与运行时开销):
| 量化版本 | 主模型体积 | mmproj-F16 | 合计参考 | 推荐人群 |
|---|---|---|---|---|
| BF16 | 约 221 GiB | 0.8 GiB | 约 240 GiB | 多卡集群 / 追求原始精度 |
| Q8_0 | 约 117 GiB | 0.8 GiB | 约 128 GiB | 高显存服务器 |
| UD-Q4_K_M | 约 69 GiB | 0.8 GiB | 约 75 GiB | 通用推荐,2×48G 或 1×96G 显存 |
| UD-IQ4_XS | 约 54 GiB | 0.8 GiB | 约 60 GiB | 显存有限,可接受少量精度损失 |
| UD-Q2_K_XL(单文件) | 约 37 GiB | 0.8 GiB | 约 42 GiB | 极致压缩,体验会明显下降 |
模型为 MoE 架构:128 个专家、每 token 激活 4 个(约 6.5B 激活参数),配合 MoE 层 offload 时,CPU + 内存混合部署也能获得不错的生成速度。
常见坑与排查清单 🔍
- 加了
--mmproj却说"我看不了图片":检查是否漏了--jinja;chat template 不匹配会导致多模态消息解析异常(这正是本仓库 Unsloth 修复的重点)。 - F32 mmproj 加载特别慢:它高达 1.6 GiB,首次加载时间明显长于 F16,属正常现象。
--mmproj与主模型版本不配套:本仓库的 mmproj 只适配 Mistral-Small-4-119B-2603 系列,不要与 3.1 / 3.2 其他版本的 mmproj 混用。- 视觉精度不够用:依次尝试 ① 换 F32 mmproj ② 主模型升一档(Q4_K_M → Q5_K_XL → Q8_0),两处的量化误差都会影响最终识别。
- 想自己量化:仓库中的 imatrix_unsloth.gguf_file 就是 Unsloth 动态量化所用的 imatrix 校准文件,可配合 Unsloth 工具链复现同款量化。
总结
- mmproj 是让 Mistral-Small-4-119B-2603-GGUF "看见"图片的视觉投影文件,默认选 F16(817 MiB),精度苛刻场景选 F32(1.6 GiB)。
- 加载方式统一:llama.cpp 命令行加
--mmproj mmproj-F16.gguf --jinja即可,支持llama-cli交互和llama-serverAPI 两种形态。 - 主模型推荐 UD-Q4_K_M(约 69 GiB)起步,配合 mmproj 总内存需求约 75 GiB,即可完整体验多模态视觉、文档解析与视觉推理能力。