OFA OCR Recognition - 昇腾 NPU 适配部署文档

1. 模型信息

项目	说明
模型名称	OFA OCR Recognition General Base ZH
模型 ID	`iic/ofa_ocr-recognition_general_base_zh`
来源	ModelScope (达摩院 iic)
任务	OCR 文字识别
语言	中文
架构	OFA (One-For-All) Encoder-Decoder Transformer + ResNet101 视觉编码器
参数规模	~180M
输入	图片 (含文字区域)
输出	识别的文字内容

2. 环境要求

依赖	版本	说明
Python	3.11
torch	2.9.0	PyTorch
torch_npu	2.9.0	昇腾 NPU 适配
CANN	8.5.1	昇腾计算框架
modelscope	1.18+	模型加载框架
transformers	4.48.3	OFA 模型依赖
fairseq	0.12.2	序列生成器 (需手动修复兼容性)
NPU	Ascend 910A/B	至少 1 张

3. 快速开始

3.1 下载模型

modelscope download --model iic/ofa_ocr-recognition_general_base_zh \
  --local_dir /opt/atomgit/.cache/modelscope/hub/models/iic/ofa_ocr-recognition_general_base_zh

3.2 安装依赖

pip install modelscope transformers==4.48.3 fairseq==0.12.2 rapidfuzz portalocker lxml

3.3 修复 fairseq 兼容性 (Python 3.11)

fairseq 0.12.2 在 Python 3.11 上存在兼容性问题，运行环境修复脚本：

bash setup_env.sh

或手动修复（详见附录 A）。

3.4 运行推理

# NPU 推理 - 单张图片
python inference.py --image /path/to/image.jpg --device npu:0

# NPU 推理 - 批量
python inference.py --image_dir /path/to/images/ --output_dir results/ --device npu:0

# CPU 推理
python inference.py --image /path/to/image.jpg --device cpu

# API 服务模式
python inference.py --serve --port 8000 --device npu:0

4. 推理正常输出证据

4.1 NPU 推理结果

使用模型自带 4 张 demo 图片在 Ascend 910 (9362) NPU 上验证推理：

============================================================
  OFA OCR Recognition - 昇腾 NPU 推理
============================================================
  Python:      3.11.14
  torch:       2.9.0
  torch_npu:   2.9.0
  NPU 0:       Ascend910_9362  (60.9GB free / 61.3GB total)
  推理设备:    npu:0
  模型目录:    /opt/atomgit/.cache/modelscope/hub/models/iic/ofa_ocr-recognition_general_base_zh
============================================================

[INFO] 加载模型: /opt/atomgit/.cache/modelscope/hub/models/iic/ofa_ocr-recognition_general_base_zh
[INFO] 模型加载完成 (2.3s)
[INFO] 模型已迁移到 npu:0

[INFO] 使用 demo 图片验证 NPU 推理...
  ocr_general_demo.png: 里万程鹏 (11.2s)
  ocr_general.png: 本外贸精品服装店专柜正品代购 (24.5s)
  ocr_scene.png: 大排档真功夫电器自助烤肉 (20.3s)
  image_ocr_recognition.jpg: 欢迎光临 (10.5s)

4.2 CPU 推理结果

  CPU  ocr_general.png: 本外贸精品服装店专柜正品代购  (53.78s)
  CPU  ocr_general_demo.png: 里万程鹏  (10.58s)
  CPU  ocr_scene.png: 大排档真功夫电器自助烤肉  (19.64s)
  CPU  image_ocr_recognition.jpg: 欢迎光临  (10.47s)

5. CPU/NPU 精度对比数据

5.1 逐张精度对比

图片	CPU 文字	NPU 文字	一致	CPU 延迟(s)	NPU 延迟(s)
ocr_general.png	本外贸精品服装店专柜正品代购	本外贸精品服装店专柜正品代购	✅	53.778	24.759
ocr_general_demo.png	里万程鹏	里万程鹏	✅	10.580	10.981
ocr_scene.png	大排档真功夫电器自助烤肉	大排档真功夫电器自助烤肉	✅	19.644	20.438
image_ocr_recognition.jpg	欢迎光临	欢迎光临	✅	10.469	11.084

5.2 汇总统计

