尧图网站建设 
PaddleOCR 多硬件平台使用指南华为昇腾 NPU 与昆仑 XPU 的环境搭建、快速推理与模型微调实战【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100 languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR本文是 PaddleOCR 在华为昇腾 Ascend NPU 与昆仑 Kunlun XPU 两类国产硬件平台上的完整使用指南涵盖 PaddlePaddle 定制版安装、OCR 与 PP-StructureV3 管线的快速推理、多卡模型微调以及 ONNX/OM 模型高性能推理方案。读完本文你将掌握如何在不改动业务代码的前提下仅通过--device npu:0/--device xpu:0与少量配置参数把 PaddleOCR 的三大核心能力PP-OCRv5 文本识别、PP-StructureV3 文档解析、PP-ChatOCRv4无缝迁移到昇腾与昆仑硬件上运行。一、平台支持概览与使用前提PaddleOCR 3.x 在昇腾 NPU 与昆仑 XPU 上的训练和推理方式与 GPU 完全一致唯一需要变化的是根据具体硬件平台修改设备与相关配置参数。在两种硬件平台上快速推理Pipeline 推理与模型微调Fine-tuning均支持 PaddleOCR 的三大核心功能PP-OCRv5 文本识别模型通用 OCR 管线det direction classification rec的默认模型版本PP-StructureV3 文档解析方案面向版面分析、表格识别、公式识别、印章识别等复杂文档结构解析PP-ChatOCRv4 文档问答方案结合 LLM 的文档内容理解。官方文档同时强调一个前提本文主要介绍基于 PaddlePaddle 推理引擎的安装与使用。如果计划使用其他推理引擎如 TensorRT、ONNX Runtime 等需要按照对应引擎的官方文档自行完成环境搭建与安装PaddleOCR 侧的代码调用方式不变。硬件支持矩阵Ascend 侧当前支持910B 芯片更多型号在持续适配中如有需求可通过 issue 反馈Kunlun 侧支持R200/R300 等芯片。以上信息以 multi_devices_use_guide.en.md 及对应安装教程NPU、XPU为准。二、环境搭建分硬件平台安装 PaddlePaddle 与 PaddleOCR2.1 昇腾 NPU 环境准备Ascend 910B考虑到各机器环境差异较大官方推荐直接使用PaddlePaddle 提供的昇腾开发镜像完成环境准备。该镜像仅用于开发环境默认内置CANN-8.0.0 昇腾算子库但不包含预编译的 PaddlePaddle 安装包。第一步拉取开发镜像# 适用于 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第二步启动容器ASCEND_RT_VISIBLE_DEVICES环境变量用于指定容器内可见的 NPU 卡号需挂载宿主机上的昇腾驱动目录/usr/local/Ascend/driver、npu-smi、dcmidocker 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$(uname -m)会自动解析为x86_64或aarch64与第一步拉取的镜像架构对应。第三步安装 PaddlePaddle 定制包注意安装顺序先安装 CPU 版本 PaddlePaddle再安装 NPU 定制包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/npu第四步固定 numpy / opencv 版本CANN-8.0.0 与部分版本的 numpy、opencv 存在兼容性问题官方建议安装指定版本python -m pip install numpy1.26.4 python -m pip install opencv-python3.4.18.65第五步仅 ARM 机器需要设置 LD_PRELOAD解决 ARM 机器上libgomp cannot allocate memory in static TLS block报错export LD_PRELOAD/usr/lib/aarch64-linux-gnu/libgomp.so.1:$LD_PRELOADx86 环境无需执行此步骤。第六步验证安装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.与works well on 8 npus.分别代表单卡与多卡场景验证通过。2.2 昆仑 XPU 环境准备Kunlun R200/R300XPU 侧同样推荐使用PaddlePaddle 官方发布的昆仑开发镜像镜像预装了昆仑基础运行时环境库XRE。第一步拉取镜像并启动容器docker pull registry.baidubce.com/device/paddle-xpu:ubuntu20-x86_64-gcc84-py310 # X86 架构 docker pull registry.baidubce.com/device/paddle-xpu:kylinv10-aarch64-gcc82-py310 # ARM 架构docker run -it --namexxx -m 81920M --memory-swap81920M \ --shm-size128G --privileged --nethost \ -v $(pwd):/workspace -w /workspace \ registry.baidubce.com/device/paddle-xpu:$(uname -m)-py310 bash第二步安装 PaddlePaddle XPU 定制包当前官方提供Python 3.10的 wheel 安装包如需其他 Python 版本可参考 PaddlePaddle 官方安装文档自行编译安装pip install https://paddle-whl.bj.bcebos.com/paddlex/xpu/paddlepaddle_xpu-2.6.1-cp310-cp310-linux_x86_64.whl # X86 架构 pip install https://paddle-whl.bj.bcebos.com/paddlex/xpu/paddlepaddle_xpu-2.6.1-cp310-cp310-linux_aarch64.whl # ARM 架构第三步验证安装python -c import paddle; paddle.utils.run_check()预期输出PaddlePaddle is installed successfully! Lets start deep learning with PaddlePaddle now.2.3 安装 PaddleOCR完成对应平台的 PaddlePaddle 安装后再按照 PaddleOCR 安装指南 安装 PaddleOCR 本体包括paddleocrPython 包及其依赖。安装完成后即可进入下一节的快速推理环节。三、快速推理一条命令跑通 NPU/XPU 管线3.1 命令行一键推理CLI安装完成后可以通过单条命令快速体验 OCR 管线推理默认使用 PP-OCRv5 模型设备通过--device指定昇腾为npu:0昆仑为xpu:0冒号后为卡号# OCR 管线推理默认模型为 PP-OCRv5 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-i/--input支持本地图片路径与 URL 两种输入形式。从源码实现看paddleocr/_utils/cli.py 中的add_simple_inference_args--device属于每个子命令都会注入的公共参数add_common_cli_opts见 paddleocr/_common_args.py支持cpu、gpu、npu、xpu等设备类型也支持gpu:0,1形式的多设备并行推理。最终由 perform_simple_inference 将参数组装后实例化对应管线类并逐条执行predict_iter期间自动打印每个样本的处理耗时并通过--save_path指定输出目录保存结果。3.2 Python API 推理集成到业务项目如果要在自己的项目中集成生产管线只需几行代码。下面分别是 OCR 与 PP-StructureV3 两个管线的最小示例设备参数device与 CLI 的--device完全等价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)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) res.save_to_markdown(save_pathoutput)从源码角度看PaddleOCRpaddleocr/_pipelines/ocr.py与PPStructureV3paddleocr/_pipelines/pp_structurev3.py都继承自PaddleXPipelineWrapperpaddleocr/_pipelines/base.py构造时通过parse_common_args解析device等公共参数再调用create_pipeline创建底层 PaddleX 管线因此device参数可以透明地传递到每个子模型文本检测、文本识别、表格结构识别等的推理引擎上无需逐个模型单独配置。这也正是训练与推理方法与 GPU 相同、仅需修改设备参数的底层原因。需要注意OCR 管线的predict输出与PP-StructureV3 管线的输出格式不同——OCR 结果可保存为图片save_to_img与 JSONsave_to_json而 PP-StructureV3 的解析结果通常保存为 JSONsave_to_json与 Markdownsave_to_markdown后者可直接作为 LLM/RAG 的结构化输入。更多细节可参考 OCR 管线使用指南 与 PP-StructureV3 管线使用指南。四、模型微调NPU/XPU 上的多卡训练如果预训练模型在自有业务数据上表现不理想可以在昇腾与昆仑平台上直接进行模型微调Fine-tuning训练入口与 GPU 完全一致——仍使用tools/train.py只是通过-o参数覆盖Global.use_gpu/Global.use_npu/Global.use_xpu来切换设备并通过环境变量为对应硬件平台做运行期调优。4.1 昇腾 NPU 上训练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各环境变量作用速查环境变量作用FLAGS_npu_storage_format0关闭 NPU 存储格式自动转换保持与模型定义一致FLAGS_npu_jit_compile0关闭 NPU 算子 JIT 编译FLAGS_use_stride_kernel0关闭 stride kernel 优化路径FLAGS_allocator_strategyauto_growth使用自动增长的显存分配策略按需申请FLAGS_npu_split_aclnnTrue/FLAGS_npu_scale_aclnnTrue开启 aclnn 算子拆分与缩放优化CUSTOM_DEVICE_BLACK_LISTpad3d,pad3d_grad将pad3d及其梯度算子列入黑名单避免在 NPU 上执行异常4.2 昆仑 XPU 上训练export FLAGS_use_stride_kernel0 export BKCL_FORCE_SYNC1 export BKCL_TIMEOUT1800 export XPU_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_xpuTrue其中BKCL_FORCE_SYNC1强制 XPU 集合通信BKCL同步执行以保证正确性BKCL_TIMEOUT1800设置通信超时时间秒XPU_BLACK_LIST与 NPU 侧的CUSTOM_DEVICE_BLACK_LIST作用类似。示例配置 configs/rec/PP-OCRv5/PP-OCRv5_mobile_rec.yml 是 PP-OCRv5 移动端识别模型的训练配置识别算法为SVTR_LCNetPPLCNetV3 骨干 MultiHead 多头头同时包含 CTC 与 NRTR 两个分支及对应MultiLoss训练数据路径、批次大小、学习率、评估间隔等均可按需调整训练时通过-o覆盖的设备开关会优先于 YAML 中的Global.use_gpu: true默认值生效。五、其他推理方式ONNX 与 OM 高性能推理5.1 问题背景在昇腾 NPU 上对于少量推理样本直接使用前述 Pipeline 推理方式可能出现结果异常主要出现在 PP-StructureV3 管线。为解决这一问题官方支持改用ONNX 模型进行推理以保证结果正确。5.2 Paddle 模型转 ONNX先安装转换工具再执行转换paddlex --install paddle2onnx paddlex --paddle2onnx --paddle_model_dir /paddle_model_dir --onnx_model_dir /onnx_model_dir --opset_version 7--paddle_model_dir指向 Paddle 模型目录--onnx_model_dir指定 ONNX 模型输出目录--opset_version指定 ONNX opset 版本示例为 7。5.3 ONNX 转昇腾 OM 模型部分模型还支持昇腾离线 OM 推理可有效优化推理性能与内存占用。使用 OM ONNX 格式的模型进行 Pipeline 推理能够同时兼顾精度与速度。用 ATC 转换工具将 ONNX 模型转为 OM 模型atc --modelinference.onnx --framework5 --outputinference --soc_versionyour_device_type --input_shape your_input_shape参数说明--framework5表示输入模型为 ONNX 格式--soc_version填写实际芯片型号如昇腾 910B 对应型号--input_shape按模型实际输入形状填写。5.4 配置推理后端并使用高性能推理 APIPaddleOCR 已将 ONNX 与 OM 模型深度集成到 PaddleX 中用于高性能推理只需修改Pipeline 配置文件将模型推理后端backend设置为ONNX或OM即可通过 PaddleX 的高性能推理 API 完成推理而无需改动业务调用代码。具体配置修改方法、推理代码示例及更多使用说明可查阅昇腾 NPU 高性能推理专题教程对应 PaddleX 文档中的 high performance NPU tutorial 章节。六、常见问题FAQQ1PP-StructureV3 管线推理结果不正确怎么办该管线中有部分模型在极少数样本上存在精度误差。可以尝试调整配置文件中的模型例如更换检测/识别子模型改用ONNX OM 模型进行推理参见本文第五节以保证精度与速度。七、小结本文从环境搭建、快速推理、模型微调、ONNX/OM 高性能推理四个层面完整梳理了 PaddleOCR 在华为昇腾 NPU 与昆仑 XPU 平台上的使用路径。核心要点可概括为三点其一代码零改动——无论是 CLI 的--device npu:0/--device xpu:0还是 Python API 的device参数都能将设备指定透传到整个管线其二训练链路复用——tools/train.py配合Global.use_npuTrue/Global.use_xpuTrue与对应的硬件调优环境变量即可完成多卡微调其三精度兜底方案——当少量样本下 NPU Pipeline 推理出现异常时可切换到 ONNX/OM 模型推理。安装细节请分别参考 Ascend NPU 安装教程 与 Kunlun XPU 安装教程。【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100 languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 PaddleOCR 多硬件平台使用指南：华为昇腾 NPU 与昆仑 XPU 的环境搭建、快速推理与模型微调实战
PaddleOCR 多硬件平台使用指南华为昇腾 NPU 与昆仑 XPU 的环境搭建、快速推理与模型微调实战【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100 languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR本文是 PaddleOCR 在华为昇腾 Ascend NPU 与昆仑 Kunlun XPU 两类国产硬件平台上的完整使用指南涵盖 PaddlePaddle 定制版安装、OCR 与 PP-StructureV3 管线的快速推理、多卡模型微调以及 ONNX/OM 模型高性能推理方案。读完本文你将掌握如何在不改动业务代码的前提下仅通过--device npu:0/--device xpu:0与少量配置参数把 PaddleOCR 的三大核心能力PP-OCRv5 文本识别、PP-StructureV3 文档解析、PP-ChatOCRv4无缝迁移到昇腾与昆仑硬件上运行。一、平台支持概览与使用前提PaddleOCR 3.x 在昇腾 NPU 与昆仑 XPU 上的训练和推理方式与 GPU 完全一致唯一需要变化的是根据具体硬件平台修改设备与相关配置参数。在两种硬件平台上快速推理Pipeline 推理与模型微调Fine-tuning均支持 PaddleOCR 的三大核心功能PP-OCRv5 文本识别模型通用 OCR 管线det direction classification rec的默认模型版本PP-StructureV3 文档解析方案面向版面分析、表格识别、公式识别、印章识别等复杂文档结构解析PP-ChatOCRv4 文档问答方案结合 LLM 的文档内容理解。官方文档同时强调一个前提本文主要介绍基于 PaddlePaddle 推理引擎的安装与使用。如果计划使用其他推理引擎如 TensorRT、ONNX Runtime 等需要按照对应引擎的官方文档自行完成环境搭建与安装PaddleOCR 侧的代码调用方式不变。硬件支持矩阵Ascend 侧当前支持910B 芯片更多型号在持续适配中如有需求可通过 issue 反馈Kunlun 侧支持R200/R300 等芯片。以上信息以 multi_devices_use_guide.en.md 及对应安装教程NPU、XPU为准。二、环境搭建分硬件平台安装 PaddlePaddle 与 PaddleOCR2.1 昇腾 NPU 环境准备Ascend 910B考虑到各机器环境差异较大官方推荐直接使用PaddlePaddle 提供的昇腾开发镜像完成环境准备。该镜像仅用于开发环境默认内置CANN-8.0.0 昇腾算子库但不包含预编译的 PaddlePaddle 安装包。第一步拉取开发镜像# 适用于 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第二步启动容器ASCEND_RT_VISIBLE_DEVICES环境变量用于指定容器内可见的 NPU 卡号需挂载宿主机上的昇腾驱动目录/usr/local/Ascend/driver、npu-smi、dcmidocker 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$(uname -m)会自动解析为x86_64或aarch64与第一步拉取的镜像架构对应。第三步安装 PaddlePaddle 定制包注意安装顺序先安装 CPU 版本 PaddlePaddle再安装 NPU 定制包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/npu第四步固定 numpy / opencv 版本CANN-8.0.0 与部分版本的 numpy、opencv 存在兼容性问题官方建议安装指定版本python -m pip install numpy1.26.4 python -m pip install opencv-python3.4.18.65第五步仅 ARM 机器需要设置 LD_PRELOAD解决 ARM 机器上libgomp cannot allocate memory in static TLS block报错export LD_PRELOAD/usr/lib/aarch64-linux-gnu/libgomp.so.1:$LD_PRELOADx86 环境无需执行此步骤。第六步验证安装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.与works well on 8 npus.分别代表单卡与多卡场景验证通过。2.2 昆仑 XPU 环境准备Kunlun R200/R300XPU 侧同样推荐使用PaddlePaddle 官方发布的昆仑开发镜像镜像预装了昆仑基础运行时环境库XRE。第一步拉取镜像并启动容器docker pull registry.baidubce.com/device/paddle-xpu:ubuntu20-x86_64-gcc84-py310 # X86 架构 docker pull registry.baidubce.com/device/paddle-xpu:kylinv10-aarch64-gcc82-py310 # ARM 架构docker run -it --namexxx -m 81920M --memory-swap81920M \ --shm-size128G --privileged --nethost \ -v $(pwd):/workspace -w /workspace \ registry.baidubce.com/device/paddle-xpu:$(uname -m)-py310 bash第二步安装 PaddlePaddle XPU 定制包当前官方提供Python 3.10的 wheel 安装包如需其他 Python 版本可参考 PaddlePaddle 官方安装文档自行编译安装pip install https://paddle-whl.bj.bcebos.com/paddlex/xpu/paddlepaddle_xpu-2.6.1-cp310-cp310-linux_x86_64.whl # X86 架构 pip install https://paddle-whl.bj.bcebos.com/paddlex/xpu/paddlepaddle_xpu-2.6.1-cp310-cp310-linux_aarch64.whl # ARM 架构第三步验证安装python -c import paddle; paddle.utils.run_check()预期输出PaddlePaddle is installed successfully! Lets start deep learning with PaddlePaddle now.2.3 安装 PaddleOCR完成对应平台的 PaddlePaddle 安装后再按照 PaddleOCR 安装指南 安装 PaddleOCR 本体包括paddleocrPython 包及其依赖。安装完成后即可进入下一节的快速推理环节。三、快速推理一条命令跑通 NPU/XPU 管线3.1 命令行一键推理CLI安装完成后可以通过单条命令快速体验 OCR 管线推理默认使用 PP-OCRv5 模型设备通过--device指定昇腾为npu:0昆仑为xpu:0冒号后为卡号# OCR 管线推理默认模型为 PP-OCRv5 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-i/--input支持本地图片路径与 URL 两种输入形式。从源码实现看paddleocr/_utils/cli.py 中的add_simple_inference_args--device属于每个子命令都会注入的公共参数add_common_cli_opts见 paddleocr/_common_args.py支持cpu、gpu、npu、xpu等设备类型也支持gpu:0,1形式的多设备并行推理。最终由 perform_simple_inference 将参数组装后实例化对应管线类并逐条执行predict_iter期间自动打印每个样本的处理耗时并通过--save_path指定输出目录保存结果。3.2 Python API 推理集成到业务项目如果要在自己的项目中集成生产管线只需几行代码。下面分别是 OCR 与 PP-StructureV3 两个管线的最小示例设备参数device与 CLI 的--device完全等价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)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) res.save_to_markdown(save_pathoutput)从源码角度看PaddleOCRpaddleocr/_pipelines/ocr.py与PPStructureV3paddleocr/_pipelines/pp_structurev3.py都继承自PaddleXPipelineWrapperpaddleocr/_pipelines/base.py构造时通过parse_common_args解析device等公共参数再调用create_pipeline创建底层 PaddleX 管线因此device参数可以透明地传递到每个子模型文本检测、文本识别、表格结构识别等的推理引擎上无需逐个模型单独配置。这也正是训练与推理方法与 GPU 相同、仅需修改设备参数的底层原因。需要注意OCR 管线的predict输出与PP-StructureV3 管线的输出格式不同——OCR 结果可保存为图片save_to_img与 JSONsave_to_json而 PP-StructureV3 的解析结果通常保存为 JSONsave_to_json与 Markdownsave_to_markdown后者可直接作为 LLM/RAG 的结构化输入。更多细节可参考 OCR 管线使用指南 与 PP-StructureV3 管线使用指南。四、模型微调NPU/XPU 上的多卡训练如果预训练模型在自有业务数据上表现不理想可以在昇腾与昆仑平台上直接进行模型微调Fine-tuning训练入口与 GPU 完全一致——仍使用tools/train.py只是通过-o参数覆盖Global.use_gpu/Global.use_npu/Global.use_xpu来切换设备并通过环境变量为对应硬件平台做运行期调优。4.1 昇腾 NPU 上训练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各环境变量作用速查环境变量作用FLAGS_npu_storage_format0关闭 NPU 存储格式自动转换保持与模型定义一致FLAGS_npu_jit_compile0关闭 NPU 算子 JIT 编译FLAGS_use_stride_kernel0关闭 stride kernel 优化路径FLAGS_allocator_strategyauto_growth使用自动增长的显存分配策略按需申请FLAGS_npu_split_aclnnTrue/FLAGS_npu_scale_aclnnTrue开启 aclnn 算子拆分与缩放优化CUSTOM_DEVICE_BLACK_LISTpad3d,pad3d_grad将pad3d及其梯度算子列入黑名单避免在 NPU 上执行异常4.2 昆仑 XPU 上训练export FLAGS_use_stride_kernel0 export BKCL_FORCE_SYNC1 export BKCL_TIMEOUT1800 export XPU_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_xpuTrue其中BKCL_FORCE_SYNC1强制 XPU 集合通信BKCL同步执行以保证正确性BKCL_TIMEOUT1800设置通信超时时间秒XPU_BLACK_LIST与 NPU 侧的CUSTOM_DEVICE_BLACK_LIST作用类似。示例配置 configs/rec/PP-OCRv5/PP-OCRv5_mobile_rec.yml 是 PP-OCRv5 移动端识别模型的训练配置识别算法为SVTR_LCNetPPLCNetV3 骨干 MultiHead 多头头同时包含 CTC 与 NRTR 两个分支及对应MultiLoss训练数据路径、批次大小、学习率、评估间隔等均可按需调整训练时通过-o覆盖的设备开关会优先于 YAML 中的Global.use_gpu: true默认值生效。五、其他推理方式ONNX 与 OM 高性能推理5.1 问题背景在昇腾 NPU 上对于少量推理样本直接使用前述 Pipeline 推理方式可能出现结果异常主要出现在 PP-StructureV3 管线。为解决这一问题官方支持改用ONNX 模型进行推理以保证结果正确。5.2 Paddle 模型转 ONNX先安装转换工具再执行转换paddlex --install paddle2onnx paddlex --paddle2onnx --paddle_model_dir /paddle_model_dir --onnx_model_dir /onnx_model_dir --opset_version 7--paddle_model_dir指向 Paddle 模型目录--onnx_model_dir指定 ONNX 模型输出目录--opset_version指定 ONNX opset 版本示例为 7。5.3 ONNX 转昇腾 OM 模型部分模型还支持昇腾离线 OM 推理可有效优化推理性能与内存占用。使用 OM ONNX 格式的模型进行 Pipeline 推理能够同时兼顾精度与速度。用 ATC 转换工具将 ONNX 模型转为 OM 模型atc --modelinference.onnx --framework5 --outputinference --soc_versionyour_device_type --input_shape your_input_shape参数说明--framework5表示输入模型为 ONNX 格式--soc_version填写实际芯片型号如昇腾 910B 对应型号--input_shape按模型实际输入形状填写。5.4 配置推理后端并使用高性能推理 APIPaddleOCR 已将 ONNX 与 OM 模型深度集成到 PaddleX 中用于高性能推理只需修改Pipeline 配置文件将模型推理后端backend设置为ONNX或OM即可通过 PaddleX 的高性能推理 API 完成推理而无需改动业务调用代码。具体配置修改方法、推理代码示例及更多使用说明可查阅昇腾 NPU 高性能推理专题教程对应 PaddleX 文档中的 high performance NPU tutorial 章节。六、常见问题FAQQ1PP-StructureV3 管线推理结果不正确怎么办该管线中有部分模型在极少数样本上存在精度误差。可以尝试调整配置文件中的模型例如更换检测/识别子模型改用ONNX OM 模型进行推理参见本文第五节以保证精度与速度。七、小结本文从环境搭建、快速推理、模型微调、ONNX/OM 高性能推理四个层面完整梳理了 PaddleOCR 在华为昇腾 NPU 与昆仑 XPU 平台上的使用路径。核心要点可概括为三点其一代码零改动——无论是 CLI 的--device npu:0/--device xpu:0还是 Python API 的device参数都能将设备指定透传到整个管线其二训练链路复用——tools/train.py配合Global.use_npuTrue/Global.use_xpuTrue与对应的硬件调优环境变量即可完成多卡微调其三精度兜底方案——当少量样本下 NPU Pipeline 推理出现异常时可切换到 ONNX/OM 模型推理。安装细节请分别参考 Ascend NPU 安装教程 与 Kunlun XPU 安装教程。【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100 languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考