allenai--olmocr/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

---

一款将 PDF 及其他基于图像的文档格式转换为干净、可读纯文本格式的工具包。

试用在线演示：https://olmocr.allenai.org/

功能特性：

• 将基于 PDF、PNG 和 JPEG 的文档转换为干净的 Markdown
• 支持公式、表格、手写体及复杂排版
• 自动移除页眉和页脚
• 即使存在插图、多栏布局和嵌入内容，也能按自然阅读顺序转换为文本
• 高效，每转换一百万页成本低于 200 美元
• （基于 70 亿参数 VLM（Vision Language Model，视觉语言模型），因此需要 GPU）

新闻

• 2025 年 10 月 21 日 - v0.4.0 - 新模型发布, 通过合成数据将 olmOCR-bench 分数提升约 4 分，并引入 RL（Reinforcement Learning，强化学习）训练。
• 2025 年 8 月 13 日 - v0.3.0 - 新模型发布, 修复了自动旋转检测及空白文档上的幻觉问题。
• 2025 年 7 月 24 日 - v0.2.1 - 新模型发布, 在 olmOCR-Bench, 上得分提高 3 分，同时由于默认采用 FP8，运行速度显著加快，且每份文档所需重试次数大幅减少。
• 2025 年 7 月 23 日 - v0.2.0 - 全新整理的 训练代码, 使自行训练 olmOCR 模型变得更加简单。
• 2025 年 6 月 17 日 - v0.1.75 - 推理流水线从 sglang 切换为基于 vLLM 的实现，Docker 镜像更新至 CUDA 12.8。
• 2025 年 5 月 23 日 - v0.1.70 - 官方 Docker 支持及镜像现已可用！查看 Docker 用法
• 2025 年 5 月 19 日 - v0.1.68 - olmOCR-Bench 发布，得分 77.4。发布版本因提示词相关 bug 修复，olmOCR 流水线性能提升 2 分。
• 2025 年 3 月 17 日 - v0.1.60 - 通过改进采样温度选择提升性能。
• 2025 年 2 月 25 日 - v0.1.58 - 首次公开发布及演示。

基准测试

olmOCR-Bench: 我们还提供一套全面的基准测试套件，涵盖 1,400 份文档中的 7,000 多个测试用例，用于衡量 OCR 系统的性能。

	ArXiv	Old scans math	Tables	Old scans	Headers & footers	Multi column	Long tiny text	Base	Overall
Mistral OCR API	77.2	67.5	60.6	29.3	93.6	71.3	77.1	99.4	72.0±1.1
Marker 1.10.1	83.8	66.8	72.9	33.5	86.6	80.0	85.7	99.3	76.1±1.1
MinerU 2.5.4*	76.6	54.6	84.9	33.7	96.6	78.2	83.5	93.7	75.2±1.1
DeepSeek-OCR	77.2	73.6	80.2	33.3	96.1	66.4	79.4	99.8	75.7±1.0
Nanonets-OCR2-3B	75.4	46.1	86.8	40.9	32.1	81.9	93.0	99.6	69.5±1.1
PaddleOCR-VL*	85.7	71.0	84.1	37.8	97.0	79.9	85.7	98.5	80.0±1.0
Infinity-Parser 7B*	84.4	83.8	85.0	47.9	88.7	84.2	86.4	99.8	82.5±?
Chandra OCR 0.1.0*	82.2	80.3	88.0	50.4	90.8	81.2	92.3	99.9	83.1±0.9
olmOCR v0.4.0	83.0	82.3	84.9	47.7	96.1	83.7	81.9	99.7	82.4±1.1

安装

系统依赖

你需要安装 poppler-utils 以及用于渲染 PDF 图像的额外字体。

安装依赖（Ubuntu/Debian）：

sudo apt-get update
sudo apt-get install poppler-utils ttf-mscorefonts-installer msttcorefonts fonts-crosextra-caladea fonts-crosextra-carlito gsfonts lcdf-typetools

Python 安装

设置 conda 环境并安装 olmocr。运行 olmOCR 的依赖项在现有 Python 环境中较难安装，因此请务必创建一个干净的 Python 环境进行安装。

conda create -n olmocr python=3.11
conda activate olmocr

选择与你的使用场景匹配的安装选项：

选项 1：远程推理（轻量）

如果你计划配合 --server 标志使用远程 vLLM 服务器，请安装基础包：

pip install olmocr

这可避免安装 PyTorch（约 2GB+）等重型 GPU 依赖。

选项 2：本地 GPU 推理

要求：

