这是华为Atlas芯片的多模态大模型套件Docker镜像,支持主流多模态模型的大规模分布式训练、微调及推理,提供端到端解决方案,预装PyTorch、CANN等基础依赖。
MindSpeed MM Docker镜像概述
快速参考
| 项目 | 描述 |
|---|---|
| 镜像名称 | mindspeed-mm |
| 维护者 | MindSpeed MM团队 |
| 源码仓库 | [***] |
| Dockerfile路径 | docker/ |
| 许可证 | Apache-2.0 |
MindSpeed MM简介
MindSpeed MM是面向华为https://www.hiAscend.com/的多模态大模型套件,支持行业主流多模态大模型的大规模分布式训练,旨在提供端到端的多模态训练解决方案,包括预构建主流模型、数据工程、分布式训练加速、预训练、微调、后训练及在线推理任务等功能。
该镜像基于Ubuntu 22.04和openEuler 24.03操作系统,支持x86_64和aarch64(ARM64)CPU架构,预装以下软件:
- PyTorch + torch_npu:深度学习框架
- decord 0.6.0:高性能视频解码库
- CANN:华为Atlas AI处理器基础软件栈
- verl_qwen3vl conda环境:预编译的VERL Qwen3VL强化学习训练环境(含vllm、vllm-ascend、verl)
由于不同模型的依赖差异,镜像仅预装上述基础包。用户拉取镜像并启动容器后,需根据目标模型的README文件在基础环境中手动安装额外依赖。
镜像下载:请访问https://www.hiascend.com/developer/ascendhub,搜索mindspeed-mm获取对应的`docker pull`命令。目前仅提供openEuler 24.03系统和aarch64架构的镜像。
项目目录结构规范
Docker项目目录遵循清晰的层级结构,便于维护和扩展:
核心目录结构
textdocker/ ├── Dockerfile # 支持多NPU类型和OS的统一Dockerfile ├── build.sh # 灵活参数配置的镜像构建脚本 ├── OVERVIEW.md # 英文文档 ├── OVERVIEW.zh.md # 中文文档 └── scripts/ # 脚本目录 └── model_install/ # 模型环境安装脚本 └── install_*.sh # 特定模型安装脚本
目录说明
- Dockerfile:统一构建文件,通过构建参数支持所有NPU类型和OS版本
- build.sh:镜像构建脚本,提供灵活参数配置和自动检测功能
- scripts/:按功能组织脚本
- model_install/:存储模型环境安装脚本,命名格式为
install_{环境名}.sh
- model_install/:存储模型环境安装脚本,命名格式为
脚本使用机制
docker/build.sh脚本在构建过程中:
- 根据
-v参数指定的版本号(默认:master)定位对应的脚本目录 - 将
docker/scripts/model_install/目录下的所有install_*.sh脚本复制到install_scripts/临时目录
重要提示:当前版本的Dockerfile仅执行预定义的特定安装脚本(如install_verl_qwen3vl.sh)。若需添加新模型环境安装脚本,必须同时更新Dockerfile以包含新脚本的复制和执行逻辑。
1. 镜像使用指南
重要提示:由于不同模型的依赖差异,镜像仅预装PyTorch、torch_npu、decord等基础依赖。用户拉取镜像并启动容器后,需根据目标模型的README文件在基础环境中手动安装所需依赖。
运行镜像
bash# 基础运行 docker run -it --rm \ docker.xuanyuan.run/mindspeed-mm:master-a3-openeuler24.03-py3.11-x86_64 bash # 带NPU设备运行(示例:设备/dev/davinci1) # 请将ascend-toolkit路径改为实际安装路径。 # 假设NPU设备安装在/dev/davinci1,驱动安装在/usr/local/Ascend: docker run -it --rm \ --device=/dev/davinci1 \ --device=/dev/davinci_manager \ --device=/dev/devmm_svm \ --device=/dev/hisi_hdc \ -v /usr/local/dcmi:/usr/local/dcmi \ -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \ -v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \ -v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \ -v /etc/ascend_install.info:/etc/ascend_install.info \ docker.xuanyuan.run/mindspeed-mm:master-a3-openeuler24.03-py3.11-x86_64 bash # 带数据目录挂载运行(示例:设备/dev/davinci1) docker run -it --rm \ --device=/dev/davinci1 \ --device=/dev/davinci_manager \ --device=/dev/devmm_svm \ --device=/dev/hisi_hdc \ -v /usr/local/dcmi:/usr/local/dcmi \ -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \ -v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \ -v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \ -v /etc/ascend_install.info:/etc/ascend_install.info \ -v /path/to/data:/data \ -v /path/to/weights:/weights \ docker.xuanyuan.run/mindspeed-mm:master-a3-openeuler24.03-py3.11-x86_64 bash
内置环境
镜像包含以下预配置环境:
| 环境 | 描述 | 工作目录 |
|---|---|---|
| base | 包含PyTorch、torch_npu、decord、MindSpeed MM的基础环境 | /workspace/MindSpeed-MM |
| verl_qwen3vl | VERL Qwen3VL模型环境(含vllm、vllm-ascend、verl) | /workspace/verl_qwen3vl |
环境说明:
- 由于verl环境需要源码编译(耗时较长),已在镜像中预安装配置
- 考虑到模型间依赖差异,镜像仅预装基础依赖
- 用户需根据目标模型的README手动安装额外依赖
2. 本地自定义安装指南
构建脚本参数说明
build.sh脚本支持多参数配置,以下为默认值示例,需根据实际调整:
| 参数 | 描述 | 默认示例 |
|---|---|---|
-t, --npu-type | NPU类型 | 无(必填) |
-o, --os | 操作系统:openeuler24.03或ubuntu22.04 | openeuler24.03 |
-v, --version | MindSpeed MM版本标识(作为Git分支名和脚本目录选择依据) | master |
--torch-version | PyTorch版本 | 2.7.1 |
--torch-npu-version | torch-npu版本 | 2.7.1 |
--base-image-version | 基础镜像CANN版本 | 9.0.0-beta.2 |
--base-image | 完整基础镜像名称 | 无 |
--torch-whl | torch离线安装包路径 | 无 |
--torch-npu-whl | torch-npu离线安装包路径 | 无 |
--cleanup-on-fail | 构建失败时清理悬空镜像/容器 | 无 |
基础构建示例
bashcd docker # 构建A3 + openEuler镜像(默认) bash build.sh -t A3 # 构建A2 + openEuler镜像 bash build.sh -t 910B # 构建A3 + Ubuntu镜像 bash build.sh -t A3 -o ubuntu22.04 # 指定PyTorch版本构建 bash build.sh -t A3 --torch-version 2.7.1 --torch-npu-version 2.7.1 # 用离线whl包构建 bash build.sh -t A3 \ --torch-whl /path/to/torch-2.7.1+cpu-cp311-cp311-linux_x86_64.whl \ --torch-npu-whl /path/to/torch_npu-2.7.1-cp311-cp311-linux_x86_64.whl # 指定基础镜像版本构建 bash build.sh -t A3 --base-image-version 9.0.0 # 指定版本构建 bash build.sh -t A3 -v master
自动下载功能说明
构建脚本支持自动下载以下资源,请确保网络连通:
- Miniconda安装器:未指定
--miniconda参数时自动下载 - decord依赖包:ARM架构自动下载
- 基础镜像:指定
--base-image且本地不存在时自动拉取
3. 自定义镜像构建/使用指南
自动基础镜像识别
构建脚本自动从基础镜像名称识别关键信息:
- NPU类型识别:从镜像标签识别芯片模型
- 操作系统识别:从镜像标签识别openeuler24.03或ubuntu22.04
- 自动生成镜像标签:基于识别信息生成符合命名规则的标签
最佳实践示例
以下示例展示如何用自定义基础镜像构建MindSpeed MM镜像:
bash#!/bin/bash SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" # 自定义配置 BASE_IMAGE="swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:9.0.0-beta.2-910b-openeuler24.03-py3.11" TORCH_VERSION="2.7.1" TORCH_NPU_VERSION="2.7.1.post2" MINDSPEED_MM_VERSION="master" # 执行构建 bash "${SCRIPT_DIR}/build.sh" \ --base-image "$BASE_IMAGE" \ --torch-version "$TORCH_VERSION" \ --torch-npu-version "$TORCH_NPU_VERSION" \ -v "$MINDSPEED_MM_VERSION" \ --cleanup-on-fail
关键特性说明:
- 自动识别:从
BASE_IMAGE自动识别NPU类型(910)和OS(openeuler24.03),本地不存在则自动拉取 - 自动标签生成:生成如
mindspeed-mm:master-910b-openeuler24.03-py3.11-x86_64的标签 - 自动下载:本地无Miniconda或decord依赖时自动下载
- 失败清理:
--cleanup-on-fail确保构建失败时清理悬空资源
添加其他模型的安装指南
若需添加其他模型的环境安装支持,可按以下步骤操作:
1. 查看模型示例
先查看examples/目录下相关模型的README,了解依赖和安装要求。
2. 按目录结构规范创建安装脚本
按docker/scripts目录层级创建新安装脚本:
- 创建脚本:在
docker/scripts/model_install/目录新建脚本 - 命名规范:脚本名格式为
install_{环境名}.sh
示例:添加Qwen3.5模型环境安装脚本
- 脚本路径:
docker/scripts/model_install/install_qwen3.5.sh
参考docker/scripts/master/model_install/install_verl_qwen3vl.sh格式创建:
bash#!/bin/bash set -e source /tmp/common_functions.sh MINDSPEED_MM_BRANCH="${1:-master}" ENV_NAME="your_model_name" # 修改为你的模型环境名 WORK_DIR="/workspace/${ENV_NAME}" echo "==========================================" echo "安装${ENV_NAME}环境" echo "==========================================" source /opt/conda/etc/profile.d/conda.sh # 接受conda服务条款 conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/main conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/r conda create --clone base -n ${ENV_NAME} -y conda activate ${ENV_NAME} mkdir -p ${WORK_DIR} cd ${WORK_DIR} # 根据模型需求安装依赖 # 示例:pip_install_retry "package_name==version" 3 # 示例:git clone仓库并安装 # 如需重新安装torch和torch_npu reinstall_torch_and_npu conda clean -ya && rm -rf /root/.cache/pip echo "==========================================" echo "${ENV_NAME}环境安装完成" echo "=========================================="
3. 更新Dockerfile以包含新脚本
当前Dockerfile仅执行预定义脚本,需手动更新:
- 添加复制命令:
dockerfile
# 复制新安装脚本 COPY install_scripts/install_your_model.sh /tmp/install_your_model.sh - 添加执行命令:
dockerfile
# 执行新安装脚本 RUN chmod +x /tmp/install_your_model.sh && \ bash /tmp/install_your_model.sh "$MINDSPEED_MM_BRANCH" && \ rm -f /tmp/install_your_model.sh - 构建脚本自动复制:
docker/build.sh会自动将install_*.sh复制到构建上下文 - 版本对应:
-v参数指定的版本号用于克隆MindSpeed-MM的对应Git分支
4. 构建镜像测试
用以下命令构建含新模型环境的镜像:
bash# -v参数指定版本号,构建脚本自动查找对应安装脚本 bash build.sh -t A3 -v master
5. 更新文档
在“内置环境”部分添加新环境信息:
| 环境 | 描述 | 工作目录 |
|---|---|---|
| your_model_name | 你的模型环境描述 | /workspace/your_model_name |
注意事项
- 目录结构规范:必须遵循
docker/scripts/model_install/结构 - 脚本命名规范:安装脚本需按
install_{环境名}.sh命名 - Dockerfile更新:需手动添加新脚本的复制和执行逻辑
- 可执行权限:确保脚本有可执行权限
- 依赖安装:使用
pip_install_retry函数重试安装 - 清理工作:脚本末尾清理临时文件和缓存以减小镜像体积
- 测试验证:构建后测试新环境是否正常工作
二次开发
基于该镜像创建自定义Dockerfile:
dockerfileFROM docker.xuanyuan.run/mindspeed-mm:master-a3-openeuler24.03-py3.11-x86_64 RUN pip install your-package==1.0.0 COPY . /workspace/your-project WORKDIR /workspace/your-project
构建并运行(示例:设备/dev/davinci1):
bashdocker build -t my-mindspeed-app:latest . docker run -it --rm \ --device=/dev/davinci1 \ --device=/dev/davinci_manager \ --device=/dev/devmm_svm \ --device=/dev/hisi_hdc \ -v /usr/local/dcmi:/usr/local/dcmi \ -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \ -v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \ -v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \ -v /etc/ascend_install.info:/etc/ascend_install.info \ docker.xuanyuan.run/my-mindspeed-app:latest bash
软件栈
| 组件 | 版本 |
|---|---|
| CANN | 9.0.0-beta.2 |
| Python | 3.11 |
| Miniconda | 26.1.1-1 |
| PyTorch | 2.7.1 |
| torch_npu | 2.7.1 |
| decord | 0.6.0 |
| MindSpeed MM | master |
兼容性变更说明
日期:2026-04-20
- 初始发布版本
- 基于CANN 9.0.0-beta.2
- PyTorch 2.7.1 + torch_npu 2.7.1
- Python 3.11(Miniconda 26.1.1-1)
- 包含verl_qwen3vl conda环境
- 支持openEuler 24.03和Ubuntu 22.04
许可证
MindSpeed MM以Apache License 2.0发布,详情见LICENSE文件。
与所有Docker镜像一样,本镜像可能包含其他许可下的软件(如基础发行版的Bash及所含主软件的直接/间接依赖)。
对于预构建镜像的任何使用,镜像用户有责任确保其使用符合其中所有软件的相关许可。
镜像拉取方式
您可以使用以下命令拉取该镜像。请将 <标签> 替换为具体的标签版本。如需查看所有可用标签版本,请访问 标签列表页面。
轩辕镜像加速拉取命令点我查看更多 mindspeed-mm 镜像标签
DockerHub 原生拉取命令
用户好评
来自真实用户的反馈,见证轩辕镜像的优质服务