冬
gcw_IDzXRVNw/trocr-small-handwritten-ascend
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

TrOCR-small-handwritten 昇腾 NPU 适配部署文档

1. 模型简介

TrOCR (Transformer-based Optical Character Recognition) 是微软发布的一个基于 Transformer 的 OCR 模型,用于手写体文本识别。

本模型是 small-sized 版本,在 IAM 数据集上微调。

模型架构

属性值
模型类型VisionEncoderDecoderModel
编码器DeiT (Vision Transformer)
解码器UniLM (Transformer)
编码器隐藏层维度768
解码器隐藏层维度 (d_model)256
解码器 FFN 维度1024
解码器层数6
解码器 Attention 头数8
位置嵌入最大长度512
权重文件大小~246 MB

模型特点

  • DeiT 编码器: Data-efficient Image Transformer
  • UniLM 解码器: 统一语言模型作为文本解码器
  • 端到端 OCR: 直接从图像生成文本
  • 手写体优化: 在 IAM 数据集上微调
  • 轻量级模型: 相比 base 版本更小更快

输入输出格式

  • 输入: RGB 图像(建议尺寸 384x128 或类似)
  • 输出: 识别出的文本字符串

2. 环境依赖清单

2.1 硬件要求

  • 华为昇腾系列 AI 处理器(Ascend 910B/310P 等)
  • 建议 ≥ 1 GB NPU 显存(TrOCR-small 推理峰值约 500 MB - 1 GB)
  • 本次实测使用 910B2(单卡 64 GB)

2.2 软件依赖

依赖项版本要求说明
操作系统CentOS 7.6+ / Ubuntu 18.04+支持主流 Linux 发行版
CANN5.0.RC2+华为昇腾计算架构
Python3.10 / 3.12推荐 3.10+
PyTorch2.0.0+推荐 2.10
torch_npu与 PyTorch 版本匹配昇腾 PyTorch 扩展
transformers4.40.0+TrOCR 模型加载
Pillow最新版图像处理
numpy最新版数值计算

2.3 安装方式

# 1) 激活已预装 torch / torch_npu 的 conda 环境
conda activate pt2100

# 2) 安装模型依赖(使用华为云源)
pip install --index-url https://repo.huaweicloud.com/repository/pypi/simple \
    transformers>=4.40.0 Pillow numpy

# 3) 验证环境
python -c "
import torch, torch_npu
print('torch:', torch.__version__)
print('torch_npu:', torch_npu.__version__)
print('NPU 可用:', torch.npu.is_available())
"

3. 分步推理操作流程

步骤 1:准备工作目录

# 进入适配目录
cd /workspace/agent1/trocr-small-handwritten-ascend

# 确认上游权重存在
ls -la /workspace/agent2/microsoft/trocr-small-handwritten/

# 期望输出:config.json pytorch_model.bin (~246MB) ...

步骤 2:检查 NPU 环境

# 检查 NPU 设备状态
npu-smi info

# 验证 torch_npu 安装
python -c "import torch; import torch_npu; print('NPU 可用:', torch.npu.is_available())"

步骤 3:运行推理脚本

# 基本用法:默认参数
python inference.py --device npu:0

# 查看 NPU 显存使用
python inference.py --device npu:0 --show_npu_memory

# 指定其他 NPU 卡
python inference.py --device npu:1

4. 完整测试用例

测试用例 1:手写体文本识别(NPU:0)

conda activate pt2100
cd /workspace/agent1/trocr-small-handwritten-ascend
python inference.py --device npu:0

实际输出:

[W822 09:03:06.591960040 FunctionLoader.cpp:48] Warning: LD_PRELOAD detected...
[W822 09:03:16.483195820 NPUCachingAllocator.cpp:201] Warning: The current CANN and Soc versions require processing for 32 padding size, with memory allocation. (function operator())
============================================================
TrOCR-small-handwritten 昇腾 NPU 推理
============================================================

[Device] npu:0
[Model Path] /workspace/agent2/microsoft/trocr-small-handwritten

[Loading] TrOCR processor...
  Processor loaded

[Loading] TrOCR model...
  Model loaded from pretrained

[Model Loaded] Allocated: 0.23 GB, Reserved: 0.25 GB

[npu-smi info]
+------------------------------------------------------------------------------------------------+
| npu-smi 25.5.2                   Version: 25.5.2                                               |
+---------------------------+---------------+----------------------------------------------------+
| NPU   Name                | Health        | Power(W)    Temp(C)           Hugepages-Usage(page)|
| Chip                      | Bus-Id        | AICore(%)   Memory-Usage(MB)  HBM-Usage(MB)        |
+===========================+===============+====================================================+
| 0     910B2               | OK            | 104.0       42                0    / 0             |
| 0                         | 0000:C1:00.0  | 0           0    / 0          3740 / 65536         |
+===========================+===============+====================================================+
+---------------------------+---------------+----------------------------------------------------+
| NPU     Chip              | Process id    | Process name             | Process memory(MB)      |
+===========================+===============+====================================================+
| 0       0                 | 1246480       | python                   | 370                    |
+===========================+===============+====================================================+


