PaddleX 寒武纪 MLU 安装与部署指南：基于飞桨 MLU 开发镜像的完整环境搭建教程-育师

人工智能
大模型
低代码
计算机视觉
深度学习
模型推理服务

【免费下载链接】PaddleX

All-in-One Development Tool based on PaddlePaddle

项目地址：https://gitcode.com/gh_mirrors/pa/PaddleX

PaddleX 作为基于飞桨（PaddlePaddle）的一站式低代码开发工具，当前支持寒武纪 MLU370X8 芯片。本文以官方安装文档 paddlepaddle_install_MLU.en.md 为骨架，完整讲解从 Docker 环境准备、飞桨 CPU 与自定义 MLU 安装包安装、到安装验证的完整流程，并结合 PaddleX 源码说明 MLU 设备在推理框架中的接入方式，帮助你在 MLU 平台上快速搭建可用的 PaddleX 运行环境。

1. 环境概述与支持范围

从当前仓库的源码结构看，MLU 是 PaddleX 明确支持的自定义设备类型之一。在 paddlex/utils/device.py 中，SUPPORTED_DEVICE_TYPE列表明确包含mlu：

SUPPORTED_DEVICE_TYPE = [ "cpu", "gpu", "xpu", "npu", "mlu", "gcu", "dcu", "iluvatar_gpu", "metax_gpu", ]

同时，paddlex/utils/custom_device_list.py 定义了MLU_WHITELIST白名单，列出了当前在 MLU 上受支持的预训练模型，包括：

图像分类：ResNet18/34/50/101/152 及 vd 系列、PP-LCNet 系列、MobileNetV3 系列、PP-HGNet 系列等；
目标检测：PP-YOLOE_plus-X/L/M/S、PicoDet-L/M/S/XS 等；
语义分割：PP-LiteSeg-T；
OCR：PP-OCRv4_server_det、PP-OCRv4_mobile_det、PP-OCRv4_server_rec、PP-OCRv4_mobile_rec 等；
异常检测：STFPM；时序模型：DLinear、RLinear、NLinear；以及 PicoDet_LCNet_x2_5_face 等人脸检测模型。

需要注意，本文安装教程面向MLU370X8芯片，且飞桨 MLU 开发镜像目前仅提供 X86 架构版本，暂不提供 Arch64 架构镜像。安装前请确认你的硬件与架构符合上述前提。

2. Docker 环境准备

考虑到不同用户环境差异较大，官方文档强烈建议使用飞桨官方提供的寒武纪 MLU 开发镜像完成环境准备。该镜像仅为开发环境，不包含预编译的飞桨安装包，因此需要在镜像内自行安装飞桨。

2.1 拉取开发镜像

# 适用于 X86 架构，暂时不提供 Arch64 架构镜像 docker pull registry.baidubce.com/device/paddle-mlu:ctr2.15.0-ubuntu20-gcc84-py310

镜像标签ctr2.15.0-ubuntu20-gcc84-py310的含义可以拆解为：基于寒武纪 MLU 运行时（Cambricon Runtime，ctr）2.15.0 版本、Ubuntu 20.04 系统、GCC 8.4 编译器、Python 3.10 环境。镜像内已包含 MLU 驱动适配层与相关依赖，但没有预编译的飞桨 wheel 安装包，这正是下一步需要手动安装的原因。

2.2 启动容器

参考以下命令启动容器：

docker run -it --name paddle-mlu-dev -v $(pwd):/work \ -w=/work --shm-size=128G --network=host --privileged \ --cap-add=SYS_PTRACE --security-opt seccomp=unconfined \ -v /usr/bin/cnmon:/usr/bin/cnmon \ registry.baidubce.com/device/paddle-mlu:ctr2.15.0-ubuntu20-gcc84-py310 /bin/bash

对启动命令中的关键参数说明如下：

参数	作用
`-v $(pwd):/work`	将宿主机当前目录挂载到容器内`/work`，方便共享代码与数据
`-w=/work`	容器启动后默认工作目录设为`/work`
`--shm-size=128G`	增大共享内存，避免分布式训练或数据加载时的共享内存不足
`--network=host`	使用宿主机网络，便于访问内部源与调试服务
`--privileged`	授予容器特权，MLU 设备访问通常需要
`--cap-add=SYS_PTRACE --security-opt seccomp=unconfined`	放开 ptrace 与 seccomp 限制，便于调试与运行推理进程
`-v /usr/bin/cnmon:/usr/bin/cnmon`	将宿主机寒武纪监控工具`cnmon`挂载进容器，用于查看 MLU 卡状态

启动成功后即进入容器内的 bash 交互环境，接下来在容器内安装飞桨。

3. 安装飞桨软件包

在启动的 Docker 容器中，下载并安装飞桨官网发布的 wheel 包。当前官方提供Python 3.10的 wheel 安装包；如有其他 Python 版本需求，可参考飞桨官方安装文档自行编译安装（本文仅以官方预编译 wheel 为准）。

3.1 安装命令（先 CPU 后 MLU 自定义包）

# 下载并安装 wheel 包 # 注意：需要先安装飞桨 CPU 版本 python -m pip install paddlepaddle -i https://www.paddlepaddle.org.cn/packages/nightly/cpu python -m pip install paddle-custom-mlu -i https://www.paddlepaddle.org.cn/packages/nightly/mlu

