你可能已经用 llama.cpp 在本地跑通了纯文本模型，现在手头有一批图片要做 OCR 或图表问答，于是想：既然框架都装好了，顺手接个视觉模型行不行？这篇不给你打包票，而是把「能不能跑、跑到什么程度、什么情况下别硬上」拆开讲，并给出一套从查支持清单到实测吞吐的检查顺序。
你可能已经用 llama.cpp 在本地跑通了纯文本模型，现在手头有一批图片要做 OCR 或图表问答，于是想：既然框架都装好了，顺手接个视觉模型行不行？答案不是简单的能或不能，而是要看模型、看附件、看你怎么用。这篇不给你打包票，而是把「能不能跑、跑到什么程度、什么情况下别硬上」拆开讲。
先把心理预期放对：llama.cpp 是推理引擎，它做的是「把别人做好的视觉能力加载进来」，不是自己训练出一双眼睛。所以问题会变成三个子问题——你选的模型家族有没有多模态变体、视觉附件跟主权重对不对得上、你的场景值不值得用本地推理硬扛。下面按查支持、备文件、跑服务、看限制、自测的顺序过一遍。
先分清：llama.cpp 支持的是「接入多模态」，不是「什么视觉模型都能跑」
llama.cpp 本身并不自带视觉能力。它的多模态支持来自两部分：一个能处理图像输入的主模型文件，外加一个视觉投影附件（一般叫 mmproj 那一类文件）。这两个必须配套，来源一致、量化档位一致，版本错开最典型的表现就是加载直接失败，或者能加载但输出一堆不相干的字。
- 支持的视觉模型是一个有限集合，不是全量覆盖。某款模型到底有没有适配，以仓库里的示例脚本和转换工具为准，别只看模型主页上的宣传图
- 遇到「能加载但答非所问」，九成是投影文件选错、跟主权重不匹配，或者量化档位对不上，不是模型本身不行
- 纯文本模型不受这套影响，加上视觉附件之后文本能力一般不会掉，但显存占用会明显上升，小显存机器要提前留余量
- 同一款模型不同量化档位的视觉表现可能差挺多，别默认「小档位能跑就等于能用」
| 现象 | 大概率原因 | 先查什么 |
|---|---|---|
| 启动就报加载失败 | 主权重和投影文件不配套 | 两个文件是否来自同一份发布、量化档位是否一致 |
| 能加载但答非所问 | 投影文件选错或档位不匹配 | 换回官方推荐的附件组合重试一次 |
| 图片一多就卡住或崩 | 显存/内存不够 | 到站内测算页核对参数量与显存口径 |
| 纯文本正常、带图就慢 | 图像编码本身开销大 | 先用低分辨率单图做基线，再逐步加码 |
真要跑起来：按「查支持 → 备文件 → 起服务 → 试一张图」四步走
别一上来就丢一叠扫描件。按下面四步走，每一步都有明确的验证点，出问题时能立刻知道是哪一层出的错。
- 查支持先确认你要用的模型家族有没有视觉变体，到 /models 看模型资料，到 /models/deploy 核对参数量和显存口径，再看 /multimodal 里同类模型的实际可用情况。三步都过了再动手下文件。
- 备文件主权重和视觉投影两个文件都要下载，量化档位保持一致。把两个路径都写进启动参数，缺一个都会报错。下完先核对文件名和来源，别混用不同发布的文件。
- 起服务先只加载主模型跑一次纯文本对话，确认没问题；再加视觉附件重启。这样一旦报错，你能马上判断是主模型的问题还是附件的问题。
- 试一张图从单图、单问题、低分辨率开始，跑通后再加多图或高分辨率。每次只改一个变量，比如先加图数，再加分辨率，不要一次全上。
跑通第一张图之后，别急着庆祝。真正的分水岭是「同一张图反复跑，结果稳不稳」。稳了才叫能用，偶尔对一次只能叫跑通过。到 /tools/speed-test 和 /usage 看一眼你自己的基线数据，心里有个数。
现阶段的限制：别拿它去顶替专门的多模态方案
llama.cpp 的好处是本地、可控、不依赖外部服务；代价是它在多模态这条路上还属于「能用但不全能」。下面这几条限制不是劝退，是提醒你提前判断场景合不合适。
- 图片数量和分辨率一上去，显存和耗时涨得很快。长文档批量 OCR 这种活，不适合用单机本地推理硬扛，用专门方案更省事
- 对中文票据、密集表格的理解容易漏字或串行，输出结果必须人工抽检，尤其涉及金额和编号的地方，别直接进流程
- 多轮带图的对话里，历史图片怎么保留、按什么粒度截断，各家实现不一致，容易把上下文撑爆，用之前先想好保留策略
- 并发是弱项。多人同时传图，排队时间会比纯文本明显拉长。如果你只是自己偶尔用几张图，这个短板基本无所谓
什么情况下别硬上？简单说：要处理成百上千张图、要求稳定结构化输出、或者多人在线同时用，这三条中任意一条成立，就应该先去 /sites 看看有没有现成的多模态服务更合适，而不是花时间调本地组合。反过来说，只是个人做几张图的小任务、或者内网不方便外发数据，本地跑反而是优势。
自测清单：用「能不能稳定复现」代替「跑没跑通」
| 样本类型 | 主要看什么 | 不通过的话 |
|---|---|---|
| 清晰印刷体 | 识别是否完整、有无错字 | 先查投影文件和量化档位 |
| 拍照歪斜 | 是否还能抓对内容 | 确认是否做了预处理，或换更稳的模型 |
| 含表格图片 | 行列有没有串 | 降低分辨率重试，或缩小任务范围 |
| 纯文字截图 | 长文本有没有截断 | 检查上下文长度设置 |
把这四类样本固定下来，同一批反复跑，不要每次换新图。记录三项：单张图的等待时间、显存峰值、结果里明显出错的位置。把「偶尔一次答对」和「同一张图十次里八次答对」严格分开看，前者不能作为选型依据。
如果连续几次结果波动很大，先降分辨率或换量化档位再试；还不行，就说明这个组合不适合你的场景，别继续在这上面加时间。判断标准很简单：同一批样本、同样的参数，结果能稳定复现，才算过关；复现不了，就换方案。
跑通一张图说明不了什么，同一张图反复跑都稳，才叫能用。下一步先到 /multimodal 看看同类模型的实际可用情况，再用自己的样本按上面的清单跑一遍，比看任何宣传都靠谱。→
常见问题
llama.cpp 能跑多模态模型吗？
能跑一部分，但前提是主权重和视觉投影文件配套、量化档位一致、框架版本匹配。它不支持「任意视觉模型随便加载」，具体到某一款有没有适配，要在模型支持清单和示例脚本里确认，别只看模型页面的宣传。
本地跑视觉模型，显存要按什么口径算？
不能只看参数量，要把主权重、视觉投影、图像编码时的中间激活和上下文一起算进去。按纯文本模型估出来的数字通常会偏小。建议到 /models/deploy 用当时的测算口径过一遍，再用小图实测峰值显存校正。
为什么我的模型能加载，但一传图就报错或输出乱码？
常见三种原因：漏了视觉投影文件、主权重和投影文件量化档位不匹配、框架版本与模型转换脚本对不上。先把两个文件路径都写全并核对档位，再退回纯文本对话确认主模型正常，然后逐层加回图片输入。
