ms-swift 安装指南从 Wheel 包、源码到官方镜像的全链路部署与环境配置【免费下载链接】swiftUse PEFT or Full-parameter to CPT/SFT/DPO/GRPO 600 LLMs (Qwen3.6, DeepSeek-V4, GLM-5.1, InternLM3, Llama4, ...) and 300 MLLMs (Qwen3-VL, Qwen3-Omni, InternVL3.5, Ovis2.5, GLM4.5v, Gemma4, Llava, Phi4, ...) (AAAI 2025).项目地址: https://gitcode.com/GitHub_Trending/swift1/swiftms-swiftSwift: Scalable lightWeight Infrastructure for Fine-Tuning是 ModelScope 社区提供的 LLM/MLLM 微调与部署框架覆盖预训练、SFT、DPO/GRPO 等对齐训练、推理、评测、量化与部署全流程。本文基于仓库官方文档 SWIFT-installation.md 与安装相关源码setup.py、requirements 系列文件完整讲解 ms-swift 的三种安装方式、可选依赖extras的底层映射、官方 Docker 镜像体系、支持硬件与运行环境版本约束帮助你在 GPU/NPU/CPU 环境下正确搭建训练与推理环境。一、Wheel 包安装与 extras 可选依赖1.1 基础安装命令官方文档推荐通过 pip 直接安装# 推荐方式 pip install ms-swift -U # 附加 Megatron 分布式训练依赖 pip install ms-swift[megatron] -U # 附加评测依赖 pip install ms-swift[eval] -U # 完整能力 pip install ms-swift[all] -U # 使用 uv 安装自动处理 torch 后端 pip install uv uv pip install ms-swift --torch-backendauto如果使用uv--torch-backendauto参数会让 uv 根据当前平台Linux CUDA、macOS MPS、纯 CPU 等自动选择对应的 PyTorch wheel 后端避免手动对齐 torch 索引源。1.2 extras 与依赖文件的源码级映射文档中列出的[megatron]、[eval]、[all]等可选安装项其真实内容在 setup.py 中定义install_requires解析自 requirements.txt其内容为一行-r requirements/framework.txt即核心框架依赖全部来自 requirements/framework.txtextra_requires[megatron]来自 requirements/megatron.txtextra_requires[eval]来自 requirements/eval.txt此外还定义了swanlab来自 requirements/swanlab.txt与ray来自 requirements/ray.txt两个 extrasextra_requires[all]由基础依赖 evalswanlabray合并而成。这里有一个值得注意的实现细节[all]并不包含megatron的依赖megatron.txt未被合入all_requires。也就是说如果你既要 Megatron 分布式训练、又要评测/Ray 能力需要同时执行pip install ms-swift[all] ms-swift[megatron] -U各 extras 的具体依赖如下extras依赖文件核心依赖基础安装requirements/framework.txttransformers4.33,5.17.0、peft0.11,0.21、datasets3.0,4.8.5、modelscope1.23、trl0.15,1.0等 38 项[megatron]requirements/megatron.txtmcore-bridge1.6.3、megatron-core0.16、peft0.15[eval]requirements/eval.txtevalscope1.0.0、evalscope[opencompass]、evalscope[vlmeval][swanlab]requirements/swanlab.txtswanlab[ray]requirements/ray.txtray[all]上述除 megatron 之外的合集基础依赖 evalscope swanlab ray1.3 安装后可用的命令行入口从 setup.py 的entry_points可以看到安装完成后注册了两个 console 命令swift对应 swift/cli/main.py 的cli_main覆盖swift sft、swift infer、swift rlhf、swift deploy等子命令megatron对应 swift/cli/_megatron/main.py 的cli_main用于 Megatron 并行训练入口。另外注册了vllm.general_plugins钩子swift.model.models.qwen:register_uembed_model用于在 vLLM 侧扩展 Qwen 模型的 uembed 能力。安装成功的快速验证方式swift --help megatron --help二、源码安装swift 4.x 与 3.x2.1 主分支swift 4.x当前仓库 main 分支面向 swift 4.x 版本swift/version.py 中版本号定义为4.6.0.dev0开发中版本。从源码安装# 或直接以 git 依赖安装 # pip install githttps://github.com/modelscope/ms-swift.git # 完整能力 # pip install ms-swift[all]githttps://github.com/modelscope/ms-swift.git git clone https://github.com/modelscope/ms-swift.git cd ms-swift pip install -e . # 完整能力 # pip install -e .[all]可编辑安装pip install -e .适合需要阅读源码、调试框架内部逻辑的场景。setup.py 中package_data声明了utils/*、dataset/data/*.*、config/*.json、loss_scale/config/*.json会随包分发因此即使不做可编辑安装内置数据集注册信息swift/dataset/data与 DeepSpeed 配置swift/config也能正常加载。2.2 安装 swift 3.x如果你需要停留在 swift 3.x 版本线例如复现已有的 3.x 训练流程需切换到release/3.12分支# pip install githttps://github.com/modelscope/ms-swift.gitrelease/3.12 # 完整能力 # pip install ms-swift[all]githttps://github.com/modelscope/ms-swift.gitrelease/3.12 git clone -b release/3.12 https://github.com/modelscope/ms-swift.git cd ms-swift pip install -e . # 使用 uv uv pip install -e . --torch-backendauto # 完整能力 # pip install -e .[all]版本选择建议新项目直接跟随 main 分支4.x已有基于 3.x 的脚本尤其是 GRPO、Megatron 相关脚本在不同大版本间参数名可能不一致则固定使用release/3.12。三、全量环境一键安装脚本对于需要同时具备训练、推理加速、量化、Web-UI、Megatron 全量能力的场景仓库提供了 requirements/install_all.sh其头部注释明确要求python3.10/3.11、cuda12.*环境# please use python3.10/3.11, cuda12.* # sh requirements/install_all.sh脚本关键步骤及作用pip install vllm0.5.1 -U # 固定核心版本上限防止 transformers/trl/peft/datasets 大版本破坏兼容性 pip install transformers5.17 trl1.0 peft0.21 datasets4.8.5 -U pip install optimum bitsandbytes gradio5.33 mcore-bridge -U pip install ms-swift[all]githttps://github.com/modelscope/ms-swift.git pip install timm deepspeed0.19 ray -U pip install qwen_vl_utils qwen_omni_utils keye_vl_utils -U pip install decord librosa icecream soundfile -U pip install pybind11 liger_kernel nvitop pre-commit math_verify py-spy wandb swanlab -U pip install flash-attn2.8.3 --no-build-isolation脚本后半部分为 Megatron 专用依赖需要编译故全部加--no-build-isolationTransformerEnginestable 分支、DeepGEMMv2.1.1.post3、flash-linear-attention、causal-conv1d、fast-hadamard-transform、Emerging-Optimizersv0.3.0用于 Muon 等优化器最后还预留了 apex 安装注释。从该脚本可以确认几个版本约束deepspeed0.19、gradio5.33、flash-attn2.8.3与官方文档环境表中的推荐值deepspeed 0.18.9、gradio 5.32.1、flash_attn 2.8.3相互印证。四、官方 Docker 镜像镜像仓库官方文档提供了预置完整运行环境的 Docker 镜像镜像 tag 遵循统一命名规范modelscope-registry.region.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda版本-pypython版本-torch版本-vllm版本-modelscope版本-swift版本当前推荐的最新镜像swift 4.5.3# swift4.5.3 modelscope-registry.cn-hangzhou.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda13.0.3-py312-torch2.13.0-vllm0.28.0-modelscope1.40.0-swift4.5.3 modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda13.0.3-py312-torch2.13.0-vllm0.28.0-modelscope1.40.0-swift4.5.3 modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda13.0.3-py312-torch2.13.0-vllm0.28.0-modelscope1.40.0-swift4.5.3近期几个版本及其预置技术栈从镜像 tag 直接可读出swift 版本CUDAPythontorchvLLMModelScope4.5.313.0.33.122.13.00.28.01.40.04.4.313.0.33.122.11.00.25.11.39.04.4.113.0.33.122.11.00.23.01.38.14.3.213.0.33.122.11.00.23.01.37.14.2.313.0.33.122.11.00.21.01.36.34.1.312.9.13.122.10.00.19.11.35.44.0.312.8.13.112.10.00.17.11.34.0历史镜像swift 3.12.5 至 3.2.2在官方文档的折叠区块中完整列出覆盖 CUDA 12.4.0 ~ 12.9.1、Python 3.10/3.11 的多种组合。镜像在cn-hangzhou、cn-beijing、us-west-1三个区域仓库同步提供可按所在地就近拉取使用镜像可完全跳过手动安装 torch/vLLM 等重依赖的步骤适合快速进入 Quick-start 的训练/推理流程。五、支持硬件官方文档给出的硬件支持矩阵硬件环境备注A10 / A100 / H100完整支持RTX 20 / 30 / 40 系列完整支持T4 / V100部分模型可能遇到 NaNAscend NPU部分模型可能遇到 NaN 或不支持的操作符MPS已知限制参见社区 issue #4572CPU支持对 T4/V100 这类计算能力较低的卡遇到 NaN 时可优先考虑降低精度敏感度如避免 FP16 下的敏感算子或升级至 A 系列显卡Ascend NPU 的支持细节可参考仓库 NPU-support.md 与 AMD-support.md 等最佳实践文档。六、运行环境版本约束官方文档给出的环境版本表组件版本范围推荐版本说明python3.103.12cudacuda12.8/13.0CPU/NPU/MPS 环境无需安装torch2.02.8.0/2.11.0transformers4.334.57.6/5.12.1modelscope1.23datasets3.0,4.8.53.6.0/4.8.4peft0.11,0.20flash_attn2.8.3/4.0.0b15trl0.15,1.00.29.1RLHF 训练deepspeed0.140.18.9训练vllm0.5.10.11.0/0.23.0推理/部署sglang0.4.6推理/部署evalscope1.0评测gradio5.32.1Web-UI/App结合源码可以进一步确认实际生效的硬约束以 requirements/framework.txt 为准transformers4.33,5.17.0、peft0.11,0.21、datasets3.0,4.8.5、trl0.15,1.0、modelscope1.23。其中 peft 的上限在源码中为0.21比文档表格中的0.20略宽实际安装时以框架依赖声明为准。install_all.sh 中transformers5.17、datasets4.8.5的上限与框架依赖一致说明大版本升级尤其 transformers 5.x 的 5.17 之后在验证完成前是被有意拦截的。另外 setup.py 声明python_requires3.8.0即包层面允许 Python 3.8但官方环境表要求 3.10推荐 3.12实际部署应以后者为准。可选依赖清单vLLM、sglang、liger_kernel、swanlab 等的完整说明见 install_all.sh。七、Notebook 免费 GPU 环境对于没有本地 GPU 的用户官方文档给出了基于 ModelScope 平台免费 A10 GPU 的快速上手路径Swift 支持训练的大多数模型可在单卡 A10 上运行访问 ModelScope 官网并登录点击左侧My Notebook启动一个免费 GPU 实例在实例中按本文第一节命令安装 ms-swift或拉取官方 Docker 镜像即可使用 A10 进行训练与推理实验。小结ms-swift 的安装路径可归纳为四条①pip install ms-swift -U完成基础安装② 按需追加[megatron]/[eval]/[all]extras注意[all]不含 megatron 依赖③ 源码安装时区分 main 分支4.x与release/3.123.x④ 使用官方 Docker 镜像获得与文档环境表严格对齐的预置技术栈。版本约束transformers、peft、datasets、deepspeed 等上限在 requirements/framework.txt 与 install_all.sh 中有明确声明升级第三方依赖前建议先核对这两处以保证训练脚本的可复现性。【免费下载链接】swiftUse PEFT or Full-parameter to CPT/SFT/DPO/GRPO 600 LLMs (Qwen3.6, DeepSeek-V4, GLM-5.1, InternLM3, Llama4, ...) and 300 MLLMs (Qwen3-VL, Qwen3-Omni, InternVL3.5, Ovis2.5, GLM4.5v, Gemma4, Llava, Phi4, ...) (AAAI 2025).项目地址: https://gitcode.com/GitHub_Trending/swift1/swift创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
