3分钟在Apple Silicon上跑通Unlimited-OCR-2-6bit:mlx-vlm从零到Markdown输出的新手教程

原创2026-10-29 10:08:151,354 阅读
文章标签:人工智能多模态计算机视觉OCR模型量化本地部署

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,且虚拟环境已激活

📁 关键文件导航

想深入源码时,这些文件最值得先看:

🎯 小结

你现在已经掌握了 Apple Silicon 上运行 OCR 大模型的完整链路:装分支版 mlx-vlm → 一条命令单页识别 → 多页批量解析 → 标签转 Markdown。Unlimited-OCR-2-6bit 用 6-bit 量化 + 稀疏注意力把整页版面解析塞进了 MacBook 的统一内存里,配合温度 0 的确定性输出,非常适合作为本地文档数字化、Markdown 工作流的第一步。

登录后查看全文
Unlimited-OCR-2-6bit