ModelScope 生态实践：在 Metax（MACA）GPU 上构建 Swift 4.x 训练镜像全指南

ModelScope 生态实践在 MetaxMACAGPU 上构建 Swift 4.x 训练镜像全指南【免费下载链接】modelscopeModelScope: bring the notion of Model-as-a-Service to life.项目地址: https://gitcode.com/GitHub_Trending/mo/modelscope导读本文基于 docker/Metax/4.4/swift_building_instructions.md 展开讲解如何在国产 Metax沐曦 MACAGPU 环境下为 ModelScope 生态中的 LLM 训练框架 ms-swift 构建可运行的 Docker 镜像并完成容器启动、虚拟环境激活与训练示例执行的完整流程。读完本文你将掌握两种构建路径从 UBI9 最小基础镜像全量编译、基于 Metax 官方发布镜像快速继承的差异、关键构建参数、容器运行参数含义以及构建背后的 vLLM-metax / cu-bridge / Megatron 适配原理可直接照搬到实际部署场景。版本说明文档标题写作 swift 4.2 image但其所处目录为docker/Metax/4.4配套构建脚本实际使用SWIFT_VERSIONv4.4.0并打镜像标签swift:v4.4.0本文以仓库实际脚本为准可对照 build.sh 与 build_from_metax_image.sh。一、背景为什么需要在 Metax GPU 上构建 Swift 镜像ms-swiftgithub.com/modelscope/ms-swift对应 ModelScope 生态的 Swift 框架是面向大模型微调与推理的开源工具链其训练后端依赖 vLLM、Megatron-LM、Transformer Engine 等组件。这些组件默认面向 NVIDIA CUDA 生态开发而 Metax 加速卡使用自研 MACAMetaX Compute Architecture软件栈运行时需要通过cu-bridgeCUDA 转译桥将 CUDA 调用映射到 MACA并使用vLLM-metaxMetaX 维护的 vLLM 分支作为推理/服务后端。因此在 ModelScope 仓库的docker/Metax/目录下4.0/4.1/4.2/4.4 各版本目录结构一致存放了一套完整的 Swift 镜像构建方案核心文件为文件作用swift_building_instructions.md构建、运行、激活环境、跑示例的说明文档本文主体Dockerfile.metax全量构建从 UBI9 最小镜像开始用 venv 虚拟环境逐层编译Dockerfile.with_metax_image快速构建继承 Metax 预发布镜像省略 vLLM/vLLM-metax 编译build.sh全量构建入口脚本封装 docker build 与全部 build-argbuild_from_metax_image.sh快速构建入口脚本override.txtuv 依赖版本覆盖规则pinningrequirements_extra.txtSwift 运行期可选依赖清单二、两种构建路径总览原文档给出了两条并行路径适用场景不同从 UBI9 基础镜像全量构建bash build.sh。以红帽 UBI9Universal Base Image为底座通过 venv 虚拟环境逐步骤编译 cu-bridge、vLLM、vLLM-metax、Megatron-LM 并安装 ms-swift。链路完整、可控性强但耗时长、需要网络下载大量依赖与源码。从 Metax 发布镜像快速构建bash build_from_metax_image.sh。以 Metax 官方已构建好的 vllm-metax 镜像为底座内含 Python/Torch/Transformer Engine只补充 Megatron-LM 与 ms-swift构建速度显著更快。其 Dockerfile 注释明确说明This fast-build path inherits Python/Torch/TE from a prebuilt Metax release image同时提示该路径可能滞后于 Megatron-SWIFT Quick Start 的推荐版本。两条路径殊途同归最终镜像内都包含可运行的 ms-swift并统一在/workspace/ms-swift下执行示例训练脚本examples/train/full/train.sh。三、路径一从 UBI9 基础镜像全量构建3.1 构建命令bash build.sh3.2 构建参数与版本钉扎build.sh 实际执行的 docker build 命令为docker build \ --network host \ -f Dockerfile.metax \ -t swift:v4.4.0 \ --build-arg PYTHON_VERSION3.12 \ --build-arg VLLM_VERSIONv0.22.0 \ --build-arg VLLM_METAX_VERSIONv0.22.0 \ --build-arg MACA_VERSION3.8.0 \ --build-arg MEGATRON_VERSIONcore_v0.16.0 \ --build-arg SWIFT_VERSIONv4.4.0 \ --build-arg TE_VERSION2.13.0 \ --build-arg CU_BRIDGE_VERSION3.8.0 \ .各构建参数含义与默认值对照 Dockerfile.metax 的 ARG 声明参数4.4 目录下取值说明BUILD_BASE_IMAGEregistry.access.redhat.com/ubi9/ubi:9.6UBI9 最小基础镜像PYTHON_VERSION3.12venv 虚拟环境使用的 Python 版本UV_EXTRA_INDEX_URLhttps://repos.metax-tech.com/r/maca-pypi/simple额外的 pip 源用于拉取 MACA 定制包UV_TRUSTED_HOSTrepos.metax-tech.com信任的下载主机VLLM_VERSIONv0.22.0上游 vllm-project/vllm 版本VLLM_METAX_VERSIONv0.22.0MetaX-MACA/vLLM-metax 分支版本MACA_VERSION3.8.0MACA SDK / Metax 驱动版本MEGATRON_VERSIONcore_v0.16.0NVIDIA Megatron-LM 版本SWIFT_VERSIONv4.4.0ms-swift 版本决定最终镜像内容TE_VERSION2.13.0Transformer Engine 版本CU_BRIDGE_VERSION3.8.0cu-bridge 转译桥版本默认继承 MACA_VERSION值得注意CU_BRIDGE_VERSION${MACA_VERSION}是 Dockerfile 中的默认关联即不显式传入时 cu-bridge 与 MACA SDK 版本保持一致保证转译层与驱动/SDK 匹配。3.3 全量构建的九个核心步骤阅读 Dockerfile.metax 可以看出全量构建按 9 个 RUN 步骤组织逐层完成从操作系统到训练框架的适配Step 0环境准备与依赖仓库写入两个 yum 源metax-driver-centos驱动含 vbios/kmd容器内实际只需要mx-smi管理工具内核版本不匹配错误会被忽略与maca-sdk-rpmSDK 包。安装基础工具链python3-pip hostname unzip vim git openblas-devel make cmake ninja-build gcc g procps-ng libibverbs librdmacm libibumad binutils numactl-libs以及metax-driver-${MACA_VERSION}* mxgvm maca_sdk-${MACA_VERSION}* mctlass_* mctlassEx_*。安装uv超高速 Python 包管理器并创建/opt/venv虚拟环境uv venv /opt/venv --python${PYTHON_VERSION}。按版本克隆四个源码仓库到/workspacems-swift、vLLM-metax、vllm、Megatron-LM均使用--depth 1 --branch浅克隆指定分支。Step 1安装 MACA SDK、Metax 驱动与 cu-bridge从 gitee 下载 cu-bridge 源码压缩包并解压为cu-bridge随后cmake -DCMAKE_INSTALL_PREFIX/opt/maca/tools/cu-bridge编译安装。cu-bridge 是打通 CUDA 生态与 MACA 的关键转译层。Step 2~3安装 vLLM-metax 构建依赖与 MACA Python 依赖在vLLM-metax目录下uv pip install -r requirements/build.txt与requirements/maca.txt后者设置了UV_HTTP_TIMEOUT960以应对大体积包下载。Step 4以 empty device 模式构建上游 vLLM关键技巧VLLM_TARGET_DEVICEempty让 vLLM 在不依赖 CUDA 设备的情况下完成编译python3 use_existing_torch.py复用既有 torchuv pip install -v . --no-build-isolation关闭隔离编译。Step 5构建并安装 vLLM-metaxpython3 -m build -w -n生成 wheel 后uv pip install dist/*.whl安装 MetaX 定制版 vLLM。Step 6安装 Megatron-LM若存在megatron/legacy/fused_kernels/__init__.py先用sed -i s/nvcc/cucc/g将 CUDA 编译器调用替换为 MACA 的cucc再uv pip install .。Step 7安装 Transformer Engine只有当TE_VERSION非空时才执行Dockerfile 注释特别说明当前不存在兼容 torch 2.10 的 transformer_engine PyPI 包因此必须降级 torch 到 2.8安装torch2.8 torchvision0.15.1 flash_attn2.6.3metax... mctlassEx... triton3.0.0metax...再装transformer_engine${TE_VERSION}。Step 8patch 并安装 ms-swift通过一行 sed 在ms-swift/swift/__init__.py的首个 import 之前插入import vllm_metax.patch让 Swift 在加载时自动应用 vLLM-metax 的补丁随后uv pip install .[megatron]安装带 Megatron 扩展依赖的 Swift。Step 9安装可选运行依赖并收尾uv pip install deepspeed从 MACA pip 源获取定制版安装requirements_extra.txt中的依赖ln -sf ${CUDA_PATH}/bin/nvcc ${CUDA_PATH}/bin/cucc建立编译器符号链接卸载 vLLM 安装过程带入的不兼容 CUDA-only wheelflashinfer-python与cupy-cuda12x。3.4 依赖版本覆盖与可选依赖override.txt 通过UV_OVERRIDE/workspace/override.txt环境变量注入 uv强制钉住关键依赖版本避免与 MACA 定制包冲突setuptools77.0.3,80 datasets3.0,4.0 transformers5.4.0 numpy1.26.4 scipy1.16.2requirements_extra.txt 提供 Swift 运行期可选依赖多模态、评测、音频视频处理等场景decord、diffusers0.35.2、evalscope1.0.0含[opencompass]/[vlmeval]扩展、keye_vl_utils、librosa、mpi4py、optimum1.27.0、pytorchvideo、qwen_omni_utils、qwen_vl_utils0.0.14、soundfile、timm。四、路径二从 Metax 发布镜像快速构建4.1 构建命令bash build_from_metax_image.sh4.2 继承的基础镜像与构建参数build_from_metax_image.sh 对应命令为docker build \ --network host \ -f Dockerfile.with_metax_image \ -t swift:v4.4.0-with-metax-base \ --build-arg VLLM_VERSIONv0.22.0 \ --build-arg VLLM_METAX_VERSIONv0.22.0 \ --build-arg MEGATRON_VERSIONcore_v0.16.0 \ --build-arg SWIFT_VERSIONv4.4.0 \ --build-arg TE_VERSION2.13.0 \ .Dockerfile.with_metax_image 的默认基础镜像为mx-devops-acr-cn-shanghai.cr.volces.com/opensource/public-ai-release/maca/vllm-metax:0.22.0-maca.ai3.8.0.5-torch2.10-py312-ubuntu22.04-amd64即一个已经包含 vLLM-metax、Python 3.12、torch 2.10 的 Ubuntu 22.04 镜像Dockerfile 注释强调保留经过验证的基础镜像 tag 而非猜测更新版本因此本路径会跳过 vLLM 与 vLLM-metax 的源码编译相关 RUN 步骤被注释掉仅克隆ms-swift与Megatron-LM。4.3 快速路径的构建差异与全量路径相比快速路径有几处关键差异Python 环境使用基础镜像自带的/opt/conda环境PATH前缀为/opt/conda/bin而非新建 venvcu-bridge 初始化若基础镜像中不存在/root/cu-bridge则调用${MACA_PATH}/tools/cu-bridge/tools/pre_make预初始化而不是重新 cmake 编译TE 安装同样因 torch 2.10 无兼容 TE 包降级安装torch2.8等版本后再装transformer_engine${TE_VERSION}并额外--force-reinstall安装apex0.1与deep_ep1.0.0Swift 安装先pip install transformers5.4.0约束版本再pip install .[megatron]与-r /workspace/requirements_extra.txt收尾pip uninstall torchao -y移除不兼容组件CMD [bash]作为默认入口。五、启动容器Docker 运行参数详解两条路径构建完成后原文档给出了相同的容器启动命令${IMAGE_ID}替换为镜像 ID例如swift:v4.4.0或swift:v4.4.0-with-metax-basedocker 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各参数在 Metax GPU 场景下的作用参数作用-d -it后台运行并保持交互终端便于后续进入容器--nethost --utshost --ipchost共享宿主网络 / UTS / IPC 命名空间满足分布式训练NCCL 类通信对网络与进程间通信的要求--privilegedtrue赋予容器特权使其可访问 GPU 设备与内核相关资源--group-add video将容器加入 video 用户组获得显卡设备访问权限--shm-size 100gb扩大/dev/shm共享内存至 100GB避免数据加载器/分布式通信因共享内存不足崩溃--ulimit memlock-1取消内存锁定上限供 GPU 驱动与显存映射使用--security-opt seccompunconfined --security-opt apparmorunconfined关闭 seccomp 与 AppArmor 安全限制避免拦截 GPU 设备访问--device/dev/dri挂载 DRM 渲染设备GPU 显示/渲染节点--device/dev/mxcd挂载 Metax 加速卡控制设备节点--name base_image为容器命名六、激活虚拟环境仅全量构建路径UBI9 venv需要此步骤。容器启动后激活 Swift 所在的 Python 虚拟环境source /opt/venv/bin/activate激活后python/pip/uv均指向/opt/venv与Dockerfile.metax中VIRTUAL_ENV/opt/venv、PATH/opt/venv/bin:/root/.local/bin:$PATH的环境变量声明一致。快速构建路径直接使用基础镜像的 conda 环境无需手动激活。七、运行 Swift 训练示例验证镜像无论哪条路径验证镜像是否构建成功的标准动作都是执行 Swift 的完整训练示例cd /workspace/ms-swift bash examples/train/full/train.shcd /workspace/ms-swift进入构建阶段克隆的 Swift 源码目录全量路径 venv 激活后、快速路径直接执行examples/train/full/train.sh是 Swift 提供的全参数微调Full Fine-tuning示例脚本会启动一个完整训练任务。若训练流程正常拉起并输出 loss 下降日志即表明 cu-bridge 转译、vLLM-metax 后端、Megatron/TE 依赖与 Swift 本身在 Metax GPU 上协同工作正常。该示例脚本实际内容位于外部 ms-swift 仓库构建时按SWIFT_VERSION克隆不在本仓库目录内需要自定义训练时可参照脚本结构替换模型名、数据集与超参数。八、构建链路要点回顾与排障提示版本一致性是硬约束CU_BRIDGE_VERSION默认等于MACA_VERSION而 cu-bridge 必须与 MACA SDK/驱动版本匹配否则运行时转译失败torch 版本回退当前 transformer_engine 没有兼容 torch 2.10 的 PyPI 包两条路径都执行了 torch 2.10 → 2.8 的降级安装见 Dockerfile.metax Step 7 与 Dockerfile.with_metax_image Step 5编译器替换Megatron 遗留的 fused kernels 通过sed s/nvcc/cucc/g与ln -sf nvcc cucc符号链接把 CUDA 编译器调用映射到 MACA 工具链Swift 自动 patchswift/__init__.py顶部被插入import vllm_metax.patch这是 Swift 与 vLLM-metax 对接的实现细节清理 CUDA-only 依赖构建收尾必须卸载flashinfer-python、cupy-cuda12x以及快速路径的torchao否则会污染 MACA 环境网络要求两条路径的构建脚本都使用--network host且构建过程需要访问 GitHub克隆四个仓库、giteecu-bridge 源码、Metax 仓库repos.metax-tech.com与阿里云 PyPI 镜像需保证这些源可达。九、延伸各版本目录的对应关系本仓库docker/Metax/下 4.0 / 4.1 / 4.2 / 4.4 四个目录结构一致均含Dockerfile.metax、Dockerfile.with_metax_image、两个 build 脚本与两个依赖清单分别对应不同 Swift 版本线的镜像构建方案。例如 build.sh 使用SWIFT_VERSIONv4.0.0、VLLM_VERSIONv0.11.2、MEGATRON_VERSIONcore_v0.15.0而 4.4 目录使用v4.4.0/v0.22.0/core_v0.16.0。部署时请根据实际需要的 Swift 版本选择对应目录并优先参考该目录下文档与脚本中锁定的版本组合避免跨目录混用导致依赖不兼容。【免费下载链接】modelscopeModelScope: bring the notion of Model-as-a-Service to life.项目地址: https://gitcode.com/GitHub_Trending/mo/modelscope创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考