图片转文字（OCR/识图）Qwen3-VL-4B-Instruct GGUF 完整部署

环境：macOS12 Intel，16G内存，llama.cpp，Qwen3-VL（视觉大模型，图片理解+OCR），对外OpenAI接口，供ChatBox/AgentScope-Java调用
目标：上传图片 → 模型识别图片里文字/内容，返回文本（图片转文字、截图OCR、图表识别）

一、前置依赖（一次性执行）

1. 安装Xcode命令行工具

xcode-select --install

2. 拉取llama.cpp源码

git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp

二、CMake编译（开启多模态支持，Intel Mac关闭Metal）

rm -rf build
cmake -B build -DGGML_METAL=OFF -DLLAMA_MULTIMODAL=ON -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(sysctl -n hw.ncpu)

✅ 编译成功标志：build/bin目录存在 llama-server 和 llama-mtmd-cli

llama-mtmd-cli 是多模态测试工具，存在=多模态模块编译生效

三、下载模型（推荐组合，16G内存首选）

仓库：Qwen/Qwen3-VL-4B-Instruct-GGUF 下载地址：https://hf-mirror.com/Qwen/Qwen3-VL-4B-Instruct-GGUF/tree/main
需要下载一对文件，缺一不可

1. 主文本模型：Qwen3VL-4B-Instruct-Q4_K_M.gguf（2.5GB）
2. 视觉编码器mmproj：mmproj-Qwen3VL-4B-Instruct-F16.gguf（836MB）

把2个文件复制到：llama.cpp/build/bin

文件说明：

• 主模型：负责文本理解、回答OCR结果
• mmproj：视觉投影层，专门用来解析图片，缺少这个直接报架构加载失败

四、启动 llama-server（OpenAI兼容接口）

cd ~/llama.cpp/build/bin
./llama-server \
-m Qwen3VL-4B-Instruct-Q4_K_M.gguf \
--mmproj mmproj-Qwen3VL-4B-Instruct-F16.gguf \
-c 8192

• -c 8192：上下文窗口。VL模型图片会消耗大量token，不能用2048
• 接口地址：http://127.0.0.1:8080/v1
  ✅ 成功日志：llama_server: model loaded + listening on http://127.0.0.1:8080

备选（内存紧张时），降低上下文窗口：-c 4096

五、接口调用测试（curl，图片转文字）

将图片转为base64，填入下面data:image/jpeg;base64,xxx

curl http://127.0.0.1:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer dummy" \
-d '{
  "model": "qwen3-vl-4b",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type":"text","text":"提取图片里面所有文字"},
        {"type":"image_url","image_url":{"url":"data:image/jpeg;base64,【这里替换图片base64】"}}
      ]
    }
  ]
}'

六、对接客户端

1. ChatBox：填入OpenAI接口，API Key随便填dummy，接口地址http://127.0.0.1:8080/v1
   本地模型设置：
   

本地模型勾选视觉

交互效果：

2. AgentScope-Java：使用OpenAIChatModel，消息体使用content数组（文本+image_url）

---

七、常见报错汇总 + 根因 + 解决方案

报错1：error loading model: unknown model architecture: ''

原因

1. 用llama-server加载文生图模型（Qwen-Image2.1这类，不是识图VL）
2. 多模态模型没有带上--mmproj视觉编码器文件
   解决

• Qwen3-VL必须同时指定 -m 主模型.gguf --mmproj mmproj.gguf
• 确认下载的是Qwen3-VL（看图理解），不是Qwen-Image（文生图）

报错2：request (3180 tokens) exceeds the available context size (2048 tokens), try increasing it

原因
图片编码会转换成大量image token，图片+提示词总token超过启动参数 -c 上下文窗口（你之前遇到的）
解决

1. 启动命令修改 -c 8192，扩大上下文窗口
2. 图片预处理：长边压缩≤1024px，降低JPG质量，不要传4K大图，减少图片token消耗
3. 单次请求只传1张图片，禁止一次性多张图

报错3：启动模型直接崩溃 / Killed / OOM

原因：内存不足，KV缓存+模型权重占用过高
解决

1. 关闭浏览器、大型软件，释放内存
2. 降级上下文：-c 4096 替代8192
3. 更换更小mmproj：mmproj-Qwen3VL-4B-Instruct-Q8_0.gguf，减少视觉编码器内存占用

报错4：ls build/bin 看不到 llama-mtmd-cli

原因：cmake编译时没有开启-DLLAMA_MULTIMODAL=ON，没有编译多模态模块
解决
删除build目录，重新执行完整cmake编译命令，编译完成再检查文件

报错5：curl返回404 Not Found

原因

1. 访问地址缺少末尾 /v1，错误地址 http://127.0.0.1:8080
2. llama-server服务未正常启动，模型加载失败直接退出
   解决
   ✅ 正确baseUrl：http://127.0.0.1:8080/v1，确认llama-server日志显示model loaded

报错6：图片传上去，但模型不识别图片，只回复文本内容

原因

1. base64编码格式错误；图片url前缀必须是data:image/jpeg;base64,
2. message的content写成简单字符串，没有使用数组结构（多模态必须content数组，分开text和image_url）

报错7：ChatBox 图片上传后请求超时

原因：Intel CPU推理速度慢，图片编码耗时久
解决

1. 压缩图片大小，降低分辨率
2. 客户端增加接口超时时间；AgentScope-Java增加http读写超时（180s）

八、优化建议（OCR识图场景）

1. 提示词固定：提取图片里面全部文字，只输出识别的文字，不要额外描述，减少多余输出
2. 图片预处理：长边1024px，JPG70%，图片越小，token越少、速度越快
3. 多轮对话：AgentScope-Java中增加历史消息截断逻辑，防止对话累积token超限

九、区分概念（避坑）

• ✅ Qwen3-VL：视觉大模型，图片理解/OCR识图，输入图片输出文字（本次部署）
• ❌ Qwen-Image：文生图模型，文字生成图片，llama.cpp不支持加载