复杂 PDF 转 Markdown,olmOCR 保姆级上手指南

这周 GitHub Trending weekly 里，allenai/olmocr 排到第 20。它不是又一个“截图识字”小工具，而是 Ai2 做的一套开源 PDF 线性化流水线：把 PDF、PNG、JPEG 这类文档，转成更适合大模型读取、训练和 RAG 入库的干净文本。

说白了，olmOCR 解决的是一个很烦但很真实的问题：PDF 看起来像文章，内部却经常像一堆带坐标的字块。两栏论文、表格、页眉页脚、公式、扫描件、手写字混在一起时，普通 OCR 很容易把阅读顺序搞乱，或者把页码、脚注、标题栏都塞进正文。

如果你做过知识库、论文解析、合同抽取、企业文档清洗，应该懂这种痛。

这个项目到底强在哪

AI智能体学习网站：ai-agent-phd.com

olmOCR 的核心思路很直接：不要只按 PDF 内部字符顺序抽文本，而是把页面当成视觉文档交给 7B 级视觉语言模型处理，让模型输出自然阅读顺序下的 Markdown。

它重点保留这些东西：

• 标题和段落结构
• 多栏文档的阅读顺序
• 表格，通常用 HTML table 更稳
• 数学公式，尽量用 LaTeX
• 手写体、旧扫描件、复杂排版
• 自动去掉页眉、页脚、页码一类噪声

项目目前的默认主线是 olmOCR 2。README 里写得很清楚：它基于 7B 参数 VLM，需要 GPU；如果你只是小规模试用，可以走在线 demo 或远程推理服务。

我看的是 2026-07-06 的仓库状态：最新 release 是 v0.4.27，主分支最新可见提交在 2026-03-25。最近提交偏维护，真正的大版本变化在 v0.4.0：新模型 olmOCR-2-7B-1025-FP8、合成数据、RL 训练。

论文笔记：它不是只发了代码

AI智能体学习网站：ai-agent-phd.com

这个项目有两份公开技术报告。

第一篇是《olmOCR: Unlocking Trillions of Tokens in PDFs with Vision Language Models》。它讲的是 v1：用 GPT-4o 给大约 26 万页 PDF 生成高质量线性化文本，再拿这些数据微调 Qwen2-VL-7B-Instruct。论文还提出 olmOCR-Bench，用 1400 多个 PDF 页面、7000 多个可验证测试来评估 OCR。

关键不是“又做了个 benchmark”，而是测试方式更像软件单元测试。

比如：

• 某段文字必须出现
• 某个页眉页脚不应该出现
• A 段应该在 B 段前面
• 表格里某个单元格和邻居关系要对
• 公式渲染后符号位置要能匹配

这点很聪明。OCR 错一个数学下标，编辑距离可能只差一个字符，但意思已经变了。用 pass/fail 测试，反而更接近真实使用。

第二篇是《olmOCR 2: Unit Test Rewards for Document OCR》。它讲的是 v2 的核心升级：把“单元测试”不只用于评测，还用于训练奖励。

olmOCR 2 的做法大概是这样：

2. 从真实 PDF 页面出发，生成带明确 HTML 源的合成文档。
4. 从 HTML 里自动抽出可验证测试。
6. 用这些测试做 RLVR，也就是可验证奖励强化学习。
8. 再用 GRPO 训练，并对多次 RL 结果做 checkpoint averaging。

结果是 benchmark 分数从初代的 68.2 提到 82.4，提升主要在公式、表格、多栏布局这些传统 OCR 容易翻车的场景。

但要说句实话：论文发布时它可以说是很强的 SOTA；到了今天，Hugging Face 的 olmOCR-bench leaderboard 已经出现更高分模型。olmOCR 现在最有价值的地方，不只是分数，而是模型、数据、训练代码、推理流水线、benchmark 基本都开放，许可证也友好。

这对工程团队更重要。

保姆级上手：先别急着装满 GPU 依赖

AI智能体学习网站：ai-agent-phd.com

如果你只是想试一下效果，最省事的路线是官方 demo：

https://olmocr.allenai.org/

它能上传文档试跑，但网页也提醒了：demo 是顺序处理页面，真要吞吐量，还是用 toolkit 的批处理。

想本地跑，建议用 Linux 或 WSL2。README 明确建议干净的 conda 环境，因为依赖重。

先装系统依赖：

sudoapt-getupdate
sudoapt-getinstallpoppler-utilsttf-mscorefonts-installermsttcorefontsfonts-crosextra-caladeafonts-crosextra-carlitogsfontslcdf-typetools

建环境：

condacreate-nolmocrpython=3.11
condaactivateolmocr

如果你准备用远程 vLLM 或 OpenAI-compatible endpoint，本地只装轻量包：

pipinstallolmocr

然后这样跑：

olmocr./localworkspace\
--serverhttp://remote-server:8000/v1\
--modelallenai/olmOCR-2-7B-1025-FP8\
--markdown\
--pdfssample.pdf

输出会在：

./localworkspace/markdown/

