OXR 内置 D-FINE 版面分析模型架构:HGNetv2 骨干与混合编码器深度拆解

原创2026-10-30 16:52:312,264 阅读
文章标签:人工智能AI 应用计算机视觉OCR多模态大模型本地部署

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 的识别与阅读顺序能力。

OXR 开源文档解析项目横幅:内置 D-FINE 版面分析模型与 1.3B 参数识别模型

版面分析服务的完整说明见 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️⃣ 想继续深入?建议的阅读路径 📖

  1. 入口与组装:model.py(125 行,最适合作为第一站)
  2. 骨干细节:backbone.py → 编码器:encoder.py
  3. 解码器与 FDR:decoder.py + 训练用去噪:denoising.py
  4. 运行时代码:runtime.py、config.py
  5. 行为验证:tests/unit/test_layout_pipeline.py、tests/unit/test_layout_client.py
  6. 第三方来源与许可:THIRD_PARTY_NOTICES.md

一句话总结:OXR 的版面分析 = HGNetv2 B2 多分支骨干抽特征,单层 Transformer + RepNCSPELAN4 融合的混合编码器搭特征金字塔,RT-DETR 式解码器 + FDR 分布细化输出 300 个候选框——再用 FP16 与 CUDA Graph 压到毫秒级,最终作为可插拔模块嵌入整个 OXR 文档解析流水线。

登录后查看全文
OXR