# https://github.com/allenai/olmocr 项目说明书 生成时间：2026-06-13 23:18:12 UTC ## 目录 - [项目概览与安装指南](#page-1) - [推理管线与集群执行 (Pipeline)](#page-2) - [olmOCR-Bench 评测套件](#page-3) - [训练、数据准备与合成数据](#page-4) ## 项目概览与安装指南 ### 相关页面 相关主题：[推理管线与集群执行 (Pipeline)](#page-2)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/allenai/olmocr/blob/main/README.md) - [Dockerfile](https://github.com/allenai/olmocr/blob/main/Dockerfile) - [Dockerfile.with-model](https://github.com/allenai/olmocr/blob/main/Dockerfile.with-model) - [pyproject.toml](https://github.com/allenai/olmocr/blob/main/pyproject.toml) - [docs/source/installation.md](https://github.com/allenai/olmocr/blob/main/docs/source/installation.md) - [docs/source/overview.md](https://github.com/allenai/olmocr/blob/main/docs/source/overview.md) - [olmocr/bench/README.md](https://github.com/allenai/olmocr/blob/main/olmocr/bench/README.md) - [olmocr/train/README.md](https://github.com/allenai/olmocr/blob/main/olmocr/train/README.md)
# 项目概览与安装指南 ## 1. 项目定位与核心能力 **olmOCR** 是由 Allen Institute for Artificial Intelligence（AI2）旗下 AllenNLP 团队开源的 PDF 文档识别工具包，目标是利用视觉语言模型（Vision Language Models, VLM）将 PDF 高质量地转换为结构化的纯文本与 Markdown 资料来源：[README.md:1-50]()。 项目的核心设计取向包括： - **面向大规模语料**：以"解锁 PDF 中数以万亿计的 token"为目标，训练数据来自 `allenai/olmOCR-mix-1025` 等公开数据集 资料来源：[README.md:60-90]()。 - **统一评测**：附带 `olmOCR-bench` 基准测试，使用"单页 PDF 单元测试"方式评估 OCR 工具的精度，刻意回避编辑距离等容易误判的软指标 资料来源：[olmocr/bench/README.md:1-30]()。 - **支持本地与远程推理**：可通过 `vLLM` 在本地 GPU 上运行，也可以指向兼容 OpenAI API 的外部推理服务（如 DeepInfra、远程 vLLM 节点） 资料来源：[README.md:30-80]()。 - **可选 Apache 2.0 协议**：可用于商业与非商业项目 资料来源：[README.md:140-150]()。 最新发布版本为 **v0.4.27**（2025 年末），主要改进了 GPU 依赖、长队列下的工作队列稳健性以及 PII 标注流水线 资料来源：[releases/v0.4.27]()。 ```mermaid flowchart LR A[PDF 文档] --> B[poppler 渲染为图像] B --> C[视觉语言模型
vLLM / 外部服务] C --> D[YAML + Markdown 输出] D --> E[Dolma 格式语料] D --> F[本地 markdown/ 目录] ``` ## 2. 系统要求与前置依赖 olmOCR 对运行环境有较严格的依赖，因此官方建议在全新的 Conda 环境中安装 资料来源：[README.md:55-75]()。 | 类别 | 要求 | 说明 | | --- | --- | --- | | Python | 3.11（推荐） | 建议使用 Conda 创建独立环境 | | GPU（本地推理） | NVIDIA 显卡 + vLLM | 需较新的 CUDA 与显存 | | 系统包（Ubuntu/Debian） | poppler-utils、ttf-mscorefonts-installer、msttcorefonts、fonts-crosextra-caladea、fonts-crosextra-carlito、gsfonts、lcdf-typetools | 用于 PDF 渲染与字体回退 | | 操作系统 | 主流 Linux 发行版 | 官方文档以 Ubuntu 为示例 | 需要特别注意：**macOS 目前不受官方支持**，issue #33（"macOS support"）显示仅依赖 NVIDIA 硬件是当前最大的限制，社区已讨论多时但尚未合并 资料来源：[issue #33]()。**ROCm/AMD 显卡**（如 7900 XTX）也尚未在主线获得 vLLM + flash-attention 的稳定支持，issue #111 报告了在 AMD 平台上出现 OOM 或空响应的问题 资料来源：[issue #111]()。 ## 3. 安装方式 ### 3.1 远程推理安装（轻量） 如果计划连接已部署好的 vLLM、DeepInfra 等兼容 OpenAI API 的服务，可使用纯 CPU 包，避免下载约 2 GB 的 PyTorch 资料来源：[README.md:65-80]()： ```bash conda create -n olmocr python=3.11 conda activate olmocr pip install olmocr ``` ### 3.2 本地 GPU 推理安装 需要在同一环境中安装 GPU 依赖，使 vLLM 能在本地拉起服务 资料来源：[README.md:75-95]()： ```bash # 在已激活的 olmocr 环境中 pip install olmocr[gpu] # 或仓库根目录的 pip install .[gpu] ``` ### 3.3 训练环境安装 要复现 `allenai/olmOCR-2-7B-1025-FP8` 模型或继续微调，需要安装训练可选依赖，训练脚本默认面向 8×H100 节点（1 卡跑 vLLM，7 卡训练） 资料来源：[olmocr/train/README.md:1-40]()： ```bash pip install .[train] pip install transformers==4.52.4 pip install flash-attn>=2.8.0.post2 --no-build-isolation ``` 训练数据推荐使用 `python -m olmocr.data.prepare_olmocrmix` 从 Hugging Face 数据集预取，目录需约 200 GB 磁盘空间 资料来源：[olmocr/train/README.md:50-80]()。 ## 4. 快速开始：CLI 与远程服务 安装完成后，可通过顶层命令 `olmocr`（或等价的 `python -m olmocr.pipeline`）调用 资料来源：[README.md:25-40]()。 **使用本地 GPU 推理：** ```bash olmocr ./localworkspace --pdfs tests/gnarly_pdfs/*.pdf --markdown ``` **指向远程 vLLM 推理服务：** ```bash olmocr ./localworkspace \ --server http://remote-server:8000/v1 \ --model allenai/olmOCR-2-7B-1025-FP8 \ --markdown \ --pdfs *.pdf ``` 运行结束后，工作区会同时包含 [Dolma](https://github.com/allenai/dolma) 格式的文档以及 `./localworkspace/markdown/` 下的 Markdown 文件 资料来源：[README.md:30-55]()。 常用 CLI 参数（节选自 README 中参数说明） 资料来源：[README.md:95-140]()： | 参数 | 用途 | | --- | --- | | `--pdfs` | 输入 PDF 列表（支持通配符） | | `--markdown` | 同时输出 Markdown 文件 | | `--server` | 指向外部推理服务 URL，跳过本地 vLLM | | `--model` | 远程模型 ID（默认 `allenai/olmOCR-2-7B-1025-FP8`） | | `--gpu-memory-utilization` | 透传给 vLLM 的 KV-cache 比例 | | `--tensor-parallel-size` / `--data-parallel-size` | 张量/数据并行度 | | `--beaker` | 提交到 Beaker 集群运行 | ## 5. 常见问题与社区反馈 虽然主流程已较为稳定，但社区仍然报告了若干值得在安装前注意的问题： - **Windows / GBK 编码报错**（issue #459）：在 Windows + Anaconda PowerShell 中输出包含 `ǐ` 这类非 GBK 字符的 Markdown 时会失败，建议设置 `PYTHONIOENCODING=utf-8` 或 `chcp 65001` 资料来源：[issue #459]()。 - **依赖缺失**（issue #452）：在干净的 bench 环境中执行 `python -m olmocr.bench.benchmark` 会因缺少 `numpy` 而抛 `ModuleNotFoundError`，需要手动 `pip install numpy` 资料来源：[issue #452]()。 - **CLI help 字符串解析错误**（issue #451）：Python 3.14 的 argparse 在某些 `formatter` 校验路径下崩溃，建议使用 Python 3.11 资料来源：[issue #451]()。 - **DeepInfra 弃用通知**（issue #460）：托管在 DeepInfra 上的 `allenai/olmOCR-2-7B-1025` 已宣布将于 2026-05-07 弃用，生产用户需提前评估替代方案（如自部署 vLLM） 资料来源：[issue #460]()。 - **超时常量不可配**（issue #455）：`olmocr/bench/runners/run_server.py` 中 HTTP 客户端硬编码了 300 秒默认超时，长文档偶发超时 资料来源：[issue #455]()。 - **缺少 Web / Python API 示例**（issue #86）：社区反复呼吁提供 Gradio 演示与 Python 调用样例，目前以 CLI 为主；issue #75 / #161 提供了社区维护的 Docker 与 Gradio 包装方案，可作参考 资料来源：[issue #86]()、[issue #75]()、[issue #161]()。 ## 6. See Also - [olmOCR-Bench 评测体系](https://github.com/allenai/olmocr/blob/main/olmocr/bench/README.md) - [olmOCR 训练流程与数据准备](https://github.com/allenai/olmocr/blob/main/olmocr/train/README.md) - [官方论文：olmOCR: Unlocking Trillions of Tokens in PDFs with Vision Language Models (arXiv 2502.18443)](https://arxiv.org/abs/2502.18443) - [官方论文：olmOCR 2: Unit Test Rewards for Document OCR (arXiv 2510.19817)](https://arxiv.org/abs/2510.19817) - [Hugging Face 数据集：allenai/olmOCR-mix-1025](https://huggingface.co/datasets/allenai/olmOCR-mix-1025) - [Hugging Face 数据集：allenai/olmOCR-bench](https://huggingface.co/datasets/allenai/olmOCR-bench) --- ## 推理管线与集群执行 (Pipeline) ### 相关页面 相关主题：[项目概览与安装指南](#page-1), [olmOCR-Bench 评测套件](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [olmocr/pipeline.py](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py) - [olmocr/prompts/prompts.py](https://github.com/allenai/olmocr/blob/main/olmocr/prompts/prompts.py) - [olmocr/prompts/anchor.py](https://github.com/allenai/olmocr/blob/main/olmocr/prompts/anchor.py) - [olmocr/work_queue.py](https://github.com/allenai/olmocr/blob/main/olmocr/work_queue.py) - [olmocr/datatypes.py](https://github.com/allenai/olmocr/blob/main/olmocr/datatypes.py) - [olmocr/s3_utils.py](https://github.com/allenai/olmocr/blob/main/olmocr/s3_utils.py)
# 推理管线与集群执行 (Pipeline) ## 1. 概述与设计目标 `olmocr.pipeline` 是 olmOCR 项目的核心批处理管线，用于将百万级别的 PDF 文档通过微调后的视觉语言模型转换为结构化的 Dolma/JSONL 与 Markdown 输出。该模块既支持单机本地执行，也支持通过 Beaker 集群编排多个 worker 同时处理大规模数据集。入口命令行可通过 `olmocr`（已配置 console_script）或 `python -m olmocr.pipeline` 触发，唯一的必填位置参数是 `workspace`，用于指定工作目录，可为本地文件夹，也可为 `s3://bucket/prefix/` 形式的远端共享存储。 资料来源：[README.md](https://github.com/allenai/olmocr/blob/main/README.md)、[olmocr/pipeline.py](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py) ## 2. 管线架构与数据流 管线核心思路是 "分组 (group) → 渲染 → 提示 → 推理 → 解析 → 校验 → 落盘"。每 `pages_per_group` 个连续页面被组合成一个工作单元，先调用 PDF 渲染工具将页面转为图像，再通过 `prompts/anchor.py` 从页面抽取锚文本以辅助定位，最终将图像 + 锚文本 + YAML 元数据组装为模型提示词送入推理后端（本地 vLLM、远端 OpenAI 兼容服务，或 Beaker 集群），解析出 Markdown 后与原始 PDF 一并写入 workspace。如下数据流图展示了端到端路径： ```mermaid flowchart LR A[PDF 输入
--pdfs glob/list] --> B[Workspace 注册
work_queue] B --> C[页面分组
pages_per_group] C --> D[PDF 渲染为图像] D --> E[Anchor 锚文本提取
anchor.py] E --> F[Prompt 组装
prompts.py] F --> G{推理后端} G -->|本地 vLLM| H[vLLM Server] G -->|远端 API| I[--server URL] G -->|Beaker| J[Beaker 集群 worker] H --> K[引导解码校验
--guided_decoding] I --> K J --> K K --> L[Markdown / Dolma 落盘] L --> M[work_queue 标记完成] ``` 资料来源：[olmocr/pipeline.py](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py)、[olmocr/prompts/prompts.py](https://github.com/allenai/olmocr/blob/main/olmocr/prompts/prompts.py)、[olmocr/prompts/anchor.py](https://github.com/allenai/olmocr/blob/main/olmocr/prompts/anchor.py)、[olmocr/work_queue.py](https://github.com/allenai/olmocr/blob/main/olmocr/work_queue.py) ## 3. 关键配置选项 下表汇总了管线常用参数及其行为，参数定义见 `pipeline.py` 顶部 argparse： | 参数 | 作用 | 备注 | | --- | --- | --- | | `--model` | 指定模型路径或 HuggingFace 仓库名 | 默认 `allenai/olmOCR-7B-0725-FP8` | | `--pages_per_group` | 每个工作单元包含的连续页数 | 影响吞吐与显存占用 | | `--workers` | 并发 worker 数量 | 多 GPU/多机部署时增大 | | `--max_page_retries` / `--max_page_error_rate` | 单页重试次数与整体可接受错误率 | 失败超过阈值会终止管线 | | `--target_longest_image_dim` / `--target_anchor_text_len` | 渲染分辨率与锚文本长度目标 | 控制 token 预算 | | `--guided_decoding` | 启用结构化输出约束 | 提升格式稳定性 | | `--gpu-memory-utilization` / `--max_model_len` | vLLM 显存与上下文长度 | CUDA 部署关键 | | `--tensor-parallel-size` / `--data-parallel-size` | 模型并行维度 | 多卡推理时使用 | | `--server` | 指向已存在的 OpenAI 兼容端点 | 跳过本地 vLLM 启动 | | `--api_key` | 远端服务认证 | 与 `--server` 配合使用 | | `--beaker` / `--beaker_*` | 在 Beaker 集群上提交任务 | 适合百万级数据 | | `--apply_filter` | 应用质量过滤 | 剔除低置信度输出 | | `--markdown` | 额外写出 Markdown 文件 | 便于人工检查 | 资料来源：[olmocr/pipeline.py](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py) ## 4. 三种执行模式 ### 4.1 本地 vLLM（GPU 必需） 默认模式下，`pipeline.py` 会在本机启动 vLLM 推理服务器，并使用 vLLM 的 OpenAI 兼容端点。安装需要 GPU 依赖： ```bash pip install olmocr[gpu] --find-links https://flashinfer.ai/whl/cu124/torch2.4/flashinfer/ olmocr ./localworkspace --markdown --pdfs tests/gnarly_pdfs/*.pdf ``` 社区多次反馈 Nvidia 是事实上的硬性要求，参见 issue [#33](https://github.com/allenai/olmocr/issues/33)（macOS 支持诉求）以及 [#111](https://github.com/allenai/olmocr/issues/111)（ROCm/AMD 实验）。因此在非 Nvidia 平台上需改用下一种模式。 ### 4.2 远端推理服务 当已有 vLLM 或第三方推理服务（实现 OpenAI API）运行时，使用 `--server` 与 `--model` 指向外部端点；安装只需 `pip install olmocr`，无需 GPU 依赖。已验证的外部提供商及价格示例见 README 表（Cirrascale、DeepInfra 等）。注意：issue [#455](https://github.com/allenai/olmocr/issues/455) 提出 HTTP 超时配置诉求，目前 `run_server.py` 默认 300 秒可能不足，建议后续版本开放 timeout 参数。 ### 4.3 Beaker 集群执行 通过 `--beaker` 配合 `--beaker_workspace`、`--beaker_cluster`、`--beaker_gpus`、`--beaker_priority` 等参数，将每个 worker 提交到 Beaker AI2 集群。该模式常用于百万级 PDF 批处理，工作目录推荐使用共享文件系统（如 S3），以便多个 worker 协同消费同一份 `work_queue`。 资料来源：[olmocr/pipeline.py](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py)、[olmocr/work_queue.py](https://github.com/allenai/olmocr/blob/main/olmocr/work_queue.py)、[olmocr/s3_utils.py](https://github.com/allenai/olmocr/blob/main/olmocr/s3_utils.py) ## 5. 已知问题与失败模式 - **GBK 编码失败**：在 Windows/Anaconda 环境下输出 Markdown 时遇到 `'gbk' codec can't encode character` 异常，需设置 `PYTHONIOENCODING=utf-8` 或 `chcp 65001`（参见 [#459](https://github.com/allenai/olmocr/issues/459)）。 - **个别 PDF 解析为空**：`--markdown` 模式下部分页面（如 `headers_footers` 数据集中的某些 PDF）可能输出空 Markdown，需结合 `--apply_filter` 与人工 review 复核（参见 [#463](https://github.com/allenai/olmocr/issues/463)）。 - **超长队列稳定性**：v0.4.15 起 `work_queue` 增强了超时与巨型共享文件系统下的鲁棒性；v0.4.27 修复了长队列下的 bug（参见 release notes）。 - **远端模型下架**：通过 DeepInfra 使用 `allenai/olmOCR-2-7B-1025` 时需要注意 2026-05-07 的弃用计划，应及时迁移至 Cirrascale 等替代端点（参见 [#460](https://github.com/allenai/olmocr/issues/460)）。 资料来源：[README.md](https://github.com/allenai/olmocr/blob/main/README.md)、社区 issue 跟踪 ## 6. 与其他模块的协作 - `prompts/prompts.py` 与 `prompts/anchor.py`：负责为每个页面生成模型提示词与锚文本，是推理质量的决定因素。 - `datatypes.py`：定义 PDF 路径、页面元数据、Dolma 文档等数据结构，贯穿管线。 - `work_queue.py`：在本地或 S3 上维护任务状态、去重与失败重试，是分布式执行的关键。 - `s3_utils.py`：在 S3 workspace 下读写页面图像与产物。 - `bench/` 子项目：使用同一管线生成候选输出，再用 `benchmark` 进行评测（参见 [olmocr/bench/README.md](https://github.com/allenai/olmocr/blob/main/olmocr/bench/README.md)）。 资料来源：[olmocr/datatypes.py](https://github.com/allenai/olmocr/blob/main/olmocr/datatypes.py)、[olmocr/work_queue.py](https://github.com/allenai/olmocr/blob/main/olmocr/work_queue.py)、[olmocr/s3_utils.py](https://github.com/allenai/olmocr/blob/main/olmocr/s3_utils.py) ## See Also - [olmOCR 评测基准 (Bench)](./Bench.md) - [olmOCR 训练流程 (Training)](./Training.md) - [数据准备与 olmOCR-mix-1025 (Data Preparation)](./Data-Preparation.md) --- ## olmOCR-Bench 评测套件 ### 相关页面 相关主题：[推理管线与集群执行 (Pipeline)](#page-2)
相关源码文件 以下源码文件用于生成本页说明： - [olmocr/bench/README.md](https://github.com/allenai/olmocr/blob/main/olmocr/bench/README.md) - [olmocr/bench/benchmark.py](https://github.com/allenai/olmocr/blob/main/olmocr/bench/benchmark.py) - [olmocr/bench/tests.py](https://github.com/allenai/olmocr/blob/main/olmocr/bench/tests.py) - [olmocr/bench/runners/run_server.py](https://github.com/allenai/olmocr/blob/main/olmocr/bench/runners/run_server.py) - [olmocr/bench/runners/run_olmocr_pipeline.py](https://github.com/allenai/olmocr/blob/main/olmocr/bench/runners/run_olmocr_pipeline.py) - [olmocr/bench/runners/run_marker.py](https://github.com/allenai/olmocr/blob/main/olmocr/bench/runners/run_marker.py) - [olmocr/train/README.md](https://github.com/allenai/olmocr/blob/main/olmocr/train/README.md) - [README.md](https://github.com/allenai/olmocr/blob/main/README.md)
# olmOCR-Bench 评测套件 ## 概述与设计目标 olmOCR-Bench 是由 AllenNLP 团队（AI2）开发的文档级 OCR 评测套件，用于自动且有效评估各类工具的 PDF 解析能力。资料来源：[olmocr/bench/README.md:1-18]()。 与基于编辑距离等软指标的评测方式不同，olmOCR-Bench 采用"事实断言"思路：以若干机器可校验的单元测试（unit-test style）形式检测文档中是否出现特定句子、公式或表格关系。该设计避免了因换序、合法的语义重写而误扣分的情况。资料来源：[olmocr/bench/README.md:5-12]()。 输入侧统一为单页 PDF，因为 PDF 通常保留数字元数据，且几乎任何格式都可转换为 PDF，但反向不行。资料来源：[olmocr/bench/README.md:14-17]()。 ### 核心原则 评测结果对 Markdown 语法不敏感（如 `**enlightenment**` 与 `enlightenment` 视为相同），对位置也不敏感（除页眉页脚测试外）。资料来源：[olmocr/bench/README.md:120-127]()。 所有 Unicode 会在评测前规范化为 NFC；连字符、双引号、单引号会被规范化为 ASCII 形式。资料来源：[olmocr/bench/README.md:130-134]()。 ## 数据集与文档类型 olmOCR-Bench 涵盖 7 类文档，每类有独立的采集与标注流程。资料来源：[olmocr/bench/README.md:25-90]()。 | 类别 | 说明 | |---|---| | ArXiv 数学 (AR) | 抓取单 TeX 源 arXiv 论文，与 KaTeX 渲染对照后人工校验 | | 古旧扫描数学 (OSM) | 来自 Internet Archive 的公共领域数学教材 | | 表格 (TA) | 使用 Gemini-Flash-2.0 筛选并核对单元格关系 | | 古旧扫描 (OS) | Library of Congress 历史信件与打字稿 | | 页眉页脚 (HF) | 使用 DocLayout-YOLO 检测后用 Gemini-Flash-2.0 抽取 | | 多栏 (MC) | 使用 Claude-Sonnet-3.7 渲染 HTML 后提取阅读顺序片段 | | 长小字 (LTT) | Internet Archive 密集小字页面 | 数据集同时已通过 URL 级去重防止与 olmOCR-Mix 训练集污染。资料来源：[olmocr/bench/README.md:21-24]()。 ## 运行流程与执行器 通过 `olmocr.bench.benchmark` 模块驱动整体流程，命令行入口形如： ```bash python -m olmocr.bench.benchmark --dir ./olmOCR-bench/bench_data ``` 评测通过不同的 runner 适配不同 OCR 后端： - `run_olmocr_pipeline.py`：调用 olmOCR 自身管线 - `run_server.py`：对接任意兼容 OpenAI API 的远端推理服务（默认 HTTP 超时 300 秒，社区已请求可配置超时） - `run_marker.py`：对接 Marker 等其他开源 OCR 工具 资料来源：[README.md:103-126]() 与 [olmocr/bench/runners/run_server.py](https://github.com/allenai/olmocr/blob/main/olmocr/bench/runners/run_server.py)。 评测完成后产生各文档类型的子分数与总体分（含 ±1 标准差）。资料来源：[olmocr/bench/README.md:60-95]()。 ## 评分机制与已知问题 `TextPresenceTest` 等测试类型由 `olmocr/bench/tests.py` 定义，使用 `partial_ratio` 等模糊匹配来判定文本是否出现。资料来源：[olmocr/bench/tests.py](https://github.com/allenai/olmocr/blob/main/olmocr/bench/tests.py)。 社区已报告并跟踪若干相关缺陷，运维与使用者应当留意： - **partial_ratio 误判**（Issue #461）：当候选输出接近空（如仅一个 `\n`）时，`partial_ratio` 会反转为命中，从而高估模型得分。资料来源：[Issue #461](https://github.com/allenai/olmocr/issues/461)。 - **依赖缺失**（Issue #452）：`[bench]` extras 未声明 `numpy`，直接运行基准会因 `ModuleNotFoundError` 失败；建议在执行前手动安装。资料来源：[Issue #452](https://github.com/allenai/olmocr/issues/452)。 - **帮助字符串格式损坏**（Issue #451）：在 Python 3.14 下 argparse 触发 `_check_help` 异常，需要修复 formatter。资料来源：[Issue #451](https://github.com/allenai/olmocr/issues/451)。 - **解析失败导致空 Markdown**（Issue #463）：部分页眉页脚 PDF（来自 `headers_footers/` 子集）会被管线解析为空文件，造成评测缺测。资料来源：[Issue #463](https://github.com/allenai/olmocr/issues/463)。 - **编码错误**（Issue #459）：在 Windows + DeepInfra 组合下出现 `'gbk' codec` 报错，需要设置 `PYTHONIOENCODING=utf-8`。资料来源：[Issue #459](https://github.com/allenai/olmocr/issues/459)。 - **HTTP 超时**（Issue #455）：`run_server.py` 默认 300 秒超时不够，请求可配置化。资料来源：[Issue #455](https://github.com/allenai/olmocr/issues/455)。 - **DeepInfra 模型弃用**（Issue #460）：`allenai/olmOCR-2-7B-1025` 在 DeepInfra 将于 2026-05-07 弃用。资料来源：[Issue #460](https://github.com/allenai/olmocr/issues/460)。 ## 与训练流程的耦合 `olmocr/train/README.md` 中提到 `prepare_workspace` 脚本可以把 `olmocr.pipeline` 跑出的工作区转换为与 olmOCR-Bench 测试用例同构的格式（`*.md`），这意味着同一套"单元测试"既可以用于训练数据构造（synthmix），也可以作为 vLLM 训练时的奖励信号（reward_bench）。资料来源：[olmocr/train/README.md:62-75]()。 ## 架构总览 ```mermaid flowchart LR PDF[单页 PDF] --> Runners Runners --> Pipeline[run_olmocr_pipeline.py] Runners --> Server[run_server.py] Runners --> Marker[run_marker.py] Pipeline --> Markdown Server --> Markdown Marker --> Markdown Markdown --> Tests[olmocr/bench/tests.py] Tests --> Scores[各类别分 + 总分] ``` ## See Also - 训练管线：[olmocr/train/README.md](https://github.com/allenai/olmocr/blob/main/olmocr/train/README.md) - 主项目说明：[README.md](https://github.com/allenai/olmocr/blob/main/README.md) - 数据集：[allenai/olmOCR-bench](https://huggingface.co/datasets/allenai/olmOCR-bench) - 论文：olmOCR 2 (arXiv 2510.19817) --- ## 训练、数据准备与合成数据 ### 相关页面 相关主题：[推理管线与集群执行 (Pipeline)](#page-2)
相关源码文件 以下源码文件用于生成本页说明： - [olmocr/train/README.md](https://github.com/allenai/olmocr/blob/main/olmocr/train/README.md) - [olmocr/train/train.py](https://github.com/allenai/olmocr/blob/main/olmocr/train/train.py) - [olmocr/train/grpo_train.py](https://github.com/allenai/olmocr/blob/main/olmocr/train/grpo_train.py) - [olmocr/train/dataloader.py](https://github.com/allenai/olmocr/blob/main/olmocr/train/dataloader.py) - [olmocr/train/config.py](https://github.com/allenai/olmocr/blob/main/olmocr/train/config.py) - [olmocr/train/muon.py](https://github.com/allenai/olmocr/blob/main/olmocr/train/muon.py) - [olmocr/synth/mine_html_templates.py](https://github.com/allenai/olmocr/blob/main/olmocr/synth/mine_html_templates.py) - [olmocr/pipeline.py](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py) - [README.md](https://github.com/allenai/olmocr/blob/main/README.md)
# 训练、数据准备与合成数据 ## 概述 olmOCR 项目提供了一整套用于训练 PDF 视觉语言模型（VLM）的工具链，覆盖从原始 PDF 文档到最终微调模型的完整流程。训练流程的核心是基于 GRPO（Group Relative Policy Optimization）的强化学习方法，配合单元测试奖励机制来提升模型在文档 OCR 任务上的表现 资料来源：[olmocr/train/README.md]()。 整个训练流程主要包括三个核心环节： 1. **数据准备**：将 PDF 文档转换为单页 PDF + Markdown 注释的训练样本 2. **合成数据生成**：通过 HTML 模板挖掘技术生成额外的训练样本 3. **模型训练**：使用 GRPO 算法在多 GPU 节点上进行强化学习微调 ## 数据准备 ### 数据集格式要求 训练数据需要按照严格的格式组织，每个 PDF 文件必须是**单页**的，并且与对应的 Markdown 注释文件配对 资料来源：[olmocr/train/README.md]()。 ``` data/ ├── document1.pdf ├── document1.md ├── document2.pdf ├── document2.md └── ... ``` 每个 Markdown 文件需要包含 YAML 前置元数据和提取的文本内容： ```markdown --- primary_language: en is_rotation_valid: True rotation_correction: 0 is_table: False is_diagram: False --- Document text goes here... ``` ### 准备 olmOCR-mix 数据集 最便捷的方式是使用 `prepare_olmocrmix.py` 脚本自动下载并准备 [olmOCR-mix-1025](https://huggingface.co/datasets/allenai/olmOCR-mix-1025) 数据集，该数据集需要约 200GB 的磁盘空间 资料来源：[olmocr/train/README.md]()。 数据集包含多个子集： | 子集名称 | 说明 | |---------|------| | `00_documents` | 通用文档 | | `01_books` | 书籍内容 | | `02_loc_transcripts` | 国会图书馆转录文本 | | `03_national_archives` | 国家档案 | ### 从工作空间提取数据 另一种获取训练数据的方式是先使用 olmOCR pipeline 处理大量文档，然后通过 `olmocr.data.prepare_workspace` 脚本提取训练数据： ```bash python -m olmocr.pipeline ./localworkspace --pdfs /home/username/pdfs/*.pdf python -m olmocr.data.prepare_workspace ./localworkspace ./localtrainingdata ``` 资料来源：[olmocr/train/README.md]()。 ## 合成数据生成 olmOCR 通过 HTML 模板挖掘技术生成合成训练数据，核心脚本为 `mine_html_templates.py` 资料来源：[olmocr/synth/mine_html_templates.py]()。 ### 训练数据流程 ```mermaid flowchart LR A[原始 PDF 文档] --> B[olmocr.pipeline 处理] B --> C[Dolma 格式输出] C --> D[prepare_workspace 提取] D --> E[训练样本] F[HTML 模板挖掘] --> G[合成测试用例] G --> E H[olmOCR-mix-1025] --> I[prepare_olmocrmix] I --> E E --> J[GRPO 训练] ``` ### 合成测试用例 合成数据生成的输出格式与 olmOCR-bench 测试用例相同，这意味着可以在 olmOCR-bench 中直接评估这些样本的性能 资料来源：[olmocr/train/README.md]()。 典型的合成数据集命名如 `synthmix-1025`，可通过指定路径作为训练基准数据文件夹使用。 ## 训练流程 ### 环境配置 训练需要额外的依赖包，在基础 olmocr 环境之上安装： ```bash pip install .[train] pip install transformers==4.52.4 pip install flash-attn>=2.8.0.post2 --no-build-isolation ``` 资料来源：[olmocr/train/README.md]()。 ### GRPO 训练参数 训练脚本 `grpo_train.py` 实现了基于单元测试奖励的强化学习训练。典型的训练命令如下 资料来源：[olmocr/train/grpo_train.py]()： ```bash ./scripts/train/grpotrainer-beaker-multi-gpu-augusta.sh --num-gpus 8 \ --model_name s3://ai2-oe-data/jakep/olmocr/qwen2.5-vl-7b-olmocrv4_1epoch_promptv4_mix1025_more_rotation-8372 \ --train_bench_data_folder /data/jakep/grpo_data_mixes/olmocr-synthmix-1025-v2-rotate10p/bench_data \ --reward_bench 1.0 --reward_front_matter 1.0 --reward_eos 1.0 \ --beta 0.01 --name promptv4_mix1025_more_rotation_multigpu_v1_beta_01_lr2e-6_frontmatter1_0_eos_28gen_synthmix-1025_rotate10p_finalrun1 \ --seed 1 --gradient_accumulation_steps 28 --learning_rate 2e-6 ``` ### 硬件配置 训练在 8xH100 GPU 节点上进行，其中 1 块 GPU 专用于运行 VLLM 推理服务，其余 7 块用于训练 资料来源：[olmocr/train/README.md]()。 ### 奖励函数 GRPO 训练使用多个奖励信号来引导模型学习 资料来源：[olmocr/train/grpo_train.py]()： | 奖励类型 | 参数 | 权重 | |---------|------|------| | 基准测试奖励 | `--reward_bench` | 1.0 | | 前置元数据奖励 | `--reward_front_matter` | 1.0 | | 终止符奖励 | `--reward_eos` | 1.0 | ### 数据加载 训练数据通过自定义的数据加载器进行批量加载和管理，配置参数定义在 `config.py` 中 资料来源：[olmocr/train/dataloader.py]() 和 [olmocr/train/config.py]()。 ## 常见问题与注意事项 ### 依赖问题 在 macOS 上由于缺少 NVIDIA GPU 支持，训练功能无法正常运行。如需 ROCm 支持，vLLM 在某些 AMD 显卡上可能出现 OOM 或 flash-attention 兼容性问题 资料来源：[Issue #111]()。 ### 编码问题 在 Windows 系统上运行 olmocr 时，可能会遇到 `'gbk' codec can't encode character` 错误，建议设置 `PYTHONIOENCODING=utf-8` 环境变量 资料来源：[Issue #459]()。 ### 性能优化 训练使用了 Muon 优化器（定义在 `muon.py` 中）来提升训练效率 资料来源：[olmocr/train/muon.py]()。 ## See Also - [olmocr-bench 评估基准](https://github.com/allenai/olmocr/blob/main/olmocr/bench/README.md) - [主项目 README](https://github.com/allenai/olmocr/blob/main/README.md) - [Pipeline 数据处理流程](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py) --- --- ## Doramagic 踩坑日志 项目：allenai/olmocr 摘要：发现 13 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：olmocr.bench scoring: `partial_ratio` falsely matches when candidate is near-empty (e.g. single `\\n`)。 ## 1. 安装坑 · 来源证据：olmocr.bench scoring: `partial_ratio` falsely matches when candidate is near-empty (e.g. single `\\n`) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：olmocr.bench scoring: `partial_ratio` falsely matches when candidate is near-empty (e.g. single `\\n`) - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/allenai/olmocr/issues/461 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 2. 配置坑 · 来源证据：configurable timeout for HTTP client in server method - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：configurable timeout for HTTP client in server method - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/allenai/olmocr/issues/455 | 来源类型 github_issue 暴露的待验证使用条件。 ## 3. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | github_repo:858798469 | https://github.com/allenai/olmocr | README/documentation is current enough for a first validation pass. ## 4. 维护坑 · 来源证据：Fail to parse b4c3c4ac3d6f7b52a993cec7ca8b3ad43cecabad_page_3.pdf - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Fail to parse b4c3c4ac3d6f7b52a993cec7ca8b3ad43cecabad_page_3.pdf - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/allenai/olmocr/issues/463 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 5. 维护坑 · 来源证据：Model allenai/olmOCR-2-7B-1025 on DeepInfra will be deprecated on 2026-05-07 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Model allenai/olmOCR-2-7B-1025 on DeepInfra will be deprecated on 2026-05-07 - 对用户的影响：可能影响升级、迁移或版本选择。 - 证据：community_evidence:github | https://github.com/allenai/olmocr/issues/460 | 来源类型 github_issue 暴露的待验证使用条件。 ## 6. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | github_repo:858798469 | https://github.com/allenai/olmocr | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | github_repo:858798469 | https://github.com/allenai/olmocr | no_demo; severity=medium ## 8. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | github_repo:858798469 | https://github.com/allenai/olmocr | no_demo; severity=medium ## 9. 安全/权限坑 · 来源证据：Writing markdown error : 'gbk' codec can't encode character '\u1eca' in position 3419 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Writing markdown error : 'gbk' codec can't encode character '\u1eca' in position 3419 - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/allenai/olmocr/issues/459 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 10. 安全/权限坑 · 来源证据：[bug] badly formed help string - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[bug] badly formed help string - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/allenai/olmocr/issues/451 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 11. 安全/权限坑 · 来源证据：numpy is missing from [bench] dependencies - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：numpy is missing from [bench] dependencies - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/allenai/olmocr/issues/452 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 12. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | github_repo:858798469 | https://github.com/allenai/olmocr | issue_or_pr_quality=unknown ## 13. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | github_repo:858798469 | https://github.com/allenai/olmocr | release_recency=unknown