深度解析 OXR：SOTA 文档解析模型的架构设计与训练范式
最近部署并深入研究了 SoMark 开源的文档解析模型 OXR（Optical Everything Recognition）——一个仅 1.3B 参数、却在 olmOCR-Bench、OmniDocBench、DocParsingBench 三大基准上排名第一的 VLM。这篇文章从源码层面拆解它的系统架构、数据流、模型设计，并探讨其训练方法。
TL;DR（太长不看）
- 双模型解耦：D-FINE 负责布局分析（检测元素类别 + 坐标），OXR 负责内容识别 + 阅读顺序，布局模型可插拔；
- Soft Visual Token：视觉特征经 softmax 映射为 65532 维概率分布，再对嵌入矩阵做加权平均——视觉到语言梯度连续可微，免去 VQ 的 stop-gradient；
- RSI 自改进：从零预训练 + Recursive Self-Improvement 循环，无需人工标注；
- 部署：D-FINE（8081）+ vLLM OXR（8080）+ OXR API（8000），24GB 显存可低并发运行。
一、总体架构：双模型解耦
OXR 最特别的设计，是把「布局分析」和「内容识别」拆成两个独立模型：
文档输入 → ① D-FINE 布局分析（检测元素类别 + 坐标）
→ ② OXR 识别模型（内容识别 + 阅读顺序）
→ ③ 后处理组装 → Markdown / JSON（含坐标）
- D-FINE：一个轻量目标检测模型，识别 12 种文档元素（标题、段落、表格、公式、化学式、代码块等）并输出边界框；
- OXR：一个多模态大模型，负责把每个布局块的内容识别出来，并在同一模型中完成阅读顺序排序——这是它的核心创新之一：把 Reading Order 集成进识别阶段，省去了独立的排序模型，速度和准确率双赢。
💡 布局模型是可插拔的：用户可以替换成自己的布局模型，OXR 仍能完成识别和排序。
二、处理流水线：每阶段的输入输出
从源码 oxr/pipeline/ 可以精确还原每一阶段：
| 阶段 |
输入 |
输出 |
| 文档解码 |
文件字节 + 文件名 |
每页图像列表 |
| 布局分析 |
页面图像（分批 8 张） |
每页 Block 列表：{类型, bbox, 置信度} |
| 阅读顺序 |
整页图 + 布局框（坐标归一化到 1000×1000） |
0-based ID 的排列 |
| 内容识别 |
裁剪块图像 + 特定 prompt |
文本 / HTML / LaTeX / Markdown / SMILES |
| 后处理 |
模型原始输出 |
去重、公式编号折叠、表格清洗 |
| 组装 |
有序 Block 列表 |
Markdown 文档 / JSON（含 bbox 和阅读顺序） |
两个值得注意的细节：
- 识别阶段针对不同元素使用不同的 prompt：表格转 HTML、公式转 KaTeX、化学结构转 SMILES、代码转 Markdown 代码块；
- 模型输出超过长度上限时还有自动恢复机制：表格缩小重试、文本提高 repetition penalty 重试。
三、OXR 模型架构：Soft Visual Token 桥接
从 config.json 和 modeling_oxr.py 可以确认，OXR 由三部分组成：
- 语言模型：Qwen3-0.6B-Base（28 层，hidden 1024，RoPE，权重共享）
- 视觉编码器：SigLIP2-SO400M-Patch16-512（27 层，NaViT 可变分辨率）
- 视觉-语言桥接层（核心创新）：
OXRVisualTokenizer + OXREmbedding
3.1 核心创新：Soft Visual Token
传统 VLM 通常把视觉特征量化成离散 ID（如 VQ-VAE），而 OXR 走了一条不同的路——软 token：
- SigLIP2 的输出经过一个 Linear + LayerNorm 投影，然后
softmax 成一个 65532 维的概率分布；
- 视觉嵌入 =
matmul(概率向量, 嵌入矩阵)，即对全部视觉词表的概率加权平均；
- 因此视觉到语言的梯度是连续可微的，不需要 VQ 式 stop-gradient，可以端到端优化视觉编码器；
- 概率向量末尾拼接 4 维零，把 65536 词表划分为「65532 个视觉原子 + 4 个指示符」——视觉内容不污染离散边界标记，结构确定、内容连续。
3.2 图像预处理
图像预处理采用 Qwen2-VL 风格的 smart_resize（像素对齐）。视觉 token 数 = 图像像素数 / 1024，例如 448×448 图像展开成 196 个视觉 token，前后各插一个离散指示符。
四、D-FINE 布局模型
D-FINE 是 OXR 的「眼睛」：它负责在整页图像上定位每个文档元素，为后续识别划定区域。它是一个 Stage-2 B2 的 DETR 系检测器（Stage-2 指两阶段训练流程第二阶段的产物，B2 是 HGNetv2 骨干的规模档位），核心配置如下：
| 组件 |
配置 |
说明 |
| Backbone |
HGNetv2-B2 |
输出 3 层特征（stride 8 / 16 / 32） |
| Encoder |
HybridEncoder |
RT-DETR 风格：CNN 多尺度融合 + 轻量 Transformer 全局建模 |
| Decoder |
DFINETransformer |
4 层解码器、300 queries、reg_max=32 分布回归 |
| 输入 |
960×960 letterbox |
等比缩放 + 填充，避免图像拉伸变形 |
| 输出 |
12 类 labels + boxes + scores |
FP16 + CUDA Graph 加速 |
4.1 为什么是 DETR 系：免 NMS
DETR 把检测视为集合预测：300 个可学习的 object queries 各自负责「寻找一个物体」，训练时用匈牙利匹配做一对一全局最优匹配，推理时天然没有重复框，不需要 NMS。省掉后处理延迟与不稳定性，对实时文档解析尤为重要。
4.2 Backbone + Encoder：高效的多尺度特征
- HGNetv2-B2 是轻量骨干，通过跨阶段「高引导」连接改善梯度流动，输出 stride 8 / 16 / 32 三层特征，兼顾小目标（标题、公式）与整块大目标（表格）；
- HybridEncoder 只在最小尺度的特征上做一层 Transformer 全局建模（AIFI），其余多尺度融合全部由 CNN 完成——用最低代价获得全局上下文。
4.3 核心创新：reg_max=32 分布回归与细粒度定位
D-FINE 与传统检测器最大的区别，在于回归头的输出形式：
- 传统回归头直接输出坐标增量（Dirac delta 点估计），无法表达定位置信度，且对微小偏移很敏感；
- D-FINE 把每条边的偏移量离散成
reg_max+1 = 33 个 bin，回归头输出每个 bin 的概率分布 Pr(n)，最终偏移 = 加权期望：
d^l = d^0 + {H,H,W,W} · Σ W(n) · Pr^l(n)
其中 {H,H,W,W} 表示把分布期望的偏移量按初始框的宽高缩放——大框允许大调整，小框只做小调整。W(n) 则是非均匀加权函数（两端陡、中间平）：
- 框已经比较准时，分布集中在中间区域，
W(n) 曲率小 → 细粒度微调；
- 框偏差较大时，分布落在两端，
W(n) 边界陡变 → 快速纠偏。
FDR（Fine-grained Distribution Refinement） 让 4 层解码器不是在坐标上加残差，而是在分布 logits 上加残差：
logits^l = Δlogits^l + logits^(l-1)，Pr^l = Softmax(logits^l)
每层只需做微小修正，分布越修越尖、框越修越准。训练时配合 FGL Loss（相邻 bin 插值 + IoU 加权）与 GO-LSD 自蒸馏（把最后一层的精细分布蒸馏给浅层），进一步加速收敛、提升定位精度。
4.4 部署工程
- 输入 960×960 letterbox，保持长宽比不拉伸；
- FP16 半精度推理，Tensor Core 加速、显存占用减半；
- CUDA Graph 把整条推理链路的 kernel 捕获成图、一次提交反复回放，消除 CPU 启动开销——对轻量模型尤其有效。
五、训练方法：RSI 循环与 RL 的探讨
官方公开的信息是：从零预训练 + 后训练阶段的 RSI（Recursive Self-Improvement）循环——对错样本、弱样本做定向优化，无需人工标注。训练代码未开源。
从推理侧可以反推出一些有意思的信号：
- 阅读顺序任务要求模型输出严格排列，而代码里配了多级容错（缺 1~2 个 ID 时用 XY-Cut++ 修复补充）——这种「硬约束输出 + 自动校验」的模式，很可能经过 RL（如 GRPO + 格式奖励）训练；
- 文档解析有天然的可编程奖励（输出可与文档原文自动比对），非常适合做 RL；
- 模型支持 thinking 两阶段生成，但文档解析主任务默认关闭，说明没有在主任务上做长思维链 RL。
⚠️ 以上属于基于源码与行为的合理推断，官方尚未公开确认，需要等论文或训练代码发布才能证实。
六、部署要点
- 三个服务：D-FINE 布局（8081）、vLLM OXR 模型（8080）、OXR API（8000）
- vLLM 需要 out-of-tree 插件注册 OXR 架构；官方插件要求
vllm==0.25.1，实测 0.25.0 也兼容
- 24GB 显存可低并发运行，官方推荐 48GB
- 模型权重约 3GB，支持任意分辨率输入，长文档和复杂表格表现突出
总结
OXR 的价值可以概括为四点：
- 把「布局检测」和「内容识别」解耦，布局模型可插拔；
- 把阅读顺序融入识别阶段，省去独立排序模型；
- 用可微的 Soft Visual Token 桥接视觉与语言，实现端到端优化；
- 配合 RSI 自我改进循环，无需人工标注即可持续提升。
这是一套完整且工程化程度很高的文档解析方案，值得文档智能方向的研究者深入拆解。