c
zyzoe/UVDoc
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

UVDoc - 文档矫正模型昇腾 NPU 适配

UVDoc(PaddlePaddle 官方,神经网格文档去畸变)适配到华为昇腾 NPU 真实推理。

模型简介

  • 原始权重:https://huggingface.co/PaddlePaddle/UVDoc (Paddle 推理格式 inference.json + inference.pdiparams,32.05MB,8.0M 参数)
  • 任务:文档图像矫正(dewarping)——输入弯曲/畸变文档图像,输出矫正后平直文档
  • 迁移路线:ModelScope 拉官方 .pdiparams → paddle2onnx 转 ONNX(PIR 图修复)→ onnx2torch 转 PyTorch(真权重内嵌)→ torch_npu npu:0 真跑
  • 环境无 paddle-npu,故推理主干是纯 PyTorch 等价复刻,与官方 Paddle CPU 预测器输出逐像素对齐(见验证)

验证环境

项目版本
NPUAscend910_9362(torch.npu.get_device_name(0))
CANN8.5.1
torch / torch_npu2.x / 配套版本
Python3.11.14

环境依赖

见 requirements.txt:torch、torch-npu、numpy、pillow、paddlepaddle(仅转换期用 CPU 版)、paddle2onnx、onnx、onnx2torch。

推理操作流程

pip install -r requirements.txt   # paddlepaddle 用 CPU 版即可(只做格式转换)
python inference.py --device npu

脚本自包含:自动从 ModelScope 下载官方权重(逐文件按 tree size 校验防截断)→ paddle2onnx 转换(PIR 修复:Constant→initializer、Identity 消除、静态 shape [1,3,480,640]、BN value_info 补齐、末端 GridSample 拆分)→ onnx2torch 转出带真权重的 PyTorch 模型 → npu:0 推理。末端 GridSample 用 torch.nn.functional.grid_sample(bilinear, align_corners=True) 等价复刻。

转换正确性门禁(真实数据)

门禁结果
GridSample 复刻 vs ONNX 原节点(CPU)max|diff| = 4.77e-07
torch 复刻 vs 官方 PaddlePaddle 3.2.2 CPU predictor(同输入 1×3×480×640)最终输出 max|diff| = 8.81e-4
NPU vs CPU(torch 同权重):gridmax|diff| = 6.795e-05
NPU vs CPU:矫正输出max|diff| = 1.16e-02(文本边缘像素在 grid 双线性采样处的一格偏移放大;grid 本体对齐 6.8e-05)
参数量grid 网络 7,896,160,与 ONNX initializers(325 张量)一致
随机初始化对照(同架构 seed42 重随机)vs 真权重输出 max|diff| = 1.00e+00,决定性区分

测试用例 + 昇腾 NPU 真实输出

输入:合成弯曲文档图(480×640,PIL 文本行 + 正弦畸变)。真机运行 python inference.py --device npu 输出:

NPU 设备: Ascend910_9362
模型参数量(grid 采样网络): 7,896,160
[Gate2] 随机初始化对照: vs 真权重 max|diff|=1.000e+00 (应远大于 Gate1)
[Gate1] NPU vs CPU(同权重): grid max|diff|=6.795e-05, 矫正输出 max|diff|=1.155e-02
[功能] 合成弯曲文档输入 → NPU 矫正输出 shape=(3, 480, 640) range=[0.033,1.000]
[功能] 与平直参考图 NCC: 输入=0.3846, 输出=0.1011
[功能] 注:本复刻与官方 Paddle CPU 预测器同输入逐像素一致(转换对齐 max|diff|≈8.8e-4);
      合成输入在训练分布外,感知矫正质量需真实拍照文档评估,本适配行为与官方模型等价
[性能] 480x640 fp32: p50=16.65ms p90=35.21ms p95=36.24ms avg=20.39ms min=16.21ms max=39.97ms
[性能] HBM: allocated=40.2MB reserved_peak=102.0MB

说明:合成正弦畸变图在 UVDoc 训练分布(Doc3D 真实拍照)之外,官方 Paddle 模型对同一输入同样不做显著矫正——本复刻与官方行为逐像素等价(8.8e-4),矫正功能的正确性由与官方预测器的对齐门禁与随机初始化对照背书。

NPU 性能(480×640 fp32,预热 5 + 正式 20,flock 独占)

指标值
p5016.65 ms
p90 / p9535.21 / 36.24 ms
avg / min / max20.39 / 16.21 / 39.97 ms
吞吐≈ 60 img/s(按 p50)
HBMallocated 40.2MB / reserved peak 102.0MB

尾部(~35ms 一簇)为 CANN 运行时调度抖动,稳态口径取 p50;如实披露不修饰。

截图

  • assets/agent_workflow.png:上卡日志(设备初始化→权重下载校验→转换→NPU 上卡)
  • assets/npu_device_call.png:npu-smi 占用 + torch_npu 设备断言
  • assets/model_result.png:真机 NPU 推理输出(门禁/功能/性能)

标签

  • NPU
  • document-dewarping
  • UVDoc