如果你有本地 NVIDIA GPU，再装 GPU 版：

pipinstallolmocr[gpu]--extra-index-urlhttps://download.pytorch.org/whl/cu128

官方建议的硬件门槛不低：近期 NVIDIA GPU，至少 12GB 显存，另准备 30GB 左右磁盘空间。别拿办公本硬跑，体验会很差。

本地单文件转换：

olmocr./localworkspace--markdown--pdfsolmocr-sample.pdf

图片也可以：

olmocr./localworkspace--markdown--pdfsrandom_page.png

批量 PDF：

olmocr./localworkspace--markdown--pdfs./pdfs/*.pdf

如果你懒得处理 CUDA 依赖，Docker 是更稳的路：

dockerpullalleninstituteforai/olmocr:latest-with-model

但这个镜像很大，README 标的是约 30GB。网络慢、磁盘小的机器，别硬上。

参数怎么调，才不容易踩坑

最常用的参数就几个。

--markdown：一定要加。它会额外生成 Markdown 文件，不然你主要拿到的是 workspace 里的 JSONL 结果。

--server：指定外部推理服务。有 vLLM 或 OpenAI-compatible 服务时，用它可以绕过本地 GPU 依赖。

--model：模型名要和服务端一致。本地一般用 allenai/olmOCR-2-7B-1025-FP8。

--workers 和 --max_concurrent_requests：吞吐量开关。小批量别乱调大，先从保守值开始。

--pages_per_group：按页面分组。远程服务并发限制小的时候，可以调小一点。

--apply_filter：会做基础过滤。做数据集清洗时有用；如果只是忠实转换业务 PDF，先别开。

--stats：目前主要用于 S3 workspace 的统计，不是本地小样本必需品。

最稳的入门命令就是这一条：

olmocr./localworkspace--markdown--pdfs./pdfs/*.pdf

确认结果、速度、显存占用都没问题，再上多 worker、远程 server、S3 workspace。

想评测自己的 OCR？olmOCR-Bench 可以直接用

olmOCR-Bench 很值得单独看。它不是让大模型当裁判，也不是简单比编辑距离，而是把 PDF 页面拆成一组可验证问题。

安装 benchmark 依赖：

pipinstallolmocr[bench]
playwrightinstallchromium

下载数据：

huggingface-clidownload--repo-typedataset--resume-downloadallenai/olmOCR-bench--local-dir./olmOCR-bench

跑评测：

python-molmocr.bench.benchmark--dir./olmOCR-bench/bench_data

如果你在做文档解析产品，它能告诉你到底是公式错、表格错、多栏顺序错，还是页眉页脚没清掉。比一句“效果不错”有用多了。

训练和微调：能做，但别轻易开工

仓库里有训练代码，不是摆设。训练文档给了 olmOCR-mix-1025 的准备方式，也给了 released model 对应配置。

但成本不小。

官方训练指南里提到，完整训练集大约 27 万页，单个 B200 级别 GPU 上一次训练可能要 24 到 48 小时。GRPO 更重，示例是 8 张 H100。

所以我的建议很简单：

• 只是转文档：直接用现成模型。
• 内部文档格式很固定：先积累失败样本，再考虑 LoRA 微调。
• 做 OCR 模型研究：再读训练目录和 synth 数据生成代码。

不要为了“可微调”三个字上头。大多数团队缺的不是训练入口，而是一批标干净的失败样本。

适合谁，不适合谁

适合：RAG 文档入库、论文/教材/合同/报告批处理、LLM 训练语料清洗、OCR benchmark 研究。

不适合：只想免费识别几张发票、没有 GPU 也不想用远程服务、需要版面坐标级还原的人。

还有一个现实限制：olmOCR 2 主要按英文文档训练和评测。中文文档不是完全不能试，但别默认它在中文场景也有同样表现。上线前一定要用自己的文档集测。

我的最终判断

olmOCR 值得收藏，但别把它当轻量小工具看。它更像“面向大模型数据工程的 PDF 清洗流水线”。

如果目标是把复杂 PDF 变成可读 Markdown，它很强；如果目标是做高吞吐、可复现、能评测的文档解析，它更强。

我的实用建议：

• 新手先用 demo 看效果。
• 工程试点优先用远程推理，少折腾 CUDA。
• 有稳定吞吐需求，再上 Docker 或本地 GPU。
• 生产前必须拿自己的 PDF 跑一轮对比，重点看表格、公式、多栏、页眉页脚。
• 中文文档、扫描烂图、强版式还原，不要只看 README，要自己测。

一句话结论：如果你的 PDF 最终是要喂给 LLM，olmOCR 值得进工具箱；如果你只是想“随便 OCR 一下”，它可能有点重。

资料入口：

• GitHub: https://github.com/allenai/olmocr
• Demo: https://olmocr.allenai.org/
• v1 技术报告: https://arxiv.org/abs/2502.18443
• v2 技术报告: https://arxiv.org/abs/2510.19817
• Hugging Face 模型集合: https://huggingface.co/collections/allenai/olmocr