RapidOCR 昇腾 NPU 适配部署

RapidOCR/
├── README.md                # 本文档
├── npu_pipeline.py          # ⭐ NPU 推理管线 (torch_npu + onnx2torch，主力方案)
├── inference.py             # NPU 推理主脚本（上层入口）
├── inference_cpu.py         # CPU 推理脚本（精度对比基线）
├── eval_precision.py        # 精度评测脚本（CPU vs NPU）
├── eval_performance.py      # NPU 性能评测脚本
├── eval_performance_cpu.py  # CPU 性能基线脚本
├── npu_config.py            # NPU 推理配置（仅用于 CANNExecutionProvider 参考）
├── npu_infer.py             # ⛔ 已弃用 — 被 npu_pipeline.py 替代
├── npu_engine.py            # ⛔ 已弃用 — 被 npu_pipeline.py 替代
├── npu_acl_engine.py        # AscendCL Python 封装（原生推理引擎）
├── bench_acl.py             # AscendCL 子进程隔离基准测试脚本
├── det_om.om                # ATC 转换的检测 OM 模型
├── rec_om.om                # ATC 转换的识别 OM 模型
├── setup_env.py             # 环境检查与配置
├── download_test_images.py  # 测试图片下载
├── test_images/             # 测试图片目录
│   ├── ch_en_num.jpg
│   ├── sample.jpg
│   └── multi_lang.jpg
└── models/                  # 模型文件（首次运行自动下载）

# 基础依赖
pip install -r requirements.txt

# 安装 RapidOCR（必需，用于模型加载）
pip install rapidocr-onnxruntime

# 安装 onnx2torch（ONNX → PyTorch 转换）
pip install onnx2torch

# 检查 NPU 驱动、torch_npu 状态
python setup_env.py

🖥  NPU 环境检查
  ✅ npu-smi: 可用
  ✅ CANN 目录: /usr/local/Ascend
  ✅ torch_npu: 可用
  ✅ onnx2torch: 可用

python download_test_images.py

python inference.py --img test_images/ch_en_num.jpg

🚀 初始化 RapidOCR NPU 引擎 (device=0)...
✅ 引擎初始化完成

📄 处理图片: ch_en_num.jpg
⏱ 推理耗时: 85.3 ms

📝 OCR 结果:
[0] 文本: 香港嘉道理農場
     置信度: 0.9912
     框: (63, 10), (304, 10), (304, 51), (6, 51)
[1] 文本: Kadoorie Farm
     置信度: 0.9875
     框: (63, 66), (226, 66), (226, 88), (6, 88)

python inference.py --img test_images/ --batch

python inference.py --img test_images/ch_en_num.jpg --vis

python inference.py --img test_images/ch_en_num.jpg --device 0

python eval_precision.py --img_dir test_images/

📊 RapidOCR NPU vs CPU 精度对比报告
──────────────────────────────────────────────────
指标                        值               结论
──────────────────────────────────────────────────
检测框平均 IOU               0.8694            ✅
框顶点平均 L2 距离            1.30 px          ✅
文本编辑距离                  0.1230            ⚠️(FP16)
文本精确匹配率                0.3000            ⚠️(FP16)
置信度平均差异                0.0328            ⚠️(FP16)
──────────────────────────────────────────────────

