PaddleOCR 昇腾 NPU 环境搭建与飞桨安装实战指南Ascend 910B / CANN 8.0【免费下载链接】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 官方《Ascend NPU PaddlePaddle Installation Tutorial》系统讲解在昇腾 910B 芯片Ascend 驱动 23.0.3、CANN 8.0.0上从零搭建飞桨运行环境并完成安装验证的完整流程包括 Docker 开发镜像的准备与容器启动、飞桨 CPU 版与 NPU 定制版 wheel 包的安装、依赖版本约束与 Arm 平台环境变量处理以及安装后的官方验证命令。读完本文你将掌握在 X86 与 Aarch64 两种架构下快速复现 NPU 推理与训练环境的标准化操作并能结合 PaddleOCR 的--use_npu等参数让 OCR 管线跑在昇腾 NPU 上。1. 支持范围与前置条件当前 PaddleOCR 支持昇腾 910B 芯片更多型号仍在支持中如有其他型号需求可向官方提交 issue 反馈对应的昇腾驱动版本为 23.0.3。考虑到不同机器环境差异较大官方推荐使用飞桨官方提供的昇腾开发镜像完成环境准备避免手工安装昇腾算子库带来的版本匹配问题。需要说明的是本文档介绍的是基于飞桨框架的安装与使用方式若你计划使用其他推理引擎如 ONNX Runtime、OM 离线模型等请参考对应引擎的官方安装与配置文档本文不展开介绍。2. Docker 环境准备2.1 拉取开发镜像官方镜像仅作为开发环境使用镜像内不包含预编译的飞桨安装包但已默认安装昇腾算子库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.0ubuntu20表示基于 Ubuntu 20.04npu-910b表示面向昇腾 910Bgcc84表示使用 GCC 8.4 编译工具链。2.2 启动容器参考如下命令启动容器其中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对各启动参数的理解便于按需调整参数作用--name paddle-npu-dev为容器命名便于后续docker exec进入-v $(pwd):/work将当前目录挂载到容器/work用于共享模型与数据--privileged授予特权模式访问昇腾设备所需--networkhost使用宿主机网络--shm-size128G增大共享内存满足分布式训练与大数据量处理需求-w/work容器内默认工作目录-v /usr/local/Ascend/driver:...挂载宿主机昇腾驱动-v /usr/local/bin/npu-smi:...挂载npu-smi工具便于容器内查看 NPU 状态-v /usr/local/dcmi:...挂载 DCMI 设备管理接口库-e ASCEND_RT_VISIBLE_DEVICES0,1,2,3,4,5,6,7指定可见 NPU 卡号按实际卡数调整$(uname -m)自动展开为宿主机架构x86_64或aarch64与所拉镜像架构对应3. 安装 PaddlePaddle 包3.1 安装 CPU 版与 NPU 定制版 wheel 包注意需要先安装飞桨 CPU 版本再安装 NPU 定制版。两条命令的版本号必须保持一致本文档以3.0.0.dev20250527为例# 注意需要先安装飞桨 cpu 版本 python -m pip install paddlepaddle3.0.0.dev20250527 -i https://www.paddlepaddle.org.cn/packages/nightly/cpu # 再安装 NPU 定制版 python -m pip install paddle-custom-npu3.0.0.dev20250527 -i https://www.paddlepaddle.org.cn/packages/nightly/npu这里使用了飞桨官方 nightly 源paddlepaddleCPU 版从nightly/cpu源安装paddle-custom-npu昇腾 NPU 定制版从nightly/npu源安装。paddle-custom-npu即飞桨为昇腾自定义设备后端提供的定制包安装后 PaddlePaddle 才能识别并使用 NPU 设备。3.2 安装指定版本的 numpy 与 opencvCANN-8.0.0 对部分版本的 numpy 和 opencv 不兼容官方建议安装如下指定版本python -m pip install numpy1.26.4 python -m pip install opencv-python3.4.18.653.3 ArmAarch64机器环境变量设置在 Arm 机器上需要设置如下环境变量X86 环境无需设置用于解决 libgomp 在 Arm 机器上运行时报错的问题# 解决libgomp在arm机器上报错 # libgomp cannot allocate memory in static TLS block export LD_PRELOAD/usr/lib/aarch64-linux-gnu/libgomp.so.1:$LD_PRELOAD该报错是 Arm 平台静态 TLSThread Local Storage空间不足导致的典型问题通过LD_PRELOAD预加载 libgomp 动态库即可规避。3.4 验证安装确认安装包安装完成后运行如下命令验证飞桨是否能正确识别并使用 NPUpython -c import paddle; paddle.utils.run_check()预期输出如下表示在 1 张和 8 张 NPU 上均工作正常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.run_check()会实际执行一次前向计算验证输出中的works well on 1 npu与works well on 8 npus说明飞桨已成功打通 NPU 计算链路。4. 源码视角PaddleOCR 如何启用 NPU环境就绪后PaddleOCR 提供了多个层面使用 NPU 的入口下面结合仓库源码说明其调用链。4.1 推理侧--use_npu参数与enable_custom_device(npu)在 tools/infer/utility.py 的init_args()中与 NPU 相关的命令行参数定义如下见 L41-L44parser.add_argument(--use_gpu, typestr2bool, defaultTrue) parser.add_argument(--use_xpu, typestr2bool, defaultFalse) parser.add_argument(--use_npu, typestr2bool, defaultFalse) parser.add_argument(--use_mlu, typestr2bool, defaultFalse)当--use_npu为 True 时底层会调用飞桨推理配置的config.enable_custom_device(npu)将后端切换到昇腾自定义设备见 utility.py L350-L351elif args.use_npu: config.enable_custom_device(npu)也就是说使用tools/infer下的推理脚本时只需在命令中追加--use_npuTrue同时将--use_gpu置为 False即可将检测、识别等模型跑在 NPU 上。4.2 训练侧设备检查与设备设置在训练流程中tools/program.py 的check_device()会校验当前飞桨是否编译了 NPU 支持使用较新版本飞桨时通过paddle.device.is_compiled_with_custom_device(npu)判断见 L148-L160。随后根据配置中的Global.use_npu选择设备NPU 设备号取自环境变量FLAGS_selected_npus见 L897 与 L960-L961use_npu config[Global].get(use_npu, False) ... elif use_npu: device npu:{0}.format(os.getenv(FLAGS_selected_npus, 0))因此训练时在 YAML 配置或-o覆盖参数中设置Global.use_npuTrue、Global.use_gpuFalse即可切换到 NPU 训练。4.3 NPU 训练环境变量参考在 多设备使用指南 中给出了昇腾 NPU 上微调/训练 PP-OCRv5 识别模型的环境变量与命令示例可作为环境配置的补充参考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其中CUSTOM_DEVICE_BLACK_LISTpad3d,pad3d_grad用于将暂不支持 NPU 的算子回退到 CPU 执行是 NPU 训练中常用的兼容性手段。5. 常见问题与注意事项版本必须对齐paddlepaddleCPU 版与paddle-custom-npuNPU 版必须使用相同版本号混装不同版本会导致设备初始化失败。numpy/opencv 版本约束若忽略 CANN-8.0.0 的兼容性要求使用新版 numpy/opencv 时可能出现算子库加载或图像预处理异常请严格按本文安装numpy1.26.4与opencv-python3.4.18.65。Arm 平台 libgomp 报错在 Aarch64 机器上如遇到libgomp cannot allocate memory in static TLS block务必设置LD_PRELOAD环境变量。可见 NPU 卡号通过ASCEND_RT_VISIBLE_DEVICES控制容器可见卡训练时与--devices/FLAGS_selected_npus配合使用。驱动版本本文档基于昇腾驱动 23.0.3 与 CANN-8.0.0 验证若宿主机驱动版本不同建议优先使用与驱动匹配的官方镜像。6. 进一步阅读本指南中文版docs/version3.x/other_devices_support/paddlepaddle_install_NPU.mdNPU/XPU 多设备使用指南快速推理、模型微调、ONNX/OM 推理docs/version3.x/other_devices_support/multi_devices_use_guide.en.mdPaddleOCR 整体安装指南docs/version3.x/installation.en.md推理参数入口源码tools/infer/utility.py训练设备初始化源码tools/program.py【免费下载链接】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），仅供参考
PaddleOCR 昇腾 NPU 环境搭建与飞桨安装实战指南（Ascend 910B / CANN 8.0）
PaddleOCR 昇腾 NPU 环境搭建与飞桨安装实战指南Ascend 910B / CANN 8.0【免费下载链接】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 官方《Ascend NPU PaddlePaddle Installation Tutorial》系统讲解在昇腾 910B 芯片Ascend 驱动 23.0.3、CANN 8.0.0上从零搭建飞桨运行环境并完成安装验证的完整流程包括 Docker 开发镜像的准备与容器启动、飞桨 CPU 版与 NPU 定制版 wheel 包的安装、依赖版本约束与 Arm 平台环境变量处理以及安装后的官方验证命令。读完本文你将掌握在 X86 与 Aarch64 两种架构下快速复现 NPU 推理与训练环境的标准化操作并能结合 PaddleOCR 的--use_npu等参数让 OCR 管线跑在昇腾 NPU 上。1. 支持范围与前置条件当前 PaddleOCR 支持昇腾 910B 芯片更多型号仍在支持中如有其他型号需求可向官方提交 issue 反馈对应的昇腾驱动版本为 23.0.3。考虑到不同机器环境差异较大官方推荐使用飞桨官方提供的昇腾开发镜像完成环境准备避免手工安装昇腾算子库带来的版本匹配问题。需要说明的是本文档介绍的是基于飞桨框架的安装与使用方式若你计划使用其他推理引擎如 ONNX Runtime、OM 离线模型等请参考对应引擎的官方安装与配置文档本文不展开介绍。2. Docker 环境准备2.1 拉取开发镜像官方镜像仅作为开发环境使用镜像内不包含预编译的飞桨安装包但已默认安装昇腾算子库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.0ubuntu20表示基于 Ubuntu 20.04npu-910b表示面向昇腾 910Bgcc84表示使用 GCC 8.4 编译工具链。2.2 启动容器参考如下命令启动容器其中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对各启动参数的理解便于按需调整参数作用--name paddle-npu-dev为容器命名便于后续docker exec进入-v $(pwd):/work将当前目录挂载到容器/work用于共享模型与数据--privileged授予特权模式访问昇腾设备所需--networkhost使用宿主机网络--shm-size128G增大共享内存满足分布式训练与大数据量处理需求-w/work容器内默认工作目录-v /usr/local/Ascend/driver:...挂载宿主机昇腾驱动-v /usr/local/bin/npu-smi:...挂载npu-smi工具便于容器内查看 NPU 状态-v /usr/local/dcmi:...挂载 DCMI 设备管理接口库-e ASCEND_RT_VISIBLE_DEVICES0,1,2,3,4,5,6,7指定可见 NPU 卡号按实际卡数调整$(uname -m)自动展开为宿主机架构x86_64或aarch64与所拉镜像架构对应3. 安装 PaddlePaddle 包3.1 安装 CPU 版与 NPU 定制版 wheel 包注意需要先安装飞桨 CPU 版本再安装 NPU 定制版。两条命令的版本号必须保持一致本文档以3.0.0.dev20250527为例# 注意需要先安装飞桨 cpu 版本 python -m pip install paddlepaddle3.0.0.dev20250527 -i https://www.paddlepaddle.org.cn/packages/nightly/cpu # 再安装 NPU 定制版 python -m pip install paddle-custom-npu3.0.0.dev20250527 -i https://www.paddlepaddle.org.cn/packages/nightly/npu这里使用了飞桨官方 nightly 源paddlepaddleCPU 版从nightly/cpu源安装paddle-custom-npu昇腾 NPU 定制版从nightly/npu源安装。paddle-custom-npu即飞桨为昇腾自定义设备后端提供的定制包安装后 PaddlePaddle 才能识别并使用 NPU 设备。3.2 安装指定版本的 numpy 与 opencvCANN-8.0.0 对部分版本的 numpy 和 opencv 不兼容官方建议安装如下指定版本python -m pip install numpy1.26.4 python -m pip install opencv-python3.4.18.653.3 ArmAarch64机器环境变量设置在 Arm 机器上需要设置如下环境变量X86 环境无需设置用于解决 libgomp 在 Arm 机器上运行时报错的问题# 解决libgomp在arm机器上报错 # libgomp cannot allocate memory in static TLS block export LD_PRELOAD/usr/lib/aarch64-linux-gnu/libgomp.so.1:$LD_PRELOAD该报错是 Arm 平台静态 TLSThread Local Storage空间不足导致的典型问题通过LD_PRELOAD预加载 libgomp 动态库即可规避。3.4 验证安装确认安装包安装完成后运行如下命令验证飞桨是否能正确识别并使用 NPUpython -c import paddle; paddle.utils.run_check()预期输出如下表示在 1 张和 8 张 NPU 上均工作正常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.run_check()会实际执行一次前向计算验证输出中的works well on 1 npu与works well on 8 npus说明飞桨已成功打通 NPU 计算链路。4. 源码视角PaddleOCR 如何启用 NPU环境就绪后PaddleOCR 提供了多个层面使用 NPU 的入口下面结合仓库源码说明其调用链。4.1 推理侧--use_npu参数与enable_custom_device(npu)在 tools/infer/utility.py 的init_args()中与 NPU 相关的命令行参数定义如下见 L41-L44parser.add_argument(--use_gpu, typestr2bool, defaultTrue) parser.add_argument(--use_xpu, typestr2bool, defaultFalse) parser.add_argument(--use_npu, typestr2bool, defaultFalse) parser.add_argument(--use_mlu, typestr2bool, defaultFalse)当--use_npu为 True 时底层会调用飞桨推理配置的config.enable_custom_device(npu)将后端切换到昇腾自定义设备见 utility.py L350-L351elif args.use_npu: config.enable_custom_device(npu)也就是说使用tools/infer下的推理脚本时只需在命令中追加--use_npuTrue同时将--use_gpu置为 False即可将检测、识别等模型跑在 NPU 上。4.2 训练侧设备检查与设备设置在训练流程中tools/program.py 的check_device()会校验当前飞桨是否编译了 NPU 支持使用较新版本飞桨时通过paddle.device.is_compiled_with_custom_device(npu)判断见 L148-L160。随后根据配置中的Global.use_npu选择设备NPU 设备号取自环境变量FLAGS_selected_npus见 L897 与 L960-L961use_npu config[Global].get(use_npu, False) ... elif use_npu: device npu:{0}.format(os.getenv(FLAGS_selected_npus, 0))因此训练时在 YAML 配置或-o覆盖参数中设置Global.use_npuTrue、Global.use_gpuFalse即可切换到 NPU 训练。4.3 NPU 训练环境变量参考在 多设备使用指南 中给出了昇腾 NPU 上微调/训练 PP-OCRv5 识别模型的环境变量与命令示例可作为环境配置的补充参考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其中CUSTOM_DEVICE_BLACK_LISTpad3d,pad3d_grad用于将暂不支持 NPU 的算子回退到 CPU 执行是 NPU 训练中常用的兼容性手段。5. 常见问题与注意事项版本必须对齐paddlepaddleCPU 版与paddle-custom-npuNPU 版必须使用相同版本号混装不同版本会导致设备初始化失败。numpy/opencv 版本约束若忽略 CANN-8.0.0 的兼容性要求使用新版 numpy/opencv 时可能出现算子库加载或图像预处理异常请严格按本文安装numpy1.26.4与opencv-python3.4.18.65。Arm 平台 libgomp 报错在 Aarch64 机器上如遇到libgomp cannot allocate memory in static TLS block务必设置LD_PRELOAD环境变量。可见 NPU 卡号通过ASCEND_RT_VISIBLE_DEVICES控制容器可见卡训练时与--devices/FLAGS_selected_npus配合使用。驱动版本本文档基于昇腾驱动 23.0.3 与 CANN-8.0.0 验证若宿主机驱动版本不同建议优先使用与驱动匹配的官方镜像。6. 进一步阅读本指南中文版docs/version3.x/other_devices_support/paddlepaddle_install_NPU.mdNPU/XPU 多设备使用指南快速推理、模型微调、ONNX/OM 推理docs/version3.x/other_devices_support/multi_devices_use_guide.en.mdPaddleOCR 整体安装指南docs/version3.x/installation.en.md推理参数入口源码tools/infer/utility.py训练设备初始化源码tools/program.py【免费下载链接】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），仅供参考
