PaddleX 昇腾 NPU 高性能推理实战指南：Docker 环境搭建、OM/ORT 双后端部署与 OCR 产线加速

人工智能大模型低代码计算机视觉深度学习NLP模型推理服务RAG【免费下载链接】PaddleXAll-in-One Development Tool based on PaddlePaddle项目地址https://gitcode.com/paddlepaddle/PaddleX点击查看免费下载PaddleX 高性能推理插件HPIHigh-Performance Inference Plugin在昇腾 NPU 上支持 910B、310P、310B 三类芯片提供 OM昇腾离线模型NPU 推理性能更优与 ORTONNX RuntimeCPU 推理模型覆盖更全两种后端可同时作用于单模型推理与整条产线推理。本教程将带你从 Docker 环境准备、PaddleX 与ultra-infer插件安装开始逐步完成单模型文本识别、图像分类与 OCR 产线在昇腾 NPU 上的高性能推理部署并掌握后端混用、静态 shape 配置与常见问题排查方法。本文以 docs/practical_tutorials/high_performance_npu_tutorial.md 为主体脉络结合仓库内 paddlex/paddlex_cli.py、paddlex/inference/utils/hpi.py 等源码与 docs/support_list/model_list_npu.md 模型列表展开所有命令与配置均可直接落地复现。1. 支持范围与总体思路当前 PaddleX 高性能推理在昇腾上支持910B、310P、310B三类芯片如有其他型号需求可向官方提交 issue。考虑到不同机器的驱动、CANN、架构差异较大官方推荐使用飞桨提供的昇腾开发镜像完成环境准备镜像内默认安装了昇腾算子库CANN-8.0.T113但不包含预编译的飞桨安装包。从源码结构看高性能推理插件对应的底层推理库是ultra-infer维护在 libs/ultra-infer 目录下PaddleX 通过paddlex --install hpi-device_type安装对应设备版本的 whl 包见 paddlex/paddlex_cli.py其中 NPU 设备安装的包名为ultra-infer-npu-python。整体部署链路如下拉取并启动昇腾开发镜像挂载驱动并指定可见 NPU 卡安装 PaddleX 本体pip install -e .[base]安装 NPU 版高性能推理插件官方 whl 或手动编译准备 OM / ONNX 模型及配套inference.yml配置文件通过 Python API 或产线配置文件完成单模型 / 产线推理。2. Docker 环境准备2.1 拉取昇腾开发镜像镜像按芯片型号 × CPU 架构提供共 6 个 tag请根据实际硬件选择# 910B x86 架构 docker pull ccr-2vdh3abv-pub.cnc.bj.baidubce.com/device/paddle-npu:cann80T113-ubuntu20-npu-910b-base-x86_64-gcc84 # 910B aarch64 架构 docker pull ccr-2vdh3abv-pub.cnc.bj.baidubce.com/device/paddle-npu:cann80T113-ubuntu20-npu-910b-base-aarch64-gcc84 # 310P aarch64 架构 docker pull ccr-2vdh3abv-pub.cnc.bj.baidubce.com/device/paddle-npu:cann80T113-ubuntu20-npu-310p-base-aarch64-gcc84 # 310P x86 架构 docker pull ccr-2vdh3abv-pub.cnc.bj.baidubce.com/device/paddle-npu:cann80T113-ubuntu20-npu-310p-base-x86_64-gcc84 # 310B aarch64 架构 docker pull ccr-2vdh3abv-pub.cnc.bj.baidubce.com/device/paddle-npu:cann80T113-ubuntu20-npu-310b-base-aarch64-gcc84 # 310B x86 架构 docker pull ccr-2vdh3abv-pub.cnc.bj.baidubce.com/device/paddle-npu:cann80T113-ubuntu20-npu-310b-base-x86_64-gcc84该镜像仅为开发环境镜像中不含预编译的飞桨安装包需要后续手动安装 PaddleX。2.2 启动容器以910B x86 架构为例启动命令如下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:cann80T113-ubuntu20-npu-910b-base-x86_64-gcc84 /bin/bash关键参数说明参数作用--privileged授予容器访问昇腾设备所需的特权--networkhost使用宿主机网络便于推理服务对外暴露端口--shm-size128G增大共享内存避免推理过程中进程间共享内存不足-v /usr/local/Ascend/driver等挂载将宿主机昇腾驱动、npu-smi工具与 DCMI 管理接口透传进容器ASCEND_RT_VISIBLE_DEVICES指定容器内可见的 NPU 卡号如0,1,2,3,4,5,6,7表示 8 张卡全部可见3. 安装 PaddleX 与高性能推理插件3.1 安装 PaddleX进入容器后将仓库克隆到本地并安装git clone https://gitcode.com/paddlepaddle/PaddleX.git cd PaddleX pip install -e .[base]-e为可编辑安装便于跟随仓库源码调试[base]为 PaddleX 基础依赖子集安装高性能推理插件前建议先确保 PaddleX 可正常执行普通推理。3.2 安装高性能推理插件NPU 版高性能推理插件的 whl 包已上传至 PaddleX 官方源推荐直接下载安装也可以手动编译安装。方式一官方 whl 包推荐# 使用PaddleX命令安装高性能推理插件 paddlex --install hpi-npu从 paddlex/paddlex_cli.py 的_install_hpi_deps实现可以看到hpi-npu对应安装ultra-infer-npu-python包并通过hpip_links.html即仓库根目录的 paddlex/hpip_links.html作为--find-links源安装命令格式为paddlex --install hpi-device_type支持的设备类型为cpu、gpu、npu且同一环境只应安装一个版本的插件。方式二手动编译安装cd PaddleX/libs/ultra-infer/python unset http_proxy https_proxy # 使能omonnx后端禁用paddle后端禁用gpu export ENABLE_OM_BACKENDON ENABLE_ORT_BACKENDON ENABLE_PADDLE_BACKENDOFF WITH_GPUOFF DEVICE_TYPENPU # 注意仅aarch64机器需要设置NPU_HOST_LIB指定libascend库 export NPU_HOST_LIB/usr/local/Ascend/ascend-toolkit/latest/aarch64-linux/lib64 python setup.py build python setup.py bdist_wheel python -m pip install dist/ultra_infer_npu*.whl编译选项说明ENABLE_OM_BACKENDON集成昇腾 OM 后端NPU 推理核心ENABLE_ORT_BACKENDON集成 ONNX Runtime 后端ENABLE_PADDLE_BACKENDOFF/WITH_GPUOFFNPU 场景下关闭飞桨后端与 GPU 支持NPU_HOST_LIB仅 aarch64 机器需要指向libascend宿主库目录。从 libs/ultra-infer/python/ultra_infer 的构建体系看ultra-infer支持按需裁剪后端这正是不同hpi-*设备包差异的来源。4. 单模型推理4.1 双后端选型OM 与 ORT在昇腾上PaddleX 高性能推理插件支持OM与ORT两种后端后端模型格式推理设备特点om昇腾 OM 模型.omNPU基于 ATC 转换后的离线模型算子经昇腾深度优化性能更优但只支持静态 shapeonnxruntimeONNX 模型.onnxCPU支持动态 shape模型支持较全基本涵盖 PaddleX 模型列表昇腾 NPU 中的全部模型在 paddlex/inference/utils/hpi.py 的后端推荐逻辑中可以看到om后端只有在推理库以 OM 支持编译is_built_with_om()、模型目录中存在om格式模型、且设备类型为npu时才会被纳入可选后端与上述表格一致。4.2 OM 后端支持模型列表OM 后端目前支持以下模型。注意不同芯片910B / 310P / 310B之间的 OM 模型不通用需要按芯片分别下载对应 tar 包。更多模型正在支持中如有需求可提 issue也欢迎开发者提交 PR 贡献新模型| 模型类型 | 模型名称 | 输入shape | 模型下载链接 | | - | - | - | - | | 文本检测 | PP-OCRv4_mobile_det | x:1,3,640,480 | 910B/310P/310B | | 文本检测 | PP-OCRv4_server_det | x:1,3,640,480 | 910B/310P/310B | | 文本识别 | PP-OCRv4_mobile_rec | x:1,3,48,320 | 910B/310P/310B | | 文本识别 | PP-OCRv4_server_rec | x:1,3,48,320 | 910B/310P/310B | | 图像分类 | ResNet50 | x:1,3,224,224 | 910B/310P/310B | | 图像分类 | CLIP_vit_base_patch16_224 | x:1,3,224,224 | 待提供 | | 图像多标签分类 | ResNet50_ML | x:1,3,448,448 | 待提供 | | 目标检测 | RT-DETR-L | im_shape:1,2;image:1,3,640,640;scale_factor:1,2 | 910B/310P/310B | | 行人属性 | PP-LCNet_x1_0_pedestrian_attribute | x:1,3,256,192 | 待提供 | | 车辆属性 | PP-LCNet_x1_0_vehicle_attribute | x:1,3,192,256 | 待提供 | | 时序预测 | DLinear | past_target:1,96,1 | 910B/310P/310B | | 时序异常检测 | DLinear_ad | observed_cov_numeric:1,96,2 | 待提供 | | 图像特征 | PP-ShiTuV2_rec | x:1,3,224,224 | 待提供 | | 印章文本检测 | PP-OCRv4_server_seal_det | x:1,3,640,480 | 待提供 | | 印章文本检测 | PP-OCRv4_mobile_seal_det | x:1,3,640,480 | 待提供 | | 文档图像方向分类 | PP-LCNet_x1_0_doc_ori | x:1,3,224,224 | 待提供 | | 文档矫正 | UVDoc | x:1,3,736,736 | 待提供 | | 版面区域检测 | PP-DocLayout-L | im_shape:1,2;image:1,3,640,640;scale_factor:1,2 | 待提供 | | 表格分类 | PP-LCNet_x1_0_table_cls | x:1,3,224,224 | 待提供 | | 表格单元格检测 | RT-DETR-L_wired_table_cell_det | im_shape:1,2;image:1,3,640,640;scale_factor:1,2 | 待提供 | | 表格单元格检测 | RT-DETR-L_wireless_table_cell_det | im_shape:1,2;image:1,3,640,640;scale_factor:1,2 | 待提供 |表格中“待提供”的模型意味着官方 OM 权重尚未发布可先用 ORT 后端推理或等待后续版本补充。4.3 OM 后端推理4.3.1 准备 OM 模型及配置文件OM 推理要求模型文件与配置文件固定命名为inference.om与inference.yml且放置在同级目录下。官方下载的 OM 模型包内已包含这两个文件若要使用自己训练的模型转换流程为用 PaddleX 的 paddle2onnx 插件把训练导出的静态图模型转为 ONNX 模型用昇腾ATC工具将 ONNX 模型转为 OM 模型inference.yml在 PaddleX 导出模型时会自动生成也可直接复用官方模型包内的配置文件。由于310 系列机器不支持动态 shape目前只能使用固定 shape 推理转换 OM 时必须通过input_shape指定输入形状参考 4.2 表格。若指定 shape 后推理精度异常可对照 PaddleX 导出模型生成的inference.yml修改input_shape参数。以PP-OCRv4_mobile_rec输入 shapex:1,3,48,320为例# 先使用PaddleX提供的paddle2onnx插件将训练导出的静态图转成onnx模型 paddlex --paddle2onnx --paddle_model_dir PaddlePaddle模型存储目录 --onnx_model_dir ONNX模型存储目录 # 昇腾默认支持fp16精度 # 使用静态shape通过参数input_shape指定输入shape atc --modelinference.onnx --framework5 --outputinference --soc_versionAscend910B2 --input_shape x:1,3,48,320 # 如果需要fp32精度需要在转换命令中加上--precision_mode_v2origin atc --modelinference.onnx --framework5 --outputinference --soc_versionAscend910B2 --input_shape x:1,3,48,320 --precision_mode_v2origin参数速查--model输入 ONNX 模型路径--framework5表示输入模型为 ONNX 格式ATC 约定的框架编号--output输出 OM 模型前缀生成inference.om--soc_version目标芯片型号如Ascend910B2需与宿主机实际芯片一致--input_shape静态输入 shape格式输入名:维度1,维度2,...--precision_mode_v2origin强制 fp32 精度默认 fp16。更多关于 ATC 工具的使用方式可参考昇腾官方“ATC 工具学习向导”文档。4.3.2 使用 PaddleX Python API 推理PP-OCRv4_mobile_rec文本识别下载官方提供的 OCR 示例图片后运行from paddlex import create_model hpi_config { auto_config: False, # 关闭自动配置功能手动配置后端 backend: om, # 选用om后端 } # model_name传入使用的模型名称 # model_dir传入模型及配置文件存放的路径 # device设置为npu:0或npu不设置卡号则默认使用0号卡 # use_hpip设置为True开启高性能推理插件 # input_shape传入模型输入shape以列表形式传入[c,w,h]需要和atc转换时指定的输入shape保持一致且目前只有OCR类的模型需要传入该参数 model create_model(model_namePP-OCRv4_mobile_rec, model_dirPP-OCRv4_mobile_rec_infer_om_910b, devicenpu:0, use_hpipTrue, hpi_confighpi_config, input_shape[3, 48, 320]) output model.predict(general_ocr_rec_001.png) for res in output: res.print(json_formatFalse) res.save_to_img(./output/) res.save_to_json(./output/res.json)从源码看input_shape参数确实只在 OCR 类模型中生效在 paddlex/inference/models/text_detection/predictor.py 与 paddlex/inference/models/text_recognition/predictor.py 中input_shape被透传给预处理流程用于将输入图固定缩放到[c, h, w]见 text_detection/processors.py 与 text_recognition/processors.py从而与 ATC 转换时指定的静态 shape 对齐。ResNet50图像分类图像分类等非 OCR 模型无需传input_shapefrom paddlex import create_model hpi_config { auto_config: False, # 关闭自动配置功能手动配置后端 backend: om, # 选用om后端 } # 无需传参input_shape model create_model(model_nameResNet50, model_dirResNet50_infer_om_910b, devicenpu, use_hpipTrue, hpi_confighpi_config) output model.predict(general_image_classification_001.jpg) for res in output: res.print(json_formatFalse) res.save_to_img(./output/) res.save_to_json(./output/res.json)hpi_config中的auto_config: False对应 paddlex/inference/utils/hpi.py 中HPIConfig.auto_config字段——该字段默认值为True安全自动配置模式PaddleX 会按先验知识自动挑选后端设为False即进入无限制手动配置模式必须显式指定backend。4.4 ORT 后端推理ORTONNX Runtime后端推理方式与 OM 类似适用于 OM 暂不支持的模型两点关键差异支持动态 shape无需考虑input_shapehpi_config中backend改为onnxruntimedevice改为cpu。各模型的静态图权重可通过 PaddleX 模型列表昇腾 NPU 下载若使用自己训练的模型同样先用 paddle2onnx 插件转换paddlex --paddle2onnx --paddle_model_dir PaddlePaddle模型存储目录 --onnx_model_dir ONNX模型存储目录以 PP-OCRv4_mobile_rec 为例from paddlex import create_model hpi_config { auto_config: False, # 关闭自动配置功能手动配置后端 backend: onnxruntime, # 选用onnxruntime后端 } # device设置为cpu # 无需设置input_shape model create_model(model_namePP-OCRv4_mobile_rec, model_dirPP-OCRv4_mobile_rec_infer_onnx, devicecpu, use_hpipTrue, hpi_confighpi_config) output model.predict(general_ocr_rec_001.png) for res in output: res.print(json_formatFalse) res.save_to_img(./output/) res.save_to_json(./output/res.json)5. 产线推理高性能推理同样支持 PaddleX产线推理。下面以OCR 产线为例说明完整流程OCR 产线的详细说明可参考 通用 OCR 产线使用教程。5.1 准备 OM 模型及配置文件与单模型推理类似先准备PP-OCRv4_mobile_det与PP-OCRv4_mobile_rec的 OM 模型文件inference.om与配置文件inference.yml分别放在两个不同的目录下。5.2 创建产线配置文件 OCR.yml关键设计思路注释已内嵌在配置中顶层设置hpi_config指定推理后端为om禁用 OM 暂不支持的模块主要保留检测与识别模块在检测与识别模块中配置input_shape设置静态 shape在检测与识别模块中配置model_dir指向模型文件及配置文件的路径。pipeline_name: OCR text_type: general use_doc_preprocessor: False use_textline_orientation: False hpi_config: auto_config: False backend: om SubPipelines: DocPreprocessor: pipeline_name: doc_preprocessor use_doc_orientation_classify: False use_doc_unwarping: False SubModules: DocOrientationClassify: module_name: doc_text_orientation model_name: PP-LCNet_x1_0_doc_ori model_dir: null DocUnwarping: module_name: image_unwarping model_name: UVDoc model_dir: null SubModules: TextDetection: module_name: text_detection model_name: PP-OCRv4_mobile_det model_dir: PP-OCRv4_mobile_det_infer_om limit_side_len: 960 limit_type: max max_side_limit: 4000 thresh: 0.3 box_thresh: 0.6 unclip_ratio: 1.5 input_shape: [3, 640, 480] TextLineOrientation: module_name: textline_orientation model_name: PP-LCNet_x0_25_textline_ori model_dir: null batch_size: 6 TextRecognition: module_name: text_recognition model_name: PP-OCRv4_mobile_rec model_dir: PP-OCRv4_mobile_rec_infer_om batch_size: 1 score_thresh: 0.0 input_shape: [3, 48, 320]字段说明TextDetection中的limit_side_len: 960、limit_type: max、max_side_limit: 4000控制检测前图像缩放策略thresh、box_thresh、unclip_ratio为检测后处理参数TextRecognition中的batch_size、score_thresh控制识别批大小与置信度过滤各模块的input_shape采用[c, h, w]顺序与 4.2 表格及 ATC 转换 shape 保持一致。5.3 使用 PaddleX Python API 进行产线推理下载官方提供的示例图片后运行from paddlex import create_pipeline # pipeline设置为修改后的产线配置文件use_hpip表示使用高性能推理 pipeline create_pipeline(pipeline./my_path/OCR.yaml, devicenpu, use_hpipTrue) output pipeline.predict( input./general_ocr_002.png, use_doc_orientation_classifyFalse, use_doc_unwarpingFalse, use_textline_orientationFalse, ) for res in output: res.print() res.save_to_img(./output/) res.save_to_json(./output/)5.4 混合后端将精度异常的模块切换为 onnxruntime由于 OM 推理不支持动态 shape在部分图片上推理精度可能受影响。此时可以只将精度异常的模块后端改为 onnxruntimeCPU 推理其余模块仍走 OM兼顾性能与精度。例如将PP-OCRv4_mobile_det切到 onnxruntimepipeline_name: OCR text_type: general use_doc_preprocessor: False use_textline_orientation: False SubPipelines: DocPreprocessor: pipeline_name: doc_preprocessor use_doc_orientation_classify: False use_doc_unwarping: False SubModules: DocOrientationClassify: module_name: doc_text_orientation model_name: PP-LCNet_x1_0_doc_ori model_dir: null DocUnwarping: module_name: image_unwarping model_name: UVDoc model_dir: null # 在TextDetection配置hpi_config指定后端为onnxruntime、设备为cpu不指定输入shape SubModules: TextDetection: module_name: text_detection model_name: PP-OCRv4_mobile_det model_dir: PP-OCRv4_mobile_det_infer_onnx limit_side_len: 960 limit_type: max max_side_limit: 4000 thresh: 0.3 box_thresh: 0.6 unclip_ratio: 1.5 hpi_config: auto_config: False backend: onnxruntime device_type: cpu TextLineOrientation: module_name: textline_orientation model_name: PP-LCNet_x0_25_textline_ori model_dir: null batch_size: 6 TextRecognition: module_name: text_recognition model_name: PP-OCRv4_mobile_rec model_dir: PP-OCRv4_mobile_rec_infer_om batch_size: 1 score_thresh: 0.0 hpi_config: auto_config: False backend: om device_type: npu input_shape: [3, 48, 320]此时推理脚本不再统一指定设备各模块各自声明from paddlex import create_pipeline # 不指定设备 pipeline create_pipeline(pipeline./my_path/OCR.yaml, use_hpipTrue) output pipeline.predict( input./general_ocr_002.png, use_doc_orientation_classifyFalse, use_doc_unwarpingFalse, use_textline_orientationFalse, ) for res in output: res.print() res.save_to_img(./output/) res.save_to_json(./output/)这种“模块级hpi_config”的配置方式与 PaddleX 高性能推理指南 中“配置文件中不同层级的配置自动合并、最深层级优先级最高”的规则一致模块级hpi_config覆盖产线顶层的全局设置从而实现同一产线内 OM 与 onnxruntime 后端共存。6. 常见问题解决方法6.1 “cannot allocate memory in static TLS block”在 armaarch64机器上可能出现形如xxx.so cannot allocate memory in static TLS block的报错。解决办法是找到报错.so文件在机器上的路径然后将其加入LD_PRELOAD例如export LD_PRELOAD/usr/lib/aarch64-linux-gnu/libgomp.so.1:$LD_PRELOAD export LD_PRELOAD/usr/lib/aarch64-linux-gnu/libGLdispatch.so.0:$LD_PRELOAD export LD_PRELOAD/usr/local/lib/python3.10/dist-packages/scikit_learn.libs/libgomp-d22c30c5.so.1.0.0:$LD_PRELOAD若仍提示其他.so文件存在同样问题按相同方式逐个加入LD_PRELOAD即可。6.2 模型推理精度问题如果模型推理精度不理想按以下顺序尝试修改模型推理后端例如将om改为onnxruntime参考 5.4 的模块级hpi_config配置方法根据实际图片调整模型输入 shape静态 shape 越接近实际图片比例精度损失越小可参考inference.yml修改input_shape修改模型推理精度例如将 fp16 改为 fp32对应 ATC 转换时加--precision_mode_v2origin。7. 更多参考PaddleX 高性能推理指南HPI 通用安装、工作模式安全自动配置 / 无限制手动配置、hpi_config各字段含义与配置优先级、模型缓存等进阶说明PaddleX 模型列表昇腾 NPU昇腾场景下各模块可用的静态图模型与下载链接通用 OCR 产线使用教程OCR 产线各模块参数与使用细节高性能推理底层推理库ultra-infer构建与后端集成说明见 libs/ultra-infer 目录及其构建脚本后端选择与HPIConfig校验逻辑的源码实现见 paddlex/inference/utils/hpi.py。赞分享人工智能大模型低代码计算机视觉深度学习NLP模型推理服务RAG【免费下载链接】PaddleXAll-in-One Development Tool based on PaddlePaddle项目地址https://gitcode.com/paddlepaddle/PaddleX点击查看免费下载相关推荐PaddleX 昇腾 NPU 高性能推理实战教程环境搭建、OM/ORT 双后端部署与产线推理PaddleX 昇腾 NPU 高性能推理实战教程环境搭建、OM/ORT 双后端部署与产线推理 PaddleX 的高性能推理HPIHigh Performa人工智能大模型低代码计算机视觉深度学习模型推理服务昇腾 NPU 上的 PaddleX 产线全览从环境搭建到业务落地的实战指南昇腾 NPU 上的 PaddleX 产线全览从环境搭建到业务落地的实战指南 本文基于 PaddleX 官方《PaddleX 产线列表NPU》文档展开系统人工智能大模型低代码计算机视觉深度学习NLP模型推理服务RAG微调语音PaddleX 昇腾 NPU910B环境搭建与飞桨安装实战教程PaddleX 昇腾 NPU910B环境搭建与飞桨安装实战教程 本篇技术指南面向需要在昇腾 910B 芯片上运行 PaddleX 的开发者完整讲解从 Do人工智能大模型低代码计算机视觉深度学习模型推理服务上一篇深入解析Xposed框架文件权限zygote_access函数mode参数的终极指南下一篇JUnit4测试分类执行效率提升自动化脚本创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考