指标	CPU	NPU
总推理时间 (4张)	94.471s	67.262s
平均每张延迟	23.618s	16.816s
最大延迟	53.778s	24.759s
最小延迟	10.469s	10.981s
精度一致性	-	✅ 4/4 全部一致 (100%)
NPU 加速比	-	1.40x
NPU 显存占用	-	0.14 GB / 61.3 GB
NPU 设备	-	Ascend910_9362

5.3 精度结论

CPU 与 NPU 推理结果完全一致，4 张 demo 图片识别文字逐字相同，无任何精度差异。

说明：OFA OCR 为 Encoder-Decoder 架构，输出为离散 token 序列（文字），因此 CPU/NPU 精度对比不存在浮点误差，只有完全一致或不一致两种情况。

6. 性能分析

6.1 NPU 加速效果

长文本场景 (ocr_general.png, 12字): NPU 加速比 2.17x (53.8s → 24.8s)
短文本场景 (ocr_general_demo.png, 4字): 延迟基本持平 (10.6s vs 11.0s)
场景文字 (ocr_scene.png, 10字): 基本持平 (19.6s vs 20.4s)

6.2 性能瓶颈分析

当前推理延迟偏高，主要瓶颈在于：

Beam Search 在 CPU 执行: OFA 的序列生成器 (fairseq SequenceGenerator) 在 CPU 上运行，每个解码 step 都有 CPU↔NPU 数据传输开销
单步串行生成: 自回归解码无法并行，累计传输开销大
CPU↔NPU 数据搬运: 每个 token 的生成需要 encoder 输出从 NPU 传到 CPU、当前 step 结果从 CPU 传回 NPU

6.3 优化建议

优化方向	预期效果	难度
替换为 HF generate()	减少 CPU↔NPU 传输	中
torch.compile 图模式	编码器加速	中
FP16 推理	减少显存和计算量	低
Batch 推理	提高 NPU 利用率	低

7. 交付件清单

文件	说明
`inference.py`	推理脚本 (NPU/CPU/API服务)
`benchmark_precision.py`	CPU/NPU 精度对比 & 性能评测脚本
`benchmark_results.json`	评测结果数据
`setup_env.sh`	环境修复脚本
`run_verify.sh`	一键验证脚本 (用户自截图用)
`README.md`	本文档

8. 自验证操作指南

8.1 一键验证 (推荐)

cd /opt/atomgit/ofa-ocr-recognition
bash run_verify.sh

运行后终端会依次输出：环境信息 → NPU推理结果 → CPU/NPU精度对比 → 单张示例 → 交付件清单。 请对终端输出截图保存，作为推理正常输出证据。

8.2 分步验证

# 步骤1: 环境检查
python3 -c "import torch, torch_npu; print(f'NPU: {torch.npu.get_device_name(0)}')"

# 步骤2: NPU 推理
python3 inference.py --device npu:0

# 步骤3: 精度对比
python3 benchmark_precision.py

# 步骤4: 单张图片推理
python3 inference.py --image YOUR_IMAGE.jpg --device npu:0

9. 启动运行推理日志

============================================================
  OFA OCR Recognition - 昇腾 NPU 推理
============================================================
  Python:      3.11.14
  torch:       2.9.0
  torch_npu:   2.9.0
  NPU 可用:    True
  NPU 0:       Ascend910_9362
  推理设备:    npu:0
  模型目录:    /opt/atomgit/.cache/modelscope/hub/models/iic/ofa_ocr-recognition_general_base_zh
============================================================

[INFO] 加载模型: /opt/atomgit/.cache/modelscope/hub/models/iic/ofa_ocr-recognition_general_base_zh
[INFO] 模型加载完成 (2.3s)
[INFO] 模型已迁移到 npu:0

[INFO] 使用 demo 图片验证 NPU 推理...
  ocr_general_demo.png: 里万程鹏 (11.2s)
  ocr_general.png: 本外贸精品服装店专柜正品代购 (24.5s)
  ocr_scene.png: 大排档真功夫电器自助烤肉 (20.3s)
  image_ocr_recognition.jpg: 欢迎光临 (10.5s)

CPU/NPU 精度对比日志

======================================================================
  OFA OCR Recognition - CPU/NPU 精度对比 & 性能评测
======================================================================
  torch:       2.9.0
  torch_npu:   2.9.0
  NPU:         Ascend910_9362
  NPU 显存:    60.9 GB free / 61.3 GB total
