复杂 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 的做法大概是这样：

从真实 PDF 页面出发，生成带明确 HTML 源的合成文档。
从 HTML 里自动抽出可验证测试。
用这些测试做 RLVR，也就是可验证奖励强化学习。
再用 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