MindSpeed-Ops Docker 镜像构建指南

本目录包含 MindSpeed-Ops 的 Docker 镜像构建文件，用于在昇腾 NPU 环境中快速部署 MindSpeed-Ops 算子库。

目录结构

docker/
├── Dockerfile                # Docker 镜像定义（三阶段构建）
├── image_build.sh            # 一键构建脚本
├── configure_apt_repo.sh     # Ubuntu 华为云镜像源配置
├── configure_yum_repo.sh     # openEuler 华为云镜像源配置
└── OVERVIEW.md               # 本文件

软件版本配套

组件	版本
CANN	9.0.0-beta.2
PyTorch	2.7.1
torch-npu	2.7.1
triton-ascend	3.2.1
Python	3.11 (openEuler: python3, Ubuntu: python3.11)

支持的配置

配置项	支持的值
NPU 类型	A3、910B
操作系统	openEuler 24.03、Ubuntu 22.04
CPU 架构	x86_64、aarch64 (ARM)

前置条件

• 已安装 Docker（建议 20.10 及以上版本）
• 宿主机已安装昇腾 NPU 驱动和 CANN Toolkit（用于运行容器时挂载）
• 构建时需要网络连接（在线安装 PyTorch、torch-npu、triton-ascend）

快速开始

1. 构建镜像

进入 docker/ 目录，使用构建脚本：

cd docker/
bash image_build.sh -t 910B

构建完成后，镜像将自动命名为：mindspeed-ops:master-910b-openeuler24.03-py3.11-x86_64

2. 运行容器

docker run -itd \
  --name mindspeed \
  --privileged \
  --network host \
  --ipc=host \
  -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
  -v /usr/local/dcmi:/usr/local/dcmi \
  -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
  -v /etc/ascend_install.info:/etc/ascend_install.info \
  -v /home:/home \
  -v /data:/data \
  -v /mnt:/mnt \
  mindspeed-ops:master-910b-openeuler24.03-py3.11-x86_64 bash

进入已启动容器：

docker exec -it mindspeed /bin/bash

如果宿主机的 npu-smi 安装在 /usr/local/sbin/npu-smi，请相应替换 npu-smi 挂载路径。

进入容器后，MindSpeed-Ops 已以 editable 模式安装在 /workspace/MindSpeed-Ops 目录下，可直接使用：

import mindspeed_ops

构建脚本参数详解

bash image_build.sh [OPTIONS]

必选参数

参数	说明
-t, --npu-type TYPE	NPU 类型：A3 或 910B

可选参数

参数	默认值	说明
-i, --image-name NAME	自动生成	自定义输出镜像名称
-o, --os OS	openEuler24.03	操作系统类型：openEuler24.03 或 ubuntu22.04
-n, --no-cache	-	不使用 Docker 构建缓存
--base-image IMAGE	-	完整的基础镜像地址，直接传递给 FROM 指令
--base-image-version VER	9.0.0-beta.2	CANN 基础镜像版本
--python-version VER	3.11	Python 版本
--torch-version VER	2.7.1	PyTorch 版本
--torch-npu-version VER	2.7.1	torch-npu 版本
--triton-ascend-version VER	3.2.1	triton-ascend 版本
--mindspeed-ops-branch BRANCH	master	MindSpeed-Ops Git 分支/版本
--soc-version VERSION	-	目标芯片型号，用于编译 ACLNN 算子（见下方说明）
--cleanup-on-fail	-	构建失败时自动清理悬空镜像
-h, --help	-	显示帮助信息

关于 ACLNN 算子编译

MindSpeed-Ops 包含三类算子后端：

后端	说明	是否需要 SOC_VERSION
Triton	基于 triton-ascend 的算子（主要后端）	不需要
TileLang	基于 TileLang 的算子	不需要
ACLNN	基于 CANN AscendC 的原生算子	需要

• 不指定 --soc-version：仅安装 Triton/Python 算子，跳过 C++ 扩展和 ACLNN 编译。适用于大多数场景。
• 指定 --soc-version：将额外编译 C++ 扩展（pybind11）和 ACLNN 自定义算子包。需要容器内能访问 NPU 驱动（通常需要在有 NPU 设备的机器上构建，或挂载驱动目录）。

SOC_VERSION 取值示例：

芯片	SOC_VERSION	架构
Ascend 910B	ascend910b1	arch32
Ascend 910_93	ascend910_9391	arch32
Ascend 950*	ascend950*	arch35

使用示例

基本构建（910B + openEuler）

bash image_build.sh -t 910B

A3 + Ubuntu

bash image_build.sh -t A3 -o ubuntu22.04

启用 ACLNN 编译（910B 芯片）

bash image_build.sh -t 910B --soc-version ascend910b1

使用自定义基础镜像

bash image_build.sh -t A3 --base-image swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:9.0.0-beta.2-a3-openeuler24.03-py3.11

指定 MindSpeed-Ops 分支版本

bash image_build.sh -t 910B --mindspeed-ops-branch v0.1.0

自定义镜像名称

bash image_build.sh -t 910B -i myregistry.com/mindspeed-ops:latest

不使用缓存构建（构建失败时自动清理）

bash image_build.sh -t 910B --no-cache --cleanup-on-fail

镜像 Tag 命名规则

默认命名格式：mindspeed-ops:{分支}-{NPU类型}-{OS}-py{Python版本}-{架构}

示例：

mindspeed-ops:master-910b-openeuler24.03-py3.11-x86_64
mindspeed-ops:master-a3-openeuler24.03-py3.11-aarch64
mindspeed-ops:v0.1.0-910b-ubuntu22.04-py3.11-x86_64

Dockerfile 构建阶段说明

镜像采用三阶段构建（multi-stage build）：

1. Stage 1 (base)：基于 CANN 官方镜像，配置 DNS、软件源、安装系统编译工具链（gcc、g++、cmake、ninja-build 等）
2. Stage 2 (builder)：安装 Python 3.11、PyTorch、torch-npu、triton-ascend 及 Python 构建依赖（pybind11、pyyaml、numpy 等）
3. Stage 3 (final)：克隆 MindSpeed-Ops 仓库并以 editable 模式安装，配置环境变量和工作目录

常见问题

Q: 如何在有 NPU 的机器上构建带 ACLNN 的镜像？

bash image_build.sh -t 910B --soc-version ascend910b1

注意：ACLNN 编译需要容器内能检测到 NPU 设备。如果构建环境没有 NPU，可以尝试通过挂载驱动目录的方式：

docker build --build-arg SOC_VERSION=ascend910b1 \
  -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
  -v /usr/local/Ascend/ascend-toolkit:/usr/local/Ascend/ascend-toolkit \
  --network=host -t mindspeed-ops:aclnn-910b .

Q: 容器内如何验证安装是否成功？

python -c "import mindspeed_ops; print('MindSpeed-Ops loaded successfully')"

# 检查 Triton 算子是否可用
python -c "from mindspeed_ops.api.triton import add; print('Triton operators available')"

# 检查 torch-npu 是否正常
python -c "import torch_npu; print(f'torch_npu version: {torch_npu.__version__}')"