• 人工智能
• 大模型
• 计算机视觉
• OCR
• 多模态
• 本地部署

ArmorOCR-GGUF 是视觉语言模型 ArmorOCR 的 GGUF 量化版本，基于 Qwen3-VL-8B-Instruct，让你用 Python 三步就能通过OpenAI 兼容 API完成图片文字识别——本地部署、图片不出内网，还能应对旋转、镜像、手写、低对比度等"花式"文字场景。本文带你从零启动服务到写出第一行调用代码。

一、认识 ArmorOCR-GGUF：本地 OCR 为什么选它

ArmorOCR-GGUF 提供两阶段"接地对抗式 OCR 感知"能力的量化权重，专为 llama.cpp 生态设计，包含两档量化：Q8_0（高精度）与Q4_K_M（低显存）。每一档都由「主模型 + 视觉投影器（mmproj）」两个文件组成，仓库内文件如下：

💡注意：mmproj文件必须与主模型同一量化档位配对使用，混用会导致识别异常。

如果你还没有这些模型文件，可以直接克隆项目仓库获取：

git clone https://gitcode.com/hf_mirrors/inclusionAI/ArmorOCR-GGUF

二、第1步：启动 OpenAI 兼容服务

1. 准备 llama.cpp 运行环境（开启 CUDA）

克隆 llama.cpp 官方源码后执行以下命令编译：

cmake -B build -DGGML_CUDA=ON && cmake --build build --config Release export LLAMA_BIN=$(pwd)/build/bin

2. 一条命令拉起服务

serve_gguf.sh接收两个参数：量化档位和端口，默认端口 8080：

# 进入模型文件所在目录后执行 GGUF_PREFIX=Qwen3VL-SafetyOCR-EP3 bash serve_gguf.sh Q8_0 8080

⚠️易踩坑点：serve_gguf.sh 中默认文件前缀是ArmorOCR，而本仓库实际文件名前缀是Qwen3VL-SafetyOCR-EP3，因此需要通过环境变量GGUF_PREFIX指定；如果你把文件重命名为ArmorOCR-Q8_0.gguf，则直接使用默认值即可。

脚本内部调用了llama-server，关键参数含义如下：

服务启动后，本地即拥有一个与 OpenAI 接口完全兼容的端点：http://127.0.0.1:8080/v1/chat/completions。

三、第2步：Python 调用 OCR 接口（核心 3 小步）

整个调用只分三小步：① 读图转 base64 → ② 发送请求 → ③ 取回结果，完整代码如下：

import base64, requests # 小步1：读取图片，编码为 base64 Data URL with open("path/to/image.png", "rb") as f: img_url = f"data:image/jpeg;base64,{base64.b64encode(f.read()).decode()}" # 小步2：向 OpenAI 兼容端点发送「图片 + 指令」 resp = requests.post("http://127.0.0.1:8080/v1/chat/completions", json={ "model": "ArmorOCR-GGUF", "messages": [{"role": "user", "content": [ {"type": "image_url", "image_url": {"url": img_url}}, {"type": "text", "text": ("Please identify the text in the image. " "Put your reasoning inside <analyze></analyze> " "and your final recognized text inside <answer></answer>.")}, ]}], "temperature": 0.0, "max_tokens": 1024, }, timeout=600) # 小步3：取出识别结果 print(resp.json()["choices"][0]["message"]["content"])

几个关键参数的含义：

• temperature: 0.0：OCR 任务要求结果稳定可复现，关闭随机采样；
• max_tokens: 1024：限制输出长度，避免回答发散；
• 提示词中的<analyze>/<answer>：让模型先输出推理过程，再在<answer>标签内给出最终识别文本，这是官方 Quickstart 推荐的两段式提示写法（见 README.md）；
• timeout: 600：首图推理可能较慢，超时时间要放宽。

四、第3步：解析结果与常见问题排查

1. 用一行正则提取纯文本

回答里包含推理过程，通常只想要<answer>里的最终结果：

import re text = resp.json()["choices"][0]["message"]["content"] m = re.search(r"<answer>(.*?)</answer>", text, re.S) print(m.group(1).strip() if m else text)

2. 常见问题速查表

五、Q8_0 还是 Q4_K_M？量化档位怎么选

两档量化在 AdvSpot 基准上的表现（数据来自 README.md，base为原始模型）：

📌选型建议：显存充足（如 24G 以上）优先Q8_0，准确率甚至略高于原始模型；显存紧张或追求更高吞吐时选Q4_K_M，绝大多数能力依然保留，IoU 仅轻微下降——这与视觉编码器被量化的预期一致。

写在最后

回顾一下 Python 3 步搞定图片文字识别的完整路径：

1. 启动：GGUF_PREFIX=Qwen3VL-SafetyOCR-EP3 bash serve_gguf.sh Q8_0 8080，一条命令获得 OpenAI 兼容端点；
2. 调用：Python 中读图转 base64，POST /v1/chat/completions发送图片与指令；
3. 解析：从choices[0].message.content中用<answer>标签提取最终识别文本。

整个流程无需任何云 API Key，图片数据完全留在本地，非常适合隐私敏感场景下的 OCR 自动化流水线。更多评测细节可参阅 README.md，服务启动逻辑详见 serve_gguf.sh。

• 人工智能
• 大模型
• 计算机视觉
• OCR
• 多模态
• 本地部署