OXR 文档解析技术架构深度解析:版面分析、内容识别与阅读顺序如何协同
OXR 文档解析技术架构深度解析:版面分析、内容识别与阅读顺序如何协同
OXR(Optical Everything Recognition)是 SoMark 团队开源的 SOTA 文档解析模型,可将 PDF 和文档图片解析为带版面坐标的 Markdown / JSON 数据。本文深度解析 OXR 文档解析的技术架构:版面分析、内容识别、阅读顺序三大模块如何通过"三阶段流水线 + 双模型协同"分工协作,让 1.3B 参数的模型同时拿下精度与速度的双领先。
一、OXR 总体技术架构:三阶段流水线 + 双模型协同
理解 OXR 的技术架构,先要记住一句话:系统由两个模型驱动——独立的 Layout Analysis(版面分析)模型 + OXR 主模型,而 OXR 主模型一人分饰两角,同时负责内容识别(Recognition)和阅读顺序(Reading Order)。
官方在 oxr/pipeline/orchestrator.py 中把整个流程编排为清晰的三个阶段:
| 阶段 | 输入 | 输出 | 执行者 | 实现模块 |
|---|---|---|---|---|
| Phase 1 版面分析 | 页面图片 | 每个区块的类型 + 坐标框 | 独立 Layout 模型(可插拔) | oxr/pipeline/layout.py |
| Phase 2 识别与阅读顺序 | 裁剪后的区块 + 原图 | 区块内容 + 页内顺序 | OXR 主模型(同一服务) | oxr/pipeline/recognition.py、oxr/pipeline/reading_order.py |
| Phase 3 装配与输出 | 识别后的 Block 列表 | Markdown / JSON | 规则化后处理 | oxr/pipeline/assembler.py |
这套"任务级"架构重构是 OXR 提速的关键:版面分析先行框出区域,识别只需对小图裁剪块逐一处理,避免整页大模型推理;阅读顺序与识别共享同一模型服务的并发预算(semaphore),两路任务并发执行、互不阻塞。
💡 架构上的另一层巧思:阅读顺序被并入 Recognition 阶段,而不是让版面模型顺带输出。这样任何 Layout Analysis 模型都能低成本接入 OXR,详见下文。
二、版面分析:可插拔的独立 Layout Analysis 模块
🧩 OXR 是首个把版面分析设计为独立、可插拔模块的文档解析模型。设计动机很实际:不同业务对元素类别、区域边界、分组规则的定义差异最大,版面分析恰恰是文档解析服务商最常被要求定制的模块。
其工作方式:
- 独立服务:内置版面模型(基于 D-FINE 架构,12 类、960×960 输入)以独立服务形式运行,默认监听端口 8081,源码位于 services/layout_analyze/,详细说明见 services/layout_analyze/README.md;
- 批量并发:analyze_layouts 将页面按
batch_size分批,用信号量控制并发,失败时整批重试,且严格保序返回; - 可整体替换:只需在配置中把
layout_analyze_model.url指向你自己的版面模型服务,OXR 的内容识别与阅读顺序能力原封不动继续工作。
配置项集中在 config.example.yaml,常用参数包括:
| 参数 | 含义 |
|---|---|
layout_analyze_model.url |
版面模型服务地址(可替换为自研模型) |
batch_size |
每次版面请求的页面数 |
score_threshold |
候选框置信度阈值 |
provides_reading_order |
版面服务是否已按阅读顺序返回(若为 true,则跳过 OXR-RO 阶段) |
三、内容识别:13 类元素的分类识别策略
📐 版面分析产出的是"元素清单"——每个区块(Block)带有类型、坐标框 <a href="https://link.gitcode.com/i/dc4f1457ef4b24b5df83c9cc15246154" target="_blank">x1,y1,x2,y2] 等字段,数据结构定义在 [oxr/pipeline/models.py。OXR 可识别 13 类文档元素:Text、Title、Caption、Footnote、Formula、Table、Picture、Page-header、Page-footer、Stamp、Chemical Equation、Code Block、Chemical Structure,覆盖 A3 试卷、报纸、竖排文字、手写等复杂版面。
识别阶段(recognize_pages)的核心策略是按类型分流:
- 裁剪:按 bbox 从原页裁出小块图像,交给 OXR 主模型做识别;
- 分类型 Prompt:文本用通用识别、公式输出 LaTeX(KaTeX)、表格输出 HTML、代码输出 Markdown 代码块、化学结构式输出 SMILES,Prompt 模板见 oxr/model/prompts.py;
- 分类型后处理:每种元素有专属后处理器(如 formula_postprocess.py、table_postprocess.py),统一输出格式;
- 长度恢复:当输出触及 token 上限(finish_reason=length)时,表格会降采样 0.75 倍重试,文本类会提高 repetition penalty 重试,最大限度避免内容截断;
- 图片直通:Picture 类不做 OCR,直接保存裁剪图像,由后处理阶段落盘。
这种"先分型、再识别"的流水线,让识别精度与版面复杂度解耦——版面越复杂,越依赖 Phase 1 的框得准,而识别只需要专注小块内容的还原。
四、阅读顺序:模型判断 + 多级回退机制
🧠 阅读顺序决定了最终 Markdown 的行序,是多栏报纸、论文这类复杂版面的命门。OXR 的方案值得新手重点学习——模型优先、规则兜底:
① 模型输出严格校验。 OXR 主模型收到含区块 ID、类型、坐标的阅读顺序 Prompt 后,只允许输出一串"以空格分隔的 0 基 ID 全排列"。parse_reading_order 会严格校验:缺号、重号、超范围一律判为无效,绝不"将就"。
② 近似完整的自动修复。 若模型漏掉了个别区块(小页面允许漏 1 个、大页面允许漏 2 个),repair_incomplete_reading_order 会保持模型已给出部分的相对顺序不变,借助 XY-Cut++ 算法的参考排序,把缺失区块插入"成对冲突最少"的位置——模型的判断尽量保留,只补漏。
③ 最终兜底全规则排序。 若重试耗尽仍无效,supplement_incomplete_reading_order 用 XY-Cut++ 补齐缺失 ID;彻底失败时直接整体回退到纯几何的 xycut_plus_order 排序,保证"最坏情况也有可用顺序",而不是直接报错。
🚀 这套"严格校验 → 局部修复 → 规则兜底"的三层设计,是 OXR 在 OmniDocBench 上 Reading Order Edit 指标做到领先(0.1214)的工程基础,完整数值可查 docs/benchmark.md。
五、装配与去重:从 Block 到干净的 Markdown / JSON
最后阶段(oxr/pipeline/orchestrator.py)负责把"识别后的区块列表"变成干净的文档输出:
- 页眉页脚过滤:Page-header / Page-footer 默认不参与正文输出(可用参数保留);
- 多级去重:视觉父子框去重(大框吸收完整包含的小框)、跨类别系统性去重、完全重叠去重等规则见 oxr/pipeline/postprocess/;
- 公式编号关联:把 (1)(2) 这类编号与邻近公式正确配对,见 formula_postprocess.py;
- 双格式输出:JSON 保留每个区块的坐标与内容(Agent-Friendly),Markdown 由 assemble_markdown 按阅读顺序逐页拼接而成。
整个流程对每个阶段单独计时,debug 模式下可在 metadata 中看到 decode / layout / recognition / assembly 各自耗时,方便定位性能瓶颈。
六、核心源码路径与配置速查
想动手深入 OXR,建议按这条路径阅读源码:
| 模块 | 路径 | 作用 |
|---|---|---|
| 流程编排(三阶段) | oxr/pipeline/orchestrator.py | 版面 → 识别/阅读顺序 → 装配的总调度 |
| 版面分析 | oxr/pipeline/layout.py | 分批、并发、保序调用版面服务 |
| 内容识别 | oxr/pipeline/recognition.py | 按类型分流识别与长度恢复 |
| 阅读顺序 | oxr/pipeline/reading_order.py | 严格解析、修复与回退 |
| XY-Cut++ 兜底排序 | oxr/pipeline/xycut_order.py | 纯几何规则排序 |
| 区块数据模型 | oxr/pipeline/models.py | 13 类 BlockType 与 Block 结构 |
| 版面模型服务 | services/layout_analyze/ | 可插拔的 D-FINE 版面模型 |
| 全局配置 | config.example.yaml | 两个模型服务的 URL 与并发参数 |
此外,OXR 在后训练阶段引入了文档解析领域首个 RSI(递归自我改进)闭环:针对模型识别错误、表现薄弱的样本进行自动化定向优化,无需人工标注,这正是它在 olmOCR-Bench(87.84)、OmniDocBench(97.18)、DocParsingBench(87.76)三大基准上全面登顶的训练侧支撑。
七、总结:这套架构对新手意味着什么
- 想换版面模型:只动
layout_analyze_model.url一个配置,识别和阅读顺序能力零改动; - 想调性能:两个模型各有独立的
max_concurrency、timeout、retry_times,可分别调优; - 想理解难点:多栏/跨栏文档的效果差异,主要取决于阅读顺序机制——而 OXR 给出了"模型判断 + 规则兜底"的教科书式解法。
版面分析负责"看得全",内容识别负责"认得准",阅读顺序负责"排得对"——三者各司其职又通过三阶段流水线无缝衔接,这就是 OXR 文档解析技术架构的核心,也是它在精度与速度两个维度同时做到 SOTA 的答案。
