3分钟在Apple Silicon上跑通Unlimited-OCR-2-6bit:mlx-vlm从零到Markdown输出的新手教程
3分钟在Apple Silicon上跑通Unlimited-OCR-2-6bit:mlx-vlm从零到Markdown输出的新手教程
Unlimited-OCR-2-6bit 是百度 Unlimited-OCR-2 OCR 大模型的 MLX 6-bit 量化版本,专为 Apple Silicon(M 系列芯片)设计,可把整页文档图片解析成带版面坐标的结构化文本,再转换为 Markdown。本教程带你用 mlx-vlm 在 3 分钟内完成安装、单页识别到多页批量解析,实现从零到 Markdown 输出的完整流程。
🧐 这是什么模型?为什么选它
在动手之前,先花 30 秒了解你要跑的东西(均来自本仓库配置文件):
| 项目 | 说明 |
|---|---|
| 基座模型 | 百度 Unlimited-OCR-2(image-text-to-text 视觉语言模型) |
| 量化方案 | 语言模型 6-bit affine 量化(group size 64),权重仅约 3.06 GB |
| 视觉塔 | SAM ViT-B + CLIP-L,保持 bfloat16 精度 |
| 语言模型 | 12 层 MoE 架构,每 token 激活 6 个路由专家 + 2 个共享专家 |
| 长上下文 | 支持 131072 token,可解析整页长文档 |
| 解析模式 | Gundam 模式:1 张 1024 全局视图 + 最多 16 张局部裁剪图 |
💡 6-bit 量化把体积压到 ~3GB,让 8GB 统一内存的 Mac 也能跑单页识别;16GB 及以上内存跑多页更从容。
关键配置文件可以直接查看:config.json、generation_config.json。
🍎 硬件与系统要求
- 芯片:M1 / M2 / M3 / M4 系列 Apple Silicon
- 内存:单页短文档 8GB 起步,多页大文档建议 16GB 以上
- 系统:macOS + Homebrew 版 Python(MLX 生态的硬性要求)
# 检查 Python 版本;若没有 Homebrew Python,可先执行:brew install python
python3 --version
# 建议建一个干净虚拟环境,避免依赖污染
python3 -m venv .venv
source .venv/bin/activate
⚡ 第一步:安装 mlx-vlm(约 1 分钟)
Unlimited-OCR-2 的 page2d RoPE 和 DASH 块稀疏注意力支持正在并入 mlx-vlm 上游,在正式发布前,需要先安装包含该支持的分支版本:
pip install -U "git+https://github.com/shuuul/mlx-vlm.git"
安装完成后无需任何其他依赖,一条命令即可调用。
📄 第二步:单页识别,一条命令出结果
mlx_vlm.generate --model mlx-community/Unlimited-OCR-2-6bit --image page.png \
--prompt "Multi page parsing." --max-tokens 8192 --temperature 0
各参数作用一目了然:
--model:模型名。首次运行会自动下载约 3GB 权重并缓存到本地,之后秒开--image:待识别的页面图片,可传 png / jpg--prompt "Multi page parsing.":页面解析的固定提示词--max-tokens 8192:单页输出上限,复杂页面可适当调大--temperature 0:温度为 0,保证输出稳定、可复现
🐢 第一次运行会同时发生"下载权重 + 构建计算缓存",速度偏慢属正常现象,第二次运行明显提速。
📚 第三步:多页批量解析
一次请求可以传入多张图片,每页生成一张 1024 基础视图:
mlx_vlm.generate --model mlx-community/Unlimited-OCR-2-6bit --image p1.png p2.png \
--prompt "Multi page parsing." --max-tokens 16384 --temperature 0
⚠️ 注意:页数越多,--max-tokens 要跟着放大(示例中 2 页给了 16384),否则输出会中途截断。
🔍 读懂输出:从 标签到 Markdown
模型不会直接吐 Markdown,而是输出带版面信息的结构化标签,常用标签有:
<PAGE>:一个页面的起止<BLOCK>label[x0, y0, x1, y1]<FORK>文本:一个内容块,含标签类别和边界框坐标(左上右下四个点)cross_*/append_*:跨越页尾断行、在下一页继续的块,用于跨页拼接
拿到标签文本后,用上游仓库提供的 Markdown 转换器即可把 <BLOCK> 结构渲染成标准 Markdown(保留标题层级、段落与表格位置)。仓库内 modeling_unlimitedocr.py 中的 draw_bounding_boxes 等函数也展示了如何把坐标画回原图,方便校验识别质量。
🩺 常见问题排查清单
| 症状 | 原因与解决 |
|---|---|
| 内存不足 / 进程被杀 | 减少一次输入的页数,调小 --max-tokens,关掉其他大内存应用 |
| 输出重复、乱码 | 确认带了 --temperature 0 |
| 输出被截断 | 多页时 --max-tokens 太小,按需调大 |
| 首次运行很慢 | 正在下载权重和建缓存,重跑命令即可续传,勿中断 |
| pip 安装报错 | 确认使用 Homebrew Python,且虚拟环境已激活 |
📁 关键文件导航
想深入源码时,这些文件最值得先看:
- 官方使用说明:README.md
- 模型配置(量化、MoE、稀疏注意力参数):config.json
- 权重文件(约 3.06 GB):model.safetensors,索引见 model.safetensors.index.json
- OCR 主模型与推理入口(
infer/infer_multi):modeling_unlimitedocr.py - DASH 块稀疏注意力实现:dash_attention.py
- Triton 稀疏 gather 注意力内核:sparse_gather_triton.py 与 sparse_gather_e2e_triton.py
- SAM + CLIP 双视觉编码器:deepencoder.py
- 对话模板:conversation.py、chat_template.jinja
- 分词器与处理器:tokenizer.json、processor_config.json
🎯 小结
你现在已经掌握了 Apple Silicon 上运行 OCR 大模型的完整链路:装分支版 mlx-vlm → 一条命令单页识别 → 多页批量解析 → 标签转 Markdown。Unlimited-OCR-2-6bit 用 6-bit 量化 + 稀疏注意力把整页版面解析塞进了 MacBook 的统一内存里,配合温度 0 的确定性输出,非常适合作为本地文档数字化、Markdown 工作流的第一步。