GOT-OCR2_0-bf16使用指南(上):OCR: 与 OCR with format: 两条指令完全解析(附发票、票据实例)
GOT-OCR2_0-bf16使用指南(上):OCR: 与 OCR with format: 两条指令完全解析(附发票、票据实例)
GOT-OCR2_0-bf16 是 OCR-2.0(GOT-OCR2_0)光学字符识别模型的 bf16 精度 MLX 版本,专为 Apple Silicon(M 系列芯片)本地推理打造,模型体积仅 1.12 GB。它不是聊天模型,只接受两条固定指令:OCR: 输出纯文本、OCR with format: 输出带结构的 Markdown/表格/公式/LaTeX。本文带你 3 分钟跑通 GOT-OCR2_0-bf16,并逐字解析这两条指令的用法、差异与发票、票据识别实例。
一、30 秒认识 GOT-OCR2_0-bf16
在动手前,先弄清楚这个仓库里装的是什么。
- 来源:基于 stepfun-ai 的 GOT-OCR2_0(OCR-2.0,560M 参数)转换而来,用
mlx-vlm0.6.14 转为 MLX 格式 - 精度:bfloat16(未量化),磁盘大小 1.12 GB,峰值内存约 2.5 GB
- 定位:这是保真度最高的参考版本——同为 8-bit / 4-bit 的量化版本都是以它做对照基准的
- 速度:M 系列 Mac 上单图推理约 138.3 tok/s(只统计生成阶段)
核心参数可以在 config.json 中查到:24 层 Transformer、隐藏层 1024、词表 151860、最大上下文 32768(config.json)。
⚠️ 重要提示:该模型需要支持 GOT-OCR 2.0 的 mlx-vlm 版本。目前官方 PR 尚未合入主线,正式发布的
mlx-vlm还无法直接加载本仓库,请使用带该补丁的开发版本。
二、GOT-OCR2_0-bf16 快速启动:一条命令完成 OCR 识别
装好支持 GOT-OCR 2.0 的 mlx-vlm 后,运行下面这条命令即可识别任意文档图片:
python -m mlx_vlm generate \
--model mlx-community/GOT-OCR2_0-bf16 \
--image document.png \
--prompt "OCR: " \
--max-tokens 1024
| 参数 | 作用 |
|---|---|
--model |
指定模型仓库(会自动拉取权重) |
--image |
待识别的图片路径(发票、票据、扫描件等) |
--prompt |
必须是 OCR: 或 OCR with format: 二选一 |
--max-tokens |
最大生成 token 数,长票据建议 1024~2048 |
这条命令来自模型卡 README.md。注意模型内部默认最多生成 4096 个 token(modeling_GOT.py),并用 no_repeat_ngram_size=20 防止复读,推理是贪心解码(do_sample=False),结果稳定可复现。
三、指令一 OCR: :纯文本 OCR 识别(发票、票据首选)
OCR: 是日常最高频的指令:输入一张图片,输出按阅读顺序排列的纯文本,不带任何格式标记。
3.1 识别一张发票
假设 invoice.png 是一张普通发票图片:
python -m mlx_vlm generate \
--model mlx-community/GOT-OCR2_0-bf16 \
--image invoice.png \
--prompt "OCR: " \
--max-tokens 1024
模型输出的示例(示意):
Invoice
No.: INV-2026-0042
Date: 2026-09-15
Bill To: Halberd Components
Address: 3011AB Industrial Park
Item Qty Unit Price Amount
Bearing 6204-2RS 120 $3.20 $384.00
Seal Kit SK-08 40 $5.50 $220.00
Subtotal: $604.00
Tax (8%): $48.32
Total Due: $652.32
可以看到:项目名、数量、单价、税率、金额等字段逐项对齐、数字完整,这正是做票据数据录入、财务归档最想要的形态。
3.2 识别一张购物小票
python -m mlx_vlm generate \
--model mlx-community/GOT-OCR2_0-bf16 \
--image receipt.png \
--prompt "OCR: " \
--max-tokens 1024
输出示例(示意):
SUNRISE MART
12/11/2026 14:32 No.004217
Orange Juice 1L 6.80
Rice 5kg 25.00
Mineral Water x6 9.90
----------------------------------
Subtotal 41.70
Discount -2.00
TOTAL 39.70
Cash 50.00
Change 10.30
模型卡中的实测数据也印证了它的票据能力:在 6 张已知文本的合成文档(发票、实验报告、快递面单、小票、规格表、旋转小票)上,bf16 版本的数字字段召回率(numeric)达到 0.9720,内容级相似度(content)为 0.9605(README.md)。
四、指令二 OCR with format: :结构化输出(表格、公式、乐谱)
OCR with format: 与 OCR: 一字之差,输出却天壤之别:模型会保留版面结构——表格变成 Markdown 表格,数学公式转成 LaTeX,乐谱输出可渲染的符号化谱面。
python -m mlx_vlm generate \
--model mlx-community/GOT-OCR2_0-bf16 \
--image spec_table.png \
--prompt "OCR with format: " \
--max-tokens 2048
一张规格表图片的示例输出(示意):
| Model | Voltage | Current | Power (W) |
|--------|---------|---------|-----------|
| M1 | 12 V | 2.5 A | 30 |
| M2 | 24 V | 1.5 A | 36 |
| M3 | 48 V | 0.8 A | 38.4 |
而一张含数学公式的文档会输出类似:
The energy equation is $E = mc^2$, and the quadratic solution is
$x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$.
4.1 结构怎么来的?看一眼源码就懂
两条指令的分支逻辑写在 chat() 方法里,非常直白(modeling_GOT.py):
if ocr_type == 'format':
qs = 'OCR with format: '
else:
qs = 'OCR: '
也就是说,指令字符串本身就是"模式开关"——模型在训练时就学会了按这两个前缀切换输出风格。这也是为什么 README 特别强调:GOT is not a chat model,任何其他提示词都属于"分布外输入",输出质量没有保证(README.md)。
4.2 输出可以直接渲染成网页
仓库自带渲染工具 render_tools.py,其中 svg_to_html、content_mmd_to_html、tik_html 等函数可以把模型输出的 LaTeX / TikZ / 乐谱内容转成可预览的 HTML;遇到乐谱(含 **kern 标记)时还会调用 verovio 渲染成 SVG(modeling_GOT.py)。
五、两条指令怎么选?发票、票据实例对比
| 对比项 | OCR: |
OCR with format: |
|---|---|---|
| 输出形态 | 纯文本,按阅读顺序 | Markdown 表格 / LaTeX 公式 / 结构化标记 |
| 典型场景 | 发票金额、小票流水、面单编号 | 规格表、数据报表、论文公式、乐谱 |
| token 消耗 | 少 | 多(建议把 --max-tokens 调大) |
| 是否参与精度基准测试 | ✅ 有 6 文档量化数据 | 仅做了运行性验证 |
| 后处理难度 | 直接落库 | 需要解析 Markdown/LaTeX |
选择口诀:
- 只关心"图里写了什么字"(如票据金额录入)→
OCR: - 关心"字的结构关系"(如表格要能复制成 Excel、公式要能编辑)→
OCR with format:
需要说明:模型卡的精度基准(第三节的 0.9720 等数字)只针对 OCR: 路径测试;OCR with format: 路径已验证可正常运行,但没有做真值打分(README.md)。
六、进阶:用坐标框和颜色指定识别区域
两条指令都不止步于"整图识别"。在 modeling_GOT.py 中还能看到两类扩展前缀:
- 按坐标框(bbox):坐标归一化到 0~1000,写在指令前面。例如只识别图片左上 1/4 区域:
[0, 0, 500, 500] OCR:
- 按颜色定位:识别图中特定颜色标注的区域:
[red] OCR:
两者同样兼容 OCR with format: (<a href="https://link.gitcode.com/i/e6bdb7797d08dd84a8cbbaf5652ac465" target="_blank">red] OCR with format: )。此外源码还保留了面向密集页面的多切片模式(OCR upon the patch reference: )和多页模式(OCR with format across multi pages: ,[modeling_GOT.py),适合超密集或跨页文档。
七、仓库文件速览:每个文件负责什么
| 文件 | 说明 |
|---|---|
| README.md | 模型卡:转换细节、精度对照、性能数据 |
| modeling_GOT.py | 模型主体 GOTQwenForCausalLM,含 chat() 指令拼装逻辑 |
| got_vision_b.py | ViT-B 视觉编码器(1024 输入、256 个图像 token) |
| render_tools.py | LaTeX / TikZ / 乐谱输出转 HTML 的渲染工具 |
| tokenization_qwen.py | Qwen 分词器实现(配合 qwen.tiktoken 词表) |
| config.json | 模型结构参数(层数、词表、图像 token 数等) |
| generation_config.json | 生成默认参数(max_new_tokens: 2048) |
| model.safetensors | bf16 权重本体(1.12 GB) |
八、常见问题 FAQ
Q1:为什么提示词换成中文(如"请识别这张发票")输出就乱套?
GOT 不是聊天模型,只训练过 OCR: 与 OCR with format: 两个前缀,其他措辞都属于分布外输入,请严格使用两条指令原文(含末尾空格)。
Q2:bf16 / 8-bit / 4-bit 版本怎么选? 在 6 张测试文档上,8-bit 与 bf16 输出逐字节相同,且更快(210.8 vs 138.3 tok/s)、更省内存(2.06 vs 2.50 GB);4-bit 会丢 1~2 个字段。追求极致保真选本仓库(bf16),日常使用 8-bit 更划算(README.md)。
Q3:识别长文档/密集表格不准怎么办?
优先尝试 OCR with format: 保留表格结构;密集页面可走多切片路径;单张图建议分辨率足够清晰(内部按 1024×1024 处理)。
Q4:支持哪些语言? 模型卡标注为 multilingual,但公开基准测试均为英文合成文档,扫描件、手写体和多语言场景请以实测为准。
九、小结
- GOT-OCR2_0-bf16 = 560M 参数 OCR-2.0 的 bf16 MLX 版,1.12 GB、约 2.5 GB 峰值内存,M 系列 Mac 即可流畅跑
- 只认两条指令:
OCR:出纯文本、OCR with format:出结构化结果,不要改成别的提示词 - 发票、票据等数字密集场景,
OCR:的数字召回率实测 0.9720,可直接用于数据录入 - 进阶玩法:bbox 坐标框、颜色定位、多切片、多页模式一应俱全
下一篇(下)将覆盖 8-bit / 4-bit 量化版本的实测对比与批量识别工程实践,敬请期待。