GOT-OCR2_0-8bit 部署指南:用 mlx-vlm 把高速本地 OCR 集成进你的 Mac 应用
GOT-OCR2_0-8bit 部署指南:用 mlx-vlm 把高速本地 OCR 集成进你的 Mac 应用
GOT-OCR2_0-8bit 是 GOT-OCR2.0 光学字符识别(OCR)模型的 8-bit MLX 量化版本,专为 Apple Silicon Mac 打造。搭配 mlx-vlm 框架,你可以在本地以 689 MB 的模型体积、约 210 tok/s 的速度完成文档识别,全程离线、隐私无忧,轻松把高速本地 OCR 集成进你的 Mac 应用。
⚙️ 为什么选择 8-bit 量化版
这个仓库由 mlx-vlm 0.6.14 转换而来,目标是把 5.6 亿参数的 OCR-2.0 模型高效跑在 M 系列芯片上。它的几个关键指标值得细看:
| 指标 | 数值 |
|---|---|
| 量化位宽 | 8-bit(group size 64,affine 模式) |
| 磁盘体积 | 约 689 MB |
| 生成速度 | 210.8 tok/s(M 系列 Mac 实测) |
| 峰值内存 | 2.06 GB |
| 精度 | 与 bf16 原版逐字节一致(6 份文档零差异) |
量化策略很克制:只有语言模型被量化,视觉塔(Vision Tower)和投影器(Projector)仍保持 bf16。官方测试显示,8-bit 版本在发票、实验报告、快递面单、小票等 6 份文档上的输出与未量化版逐字节相同,而速度却快了约 53%(bf16 为 138.3 tok/s,占用 2.50 GB)。也就是说,量化几乎"免费"——你拿到的是纯性能收益。
💡 想更省内存、更快?仓库同系列还有 4-bit 版本(272.9 tok/s / 1.83 GB),代价是字符错误率(CER)从 0 升至 0.0116。生产环境建议优先 8-bit。
✅ 部署前检查清单
在开始之前,请确认你的 Mac 满足以下条件:
- ✅ Apple Silicon 芯片(M1 及以上;Intel Mac 不支持 MLX 后端)
- ✅ Python 环境,建议 Python 3.10+
- ✅ 已安装
mlx(0.32.0)与mlx-vlm(0.6.14 或更高) - ✅ 至少 4 GB 可用内存(实测峰值仅 2.06 GB)
⚠️ 重要提示:mlx-vlm 对 GOT-OCR 2.0 的支持目前仍在相关 PR(Blaizzy/mlx-vlm#1908)中,尚未合并。这意味着直接 pip install 的最新发布版可能无法加载本仓库,你需要基于包含该 PR 的源码自行构建 mlx-vlm。这是部署前唯一需要留意的门槛。
🚀 三步完成本地 OCR 部署
第 1 步:安装 mlx-vlm
pip install mlx-vlm
若需 GOT-OCR 2.0 支持,请从包含 PR #1908 的源码分支构建安装(pip install -e .),README 中有明确说明。
第 2 步:加载模型并识别纯文本
python -m mlx_vlm generate \
--model mlx-community/GOT-OCR2_0-8bit \
--image document.png \
--prompt "OCR: " \
--max-tokens 1024
首次运行会自动下载模型并缓存到本地,之后完全离线可用。一条命令,几秒出结果。
第 3 步:切换为结构化识别模式
python -m mlx_vlm generate \
--model mlx-community/GOT-OCR2_0-8bit \
--image table.png \
--prompt "OCR with format: " \
--max-tokens 2048
📝 记住这两个"魔法提示词"
GOT 不是聊天模型,它只认两条指令,其他提示词都属于分布外输入,识别质量无法保证:
| 提示词 | 作用 |
|---|---|
OCR: |
纯文本识别(默认场景) |
OCR with format: |
结构化输出(表格、公式、五线谱) |
提示词的拼装逻辑可以参考仓库内的 modeling_GOT.py,其中还演示了如何附加裁剪框(bbox)和颜色定位等进阶参数。
🔌 集成进你的 Mac 应用
在你的应用代码中,建议启动时加载一次模型、之后复用,避免每次识别都重新加载:
from mlx_vlm import load_model, generate
# 应用启动时加载一次(约几秒)
model, processor = load_model("mlx-community/GOT-OCR2_0-8bit")
# 之后每次识别只需传图片与提示词
output = generate(model, processor, "OCR: ", image="receipt.png", max_tokens=1024)
参数名以你所装 mlx-vlm 版本的实际 API 为准。得益于 210 tok/s 的生成速度与 2 GB 的内存占用,即使在小内存 Mac 上,把 OCR 做成应用内的实时功能也毫无压力。
📂 仓库关键文件导览
| 文件 | 说明 |
|---|---|
| README.md | 模型卡片:量化参数、精度与速度实测数据 |
| model.safetensors | 689 MB 的 8-bit 量化权重本体 |
| model.safetensors.index.json | 权重分片索引 |
| config.json | 模型与量化配置(8-bit / group_size 64) |
| generation_config.json | 生成默认参数(max_new_tokens 2048) |
| modeling_GOT.py | 参考实现,含提示词构建逻辑 |
| got_vision_b.py | ViT-B 视觉编码器 |
| tokenization_qwen.py | Qwen 分词器实现 |
| qwen.tiktoken | BPE 词表 |
| tokenizer_config.json | 分词器配置 |
| special_tokens_map.json | 特殊 token 映射 |
| render_tools.py | SVG 渲染工具 |
⚠️ 使用边界与注意事项
官方 README 明确标注了以下未测试范围,使用时请留意:
- 精度测试仅覆盖标准 1024×1024 单裁剪路径;细粒度区域模式、密集页面多裁剪、多页模式未纳入测试
- 测试样本为 6 份英文合成文档;真实扫描件、手写体与多语言表现未经此处验证
OCR with format:模式做了冒烟测试可正常运行,但未做精度打分
🔎 常见问题
Q:加载模型时报错,提示架构不支持? 确认你的 mlx-vlm 是否包含了 GOT-OCR 2.0 支持(PR #1908),发布版可能尚未包含。
Q:8-bit 和 4-bit 怎么选? 追求零精度损失选 8-bit(与 bf16 输出逐字节一致);追求极限速度与最低内存选 4-bit(272.9 tok/s / 1.83 GB),可接受极小误差。
Q:需要联网吗?数据会上传吗? 模型下载后完全离线推理,文档图片不出本机,天然适合处理敏感票据与合同。
📌 小结:GOT-OCR2_0-8bit 用 689 MB 的体积换来了与全精度一致的识别效果和 210+ tok/s 的本地速度。只要你的 Mac 是 Apple Silicon 芯片,配合支持 GOT-OCR 2.0 的 mlx-vlm,三条命令即可拥有一台私有的高速 OCR 引擎——把它嵌入你的笔记、发票或文档应用,只差一步。