为什么必须先安装 CPU 版飞桨？这是因为paddle-custom-mlu是飞桨针对寒武纪 MLU 的自定义设备扩展包，它依赖基础飞桨框架（CPU/通用算子库）作为运行时底座，再通过paddle_custom_device机制注册 MLU 后端。两条命令缺一不可：

第一条安装通用飞桨框架（paddlepaddle），提供核心计算图、算子框架与 Python API；
第二条安装 MLU 自定义设备包（paddle-custom-mlu），提供 MLU 上的算子实现与设备接入层。

安装完成后，PaddleX 推理框架在加载模型时即可通过paddle.inference.Config.enable_custom_device("mlu", device_id)将推理执行在 MLU 设备上。对应实现在 paddlex/inference/models/runners/paddle_static/runner.py：

elif self._config["device_type"] == "mlu": config.enable_custom_device("mlu", self._config.get("device_id", 0)) if hasattr(config, "enable_new_ir"): config.enable_new_ir(self._config.get("enable_new_ir", True)) if hasattr(config, "enable_new_executor"): config.enable_new_executor()

可以看到，MLU 分支与 NPU、Metax GPU 等自定义设备走的是同一套enable_custom_device接入路径，并默认开启新 IR 与新执行器。此外，paddlex/inference/models/runners/paddle_static/config/pp_option.py 的运行选项也把mlu纳入合法设备取值。

3.2 安装验证

安装完成之后，运行如下命令验证安装：

python -c "import paddle; paddle.utils.run_check()"

预期得到如下输出结果：

Running verify PaddlePaddle program ... PaddlePaddle works well on 1 mlu. PaddlePaddle works well on 16 mlus. PaddlePaddle is installed successfully! Let's start deep learning with PaddlePaddle now.

输出中PaddlePaddle works well on 1 mlu.表示飞桨已成功识别并在 1 张 MLU 卡上完成算子自检，works well on 16 mlus则验证了多卡环境下 16 张 MLU 卡均可正常调度。若出现报错，请优先检查镜像版本、cnmon挂载是否成功，以及 MLU 驱动是否与 ctr2.15.0 运行时匹配。

4. 在 MLU 上使用 PaddleX

飞桨安装并验证通过后，即可安装 PaddleX（推荐以 wheel 方式安装，或参考多设备使用指南选择插件安装模式进行二次开发）。PaddleX 在 MLU 等国产硬件平台上的用法与 GPU 完全一致，只需将设备参数改为mlu即可，例如：

paddlex --pipeline OCR --input general_ocr_002.png --device mlu:0

Python 脚本方式：

from paddlex import create_pipeline pipeline = create_pipeline(pipeline="OCR", device="mlu:0") output = pipeline.predict("general_ocr_002.png") for res in output: res.print() res.save_to_img("./output/")

从源码层面看，PaddleX 在切换设备时还会自动做两件事：

设备白名单校验：在 paddlex/utils/device.py 的check_supported_device_type中，当device_type == "mlu"时会校验模型名是否位于MLU_WHITELIST，若不在白名单内会提示The MLU device does not yet support xxx model!，并可通过环境变量PADDLE_PDX_DISABLE_DEV_MODEL_WL关闭该校验。
运行环境变量注入：同一文件 paddlex/utils/device.py 中，set_env_for_device_type会在 MLU 设备上自动设置：

if device_type.lower() == "mlu": envs = { "FLAGS_use_stride_kernel": "0", "FLAGS_use_stream_safe_cuda_allocator": "0", } _set(envs)

FLAGS_use_stride_kernel=0用于关闭 stride kernel 优化路径以保证 MLU 算子兼容性，FLAGS_use_stream_safe_cuda_allocator=0用于禁用 stream-safe 分配器，避免在 MLU 后端出现内存分配问题。这两个环境变量在推理启动时由 PaddleX 自动注入，无需手动设置。

此外，在 paddlex/inference/utils/misc.py 中，MLU 也被纳入 bfloat16 与 float16 混合精度可用性判断的设备类型，说明 MLU 上支持使用混合精度推理。

5. 注意事项与补充说明

架构限制：官方 MLU 开发镜像目前仅提供 X86 架构版本，Arch64 架构用户需自行编译飞桨，或关注官方后续发布的镜像。
Python 版本：当前 wheel 包针对 Python 3.10 提供；其他版本需参考飞桨官方编译安装说明自行构建paddlepaddle与paddle-custom-mlu。
驱动与监控：容器内需要能够访问寒武纪驱动；cnmon工具通过-v /usr/bin/cnmon:/usr/bin/cnmon挂载进入容器，可用来确认 MLU 卡是否可见、显存与算力状态。
多卡使用：验证输出显示飞桨支持多张 MLU 卡（如 16 卡）。训练场景下可在配置文件中通过Global.device指定多卡，例如-o Global.device=mlu:0,1,2,3，用法与 GPU 多卡一致。
模型支持范围：并非所有 PaddleX 模型都在 MLU 上受支持，请以MLU_WHITELIST（paddlex/utils/custom_device_list.py）为准，OCR 检测识别、图像分类、目标检测、语义分割、异常检测与部分时序模型均已覆盖。
更多硬件平台：若还需在昇腾 NPU、昆仑芯 XPU、海光 DCU、燧原 GCU 等设备上部署，可参考 Ascend NPU 安装指南与 PaddleX 多设备使用指南中对应章节，安装流程与本教程高度一致（均为"开发镜像 + CPU 包 + 自定义设备包"的组合）。