📝 逐框文本对比（仅显示不一致的）
──────────────────────────────────────────────────
  [sample.jpg 框#0] CPU=[wwwnKadoorieFarm] NPU=[KadoorieFarm] ✗
  [sample.jpg 框#1] CPU=[RapidOCRwaNPU] NPU=[RapidOCR图NPU] ✗
  [sample.jpg 框#3] CPU=[01234567891@#$%*()] NPU=[0123456789！@$%8] ✗
  [multi_lang.jpg 框#0] CPU=[Welcome toNPU OCR图] NPU=[Welcome to国NPU OCR图] ✗
  [multi_lang.jpg 框#1] CPU=[Artificial Intelligence] NPU=[ArtificialIntelligence] ✗
  [multi_lang.jpg 框#4] CPU=[2024-01-15|HelloWorld!] NPU=[2024-01-15|HelloWorld！] ✗
──────────────────────────────────────────────────

# NPU 性能
python eval_performance.py --img_dir test_images/ --warmup 3 --iters 10

# CPU 基线（用于对比）
python eval_performance_cpu.py --img_dir test_images/ --iters 5

输入图片
    │
    ▼
┌─────────────────────────────────────┐
│   npu_pipeline.py (RapidOCRNPU)     │
│                                     │
│   ┌───────────┐  ┌───────────────┐  │
│   │  文本检测  │  │  ONNX 模型   │  │
│   │  预处理+后 │  │ PP-OCRv4_det │  │
│   │  (复用原版)│  │ (onnx2torch) │  │
│   └─────┬─────┘  └───────┬───────┘  │
│         │                │          │
│   ┌─────▼─────┐  ┌───────▼───────┐  │
│   │  文本方向  │  │  ONNX 模型   │  │
│   │  分类+旋转 │  │ PP-OCRv4_cls │  │
│   └─────┬─────┘  └───────┬───────┘  │
│         │                │          │
│   ┌─────▼─────┐  ┌───────▼───────┐  │
│   │  文本识别  │  │  ONNX 模型   │  │
│   │  CTC解码  │  │ PP-OCRv4_rec │  │
│   └───────────┘  └───────┬───────┘  │
│                          │          │
│                    ┌─────▼──────┐   │
│                    │ torch_npu  │   │
│                    │ (AMP FP16) │◀── NPU
│                    └────────────┘   │
└─────────────────────────────────────┘

# 核心用法（npu_pipeline.py）
engine = RapidOCRNPU(device_id=0, use_fp16=True, batch_size=6)
engine.warmup()
result, _ = engine("test_images/sample.jpg")
engine.close()

A: 确认当前使用的推理路径:
   - torch_npu 路径 (npu_pipeline.py): 开箱即用，最稳定
   - AscendCL 路径 (bench_acl.py): 需先 source set_env.sh 并转换 OM 模型

   torch_npu 与 acl Python 库存在 libascendcl.so 版本冲突:
   - 在同一进程同时 import torch_npu 和 acl 会导致 std::bad_alloc
   - bench_acl.py 通过子进程隔离运行 ACL 推理

A: 确保 CANN Toolkit 已安装，执行:
   # 1. 设置环境
   source /usr/local/Ascend/ascend-toolkit/latest/set_env.sh

   # 2. 转换模型
   atc --model=models/ch_PP-OCRv4_det_infer.onnx --framework=5 --output=det_om \
       --soc_version=Ascend910_9362 --input_shape="x:1,3,960,960" \
       --input_format=NCHW --output_type=FP32
   atc --model=models/ch_PP-OCRv4_rec_infer.onnx --framework=5 --output=rec_om \
       --soc_version=Ascend910_9362 --input_shape="x:1,3,48,320" \
       --input_format=NCHW --output_type=FP32

   # 3. 运行基准测试
   python3 bench_acl.py test_images/sample.jpg 20

   # 替换 soc_version 为您设备的 SoC 型号:
   #   Ascend910_9362 → Atlas 800 A2 (Ascend 910B2/910_9362)
   #   Ascend910B1    → Atlas 800 A2 (Ascend 910B1/910B)
   #   Ascend310P3    → Atlas 200I A2

   性能对比:
   | 指标 | torch_npu | AscendCL (OM) | 加速 |
   |:----|:---------:|:-------------:|:----:|
   | DET 推理 | 8.36ms | 2.26ms | 3.7× |
   | REC 推理 | 4.01ms | 0.90ms | 4.5× |
   | 端到端含pre/post | 64ms | 36ms | 1.78× |

A: 手动下载或使用代理:
   # 开启代理
   export http_proxy=http://proxy:port
   export https_proxy=http://proxy:port
   
   # 或手动下载模型至 models/ 目录

A: 运行精度评测，查看具体差异:
   python eval_precision.py --img_dir test_images/
   
   常见原因:
   - fp16 精度模式导致的数值差异
   - onnx2torch 转换产生的微小浮点差异 (~3e-6)
   - 运行 `eval_precision.py` 确认各项指标

A: 当前已实现两条推理路径，可直接使用:

1. **torch_npu 路径**（推荐，开箱即用）
   使用 npu_pipeline.py，CPU~1108ms → NPU~57ms，加速 ~19×
   安装依赖后直接运行即可

2. **AscendCL 原生路径**（需 CANN Toolkit）
   使用 bench_acl.py 子进程隔离运行 ACL 推理
   NPU 推理延迟: DET 2.26ms / REC 0.90ms / 端到端含pre/post ~36ms (28 FPS)
   详见 FAQ「如何使用 AscendCL 原生推理（OM 模型）获得极致性能」