cv_resnet18_card_correction on Ascend NPU

1. 简介

本文档记录 PoseResNet 卡片检测与矫正模型在昇腾 NPU (Ascend 910B3) 上的迁移适配与精度验证结果。

该模型基于 ResNet18 骨干网络，通过关键点检测实现身份证、银行卡等卡片的定位与透视矫正。模型输出热力图（heatmap）、边界框回归等多项预测。

2. 验证环境

组件	版本
`CANN`	`8.5.1`
`torch`	`2.8.0`
`torch_npu`	`2.8.0.post4`
`modelscope`	`1.37.0`
`opencv-python-headless`	`4.13.0`

NPU：Ascend 910B3，单卡推理
模型大小：约 10.3M 参数
输入：[1, 3, 768, 768] RGB 图像

3. 推理启动

3.1 环境准备

conda create -n cv_resnet18_card_correction python=3.10 -y
conda activate cv_resnet18_card_correction

pip install torch==2.8.0 torch_npu==2.8.0.post4 torchvision==0.23.0 \
    -i https://mirrors.huaweicloud.com/repository/pypi/simple \
    --trusted-host mirrors.huaweicloud.com

pip install modelscope==1.37.0 opencv-python-headless numpy \
    sortedcontainers simplejson addict datasets pyarrow Pillow \
    -i https://mirrors.huaweicloud.com/repository/pypi/simple \
    --trusted-host mirrors.huaweicloud.com

3.2 下载模型权重

modelscope download --model damo/cv_resnet18_card_correction \
    --local_dir ./cv_resnet18_card_correction

3.3 命令行推理

python inference.py --image card.jpg --device npu

3.4 Python API

from inference import run_inference
result = run_inference("card.jpg", device="npu")
print(f"耗时: {result['time_ms']:.1f}ms")

4. Smoke 验证

python evaluate.py

验证结果：

CPU 推理正常，输出热力图 [1, 1, 192, 192]
NPU 推理正常，输出同形状
精度评测通过

5. 性能参考

测试条件：input [1, 3, 768, 768]。

指标	CPU	NPU (Ascend 910B3)
推理耗时	`1671 ms`	`8 ms`
加速比	—	201.5x

6. 精度评测

6.1 评测方法

对比 CPU (PyTorch) 与 NPU (torch_npu) 在相同随机输入下模型输出热力图 (hm) 的鲁棒平均相对误差（|value| > 0.01）。

6.2 评测结果

指标	数值
输出形状	`[1, 1, 192, 192]`
鲁棒平均相对误差	0.0111%
精度要求	平均相对误差 < 1%
精度评测	通过

7. 注意事项

模型接口：通过 pipeline.infer_model 获取 PoseResNet 模型，输出为 list of dict 包含 hm、reg、wh 等多个头
输入尺寸：固定 768×768，预处理需 resize 到此尺寸
后处理：关键点解码、透视变换等后处理在 CPU 执行
首次推理：NPU 首次推理有算子编译开销（约 10-20s），后续稳定在 ~8ms