allenai/olmocr

来源: https://github.com/allenai/olmocr

将 PDF 及其他基于图像的文档格式转换为清晰、可读的纯文本格式的工具包。
试玩在线演示: https://olmocr.allenai.org/

特性:

• 将 PDF、PNG 和 JPEG 格式的文档转换为干净的 Markdown
• 支持公式、表格、手写及复杂排版
• 自动移除页眉和页脚
• 转换为具有自然阅读顺序的文本，即使存在图形、多栏布局和内嵌内容
• 高效，每百万页转换成本低于 200 美元
• （基于 7B 参数 VLM，因此需要 GPU）

新闻

• 2025 年 10 月 21 日 - v0.4.0 - 新模型发布 (https://huggingface.co/allenai/olmOCR-2-7B-1025-FP8)，通过合成数据将 olmOCR-bench 得分提升约 4 分，并引入 RL 训练。
• 2025 年 8 月 13 日 - v0.3.0 - 新模型发布 (https://huggingface.co/allenai/olmOCR-7B-0825-FP8)，修复了自动旋转检测和空白文档幻觉问题。
• 2025 年 7 月 24 日 - v0.2.1 - 新模型发布 (https://huggingface.co/allenai/olmOCR-7B-0725-FP8)，在 olmOCR-Bench (https://github.com/allenai/olmocr/tree/main/olmocr/bench) 上得分提高 3 分，由于默认采用 FP8，运行速度也显著提升，每个文档所需的重试次数大大减少。
• 2025 年 7 月 23 日 - v0.2.0 - 全新整理后的训练器代码 (https://github.com/allenai/olmocr/tree/main/olmocr/train)，让自行训练 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 (https://github.com/allenai/olmocr/tree/main/olmocr/bench) 发布，得分 77.4。该发布因提示修复为 olmOCR 管线带来 2 分性能提升。
• 2025 年 3 月 17 日 - v0.1.60 - 通过更好的采样温度选择实现性能改进。
• 2025 年 2 月 25 日 - v0.1.58 - 初始公开发布及演示。

基准测试

olmOCR-Bench (https://github.com/allenai/olmocr/tree/main/olmocr/bench): 我们还附带了一套全面的基准测试套件，涵盖超过 1400 个文档的 7000 多个测试用例，帮助衡量 OCR 系统的性能。

安装

系统依赖

你需要安装 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：远程推理（轻量级）
如果你计划使用远程 vLLM 服务器并指定 --server 参数，安装基础包即可：

pip install olmocr  

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

方式 2：本地 GPU 推理
要求：

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

运行本地 GPU 推理：

pip install olmocr[gpu] --extra-index-url https://download.pytorch.org/whl/cu128  
# 推荐：安装 flash infer 以加速 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 支持  
pip install olmocr[gpu,beaker] --extra-index-url https://download.pytorch.org/whl/cu128  
# GPU + Benchmark 支持  
pip install olmocr[gpu,bench] --extra-index-url https://download.pytorch.org/whl/cu128  

故障排除
如果遇到 too many open files 错误，请更新你的 ulimit：

ulimit -n 65536  

使用示例

快速测试可尝试网页演示 (https://olmocr.allen.ai/)。

转换单个 PDF（本地 GPU）：

# 下载示例 PDF  
curl -o olmocr-sample.pdf https://olmocr.allenai.org/papers/olmocr_3pg_sample.pdf  
# 转换为 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 (https://github.com/allenai/dolma) 和 markdown 文件（如果使用了 --markdown）。

cat localworkspace/markdown/olmocr-sample.md  

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

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

如果你在其他地方已有运行中的 vLLM 服务器（或任何实现 OpenAI API 的推理平台），可以指定 olmOCR 使用它，而不是启动本地实例。

远程推理安装：

# 轻量安装 - 无需 GPU 依赖  
pip install olmocr  

使用外部服务器：

# 使用外部 vLLM 服务器替代本地  
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 并在以下外部模型提供商上确认可用：

参数说明

• --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 (https://www.beaker.org) 高效线性化数百万 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 仓库 (https://hub.docker.com/r/alleninstituteforai/olmocr) 了解更多信息。

完整文档

查看所有可用选项：

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  

通过批推理管线运行数百万 PDF 的管理器  

positional arguments:  
  workspace             工作存储的文件系统路径，可以是本地文件夹，如果是多工作节点协调工作，则为 s3 路径：s3://bucket/prefix/  

options:  
  -h, --help            显示此帮助信息并退出  
  --pdfs [PDFS ...]     添加存储于 s3 的 PDF 到工作空间的路径，可以是 glob 路径 s3://bucket/prefix/*.pdf 或包含 PDF 路径列表的文件路径  
  --model MODEL         模型所在路径，默认为 allenai/olmOCR-7B-0725-FP8，可以是本地、s3 或 Hugging Face 路径。  
  --workspace_profile WORKSPACE_PROFILE  
                        用于访问工作空间的 S3 配置 profile  
  --pdf_profile PDF_PROFILE  
                        用于访问原始 PDF 文档的 S3 配置 profile  
  --pages_per_group PAGES_PER_GROUP  
                        每个工作项组的目标 PDF 页数  
  --max_page_retries MAX_PAGE_RETRIES  
                        渲染一页的最大重试次数  
  --max_page_error_rate MAX_PAGE_ERROR_RATE  
                        文档中允许的失败页比例，默认为 1/250  
  --workers WORKERS     同时运行的工作节点数量  
  --apply_filter        对非表格类、非 SEO 垃圾邮件的英文 PDF 进行基础过滤  
  --stats               不运行任何任务，只报告当前工作空间的统计信息  
  --markdown            同时将自然文本写入 markdown 文件，保持输入 PDF 的文件夹结构  
  --target_longest_image_dim TARGET_LONGEST_IMAGE_DIM  
                        渲染 PDF 页面时最长边使用的尺寸  
  --target_anchor_text_len TARGET_ANCHOR_TEXT_LEN  
                        使用的锚文本最大长度（字符数），新模型不适用  
  --guided_decoding     为模型 YAML 类型输出启用引导解码  

VLLM arguments:  
  --gpu-memory-utilization GPU_MEMORY_UTILIZATION  
                        vLLM 可以为 KV-cache 预分配的 VRAM 比例（透传给 vllm serve）  
  --max_model_len MAX_MODEL_LEN  
                        vLLM 为 KV-cache 分配的上限（tokens），若 VLLM 无法启动可降低  
  --tensor-parallel-size TENSOR_PARALLEL_SIZE, -tp TENSOR_PARALLEL_SIZE  
                        vLLM 的张量并行大小  
  --data-parallel-size DATA_PARALLEL_SIZE, -dp DATA_PARALLEL_SIZE  
                        vLLM 的数据并行大小  
  --port PORT            VLLM 服务器端口  
  --server SERVER        外部 vLLM（或其他兼容提供商）服务器的 URL（例如 http://hostname:port）。若提供，则不启动本地 vLLM 实例  

beaker/cluster execution:  
  --beaker               将此任务提交到 beaker 而不是本地运行  
  --beaker_workspace BEAKER_WORKSPACE  
                        提交到的 Beaker 工作空间  
  --beaker_cluster BEAKER_CLUSTER  
                        你想要运行的 Beaker 集群  
  --beaker_gpus BEAKER_GPUS  
                        运行的 GPU 副本数量  
  --beaker_priority BEAKER_PRIORITY  
                        任务的 Beaker 优先级  

代码概览

以下是一些可复用的代码片段，可能对你的项目有用：

• 使用 ChatGPT 4o 获取高质量自然文本解析的提示策略 - buildsilver.py (https://github.com/allenai/olmocr/blob/main/olmocr/data/buildsilver.py)
• 按语言和 SEO 垃圾邮件基础过滤 - filter.py (https://github.com/allenai/olmocr/blob/main/olmocr/filter/filter.py)
• Qwen2.5-VL 的 SFT 微调代码 - train.py (https://github.com/allenai/olmocr/blob/main/olmocr/train/train.py)
• GRPO RL 训练器 - grpo_train.py (https://github.com/allenai/olmocr/blob/main/olmocr/train/grpo_train.py)
• 合成数据生成 - mine_html_templates.py (https://github.com/allenai/olmocr/blob/main/olmocr/synth/mine_html_templates.py)
• 使用 VLLM 通过微调模型处理数百万 PDF - pipeline.py (https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py)
• 查看由 PDF 创建的 Dolma 文档 (https://github.com/allenai/dolma) - dolmaviewer.py (https://github.com/allenai/olmocr/blob/main/olmocr/viewer/dolmaviewer.py)

团队

olmOCR 由 AllenNLP 团队开发和维护。