GOT-OCR2_0-8bit 使用指南:OCR 与 OCR with format 两种 Prompt 的完整用法拆解
GOT-OCR2_0-8bit 使用指南:OCR 与 OCR with format 两种 Prompt 的完整用法拆解
GOT-OCR2_0-8bit 是 560M 参数 OCR-2.0 大模型的 8-bit 量化版本,专为 Apple Silicon(M 系列芯片)通过 MLX 框架做 OCR 识别推理设计。它的用法非常"克制":模型只认两种 Prompt——OCR: 用于纯文本识别,OCR with format: 用于输出表格、公式、乐谱等结构化结果。本文把这两种 Prompt 的用法、差异和进阶变体一次讲透,帮你零踩坑跑通本地 OCR。
GOT-OCR2_0-8bit 是什么?
先了解背景,再动手:
- 📦 模型来源:基于 stepfun-ai/GOT-OCR2_0(OCR-2.0),经
mlx-vlm0.6.14 转换为 MLX 格式 - 🧮 量化规格:8-bit 量化(group size 64,affine 模式),磁盘占用约 689 MB,有效位宽 9.851 bit/weight
- 🖥️ 目标平台:Apple Silicon Mac,单图推理峰值内存约 2.06 GB,实测约 210 tok/s
- ⚠️ 不是聊天模型:GOT 只接受上面提到的两条指令,写任何其他 Prompt(比如"请帮我翻译这张图")都属于分布外输入,输出不可靠
核心模型定义在 modeling_GOT.py,量化参数记录在 config.json 的 quantization 字段中。
两种 Prompt 怎么选?
这是全文最重要的部分。模型源码里对指令的选择逻辑非常直白(见 modeling_GOT.py):
if ocr_type == 'format':
qs = 'OCR with format: '
else:
qs = 'OCR: '
| 对比项 | OCR: |
OCR with format: |
|---|---|---|
| 用途 | 纯文本识别 | 结构化内容识别 |
| 适用场景 | 发票、票据、书页、通知等纯文字 | 表格、数学公式、乐谱 |
| 输出形式 | 纯文本,保留原始行文 | 带结构标记(如表格、LaTeX 公式、MusicXML) |
| 精度验证 | 官方已用 6 份文档打分,与 bf16 完全一致 | 官方仅做了冒烟测试(可正常运行) |
| 渲染支持 | 无 | 可配合 render_tools.py 把公式/乐谱渲染成 HTML 预览 |
一句话选择原则:图里是"文字"就用 OCR: ;图里有"表格、公式、五线谱"就用 OCR with format: 。
OCR: —— 纯文本识别
最常见的场景。它会把图片中的文字按阅读顺序转成纯文本,不做格式加工。官方精度表中六份合成文档(发票、化验单、快递面单、收据、规格表、旋转收据)的 field / content / numeric 三项得分,8-bit 版与 bf16 版逐字节一致——也就是说 8-bit 量化对纯文本识别几乎无损。
OCR with format: —— 结构化识别
当文档包含表格、公式或乐谱时,这条指令会让模型输出"带骨架"的结果:表格会带上行列结构,公式以 LaTeX 风格呈现,乐谱则生成可渲染的符号化数据。
模型内置了配套的渲染工具链(见 render_tools.py 中的 svg_to_html、content_mmd_to_html、tik_html),可以把识别出的公式或乐谱渲染成 HTML 页面,方便肉眼核对识别质量。
💡 小贴士:结构化输出的长度通常比纯文本更长(表格/公式的标记符号多),建议把
--max-tokens调大一些,例如 1024 以上。
快速上手:三步跑通推理
⚠️ 前提:需要带有 GOT-OCR 2.0 支持的 mlx-vlm(该 PR 尚未合入正式版,已发布的 mlx-vlm 无法加载本仓库)。
python -m mlx_vlm generate \
--model mlx-community/GOT-OCR2_0-8bit \
--image document.png \
--prompt "OCR: " \
--max-tokens 1024
- 换成结构化识别,只需把
--prompt改为"OCR with format: " - 注意指令结尾带一个空格,这是训练时的固定格式,不要删
生成参数(max_new_tokens 等)定义在 generation_config.json。
进阶 Prompt 变体:区域与颜色识别
除了两条基础指令,源码还支持在指令前加"定位前缀"(见 modeling_GOT.py):
| 变体 | 指令形式 | 说明 |
|---|---|---|
| 区域识别(box) | [x0, y0] OCR: 或 [x0, y0, x2, y2] OCR: |
只识别指定坐标区域(坐标为千分比) |
| 颜色识别(color) | [red] OCR with format: |
按文字颜色提取,例如只取红色批注 |
此外,针对密集长页还有多切片(multi-crop)路径 chat_crop,它会把大图动态切成 1~6 块分别识别,对应指令为 OCR with format upon the patch reference: ,适合文字密集的整页扫描。
这些变体属于高级用法,新手建议先用好两条基础指令。
8-bit 量化值得信任吗?
仓库作者在 README.md 中给出了完整数据,这里挑重点:
| 精度档位 | 文档识别 content 得分 | 数字恢复 numeric 得分 | 速度 tok/s | 峰值内存 |
|---|---|---|---|---|
| bf16 | 0.9605 | 0.9720 | 138.3 | 2.50 GB |
| 8-bit(本仓库) | 0.9605 | 0.9720 | 210.8 | 2.06 GB |
| 4-bit | 0.9474 | 0.9623 | 272.9 | 1.83 GB |
结论很清晰:🔹 8-bit 在测试集上输出与 bf16 完全相同,速度却快了约 50%,内存还更省;🔹 4-bit 略有精度损失,追求极致速度才考虑。
常见问题与避坑
- 输出乱码/答非所问? 99% 是 Prompt 写错了。GOT 不是聊天模型,只接受
OCR:和OCR with format:,且冒号后必须保留空格。 - 表格识别成乱行? 换用
OCR with format:,并增大--max-tokens。 - 模型加载失败? 检查
mlx-vlm是否包含 GOT-OCR 2.0 支持(README.md 中已标注版本要求)。 - 图片太模糊、是拍照而非扫描件? 官方精度验证基于清晰渲染文档,手写体与实拍扫描件效果可能下降,建议先提高图像质量。
- 单图路径之外的高级模式(区域/颜色/多页)尚未做精度验证,请以实际输出为准。
相关文件速查
| 文件 | 作用 |
|---|---|
| modeling_GOT.py | 模型主体,包含 chat / chat_crop 推理入口与 Prompt 拼装逻辑 |
| got_vision_b.py | 视觉塔(ViT-B,保持 bf16 未量化) |
| config.json | 模型结构配置与 8-bit 量化参数 |
| generation_config.json | 生成默认参数(max_new_tokens 2048 等) |
| tokenization_qwen.py / qwen.tiktoken | Qwen 词表分词器及 BPE 数据 |
| render_tools.py | 公式/乐谱渲染工具(SVG→HTML、TikZ 等) |
| model.safetensors | 8-bit 量化权重(约 689 MB) |
总结:记住两条指令就掌握了这个模型 90% 的用法——纯文本用 OCR: ,表格公式乐谱用 OCR with format: ;其余都是锦上添花的进阶变体。