RapidOCR 昇腾 NPU 部署方案

本项目基于 RapidOCR 轻量化模型，完成检测（det）、方向分类（cls）、识别（rec）三阶段模型在华为昇腾 NPU 上的适配、精度验证与性能优化。

环境要求

# 基础依赖
pip install torch torchvision torch-npu
pip install opencv-python pillow numpy

模型文件

将以下模型文件放置于项目根目录（或 --model-dir 指定目录）：

模型由 ONNX 经 fix_hardswish_onnx.py 修复后转换得到，确保 HardSwish 算子在 NPU 上正确执行。

快速部署

# 1. 克隆/拷贝项目代码到目标环境
# 2. 确认模型文件已到位
ls *.pt

# 3. 验证 NPU 可用
python -c "import torch; print(torch.npu.is_available())"

# 4. 运行单图推理
python inference.py -i sample.jpg -o ./results --visualize

# 5. 运行批量推理
python inference.py -i ./images/ -o ./results

推理脚本使用

inference.py

面向生产环境的推理入口，支持单图/批量输入、可视化输出、JSON 结构化结果。

python inference.py \
  --input ./images/ \
  --output ./results \
  --det-batch 32 \
  --rec-batch 512 \
  --cls-batch 512 \
  --workers 8 \
  --visualize \
  --warmup 2

参数说明：

输出结构：

results/
├── results.json      # 结构化推理结果
└── visualized/       # 可视化图片（--visualize 时生成）

results.json 包含每张图片的检测框坐标、分类/识别预测索引及性能元数据。

精度评测

eval_precision.py

端到端精度对比脚本，CPU 作为基准，NPU 作为目标，对比 det/rec/cls 三阶段输出。

python eval_precision.py

评测指标与通过标准：

结果同时输出到终端与 logs/precision_eval.log。

性能评测

eval_performance.py

固定最优 batch size（det=32, rec=512, cls=512），在测试集上运行多轮取平均，输出完整性能报告。

python eval_performance.py

关键性能指标：

结果同时输出到终端与 logs/performance_eval.log。

性能基准（参考值）

以下数据基于 Ascend 910B 单卡，batch size det=32/rec=512/cls=512，ICDAR2015 测试集（500 张图），测试时间 2026-05-28。

端到端 wall-clock 时间（核心指标）

NPU vs CPU 加速比：40.47x

优化收益：端到端时间从 22.9s 降至 10.9s（-52%），精度结果保持一致。

各阶段耗时拆解（NPU，500 图）

实际数值请运行 eval_performance.py 获取。

性能基线对比（NPU 是否达标）

以下将本方案 NPU 实测数据与 RapidOCR 官方 CPU 基线（i5-10400F，16GB，800×600 常规图文）进行横向对比。

结论

• 速度层面：NPU 端到端推理速度 大幅优于 官方 CPU 基线，达标。
• 精度层面：检测与分类完全达标；识别阶段张量数值误差 < 1%（rapidocr_npu_verify.py 验证通过），但端到端 argmax 一致性为 97%，存在 3% 的单字符差异。若业务场景对识别准确率要求 ≥ 99%，建议尝试调整 ACL_PRECISION_MODE 或 ACL_OP_SELECT_IMPL_MODE 进一步调优（参考 test_npu_precision_opts.py）。
• 待补数据：NPU 内存占用、中文场景绝对准确率、与 PaddleOCR NPU 版的直接对比。

项目文件结构

.
├── inference.py              # 生产推理入口
├── eval_precision.py         # 精度评测脚本
├── eval_performance.py       # 性能评测脚本
├── rapidocr_npu_verify.py    # 单图精度验证（开发调试用）
├── rapidocr_npu_e2e_batch.py # 端到端批量验证（开发调试用）
├── rapidocr_npu_e2e_optimized.py # 优化版端到端验证（开发调试用）
├── batch_size_tuning.py      # Batch size 调优（开发调试用）
├── test_npu_precision_opts.py # NPU 精度选项探索（开发调试用）
├── fix_hardswish_onnx.py     # ONNX HardSwish 修复工具
├── logs/                     # 评测日志输出目录
├── results/                  # 推理结果输出目录
├── *.pt                      # 模型文件
└── readme.md                 # 本文档

精度说明

• 相对误差（valid-region max relative error）< 1%
• 功能等价性：argmax 一致性 >= 99%
• 检测框坐标误差 < 2 像素
• 若精度不达标，可尝试调整 ACL_PRECISION_MODE 或 ACL_OP_SELECT_IMPL_MODE（参考 test_npu_precision_opts.py）

常见问题

1. NPU 初始化慢：首次推理包含算子编译缓存生成，属正常现象；warmup 后的推理速度稳定。
2. OOM：适当降低 --rec-batch 或 --cls-batch。
3. 精度偏差大：检查是否使用了经 fix_hardswish_onnx.py 修复后的模型。

许可证

模型与代码遵循各自原始许可证。本项目适配代码仅供昇腾 NPU 部署参考。