• 较新的 NVIDIA GPU（已在 RTX 4090、L40S、A100、H100 上测试），至少 12 GB GPU 显存
• 30GB 可用磁盘空间

使用自有 GPU 运行推理：

pip install olmocr[gpu] --extra-index-url https://download.pytorch.org/whl/cu128

# Recommended: Install flash infer for faster inference on GPU
pip install https://download.pytorch.org/whl/cu128/flashinfer/flashinfer_python-0.2.5%2Bcu128torch2.7-cp38-abi3-linux_x86_64.whl

选项 3：Beaker 集群执行

用于向 Beaker 集群提交作业，并配合 --beaker 标志：

pip install olmocr[beaker]

选项 4：基准测试套件

用于运行 olmOCR 基准测试套件：

pip install olmocr[bench]

组合安装

你可以组合多个选项：

# GPU + Beaker support
pip install olmocr[gpu,beaker] --extra-index-url https://download.pytorch.org/whl/cu128

# GPU + Benchmark support
pip install olmocr[gpu,bench] --extra-index-url https://download.pytorch.org/whl/cu128

故障排查

如果遇到与 too many open files 相关的错误，请更新 ulimit：

ulimit -n 65536

使用示例

如需快速测试，可尝试 web demo.

转换单个 PDF（本地 GPU）：

# Download a sample PDF
curl -o olmocr-sample.pdf https://olmocr.allenai.org/papers/olmocr_3pg_sample.pdf

# Convert it to markdown
olmocr ./localworkspace --markdown --pdfs olmocr-sample.pdf

转换图像文件：

olmocr ./localworkspace --markdown --pdfs random_page.png

转换多个 PDF：

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

使用远程推理服务器：

olmocr ./localworkspace --server http://remote-server:8000/v1 --model allenai/olmOCR-2-7B-1025-FP8 --markdown --pdfs *.pdf

配合 --markdown 标志，结果将以 markdown 文件形式保存在 ./localworkspace/markdown/ 内。

注意： 如果你愿意，也可以使用 python -m olmocr.pipeline 代替 olmocr。

查看结果

随后，./localworkspace/ 工作区文件夹将同时包含 Dolma 和 markdown 文件（若使用 --markdown）。

cat localworkspace/markdown/olmocr-sample.md 

olmOCR: Unlocking Trillions of Tokens in PDFs with Vision Language Models
...

使用推理提供商或外部服务器

如果你已在其他地方运行 vLLM 服务器（或任何实现 OpenAI API 的推理平台），可以让 olmOCR 指向它，而无需在本地启动实例。

远程推理安装：

# Lightweight installation - no GPU dependencies needed
pip install olmocr

使用外部服务器：

# Use external vLLM server instead of local one
olmocr ./localworkspace --server http://remote-server:8000/v1 --model allenai/olmOCR-2-7B-1025-FP8 --markdown --pdfs tests/gnarly_pdfs/*.pdf

vLLM 中提供的模型名称必须与 --model 中提供的值一致。

vLLM 服务器启动示例：

vllm serve allenai/olmOCR-2-7B-1025-FP8 --max-model-len 16384

已验证的外部提供商

我们已在以下外部模型提供商上测试 olmOCR-2-7B-1025-FP8，并确认其可用

	$/1M Input tokens	$/1M Output tokens	Example Command
Cirrascale	$0.07	$0.15	olmocr ./workspace --server https://ai2endpoints.cirrascale.ai/api --api_key sk-XXXXXXX --workers 1 --max_concurrent_requests 20 --model olmOCR-2-7B-1025 --pdfs tests/gnarly_pdfs/*.pdf
DeepInfra	$0.09	$0.19	olmocr ./workspace --server https://api.deepinfra.com/v1/openai --api_key DfXXXXXXX --workers 1 --max_concurrent_requests 20 --model allenai/olmOCR-2-7B-1025 --pdfs tests/gnarly_pdfs/*.pdf
Parasail	$0.10	$0.20	olmocr ./workspace --server https://api.parasail.io/v1 --api_key psk-XXXXX --workers 1 --max_concurrent_requests 20 --model allenai/olmOCR-2-7B-1025 --pdfs tests/gnarly_pdfs/*.pdf

参数说明

• --server：定义 OpenAI 兼容端点，例如 https://api.deepinfra.com/v1/openai
• --api_key：你的 API 密钥，通过 Authorization Bearer HTTP 标头传入
• --max_concurrent_requests：同时发往推理提供商的在途请求最大并发数
• --workers：一次处理的最大页面组数量。你可能希望将其设为 1，以便在处理下一组之前先完成当前一组。
• --pages_per_group：你可能希望每组包含更少的页数，因为许多外部提供商的并发请求上限较低
• --model：模型标识符，例如 allenai/olmOCR-2-7B-1025；不同提供商的名称各不相同，若在本地运行，可使用 olmocr
• 其他参数与本地推理时的用法相同

