mindspeed-mm

ascendai/mindspeed-mm Docker Image

这是华为Atlas芯片的多模态大模型套件Docker镜像,支持主流多模态模型的大规模分布式训练、微调及推理,提供端到端解决方案,预装PyTorch、CANN等基础依赖。

下载次数: 0状态:社区镜像维护者:昇腾 Ascend AI 容器镜像仓库类型:镜像最近更新:

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项目目录遵循清晰的层级结构,便于维护和扩展:

核心目录结构

text
docker/
├── Dockerfile                 # 支持多NPU类型和OS的统一Dockerfile
├── build.sh                   # 灵活参数配置的镜像构建脚本
├── OVERVIEW.md                # 英文文档
├── OVERVIEW.zh.md             # 中文文档
└── scripts/                   # 脚本目录
    └── model_install/         # 模型环境安装脚本
        └── install_*.sh       # 特定模型安装脚本

目录说明

  1. Dockerfile:统一构建文件,通过构建参数支持所有NPU类型和OS版本
  2. build.sh:镜像构建脚本,提供灵活参数配置和自动检测功能
  3. scripts/:按功能组织脚本
    • model_install/:存储模型环境安装脚本,命名格式为install_{环境名}.sh

脚本使用机制

docker/build.sh脚本在构建过程中:

  1. 根据-v参数指定的版本号(默认:master)定位对应的脚本目录
  2. 将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_qwen3vlVERL Qwen3VL模型环境(含vllm、vllm-ascend、verl)/workspace/verl_qwen3vl

环境说明:

  • 由于verl环境需要源码编译(耗时较长),已在镜像中预安装配置
  • 考虑到模型间依赖差异,镜像仅预装基础依赖
  • 用户需根据目标模型的README手动安装额外依赖

2. 本地自定义安装指南

构建脚本参数说明

build.sh脚本支持多参数配置,以下为默认值示例,需根据实际调整:

参数描述默认示例
-t, --npu-typeNPU类型无(必填)
-o, --os操作系统:openeuler24.03或ubuntu22.04openeuler24.03
-v, --versionMindSpeed MM版本标识(作为Git分支名和脚本目录选择依据)master
--torch-versionPyTorch版本2.7.1
--torch-npu-versiontorch-npu版本2.7.1
--base-image-version基础镜像CANN版本9.0.0-beta.2
--base-image完整基础镜像名称无
--torch-whltorch离线安装包路径无
--torch-npu-whltorch-npu离线安装包路径无
--cleanup-on-fail构建失败时清理悬空镜像/容器无

基础构建示例

bash
cd 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

自动下载功能说明

构建脚本支持自动下载以下资源,请确保网络连通:

  1. Miniconda安装器:未指定--miniconda参数时自动下载
  2. decord依赖包:ARM架构自动下载
  3. 基础镜像:指定--base-image且本地不存在时自动拉取

3. 自定义镜像构建/使用指南

自动基础镜像识别

构建脚本自动从基础镜像名称识别关键信息:

  1. NPU类型识别:从镜像标签识别芯片模型
  2. 操作系统识别:从镜像标签识别openeuler24.03或ubuntu22.04
  3. 自动生成镜像标签:基于识别信息生成符合命名规则的标签

最佳实践示例

以下示例展示如何用自定义基础镜像构建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

关键特性说明:

  1. 自动识别:从BASE_IMAGE自动识别NPU类型(910)和OS(openeuler24.03),本地不存在则自动拉取
  2. 自动标签生成:生成如mindspeed-mm:master-910b-openeuler24.03-py3.11-x86_64的标签
  3. 自动下载:本地无Miniconda或decord依赖时自动下载
  4. 失败清理:--cleanup-on-fail确保构建失败时清理悬空资源

添加其他模型的安装指南

若需添加其他模型的环境安装支持,可按以下步骤操作:

1. 查看模型示例

先查看examples/目录下相关模型的README,了解依赖和安装要求。

2. 按目录结构规范创建安装脚本

按docker/scripts目录层级创建新安装脚本:

  1. 创建脚本:在docker/scripts/model_install/目录新建脚本
  2. 命名规范:脚本名格式为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仅执行预定义脚本,需手动更新:

  1. 添加复制命令:
    dockerfile
    # 复制新安装脚本
    COPY install_scripts/install_your_model.sh /tmp/install_your_model.sh
    
  2. 添加执行命令:
    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
    
  3. 构建脚本自动复制:docker/build.sh会自动将install_*.sh复制到构建上下文
  4. 版本对应:-v参数指定的版本号用于克隆MindSpeed-MM的对应Git分支

4. 构建镜像测试

用以下命令构建含新模型环境的镜像:

bash
# -v参数指定版本号,构建脚本自动查找对应安装脚本
bash build.sh -t A3 -v master

5. 更新文档

在“内置环境”部分添加新环境信息:

环境描述工作目录
your_model_name你的模型环境描述/workspace/your_model_name

注意事项

  1. 目录结构规范:必须遵循docker/scripts/model_install/结构
  2. 脚本命名规范:安装脚本需按install_{环境名}.sh命名
  3. Dockerfile更新:需手动添加新脚本的复制和执行逻辑
  4. 可执行权限:确保脚本有可执行权限
  5. 依赖安装:使用pip_install_retry函数重试安装
  6. 清理工作:脚本末尾清理临时文件和缓存以减小镜像体积
  7. 测试验证:构建后测试新环境是否正常工作

二次开发

基于该镜像创建自定义Dockerfile:

dockerfile
FROM 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):

bash
docker 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

软件栈

组件版本
CANN9.0.0-beta.2
Python3.11
Miniconda26.1.1-1
PyTorch2.7.1
torch_npu2.7.1
decord0.6.0
MindSpeed MMmaster

兼容性变更说明

日期: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 镜像标签

docker pull docker.xuanyuan.run/ascendai/mindspeed-mm:<标签>

DockerHub 原生拉取命令

docker pull ascendai/mindspeed-mm:<标签>
专业版 · 高速稳定拉取镜像
50GB 仅 ¥8/年
高速镜像下载在线技术支持专业版保障服务可用付费会员免广告