PaddleOCR 昇腾 NPU 环境搭建实战基于飞桨框架的 Docker 安装、验证与多卡使用指南【免费下载链接】PaddleOCR飞桨多语言OCR工具包实用超轻量OCR系统支持80种语言识别提供数据标注与合成工具支持服务器、移动端、嵌入式及IoT设备端的训练与部署 Awesome multilingual OCR toolkits based on PaddlePaddle (practical ultra lightweight OCR system, support 80 languages recognition, provide data annotation and synthesis tools, support training and deployment among server, mobile, embedded and IoT devices)项目地址: https://gitcode.com/paddlepaddle/PaddleOCR本指南以飞桨 PaddleOCR 官方文档《昇腾 NPU 飞桨安装教程》为核心系统讲解如何在昇腾 910B 芯片上从零搭建 PaddleOCR 的飞桨运行环境涵盖官方开发镜像拉取、容器启动、飞桨 CPU 版与 NPU 定制版安装、依赖版本约束、安装验证以及安装完成后 NPU 上的产线推理与模型微调用法。读完本文你将具备一套可复现、可排错的昇腾 NPU 环境准备流程并能在该硬件上直接运行 PaddleOCR 的三大特色能力PP-OCRv5 文字识别、PP-StructureV3 文档解析、PP-ChatOCRv4。1、支持范围与环境前提当前 PaddleOCR 对昇腾 NPU 的支持以昇腾 910B 芯片为基准昇腾驱动版本要求为23.0.3更多芯片型号仍在持续适配中。考虑到宿主机环境差异较大驱动版本、CANN 算子库、系统架构各不相同官方推荐使用飞桨提供的昇腾开发镜像完成环境准备以最大程度规避环境差异带来的兼容性问题。需要特别说明的是本文档介绍的是基于飞桨框架的安装与使用方式如果你计划使用其他推理引擎如 vLLM、ONNX Runtime 等请参考对应引擎的官方文档完成安装与配置。此外昇腾 NPU 环境准备完成后PaddleOCR 在该硬件上的训练、推理用法与 GPU 基本一致只需将设备参数改为npu即可详见后文第 5 节。2、Docker 开发环境准备2.1 拉取飞桨昇腾开发镜像飞桨官方提供了专门面向昇腾 910B 的开发镜像镜像中已默认安装昇腾算子库CANN-8.0.0。注意该镜像仅为开发环境其中不包含预编译的飞桨安装包飞桨需要后续手动安装。根据宿主机 CPU 架构选择对应镜像# 适用于 X86 架构 docker pull ccr-2vdh3abv-pub.cnc.bj.baidubce.com/device/paddle-npu:cann800-ubuntu20-npu-910b-base-x86_64-gcc84 # 适用于 Aarch64 架构 docker pull ccr-2vdh3abv-pub.cnc.bj.baidubce.com/device/paddle-npu:cann800-ubuntu20-npu-910b-base-aarch64-gcc84从镜像名称可以解读出关键信息cann800表示内置 CANN-8.0.0 算子库ubuntu20表示基于 Ubuntu 20.04npu-910b表示面向昇腾 910Bgcc84表示使用 GCC 8.4 工具链编译。仓库中 deploy/paddleocr_vl_docker/accelerators/huawei-npu/pipeline.Dockerfile 同样以这两个镜像作为多阶段构建的基底印证了它们是昇腾 NPU 侧统一使用的官方基础镜像。2.2 启动容器并挂载 NPU 设备参考如下命令启动容器其中ASCEND_RT_VISIBLE_DEVICES用于指定容器内可见的 NPU 卡号docker run -it --name paddle-npu-dev -v $(pwd):/work \ --privileged --networkhost --shm-size128G -w/work \ -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \ -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \ -v /usr/local/dcmi:/usr/local/dcmi \ -e ASCEND_RT_VISIBLE_DEVICES0,1,2,3,4,5,6,7 \ ccr-2vdh3abv-pub.cnc.bj.baidubce.com/device/paddle-npu:cann800-ubuntu20-npu-910b-base-$(uname -m)-gcc84 /bin/bash关键参数说明参数作用--privileged赋予容器特权模式访问 NPU 设备与内核模块所必需--networkhost使用宿主机网络便于多卡通信与调试--shm-size128G扩大共享内存满足大数据量训练/推理的进程间通信需求-v /usr/local/Ascend/driver:/usr/local/Ascend/driver挂载宿主机昇腾驱动容器复用驱动而非自带-v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi挂载npu-smi监控工具容器内可查询 NPU 状态-v /usr/local/dcmi:/usr/local/dcmi挂载 DCMIDevice Control Management Interface管理接口-e ASCEND_RT_VISIBLE_DEVICES0,1,2,3,4,5,6,7指定容器可见的 NPU 卡号列表-w/work设置容器内工作目录为挂载的宿主机目录使用$(uname -m)可自动匹配 x86_64 / aarch64 对应的镜像标签无需手动区分架构。如果只想让容器使用部分卡将ASCEND_RT_VISIBLE_DEVICES改为对应卡号即可例如0,1。3、安装飞桨 NPU 定制版3.1 安装顺序先 CPU 版再 NPU 定制版进入容器后首先安装飞桨 CPU 版本再安装 NPU 定制版本paddle-custom-npu两个包的版本号需要严格保持一致# 注意需要先安装飞桨 cpu 版本 python -m pip install paddlepaddle3.0.0.dev20250527 -i https://www.paddlepaddle.org.cn/packages/nightly/cpu python -m pip install paddle-custom-npu3.0.0.dev20250527 -i https://www.paddlepaddle.org.cn/packages/nightly/npupaddlepaddle为飞桨基础框架CPU 版提供算子定义、自动微分、分布式等核心能力paddle-custom-npu为昇腾 NPU 定制安装包内含 NPU 算子实现与设备适配层依赖基础框架运行两者版本号必须一一对应如上例均为3.0.0.dev20250527否则可能因算子接口不匹配而加载失败安装源使用了飞桨 nightly 定制源CPU 包走.../nightly/cpuNPU 定制包走.../nightly/npu。如果使用稳定版本路线仓库中 deploy/paddleocr_vl_docker/accelerators/huawei-npu/pipeline.Dockerfile 给出了稳定版安装示例paddlepaddle3.2.0stable/cpu 源paddle-custom-npu3.2.0stable/npu 源docs/version3.x/pipeline_usage/PaddleOCR-VL-Huawei-Ascend-NPU.md 也明确要求安装 3.2.0 及以上版本的飞桨框架。实际使用时可根据需要选择 nightly 或 stable 源但务必保持两个包版本一致。3.2 固定 numpy 与 opencv 版本CANN-8.0.0 对numpy和opencv的部分版本不兼容官方建议安装如下指定版本python -m pip install numpy1.26.4 python -m pip install opencv-python3.4.18.65这是昇腾 NPU 环境中最常见的坑之一若 numpy/opencv 版本与 CANN 算子库冲突可能出现算子编译失败或运行时异常。在 deploy/paddleocr_vl_docker/accelerators/huawei-npu/pipeline.Dockerfile 中可以看到官方 NPU 镜像同样将 numpy 固定为1.26.4opencv 则使用opencv-contrib-python4.11.0.86说明该版本组合是经过验证的。3.3 ARM 机器的环境变量x86 无需设置在 ARMaarch64机器上需要额外设置环境变量解决libgomp的动态链接错误# 解决libgomp在arm机器上报错 # libgomp cannot allocate memory in static TLS block export LD_PRELOAD/usr/lib/aarch64-linux-gnu/libgomp.so.1:$LD_PRELOAD该错误源于 ARM 架构下 OpenMP 运行库libgomp的静态 TLSThread Local Storage分配限制通过LD_PRELOAD提前加载共享库可绕过该问题。x86 环境下无需设置此变量。建议将上述export写入容器的~/.bashrc避免每次进入容器重复设置。4、验证安装安装完成后运行飞桨自带的运行检查命令python -c import paddle; paddle.utils.run_check()预期得到如下输出Running verify PaddlePaddle program ... PaddlePaddle works well on 1 npu. PaddlePaddle works well on 8 npus. PaddlePaddle is installed successfully! Lets start deep learning with PaddlePaddle now.输出中的关键信息PaddlePaddle works well on 1 npu.单卡计算正确NPU 算子可正常执行PaddlePaddle works well on 8 npus.多卡通信8 卡验证通过PaddlePaddle is installed successfully!整体安装成功。如果输出与上述不一致或报错可依次检查驱动是否已挂载进容器npu-smi info是否可查询到卡、ASCEND_RT_VISIBLE_DEVICES是否设置、paddlepaddle与paddle-custom-npu版本是否一致、numpy/opencv 版本是否为指定版本。5、安装完成后的 NPU 使用快速推理与模型微调环境就绪后PaddleOCR 在昇腾 NPU 上的训练、推理用法与 GPU 相同只需把设备参数改为npu。在 NPU 上支持 PaddleOCR 三大特色能力的快速推理和模型微调包括文字识别模型 PP-OCRv5、文档解析方案 PP-StructureV3 和 PP-ChatOCRv4详见 多硬件使用指南。5.1 一行命令快速推理# 默认使用 PP-OCRv5 模型将设备名修改为 npu 即可 paddleocr ocr -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_ocr_002.png --device npu:0 # PP-StructureV3 产线推理 paddleocr pp_structurev3 -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/pp_structure_v3_demo.png --device npu:0其中--device npu:0表示使用第 0 号昇腾 NPU 卡与--device gpu:0的写法保持一致。5.2 Python API 推理from paddleocr import PaddleOCR ocr PaddleOCR(devicenpu:0) result ocr.predict(./general_ocr_002.png) for res in result: res.print() res.save_to_img(output) res.save_to_json(output)文档解析产线 PP-StructureV3 的用法同理from paddleocr import PPStructureV3 pipeline PPStructureV3(devicenpu:0) output pipeline.predict(./pp_structure_v3_demo.png) for res in output: res.print() # 打印预测的结构化输出 res.save_to_json(save_pathoutput) # 保存当前图像的结构化 json 结果 res.save_to_markdown(save_pathoutput) # 保存当前图像的 markdown 格式结果5.3 模型微调如果预训练模型效果不满意可以在 NPU 上对产线模型进行微调。昇腾 NPU 微调前需先设置一组运行环境变量再以Global.use_npuTrue启动训练export FLAGS_npu_storage_format0 export FLAGS_npu_jit_compile0 export FLAGS_use_stride_kernel0 export FLAGS_allocator_strategyauto_growth export FLAGS_npu_split_aclnnTrue export FLAGS_npu_scale_aclnnTrue export CUSTOM_DEVICE_BLACK_LISTpad3d,pad3d_grad python3 -m paddle.distributed.launch --devices 0,1,2,3 \ tools/train.py -c configs/rec/PP-OCRv5/PP-OCRv5_mobile_rec.yml \ -o Global.use_gpuFalse Global.use_npuTrue这些环境变量的作用分别是关闭 NPU 存储格式重排与 JIT 算子编译提升兼容性、关闭 stride kernel、设置显存分配策略为 auto_growth、开启 aclnn 算子的拆分与缩放并通过CUSTOM_DEVICE_BLACK_LIST将pad3d及其反向算子标记为回退到 CPU 执行NPU 侧尚未实现该算子时必备。多卡训练通过--devices 0,1,2,3指定参与训练的 NPU 卡号。5.4 其他推理方式ONNX 与 OM 模型对于少量推理样本使用产线直接推理尤其是 PP-StructureV3 产线在 NPU 上可能存在结果异常的情况此时官方建议使用 ONNX 模型保证推理结果正确paddlex --install paddle2onnx paddlex --paddle2onnx --paddle_model_dir /paddle_model_dir --onnx_model_dir /onnx_model_dir --opset_version 7同时部分模型支持昇腾离线 OM 推理可有效优化推理性能和内存占用。使用atc工具将 ONNX 模型转换为 OM 模型atc --modelinference.onnx --framework5 --outputinference --soc_versionyour_device_type --input_shape your_input_shape其中--framework5表示输入为 ONNX 格式--soc_version填写实际芯片型号如 910B 对应型号。ONNX 与 OM 模型已深度集成进 PaddleX 高性能推理修改产线配置文件、将推理后端配置为 ONNX 或 OM 后即可使用 PaddleX 高性能推理 API。6、常见问题1. 使用 PP-StructureV3 产线推理结果不正确该产线上的部分模型在少量 case 上存在精度误差。可以尝试调整配置文件中的模型或者改用 ONNXOM 模型进行推理见 5.4 节。2. ARM 机器上libgomp cannot allocate memory in static TLS block报错按第 3.3 节设置LD_PRELOAD环境变量指向/usr/lib/aarch64-linux-gnu/libgomp.so.1。3.paddle.utils.run_check()无法识别 NPU依次检查驱动挂载-v /usr/local/Ascend/driver等三个挂载点、ASCEND_RT_VISIBLE_DEVICES卡号、paddlepaddle与paddle-custom-npu版本一致性、numpy/opencv 是否为指定版本。4. 希望使用特定版本或稳定版飞桨将paddlepaddle与paddle-custom-npu的版本号替换为同一稳定版本如3.2.0并将安装源从nightly/cpu、nightly/npu换成stable/cpu、stable/npu参考 deploy/paddleocr_vl_docker/accelerators/huawei-npu/pipeline.Dockerfile 中的稳定版安装方式。相关文档昇腾 NPU 飞桨安装教程英文版PaddleOCR 多硬件使用指南PaddleOCR-VL 华为昇腾 NPU 使用教程PaddleOCR 安装教程昇腾 NPU 产线镜像构建 Dockerfile【免费下载链接】PaddleOCR飞桨多语言OCR工具包实用超轻量OCR系统支持80种语言识别提供数据标注与合成工具支持服务器、移动端、嵌入式及IoT设备端的训练与部署 Awesome multilingual OCR toolkits based on PaddlePaddle (practical ultra lightweight OCR system, support 80 languages recognition, provide data annotation and synthesis tools, support training and deployment among server, mobile, embedded and IoT devices)项目地址: https://gitcode.com/paddlepaddle/PaddleOCR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考