多节点 / 集群用法

如果你想使用多个并行运行的节点将数百万份 PDF 进行转换，olmOCR 支持 从 AWS S3 读取 PDF，并使用 AWS S3 输出存储桶协调任务。

启动第一个工作节点：

olmocr s3://my_s3_bucket/pdfworkspaces/exampleworkspace --pdfs s3://my_s3_bucket/jakep/gnarly_pdfs/*.pdf

这会在你的 AWS 存储桶中建立一个简单的工作队列，并开始转换 PDF。

在后续工作节点上：

olmocr s3://my_s3_bucket/pdfworkspaces/exampleworkspace

它们会自动从同一工作区队列中获取任务。

使用 Beaker 进行集群执行

如果你在 Ai2，并希望借助 beaker, 高效地将数百万份 PDF 线性化，请安装带 Beaker 支持的版本：

pip install olmocr[gpu,beaker] --extra-index-url https://download.pytorch.org/whl/cu128

然后使用 --beaker 标志在本地准备工作区，并在集群中启动 N 个 GPU 工作节点：

olmocr s3://my_s3_bucket/pdfworkspaces/exampleworkspace --pdfs s3://my_s3_bucket/jakep/gnarly_pdfs/*.pdf --beaker --beaker_gpus 4

使用 Docker

拉取 Docker 镜像（体积较大，包含模型，约 30GB）：

docker pull alleninstituteforai/olmocr:latest-with-model

对于希望自行管理模型下载的高级用户，我们还提供不含模型的基础镜像：

docker pull alleninstituteforai/olmocr:latest

快速开始 - 处理 PDF

处理当前目录中的单个 PDF：

docker run --gpus all \
  -v $(pwd):/workspace \
  alleninstituteforai/olmocr:latest-with-model \
  -c "olmocr /workspace/output --markdown --pdfs /workspace/sample.pdf"

处理多个 PDF：

docker run --gpus all \
  -v /path/to/pdfs:/input \
  -v /path/to/output:/output \
  alleninstituteforai/olmocr:latest-with-model \
  -c "olmocr /output --markdown --pdfs /input/*.pdf"

交互模式

以交互方式运行容器，便于探索和调试：

docker run -it --gpus all alleninstituteforai/olmocr:latest-with-model

访问我们在 Docker Hub 上的 Docker 仓库以了解更多信息。

完整文档

要查看所有可用选项：

olmocr --help
usage: pipeline.py [-h] [--pdfs [PDFS ...]] [--model MODEL] [--workspace_profile WORKSPACE_PROFILE] [--pdf_profile PDF_PROFILE] [--pages_per_group PAGES_PER_GROUP] [--max_page_retries MAX_PAGE_RETRIES] [--max_page_error_rate MAX_PAGE_ERROR_RATE] [--workers WORKERS]
                   [--apply_filter] [--stats] [--markdown] [--target_longest_image_dim TARGET_LONGEST_IMAGE_DIM] [--target_anchor_text_len TARGET_ANCHOR_TEXT_LEN] [--guided_decoding] [--gpu-memory-utilization GPU_MEMORY_UTILIZATION] [--max_model_len MAX_MODEL_LEN]
                   [--tensor-parallel-size TENSOR_PARALLEL_SIZE] [--data-parallel-size DATA_PARALLEL_SIZE] [--port PORT] [--server SERVER] [--beaker] [--beaker_workspace BEAKER_WORKSPACE] [--beaker_cluster BEAKER_CLUSTER] [--beaker_gpus BEAKER_GPUS] [--beaker_priority BEAKER_PRIORITY]
                   workspace

Manager for running millions of PDFs through a batch inference pipeline

positional arguments:
  workspace             The filesystem path where work will be stored, can be a local folder, or an s3 path if coordinating work with many workers, s3://bucket/prefix/