[Creating] Dummy handwritten text image (384x128)...

[Input Image] Size: (384, 128)

[Running Inference]...

[npu-smi info]
+------------------------------------------------------------------------------------------------+
| npu-smi 25.5.2                   Version: 25.5.2                                               |
+---------------------------+---------------+----------------------------------------------------+
| NPU   Name                | Health        | Power(W)    Temp(C)           Hugepages-Usage(page)|
| Chip                      | Bus-Id        | AICore(%)   Memory-Usage(MB)  HBM-Usage(MB)        |
+===========================+===============+====================================================+
| 0     910B2               | OK            | 104.3       41                0    / 0             |
| 0                         | 0000:C1:00.0  | 0           0    / 0          3739 / 65536         |
+===========================+===============+====================================================+
+---------------------------+---------------+----------------------------------------------------+
| NPU     Chip              | Process id    | Process name             | Process memory(MB)      |
+===========================+===============+====================================================+
| 0       0                 | 1246480       | python                   | 370                    |
+===========================+===============+====================================================+


[Generating text]...

[npu-smi info]
+------------------------------------------------------------------------------------------------+
| npu-smi 25.5.2                   Version: 25.5.2                                               |
+---------------------------+---------------+----------------------------------------------------+
| NPU   Name                | Health        | Power(W)    Temp(C)           Hugepages-Usage(page)|
| Chip                      | Bus-Id        | AICore(%)   Memory-Usage(MB)  HBM-Usage(MB)        |
+===========================+===============+====================================================+
| 0     910B2               | OK            | 104.6       42                0    / 0             |
| 0                         | 0000:C1:00.0  | 0           0    / 0          3790 / 65536         |
+===========================+===============+====================================================+
+---------------------------+---------------+----------------------------------------------------+
| NPU     Chip              | Process id    | Process name             | Process memory(MB)      |
+===========================+===============+====================================================+
| 0       0                 | 1246480       | python                   | 420                    |
+===========================+===============+====================================================+


[Results]
  Generated text: a b
  Generated IDs shape: torch.Size([1, 4])
[Memory After Inference] Allocated: 0.23 GB, Reserved: 0.28 GB

[Done]

✅ 验证要点:

  • 模型加载成功: TrOCRProcessor + VisionEncoderDecoderModel 全部加载
  • NPU 推理稳定: generate 阶段模型在 NPU 上运行
  • NPU 显存峰值: Allocated 0.23 GB, Reserved 0.28 GB(约 420 MB 进程内存)
  • 输出形状: Generated IDs (1, 4) - 生成的 token 序列
  • 进程监控: npu-smi 显示 Python 进程 (PID 1246480) 在 NPU 上运行
  • 轻量级模型: 相比 base 版本更小的模型,显存占用更低(约 420 MB vs 1600 MB)

5. 常见问题解答

Q1:提示 "NPU 不可用" 怎么办?

解决方案:

  1. 确认已安装 CANN 驱动并设置环境变量(source /usr/local/Ascend/ascend-toolkit/latest/set_env.sh)
  2. 运行 npu-smi info 检查设备状态
  3. 确认 PyTorch 和 torch_npu 版本匹配

Q2:生成文本乱码或无意义?

解释:TrOCR 是 OCR 模型,使用随机图像输入时生成的是无意义字符。实际使用时需要输入包含手写体文本的图像。

Q3:与 base-printed 版本有什么区别?

解释:

  • small-handwritten: 在 IAM 数据集上微调,用于手写体识别,模型更小
  • base-printed: 在 SROIE 数据集上微调,用于印刷体识别,模型更大

6. 文件结构

trocr-small-handwritten-ascend/
├── inference.py              # 推理脚本(torch_npu 推理)
├── README.md                 # 本文档
├── requirements.txt          # 依赖列表
└── assets/                   # 资源占位目录

上游权重目录(只读,未被修改):

/workspace/agent2/microsoft/trocr-small-handwritten/
├── config.json               # TrOCR 配置
├── pytorch_model.bin        # 权重(约 246MB)
├── sentencepiece.bpe.model   # BPE 分词模型
├── processor_config.json     # 处理器配置
├── tokenizer_config.json     # 分词器配置
└── README.md                # 原始文档

7. requirements.txt - 依赖列表

# TrOCR-small-handwritten 昇腾 NPU 推理环境依赖

# 核心依赖(必须)
torch>=2.0.0
torch_npu
transformers>=4.40.0
Pillow
numpy

使用方式:

# 激活环境
conda activate pt2100

# 安装依赖(华为云源)
pip install --index-url https://repo.huaweicloud.com/repository/pypi/simple -r requirements.txt

8. 参考资源

  • TrOCR 论文
  • TrOCR GitHub
  • HuggingFace 模型页
  • IAM 数据集
  • 华为昇腾文档
  • torch_npu GitHub