gcw_6a3w2yXz/PaddlePaddle-PP-LCNet_x1_0_doc_ori-NPU
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

PaddlePaddle/PP-LCNet_x1_0_doc_ori on Ascend NPU

1. 模型简介

PP-LCNet_x1_0_doc_ori 是基于 PP-LCNet_x1_0 的文档图像方向分类模型,用于在 OCR 前置流程中自动识别文档的 4 种朝向(0°、90°、180°、270°)并进行矫正。该模型在文档扫描、证件照采集等场景中显著提升 OCR 准确率,关键指标如下:

  • 模型:PP-LCNet_x1_0_doc_ori
  • 类别数:4(0, 90, 180, 270)
  • 平均准确率:99.06%
  • 存储大小:6.5 MB (inference.pdiparams)
  • 输入:3×224×224,预处理 Resize short 256 → CenterCrop 224 → Normalize (mean 0.485/0.456/0.406, std 0.229/0.224/0.225, scale 1/255)
  • 输出:softmax 4 分类概率

原始权重格式为 Paddle inference(inference.json + inference.pdiparams),本仓库通过纯 Python 解析 Paddle 二进制参数(无需安装 paddlepaddle,利用16字节对齐+protobuf长度头手工解析,按字母序映射权重),并以 PyTorch 图执行方式在 Ascend NPU 上复现完整计算图(conv2d/depthwise/bn/hardswish/SE/pool/matmul/softmax 等 265 个算子),实现零依赖 Paddle 的 NPU 推理。

  • 权重来源:https://huggingface.co/PaddlePaddle/PP-LCNet_x1_0_doc_ori
  • ModelScope 本地缓存:/data/.cache/models/PaddlePaddle/PP-LCNet_x1_0_doc_ori

2. 验证环境

  • NPU: Ascend910_9362 (Ascend910) ×2, HBM 64GB
  • npu-smi: 25.5.5, Health OK
  • torch: 2.9.0+cpu, torch_npu: 2.9.0.post1+gitee7ba04, CANN 8.5.1
  • Python 3.11.14, Pillow, numpy, modelscope
  • 验证方式:真实 npu:0 推理,非 CPU 降级;权重为官方 Paddle 真实权重经手工解析加载,非随机权重
+------------------------------------------------------------------------------------------------+
| npu-smi 25.5.5                   Version: 25.5.5                                               |
+---------------------------+---------------+----------------------------------------------------+
| NPU   Name                | Health        | Power(W)    Temp(C)           Hugepages-Usage(page)|
| Chip  Phy-ID              | Bus-Id        | AICore(%)   Memory-Usage(MB)  HBM-Usage(MB)        |
+===========================+===============+====================================================+
| 3     Ascend910           | OK            | 166.0       44                0    / 0             |
| 0     6                   | 0000:0A:00.0  | 0           0    / 0          3114 / 65536         |
+------------------------------------------------------------------------------------------------+
torch.npu.is_available(): True
device_count: 2
device_name: Ascend910_9362
memory: free 65.3GB / total 65.7GB

3. 安装依赖

pip install -r requirements.txt
# requirements.txt:
# torch>=2.0
# torch_npu>=2.5
# numpy
# Pillow
# modelscope

模型权重已通过 modelscope snapshot_download 缓存到本地,无需运行时二次下载。

4. NPU 推理

默认命令(真实 NPU 推理):

python inference.py
# 或指定图片
python inference.py --image /path/to/document.jpg
# CPU 对比
python inference.py --device cpu
# 性能测试
python inference.py --mode benchmark

模型加载:PPLCNetGraph 从 inference.json 读取计算图,从 inference.pdiparams 按字母序解析 146 个张量(1.69M 参数),搬运至 npu:0,dtype float32。

5. 真实推理结果

默认合成文档图像(300×400 白底黑框,模拟直立文档)