options:
  -h, --help            show this help message and exit
  --pdfs [PDFS ...]     Path to add pdfs stored in s3 to the workspace, can be a glob path s3://bucket/prefix/*.pdf or path to file containing list of pdf paths
  --model MODEL         Path where the model is located, allenai/olmOCR-7B-0725-FP8 is the default, can be local, s3, or hugging face.
  --workspace_profile WORKSPACE_PROFILE
                        S3 configuration profile for accessing the workspace
  --pdf_profile PDF_PROFILE
                        S3 configuration profile for accessing the raw pdf documents
  --pages_per_group PAGES_PER_GROUP
                        Aiming for this many pdf pages per work item group
  --max_page_retries MAX_PAGE_RETRIES
                        Max number of times we will retry rendering a page
  --max_page_error_rate MAX_PAGE_ERROR_RATE
                        Rate of allowable failed pages in a document, 1/250 by default
  --workers WORKERS     Number of workers to run at a time
  --apply_filter        Apply basic filtering to English pdfs which are not forms, and not likely seo spam
  --stats               Instead of running any job, reports some statistics about the current workspace
  --markdown            Also write natural text to markdown files preserving the folder structure of the input pdfs
  --target_longest_image_dim TARGET_LONGEST_IMAGE_DIM
                        Dimension on longest side to use for rendering the pdf pages
  --target_anchor_text_len TARGET_ANCHOR_TEXT_LEN
                        Maximum amount of anchor text to use (characters), not used for new models
  --guided_decoding     Enable guided decoding for model YAML type outputs

VLLM arguments:
  --gpu-memory-utilization GPU_MEMORY_UTILIZATION
                        Fraction of VRAM vLLM may pre-allocate for KV-cache (passed through to vllm serve).
  --max_model_len MAX_MODEL_LEN
                        Upper bound (tokens) vLLM will allocate KV-cache for, lower if VLLM won't start
  --tensor-parallel-size TENSOR_PARALLEL_SIZE, -tp TENSOR_PARALLEL_SIZE
                        Tensor parallel size for vLLM
  --data-parallel-size DATA_PARALLEL_SIZE, -dp DATA_PARALLEL_SIZE
                        Data parallel size for vLLM
  --port PORT           Port to use for the VLLM server
  --server SERVER       URL of external vLLM (or other compatible provider)
                        server (e.g., http://hostname:port). If provided,
                        skips spawning local vLLM instance

beaker/cluster execution:
  --beaker              Submit this job to beaker instead of running locally
  --beaker_workspace BEAKER_WORKSPACE
                        Beaker workspace to submit to
  --beaker_cluster BEAKER_CLUSTER
                        Beaker clusters you want to run on
  --beaker_gpus BEAKER_GPUS
                        Number of gpu replicas to run
  --beaker_priority BEAKER_PRIORITY
                        Beaker priority level for the job

代码概览

其中有一些很好的可复用代码片段，也许对你自己的项目有帮助：

• 一种使用 ChatGPT 4o 获得高质量自然语言文本解析的提示策略（prompting strategy）- buildsilver.py
• 按语言进行基础过滤并去除 SEO 垃圾内容 - filter.py
• Qwen2.5-VL 的 SFT 微调代码 - train.py
• GRPO 强化学习（RL）训练器 - grpo_train.py
• 合成数据生成 - mine_html_templates.py
• 使用 VLLM 通过微调模型处理数百万份 PDF - pipeline.py
• 查看由 PDF 生成的 Dolma 文档 - dolmaviewer.py

团队

olmOCR 由 AllenNLP 团队开发并维护，得到 艾伦人工智能研究所（Allen Institute for Artificial Intelligence，AI2）. 的支持 AI2 是一家非营利研究机构，使命是通过高影响力的 AI 研究与工程为人类作出贡献。 若要了解具体有哪些人为本代码库作出贡献，请参阅我们的贡献者 页面。

许可证

olmOCR 采用 Apache 2.0. 许可证 完整许可证副本可在 GitHub. 上找到

引用

引用 olmOCR v1 与 OlmOCR-bench：

@misc{olmocrbench,
      title={{olmOCR: Unlocking Trillions of Tokens in PDFs with Vision Language Models}},
      author={Jake Poznanski and Jon Borchardt and Jason Dunkelberger and Regan Huff and Daniel Lin and Aman Rangapur and Christopher Wilhelm and Kyle Lo and Luca Soldaini},
      year={2025},
      eprint={2502.18443},
      archivePrefix={arXiv},
      primaryClass={cs.CL},
      url={https://arxiv.org/abs/2502.18443},
}

引用 olmOCR v2 Unit Testing Rewards with RL：

@misc{olmocr2,
      title={olmOCR 2: Unit Test Rewards for Document OCR}, 
      author={Jake Poznanski and Luca Soldaini and Kyle Lo},
      year={2025},
      eprint={2510.19817},
      archivePrefix={arXiv},
      primaryClass={cs.CV},
      url={https://arxiv.org/abs/2510.19817}, 
}