ModelScope 仓库 Metax 4.0 目录基于 MACA 加速卡的 ms-swift 训练镜像构建与运行全指南【免费下载链接】modelscopeModelScope: bring the notion of Model-as-a-Service to life.项目地址: https://gitcode.com/GitHub_Trending/mo/modelscope导读本指南基于 swift_building_instructions.md讲解如何在 ModelScope 仓库的docker/Metax/4.0目录下为沐曦MetaXMACA 系列加速卡构建可运行 ms-swiftSWIFTScalable lightWeight Infrastructure for Fine-Tuning训练框架的 Docker 镜像并正确启动容器、激活虚拟环境、跑通全参训练示例。文章覆盖从 UBI9 最小基础镜像完整构建与基于 Metax 预发布镜像快速构建两条路线并深入解读配套的 Dockerfile.metax、Dockerfile.with_metax_image、build.sh 与 build_from_metax_image.sh 实现细节。读完本文你将能够独立复现 vLLM-metax Megatron-LM ms-swift 的整套 MACA 训练环境并理解镜像内部各构建步骤的作用与顺序。一、背景为什么需要两套镜像构建方案ms-swiftMS-Swift是 ModelScope 社区推出的轻量级大模型微调框架而 vLLM-metax、MACA SDK 等组件属于沐曦 GPUMACA 架构的专属生态。ModelScope 仓库在docker/Metax/下按 Metax 软件版本维护了4.0、4.1、4.2、4.4四个构建目录每个目录都含相同的 6 个文件两份 Dockerfile、两个构建脚本、override.txt、requirements_extra.txt与本文档。本指南以 4.0 目录为准其余版本目录结构与用法完全一致仅构建参数如版本号不同。两种方案的核心差异维度方案一从 UBI9 完整构建方案二基于 Metax 发布镜像入口脚本build.shbuild_from_metax_image.sh使用的 DockerfileDockerfile.metaxDockerfile.with_metax_image基础镜像registry.access.redhat.com/ubi9/ubi:9.6最小化系统预装 MACA SDK 的发布镜像.../maca/ms-swift:3.10.3-maca.ai3.3.0.16-torch2.6-py310-ubuntu22.04-amd64Python 环境venv/opt/venvconda/opt/conda包管理工具uv高性能 Python 包管理器pip构建耗时慢需从零安装驱动、SDK、cu-bridge快复用预构建产物适用场景环境完全可控、可复现快速验证、节省构建时间二、方案一从 UBI9 基础镜像完整构建venv 环境原文档指出该方案是从最小基础镜像完整构建使用 venv 虚拟环境。整个流程分为构建 → 运行容器 → 激活 venv → 运行 swift 示例。2.1 执行构建bash build.shbuild.sh 的实际内容如下其中每个--build-arg都可按需覆盖docker build \ --network host \ -f Dockerfile.metax \ -t swift:v4.0.0 \ --build-arg VLLM_VERSIONv0.11.2 \ --build-arg VLLM_METAX_VERSIONv0.11.2 \ --build-arg MACA_VERSION3.3.0 \ --build-arg MEGATRON_VERSIONcore_v0.15.0 \ --build-arg SWIFT_VERSIONv4.0.0 \ --build-arg TE_VERSION2.8 \ --build-arg CU_BRIDGE_VERSION3.3.0 \ --no-cache \ .参数速查表构建参数默认值4.0作用VLLM_VERSIONv0.11.2上游 vLLM 版本用于构建空设备 vLLMVLLM_METAX_VERSIONv0.11.2vLLM-metax 分支/标签版本MACA_VERSION3.3.0Metax 驱动与 MACA SDK 版本MEGATRON_VERSIONcore_v0.15.0Megatron-LM 版本SWIFT_VERSIONv4.0.0ms-swift 版本TE_VERSION2.8Transformer Engine 版本CU_BRIDGE_VERSION3.3.0cu-bridgeCUDA 兼容桥接层版本提示构建需要访问 UBI9、GitHub 代码仓库、Metax 软件源repos.metax-tech.com与阿里云 PyPI 镜像请确保网络可达--network host模式下容器复用宿主机网络可避免代理/镜像源解析问题。2.2 启动容器docker run -d -it --nethost --utshost --ipchost --privilegedtrue --group-add video \ --shm-size 100gb --ulimit memlock-1 \ --security-opt seccompunconfined --security-opt apparmorunconfined \ --device/dev/dri --device/dev/mxcd \ --name base_image \ ${IMAGE_ID} bash各关键参数说明--nethost --utshost --ipchost共享宿主机的网络、UTS主机名与 IPC 命名空间这是高性能计算/多卡训练容器最常见的配置--privilegedtrue授予容器全部权限--group-add video将容器进程加入 video 组便于访问 GPU/显示相关设备--shm-size 100gb将/dev/shm放大到 100GB避免分布式训练中 NCCL/集合通信的共享内存瓶颈--ulimit memlock-1解除内存锁定上限vLLM、pinned memory 场景必需--security-opt seccompunconfined --security-opt apparmorunconfined关闭安全模块限制规避 GPU 驱动调用被拦截的问题--device/dev/dri --device/dev/mxcd直通 DRI 图形设备与沐曦计算设备mxcd即 MACA 计算设备节点。2.3 激活 venv 虚拟环境方案一使用 venv 而非 condasource /opt/venv/bin/activate/opt/venv由 Dockerfile.metax 通过VIRTUAL_ENV/opt/venv与uv venv /opt/venv --python${PYTHON_VERSION}创建Python 3.12同时 Dockerfile 已把/opt/venv/bin注入PATH。2.4 运行 swift 训练示例cd /workspace/ms-swift bash example/train/full/train.sh/workspace/ms-swift在构建阶段由git clone --branch ${SWIFT_VERSION} .../ms-swift.git拉取见 Dockerfile.metaxexample/train/full/train.sh即 ms-swift 仓库自带的**全参微调Full Parameter Fine-Tuning**示例脚本。三、方案二基于 Metax 发布镜像快速构建conda 环境原文档说明该方案是基于预构建的 Metax 发布镜像快速构建使用 conda 虚拟环境省去了从零安装驱动与 SDK 的漫长过程。3.1 执行构建bash build_from_metax_image.shbuild_from_metax_image.sh 内容如下docker build \ --network host \ -f Dockerfile.with_metax_image \ -t swift:v4.0.0 \ --build-arg VLLM_VERSIONv0.11.2 \ --build-arg VLLM_METAX_VERSIONv0.11.2 \ --build-arg MEGATRON_VERSIONcore_v0.15.0 \ --build-arg SWIFT_VERSIONv4.0.0 \ --progressplain \ --no-cache \ .注意此处--progressplain可输出完整构建日志便于排查且未传MACA_VERSION/TE_VERSION等参数因为它们已由基础镜像提供。3.2 启动容器与方案一完全相同直接复用上文 2.2 的docker run命令即可。两套方案产出的镜像对外暴露的运行时接口设备映射、共享内存、命名空间是一致的。3.3 运行 swift 示例cd /workspace/ms-swift bash example/train/full/train.sh与原文档一致。由于基础镜像已内置 conda 且PATH已配置好/opt/conda/bin见 Dockerfile.with_metax_image无需额外激活环境。四、源码级拆解Dockerfile 内部构建流水线为帮助读者理解镜像里到底装了什么、为什么这样装下面结合两份 Dockerfile 梳理关键阶段。4.1 完整构建Dockerfile.metaxDockerfile.metax 依次完成以下阶段基础环境初始化基于 UBI9 9.6 安装python3-pip、hostname随后用uv venv创建 Python 3.12 的/opt/venv再安装unzip vim git openblas-devel make cmake ninja-build gcc g procps-ng libibverbs librdmacm libibumad等编译与 RDMA远程直接内存访问依赖。克隆四个仓库按SWIFT_VERSION、VLLM_METAX_VERSION、VLLM_VERSION、MEGATRON_VERSION分别克隆 ms-swift、vLLM-metax、vLLM、Megatron-LM。安装 MACA SDK 与 cu-bridge通过 Metax 的 yum 源安装metax-driver-${MACA_VERSION}*仅取其中的mx-smi管理工具驱动内核模块在容器内不需要与maca_sdk-${MACA_VERSION}*随后从 gitee 下载cu-bridge源码用cmake ... make make install编译安装到/opt/maca/tools/cu-bridge——cu-bridge 是 CUDA 调用到 MACA 的兼容转换层并设置CUCC_PATH、CUDA_PATH、CUCC_CMAKE_ENTRY2等环境变量。清理冗余组件卸载mcflashattn、mcflashinfer、mxreport、mccltests等 SDK 附带组件删除/opt/maca下所有*.a静态库以减小镜像体积。构建 vLLM-metax 与 vLLM先安装 vLLM-metax 的 build 依赖随后进入 vllm 目录执行python3 use_existing_torch.py复用既有 torch 而非强制 CUDA 版并以VLLM_TARGET_DEVICEempty空设备模式安装 vLLM 本体避免触发 CUDA 依赖再对 vLLM-metax 执行python3 -m build -w -n打包并安装生成的 wheel。安装 Megatron-LM 与 Transformer Engine关键的一步是sed -i s/nvcc/cucc/g megatron/legacy/fused_kernels/__init__.py——将 Megatron 融合内核构建命令中的nvcc替换为cucccu-bridge 提供的编译器见 Dockerfile.metaxTE 则从 Metax 的 PyPI 源安装指定版本transformer_engine${TE_VERSION}。安装 ms-swift 并注入 Metax 补丁通过sed在ms-swift/swift/__init__.py首个 import 前插入import vllm_metax.patchDockerfile.metax使 ms-swift 在导入时自动加载 vLLM-metax 的适配补丁然后uv pip install -r requirements.txt uv pip install .。安装附加依赖并收尾安装deepspeed、requirements_extra.txt 中的扩展依赖diffusers、evalscope、librosa、ms-opencompass、optimum、timm、qwen_vl_utils 等建立nvcc - cucc符号链接最后卸载 vLLM 捎带进来的flashinfer-python与cupy-cuda12x注释明确说明这是已知问题修复。/workspace/override.txt内容为setuptools77.0.3,80、flash-linear-attention、mcoplib通过UV_OVERRIDE/workspace/override.txt作为 uv 的版本覆盖约束文件参与安装用于固定 setuptools 版本区间并补充 Metax 专用包。4.2 快速构建Dockerfile.with_metax_imageDockerfile.with_metax_image 以预装好 MACA SDK、cu-bridge 与 PyTorch 2.6 的发布镜像为基础基础镜像名可看到3.10.3-maca.ai3.3.0.16-torch2.6-py310-ubuntu22.04流程显著精简环境变量与 cu-bridge 初始化设置MACA_PATH、CUCC_CMAKE_ENTRY、CUDA_PATH、CUCC_PATH等若/root/cu-bridge不存在则调用${MACA_PATH}/tools/cu-bridge/tools/pre_make初始化Dockerfile.with_metax_image。构建 vLLM 与 vLLM-metax同样执行use_existing_torch.py与VLLM_TARGET_DEVICEempty空设备构建 vLLM对 vLLM-metax 使用use_existing_metax.py后打包安装 wheel。Megatron-LM克隆指定版本并执行同样的nvcc → cucc补丁此处未执行pip install .因为发布镜像通常已内置。ms-swiftrm -rf /workspace/ms-swift后重新克隆目标版本同样插入import vllm_metax.patch补丁pip install -r requirements.txt pip install .。默认命令CMD [bash]容器启动即进入 bash。五、验证与排障要点镜像是否可用构建完成后执行docker images | grep swift确认swift:v4.0.0存在进入容器后执行source /opt/venv/bin/activate python -c import swift, vllm_metax; print(ok)方案一或直接python -c import swift, vllm_metax方案二。设备是否可见容器内执行mx-smiMetax 管理工具应能列出 MACA 计算设备若设备不可见重点检查--device/dev/mxcd、--privileged与--group-add video是否齐备。训练是否跑通cd /workspace/ms-swift bash example/train/full/train.sh应正常进入训练循环若报编译类错误多半是 cu-bridge 的cucc路径或CUCC_CMAKE_ENTRY未生效可检查which cucc与echo $CUCC_PATH。版本一致性镜像标签建议与SWIFT_VERSION、MACA_VERSION保持一致如swift:v4.0.0多版本目录4.0/4.1/4.2/4.4并存时可分别打不同 tag避免覆盖。六、仓库相关资源索引构建与运行指南docker/Metax/4.0/swift_building_instructions.md完整构建 Dockerfiledocker/Metax/4.0/Dockerfile.metax快速构建 Dockerfiledocker/Metax/4.0/Dockerfile.with_metax_image构建脚本docker/Metax/4.0/build.sh、docker/Metax/4.0/build_from_metax_image.sh附加依赖与版本覆盖docker/Metax/4.0/requirements_extra.txt、docker/Metax/4.0/override.txt其余版本目录docker/Metax/4.1/、docker/Metax/4.2/、docker/Metax/4.4/结构一致参数随版本变化说明文档中出现的example/train/full/train.sh为 ms-swift 仓库内的脚本位于构建阶段克隆的/workspace/ms-swift中不随本仓库ModelScope分发。【免费下载链接】modelscopeModelScope: bring the notion of Model-as-a-Service to life.项目地址: https://gitcode.com/GitHub_Trending/mo/modelscope创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考