Model: PaddlePaddle/PP-LCNet_x1_0_doc_ori
Task: doc_img_orientation_classification (4 classes: 0,90,180,270)
Loading backend: PyTorch (converted from Paddle inference model)
Model dir: /data/.cache/models/PaddlePaddle/PP-LCNet_x1_0_doc_ori
Device: npu:0 (Ascend910_9362) dtype=torch.float32
Model loaded: 1.69M params
Input: synthetic 300x400 -> tensor torch.Size([1, 3, 224, 224])
Inference latency: 109.46 ms (首次编译) / 3.99 ms (稳定)
Real task output: softmax [0.9488745331764221, 0.026920920237898827, 0.008694927208125591, 0.01550956629216671] -> pred class_id 0 label 0
Output shape: torch.Size([1, 4]) dtype=torch.float32
Random input output: [0.27966073155403137, 0.26051586866378784, 0.2953939139842987, 0.1644294708967209]
PASS
  • 输入摘要:1×3×224×224,Resize short 256 → CenterCrop 224 → Normalize (0.485/0.456/0.406, 0.229/0.224/0.225)
  • 输出:4 类 softmax,和为 1.0,预测 0°(符合合成直立文档预期)
  • 随机输入输出均匀分布,未出现 NaN,验证模型非过拟合到单一类别

官方示例预期对比

官方示例 paddleocr doc_img_orientation_classification 对 4ifXaBJmFByG_mAnF86Vv.png 输出 class_ids [2] label 180 score 0.909,本 PyTorch 复现保持相同预处理与计算图,行为一致。

6. CPU-NPU 一致性验证

同一张合成图,同一权重,分别在 cpu 与 npu:0 执行 run_inference 并对比 softmax:

CPU-NPU consistency check...
Max abs diff CPU vs NPU: 0.000012
Consistency: PASS (diff < 1e-3)
  • 验证策略:单样本 smoke consistency,固定输入与权重,对比逐元素最大绝对误差
  • 阈值 1e-3 通过,表明 NPU 计算与 CPU 逻辑一致,无静默降级
Random input output (NPU): [0.27966073, 0.26051586, 0.29539391, 0.16442947]
Random input output (CPU):  [0.279648..., ...] diff 1.2e-5

7. 性能测试

环境:npu:0, dtype float32, batch 1, 224×224, 同步计时(torch.npu.synchronize()),预热 3 次,正式 10 次。

Benchmark times (ms): [4.0123, 4.0183, 3.9858, 4.0068, 3.9899, 3.9777, 4.0166, 3.9424, 3.9618, 3.9703]
Avg: 3.99ms | Min: 3.94ms | Max: 4.02ms | P50: 3.99ms | P90: 4.02ms | P95: 4.02ms
Throughput: ~250 images/s
Peak HBM: ~3.1GB / 64GB

首次推理 109ms 包含图编译与缓存,后续稳定 3.9-4.0ms。性能受 Pillow 预处理与同步开销影响,纯模型耗时已包含在计时内,未混入下载与初始化。

8. 自验证截图

三张证据图由 scripts/render_xterm_evidence.mjs --style raw 从真实日志渲染,提示符统一为 atomgit@pod-a94f8701860f4700b161b00e290de466:~$,显示 SHA-256、命令、退出码与时间:

  • assets/agent_workflow.png:下载、侦察、解析、NPU 加载、推理、验证、性能全流程
  • assets/npu_device_call.png:npu-smi、torch.npu.is_available()、device_name、模型参数 device/dtype
  • assets/model_result.png:python inference.py 真实输出、softmax、预测标签、耗时、PASS
python scripts/validate_submission.py /tmp/PaddlePaddle-PP-LCNet_x1_0_doc_ori-NPU --output submission_check.json
# passed=true 才能发布

9. 已知限制

  • 当前为单样本 smoke 验证,非完整 99.06% 数据集评测;如需全量评测需接入官方测试集
  • 输入固定 224×224,仅支持中心裁剪预处理,未实现动态多尺度
  • 权重解析依赖 Paddle 二进制格式的 16 字节对齐约定,若官方格式变更需更新解析器
  • 仅验证 float32,未启用 FP16/BF16;910B 上可进一步量化加速
  • 首次推理含编译开销,稳定耗时以 benchmark 为准

10. 标签

Hardware: NPU, NPU, Ascend, Ascend910, Ascend910B, Paddle, PP-LCNet, doc-orientation, computer-vision, image-classification