OXR 内置 D-FINE 版面分析模型架构:HGNetv2 骨干与混合编码器深度拆解
OXR 内置 D-FINE 版面分析模型架构:HGNetv2 骨干与混合编码器深度拆解
OXR(Optical Everything Recognition)是一款开源文档解析模型,能把 PDF 和文档图像转成带坐标的 Markdown / JSON。其中负责"看版面"的是内置的 D-FINE Stage-2 B2 版面分析模型:输入 960×960 图像,输出 12 类文档元素(标题、文本、公式、表格、代码块等)的边界框。这篇文章带你拆解它的两大核心——HGNetv2 骨干网络与混合编码器(HybridEncoder),并顺带讲清解码器、推理加速与工程细节。
1️⃣ OXR 的版面分析模块:独立、可插拔的 D-FINE
OXR 是首批把版面分析做成独立可插拔模块的文档解析系统:版面检测由 D-FINE 模型独立完成,内容识别与阅读顺序交给 OXR 主模型。这种分工带来两个好处:
- 更快:版面模型轻量(B2 规格),可与识别并行流水线执行;
- 更灵活:如果你的业务对"版面元素"定义不同,可以只替换版面模型,保留 OXR 的识别与阅读顺序能力。
版面分析服务的完整说明见 services/layout_analyze/README.md,模型总入口在 model.py:
| 模块 | 文件 | 职责 |
|---|---|---|
DFINE |
model.py | 组装 骨干 → 编码器 → 解码器 |
HGNetv2 |
backbone.py | 提取多尺度特征(C2/C3/C4) |
HybridEncoder |
encoder.py | Transformer + FPN/PAN 特征融合 |
DFINETransformer |
decoder.py | 查询式检测与 FDR 框细化 |
DFINEPostProcessor |
postprocessor.py | 取 Top-300 框并映射回原图 |
12 个版面类别(Caption、Footnote、Formula、Text、Page-footer、Page-header、Picture、Title、Table、Code Block、Stamp、Chemical Structure)在 config.py 中固化,启动时会连同权重 SHA-256 一起校验。
2️⃣ HGNetv2 B2 骨干:多分支聚合 + 轻量卷积
骨干选用 HGNetv2,OXR 采用中间的 B2 规格(use_lab=True,return_idx=<a href="https://link.gitcode.com/i/db531005e484f4e69d3dadcb3037a7c2" target="_blank">1, 2, 3],见 [model.py)。它输出 stride 为 8 / 16 / 32 的三层特征,通道数分别为 384 / 768 / 1536——正好对应 960×960 输入下的 120²、60²、30² 特征图。
B2 的 Stage 配置(backbone.py):
| Stage | 输入通道 | 输出通道 | 块数 | 卷积核 | 下采样 | 输出 stride |
|---|---|---|---|---|---|---|
| Stem | 3 | 32 | - | 3×3 拆分为 2×2 | 4× | 4 |
| Stage 1 | 32 | 96 | 1 | 3×3 | 否 | 4 |
| Stage 2 | 96 | 384 | 1 | 3×3 | 2× | 8 |
| Stage 3 | 384 | 768 | 3 | 5×5(轻量块) | 2× | 16 |
| Stage 4 | 768 | 1536 | 1 | 5×5(轻量块) | 2× | 32 |
2.1 HG_Block:一条输入、多条支路,再拼接聚合
HGNetv2 的核心单元是 HG_Block:它把输入串过 layer_num 层卷积(B2 中为 4 层),把每一层的中间输出全部保留,最后连同输入一起拼接,再用 1×1 卷积 + EseModule 通道注意力做一次聚合。
这种"多分支并行聚合"相当于给网络提供了多条不同深度的信息通路:浅支路保留细节,深支路承载语义,聚合时由网络自己学习取舍——这也是 HGNetv2 精度高于同级纯串行结构的关键。
2.2 三个推理友好的设计
- StemBlock 拆分卷积:用两组 2×2 卷积替代 3×3 卷积分支(StemBlock),算力更省;
- LightConvBNAct:Stage 3/4 使用"1×1 逐点 + 深度可分离"的轻量块(LightConvBNAct),大核 5×5 只作用在深度卷积上;
- 冻结 BatchNorm:
freeze_norm=True会在部署时把BatchNorm2d原地替换为 FrozenBatchNorm2d,前向退化为一次乘加,对算子融合与量化都更友好。
3️⃣ 混合编码器 HybridEncoder:Transformer 自注意力 × FPN/PAN
HybridEncoder 是"混合"二字的出处:它在 CNN 特征上叠加一层轻量 Transformer,再做 FPN/PAN 双向融合。整体流程分四步:
3.1 通道投影
三路骨干特征(384/768/1536 通道)分别经 1×1 Conv + BN 投影到统一的 256 维(encoder.py),保证后续注意力与融合模块维度一致。
3.2 只在最深层跑一层 Transformer
use_encoder_idx=<a href="https://link.gitcode.com/i/a093081535a7c706384654b2f7ed2ab6" target="_blank">2] 意味着 Transformer 自注意力只施加在 stride-32 的语义最深特征上:8 头、FFN 1024、GELU 激活,仅 1 层([TransformerEncoderLayer),位置编码用 2D sincos 且推理时预计算缓存(encoder.py)。
这是典型的"精度/速度权衡":让最需要全局上下文的深层特征吃到注意力收益,而不为全部三层的上万个 token 都付 Transformer 成本。
3.3 RepNCSPELAN4:FPN 上采样 + PAN 下采样
融合部分采用 RepNCSPELAN4 块:
- Top-down FPN(encoder.py):深层特征 1×1 投影后最近邻上采样 2 倍,与浅层特征拼接,交给 RepNCSPELAN4 融合;
- Bottom-up PAN(encoder.py):反过来用 SCDown 下采样浅层特征再与深层特征拼接融合。
最终编码器输出 3 路 stride 8/16/32、通道均为 256 的特征,供解码器做多尺度采样。其中 depth_mult=0.67 把 CSP 块深度压到 2,进一步降低融合层开销。
4️⃣ DFINETransformer 解码器:300 个查询 + FDR 分布细化
解码器源自 RT-DETR 系架构,D-FINE 的含义即"Redefine Regression Task of DETRs as Fine-grained Distribution Refinement"(把回归任务重定义为细粒度分布细化)。
4.1 锚点查询选择
推理时先在 3 层特征上生成网格锚点(grid_size=0.05,越深层锚点越大,见 _generate_anchors),编码器打分后按分数 Top-300 选出查询(_select_topk)。这 300 个查询就是最终候选框的上限——与后处理器 num_top_queries=300 一一对应。
4.2 可变形注意力 + 门控融合
每层解码器(共 4 层)包含:自注意力、多尺度可变形注意力(MSDeformableAttention,各层采样点数 num_points=<a href="https://link.gitcode.com/i/7e42258f8851bc2a4be973636e5ec9c1" target="_blank">3, 6, 3])、以及一个 [Gate 门控模块把交叉注意力输出与原特征软加权混合,再进 FFN。可变形注意力只在少数可学习采样点上取值,计算量与特征图大小近似解耦——这是 RT-DETR 系解码器快的原因。
4.3 FDR:把"回归框"变成"积分 32 桶分布"
D-FINE 的关键创新在框回归方式:不再直接输出 4 个连续坐标,而是对每个角点预测一个 reg_max=32 桶的概率分布(Integral),坐标 = 概率加权求和(reg_scale=4)。每一层解码器都叠加前层的修正量(TransformerDecoder.forward),实现逐层"分布细化"——这就是 FDR 中 Refinement 的含义。
配套的 LQE(位置质量估计器)会用框分布的集中度微调类别得分:分布越"散",说明定位越不确定,类别置信度相应下调,天然抑制误检。
训练阶段还有 100 个去噪查询(denoising.py:标签翻转率 0.5、框噪声 1.0),推理时完全不存在。
5️⃣ 推理工程:FP16、Letterbox 与 CUDA Graph
模型加载与封装见 load_model:
- 精度:CUDA 上用 FP16 autocast(DfineWithPostProcessor),CPU 回落 FP32;
- 预处理:Letterbox 缩放到 960×960 正方形画布,LANCZOS4 插值、灰度 114 填充(resize_and_pad),后处理器按同一 Letterbox 参数把框映射回原图尺寸(postprocess_boxes);
- CUDA Graph:固定形状的 Batch-1 推理会先预热 3 次再捕获图,之后每次请求只复制输入并
replay()(CUDAGraphModel),省掉大量内核启动开销; - 服务化:FastAPI 提供
/inference、/health、/model/info(api.py),Server-Timing响应头会拆分 decode / preprocess / inference 耗时,方便定位瓶颈。
这套工程化收益直接体现在速度上:按 docs/benchmark.md 的 21 模型对比,OXR 端到端吞吐约 0.99 页/秒(RTX PRO 6000 Blackwell),居同类文档解析模型之首。
6️⃣ 架构要点速查表
| 关注点 | 设计选择 | 位置 |
|---|---|---|
| 骨干规格 | HGNetv2 B2,输出 C2/C3/C4 | model.py |
| 特征聚合 | HG_Block 多分支拼接 + Ese 注意力 | backbone.py |
| 编码器 | 1 层 Transformer(仅 stride-32)+ FPN/PAN | encoder.py |
| 查询数 | 锚点打分 Top-300 | decoder.py |
| 框回归 | FDR:32 桶分布积分,4 层细化 | decoder.py |
| 类别数 / 输入 | 12 类 / 960×960 | config.py |
| 推理加速 | FP16 autocast + CUDA Graph + FrozenBN | model.py、cuda_graph.py |
7️⃣ 想继续深入?建议的阅读路径 📖
- 入口与组装:model.py(125 行,最适合作为第一站)
- 骨干细节:backbone.py → 编码器:encoder.py
- 解码器与 FDR:decoder.py + 训练用去噪:denoising.py
- 运行时代码:runtime.py、config.py
- 行为验证:tests/unit/test_layout_pipeline.py、tests/unit/test_layout_client.py
- 第三方来源与许可:THIRD_PARTY_NOTICES.md
一句话总结:OXR 的版面分析 = HGNetv2 B2 多分支骨干抽特征,单层 Transformer + RepNCSPELAN4 融合的混合编码器搭特征金字塔,RT-DETR 式解码器 + FDR 分布细化输出 300 个候选框——再用 FP16 与 CUDA Graph 压到毫秒级,最终作为可插拔模块嵌入整个 OXR 文档解析流水线。