======================================================================

  [1/2] CPU 推理
  ======================================================================
  CPU  ocr_general.png: 本外贸精品服装店专柜正品代购  (avg 53.778s)
  CPU  ocr_general_demo.png: 里万程鹏  (avg 10.580s)
  CPU  ocr_scene.png: 大排档真功夫电器自助烤肉  (avg 19.644s)
  CPU  image_ocr_recognition.jpg: 欢迎光临  (avg 10.469s)

  [2/2] NPU 推理 (npu:0)
  ======================================================================
  Warmup...
  NPU  ocr_general.png: 本外贸精品服装店专柜正品代购  (avg 24.759s)
  NPU  ocr_general_demo.png: 里万程鹏  (avg 10.981s)
  NPU  ocr_scene.png: 大排档真功夫电器自助烤肉  (avg 20.438s)
  NPU  image_ocr_recognition.jpg: 欢迎光临  (avg 11.084s)

======================================================================
  精度对比 & 性能报告
======================================================================
图片                                  CPU文字                NPU文字                一致     CPU_avg(s)   NPU_avg(s)
----------------------------------------------------------------------------------------------------
ocr_general.png                     本外贸精品服装店专柜正品代购       本外贸精品服装店专柜正品代购       ✅      53.778       24.759
ocr_general_demo.png                里万程鹏                 里万程鹏                 ✅      10.580       10.981
ocr_scene.png                       大排档真功夫电器自助烤肉         大排档真功夫电器自助烤肉         ✅      19.644       20.438
image_ocr_recognition.jpg           欢迎光临                 欢迎光临                 ✅      10.469       11.084
----------------------------------------------------------------------------------------------------
总计/平均                                                                                94.471       67.262
平均每张                                                                                 23.618       16.816

精度一致性: ✅ 全部一致
NPU 加速比:  1.40x
NPU 显存占用: 0.14 GB / 61.3 GB

结果已保存: /opt/atomgit/ofa-ocr-recognition/benchmark_results.json

10. API 服务

python inference.py --serve --port 8000 --device npu:0

GET 请求

curl "http://localhost:8000/?image=/path/to/image.jpg"

POST 请求

curl -X POST http://localhost:8000/ \
  -H "Content-Type: application/json" \
  -d '{"image": "/path/to/image.jpg"}'

响应格式

{
  "image": "/path/to/image.jpg",
  "text": "识别的文字内容",
  "inference_time_s": 10.5
}

附录 A: fairseq 手动修复步骤

fairseq 0.12.2 与 Python 3.11 存在两处兼容性问题：

A.1 修复 hydra_init

FAIRSEQ_INIT=~/.local/lib/python3.11/site-packages/fairseq/__init__.py

# 将 hydra_init() 调用包裹在 try-except 中
sed -i 's/^hydra_init()$/try:\n    hydra_init()\nexcept Exception:\n    pass/' "$FAIRSEQ_INIT"

A.2 修复 dataclass mutable default

FAIRSEQ_CONFIG=~/.local/lib/python3.11/site-packages/fairseq/models/transformer/transformer_config.py

# 在文件头添加 field 导入
sed -i '/from dataclasses import dataclass/s/dataclass/field, dataclass/' "$FAIRSEQ_CONFIG"

# 将可变默认值改为 field(default_factory=...)
# encoder: EncDecBaseConfig = EncDecBaseConfig()
# → encoder: EncDecBaseConfig = field(default_factory=EncDecBaseConfig)
sed -i 's/encoder: EncDecBaseConfig = EncDecBaseConfig()/encoder: EncDecBaseConfig = field(default_factory=EncDecBaseConfig)/' "$FAIRSEQ_CONFIG"
sed -i 's/decoder: DecoderConfig = DecoderConfig()/decoder: DecoderConfig = field(default_factory=DecoderConfig)/' "$FAIRSEQ_CONFIG"
sed -i 's/quant_noise: QuantNoiseConfig = field(default=QuantNoiseConfig())/quant_noise: QuantNoiseConfig = field(default_factory=QuantNoiseConfig)/' "$FAIRSEQ_CONFIG"

A.3 创建 decord stub (aarch64)

mkdir -p ~/.local/lib/python3.11/site-packages/decord
cat > ~/.local/lib/python3.11/site-packages/decord/__init__.py << 'EOF'
class VideoReader:
    def __init__(self, *args, **kwargs):
        raise NotImplementedError("decord stub: video not supported on aarch64")
EOF

附录 B: 评测结果原始数据

见 benchmark_results.json 文件。