尧图网页设计 
SWIFTms-swift安装完全指南pip / 源码 / Docker 三种方式与运行环境配置详解【免费下载链接】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/swiftSWIFT 是模型即服务的可扩展轻量级微调基础设施Scalable lightWeight Infrastructure for Fine-Tuning当前仓库已支持 600 纯文本大模型与 300 多模态大模型Qwen、DeepSeek、GLM、InternLM、Llama 等的预训练、微调、RLHF/GRPO 强化学习、推理、评测与部署。本文以仓库内 SWIFT-installation.md 为骨架系统讲解 SWIFT 的 Wheel 包安装、源码安装、Docker 镜像三种方式并深入解读支持的硬件矩阵、运行环境版本约束、可选依赖构成与免费 Notebook 环境帮助你在 NVIDIA GPU、Ascend NPU、MPS 或 CPU 上快速搭建起可用环境并理解每一步背后的依赖实现。安装方式总览SWIFT 官方提供三种主流安装路径适用于不同的使用场景安装方式适用场景特点Wheel 包安装pip绝大多数用户、快速上手一键安装、自动解析依赖推荐方式源码安装git pip -e开发者、需要跟进最新特性或二次开发可修改源码即时生效与 main 分支同步Docker 镜像团队统一环境、生产部署、多机复现环境即代码版本完全锁定其中 Wheel 包与源码安装均支持按需选择全能力或专项能力依赖集Docker 镜像则按 SWIFT 版本 CUDA PyTorch vLLM 的组合预先构建开箱即用。方式一Wheel 包安装推荐使用 pip 即可完成安装安装包名为ms-swift-U表示升级到最新版本# 推荐 pip install ms-swift -U # 额外安装 Megatron 依赖 pip install ms-swift[megatron] -U # 额外安装评测依赖 pip install ms-swift[eval] -U # 全能力 pip install ms-swift[all] -Uextras 依赖集背后setup.py 如何组织从源码 setup.py 可以确认ms-swift的依赖分为基础依赖与可选 extras两层基础依赖解析自requirements.txt实际内容为-r requirements/framework.txt即 requirements/framework.txt包含transformers4.33,5.17.0、datasets3.0,4.8.5、peft0.11,0.21、trl0.15,1.0、modelscope1.23、deepspeed、accelerate、einops、sentencepiece、tiktoken等训练与推理必需组件。可选 extras见 setup.pymegatron解析 requirements/megatron.txt包含mcore-bridge1.6.3、megatron-core0.16、peft0.15用于 TP/PP/CP/EP 等 Megatron 并行训练eval解析 requirements/eval.txt包含evalscope1.0.0及evalscope[opencompass]、evalscope[vlmeval]用于模型评测swanlab解析 requirements/swanlab.txt提供 SwanLab 实验可视化ray解析 requirements/ray.txt提供 Ray 分布式调度支持all由install_requires eval swanlab ray拼合而成不包含 megatron即全能力安装。因此只需 SFT/推理pip install ms-swift即可需要 Megatron 大规模并行训练追加[megatron]需要 EvalScope 评测追加[eval]想一步到位直接pip install ms-swift[all] -U。使用 uv 安装uv 是更快的 Python 包管理器SWIFT 同样支持pip install uv uv pip install ms-swift --torch-backendauto--torch-backendauto会让 uv 根据当前 CUDA 环境自动选择对应的 PyTorch 构建版本简化了手动匹配 torch/CUDA 版本的过程。方式二源代码安装源码安装适合两类用户想第一时间体验 main 分支新特性的用户以及需要对 SWIFT 源码进行二次开发的用户pip install -e .为可编辑安装修改源码后无需重装即生效。安装 swift4.x当前 main 分支当前仓库main分支对应 swift4.x 版本swift/version.py 中__version__ 4.6.0.dev0也印证了这一点dev0表示开发版正式发布时才会更新为稳定版本号。# 从 git 直接安装等价于下面 clone 后 install # pip install githttps://github.com/modelscope/ms-swift.git # 全能力 # pip install ms-swift[all]githttps://github.com/modelscope/ms-swift.git # 推荐clone 到本地后以可编辑模式安装 git clone https://github.com/modelscope/ms-swift.git cd ms-swift pip install -e . # 使用 uv uv pip install -e . --torch-backendauto # 全能力 # pip install -e .[all]安装 swift3.x历史稳定分支如果需要使用 swift3.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 . # 全能力 # pip install -e .[all]提示3.x 与 4.x 在命令行参数、训练流程上有差异切换分支前请先阅读对应版本的 快速开始 与 命令行参数说明。方式三Docker 镜像对于需要统一团队环境、保证复现性、或避免本地依赖冲突的场景官方提供了预构建 Docker 镜像镜像命名直接体现了内部的软件栈版本组合。镜像命名规范解读以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为例tag 依次为系统版本-CUDA版本-Python版本-PyTorch版本-vLLM版本-ModelScope版本-SWIFT版本即Ubuntu 22.04 CUDA 13.0.3 Python 3.12 torch 2.13.0 vllm 0.28.0 modelscope 1.40.0 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 # swift4.4.3 modelscope-registry.cn-hangzhou.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda13.0.3-py312-torch2.11.0-vllm0.25.1-modelscope1.39.0-swift4.4.3 modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda13.0.3-py312-torch2.11.0-vllm0.25.1-modelscope1.39.0-swift4.4.3 modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda13.0.3-py312-torch2.11.0-vllm0.25.1-modelscope1.39.0-swift4.4.3 # swift4.4.1 modelscope-registry.cn-hangzhou.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda13.0.3-py312-torch2.11.0-vllm0.23.0-modelscope1.38.1-swift4.4.1 modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda13.0.3-py312-torch2.11.0-vllm0.23.0-modelscope1.38.1-swift4.4.1 modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda13.0.3-py312-torch2.11.0-vllm0.23.0-modelscope1.38.1-swift4.4.1 # swift4.3.2 modelscope-registry.cn-hangzhou.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda13.0.3-py312-torch2.11.0-vllm0.23.0-modelscope1.37.1-swift4.3.2 modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda13.0.3-py312-torch2.11.0-vllm0.23.0-modelscope1.37.1-swift4.3.2 modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda13.0.3-py312-torch2.11.0-vllm0.23.0-modelscope1.37.1-swift4.3.2每个版本均提供杭州cn-hangzhou、北京cn-beijing、美西us-west-1三个地域的仓库地址国内用户建议优先使用 cn-hangzhou / cn-beijing 以加快拉取速度。历史镜像swift4.x 早期版本与 swift3.x# swift4.2.3 modelscope-registry.cn-hangzhou.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda13.0.3-py312-torch2.11.0-vllm0.21.0-modelscope1.36.3-swift4.2.3 modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda13.0.3-py312-torch2.11.0-vllm0.21.0-modelscope1.36.3-swift4.2.3 modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda13.0.3-py312-torch2.11.0-vllm0.21.0-modelscope1.36.3-swift4.2.3 # swift4.1.3 modelscope-registry.cn-hangzhou.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.9.1-py312-torch2.10.0-vllm0.19.1-modelscope1.35.4-swift4.1.3 modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.9.1-py312-torch2.10.0-vllm0.19.1-modelscope1.35.4-swift4.1.3 modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.9.1-py312-torch2.10.0-vllm0.19.1-modelscope1.35.4-swift4.1.3 # swift4.0.3 modelscope-registry.cn-hangzhou.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.8.1-py311-torch2.10.0-vllm0.17.1-modelscope1.34.0-swift4.0.3 modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.8.1-py311-torch2.10.0-vllm0.17.1-modelscope1.34.0-swift4.0.3 modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.8.1-py311-torch2.10.0-vllm0.17.1-modelscope1.34.0-swift4.0.3 # swift3.12.5 modelscope-registry.cn-hangzhou.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.8.1-py311-torch2.9.0-vllm0.13.0-modelscope1.33.0-swift3.12.5 modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.8.1-py311-torch2.9.0-vllm0.13.0-modelscope1.33.0-swift3.12.5 modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.8.1-py311-torch2.9.0-vllm0.13.0-modelscope1.33.0-swift3.12.5 # swift3.11.3 modelscope-registry.cn-hangzhou.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.9.1-py311-torch2.8.0-vllm0.11.0-modelscope1.32.0-swift3.11.3 modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.9.1-py311-torch2.8.0-vllm0.11.0-modelscope1.32.0-swift3.11.3 modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.9.1-py311-torch2.8.0-vllm0.11.0-modelscope1.32.0-swift3.11.3 # swift3.10.3 / swift3.9.3 modelscope-registry.cn-hangzhou.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.8.1-py311-torch2.8.0-vllm0.11.0-modelscope1.31.0-swift3.10.3 modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.8.1-py311-torch2.8.0-vllm0.11.0-modelscope1.31.0-swift3.10.3 modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.8.1-py311-torch2.8.0-vllm0.11.0-modelscope1.31.0-swift3.10.3 # swift3.8.3 modelscope-registry.cn-hangzhou.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.6.3-py311-torch2.7.1-vllm0.10.1.1-modelscope1.29.2-swift3.8.3 modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.6.3-py311-torch2.7.1-vllm0.10.1.1-modelscope1.29.2-swift3.8.3 modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.6.3-py311-torch2.7.1-vllm0.10.1.1-modelscope1.29.2-swift3.8.3 # swift3.7.2 modelscope-registry.cn-hangzhou.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.6.3-py311-torch2.7.1-vllm0.10.0-modelscope1.28.2-swift3.7.2 modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.6.3-py311-torch2.7.1-vllm0.10.0-modelscope1.28.2-swift3.7.2 modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.6.3-py311-torch2.7.1-vllm0.10.0-modelscope1.28.2-swift3.7.2 # swift3.6.4 / swift3.5.3 modelscope-registry.cn-hangzhou.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.4.0-py310-torch2.6.0-vllm0.8.5.post1-modelscope1.28.1-swift3.6.4 modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.4.0-py310-torch2.6.0-vllm0.8.5.post1-modelscope1.28.1-swift3.6.4 modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.4.0-py310-torch2.6.0-vllm0.8.5.post1-modelscope1.28.1-swift3.6.4 # swift3.4.1.post1 modelscope-registry.cn-hangzhou.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.4.0-py311-torch2.6.0-vllm0.8.5.post1-modelscope1.26.0-swift3.4.1.post1 modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.4.0-py311-torch2.6.0-vllm0.8.5.post1-modelscope1.26.0-swift3.4.1.post1 modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.4.0-py311-torch2.6.0-vllm0.8.5.post1-modelscope1.26.0-swift3.4.1.post1 # swift3.3.0.post1 modelscope-registry.cn-hangzhou.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.4.0-py311-torch2.6.0-vllm0.8.3-modelscope1.25.0-swift3.3.0.post1 modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.4.0-py311-torch2.6.0-vllm0.8.3-modelscope1.25.0-swift3.3.0.post1 # swift3.2.2 modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.4.0-py311-torch2.5.1-modelscope1.25.0-swift3.2.2支持的硬件环境SWIFT 官方支持的硬件矩阵如下硬件环境备注A10/A100/H100主力训练/推理平台体验最佳RTX 20/30/40 系列消费级显卡支持 LoRA/QLoRA 等轻量微调T4/V100部分模型可能出现 NANAscend NPU部分模型可能出现 NAN 或算子不支持MPSApple 芯片M 系列具体限制参考官方 issueCPU可训练可推理速度较慢适合小模型调试几点实战提示A10/A100/H100 与 RTX 系列是官方推荐环境绝大多数模型可无障碍训练T4/V100属于较老架构部分新模型如对计算精度敏感的模型可能出现 NAN建议优先使用较新卡型或改用混合精度策略Ascend NPU使用昇腾生态官方提供了专门的 NPU 支持文档 与 Metax 支持文档部分算子可能不受支持需参考对应最佳实践排查CPU 环境无需安装 CUDA适合做数据预处理、小模型调试或 CI 验证硬件相关的安装细节可参考仓库内 requirements/npu.txt 等专项依赖文件。运行环境与版本约束SWIFT 对各基础组件有明确的版本范围与推荐值安装前请先对照下表确认环境组件支持范围推荐备注python3.103.12强烈建议 3.10/3.11/3.12cuda—12.8 / 13.0使用 CPU、NPU、MPS 则无需安装torch2.02.8.0 / 2.11.0与 CUDA 版本配套transformers4.334.57.6 / 5.12.1上限约束见 framework.txtmodelscope1.23—模型与数据集下载datasets3.0,4.8.53.6.0 / 4.8.4上限 4.8.5peft0.11,0.20—训练器与 tuner 依赖flash_attn—2.8.3 / 4.0.0b15显存与速度优化trl0.15,1.00.29.1RLHF 系列任务deepspeed0.140.18.9分布式训练vllm0.5.10.11.0 / 0.23.0推理/部署加速sglang0.4.6—推理/部署加速evalscope1.0—模型评测gradio—5.32.1Web-UI / App版本约束的源码依据这些约束并非凭空而来仓库的依赖文件是最终依据requirements/framework.txt 中写明了transformers4.33,5.17.0、datasets3.0,4.8.5、peft0.11,0.21、trl0.15,1.0、modelscope1.23等硬性约束安装时 pip 会自动解析注意文档表格中的peft 0.20与 framework.txt 中的0.21存在细微差异实际以当前仓库依赖文件0.21为准requirements/install_all.sh 给出了完整的一键环境搭建脚本其中命令pip install transformers5.17 trl1.0 peft0.21 datasets4.8.5 -U与 framework.txt 约束一致flash-attn2.8.3需要--no-build-isolation从源码编译若编译失败可尝试官方预编译 wheeldeepspeed0.19与文档推荐的 0.18.9 对应Megatron 相关依赖TransformerEngine、DeepGEMM、flash-linear-attention、causal-conv1d、fast-hadamard-transform 等同样在该脚本中给出需配合--no-build-isolation从源码安装。版本策略小结python3.10是硬性要求CUDA 12.8/13.0 为当前推荐如果使用 CPU/NPU/MPS 后端则完全不需要安装 CUDA 工具链。安装后的验证安装完成后可通过以下方式验证环境是否可用# 查看 SWIFT 版本 swift --version # 查看 CLI 子命令帮助 swift --help从源码 swift/cli/main.py 的入口路由可以看到swift命令内置了pt预训练、sft微调、rlhf人类对齐/强化学习、infer推理、deploy部署、eval评测、export导出量化、merge-lora权重合并、web-ui界面、sample数据采样等完整子命令安装成功后可立即用 快速开始 中的示例命令跑通第一个 SFT 任务CUDA_VISIBLE_DEVICES0 \ swift sft \ --model Qwen/Qwen3-4B-Instruct-2507 \ --tuner_type lora \ --dataset AI-ModelScope/alpaca-gpt4-data-zh#500 AI-ModelScope/alpaca-gpt4-data-en#500 swift/self-cognition#500小贴士模型与数据集默认通过 ModelScope 下载如需走 HuggingFace在命令中追加--use_hf true即可。Notebook 环境免费 A10 GPU 快速上手SWIFT 支持训练的绝大多数模型都可以在单张 A10 显卡上跑通配合 LoRA/QLoRA 等轻量微调技术。ModelScope 官方为注册用户提供免费的 GPU Notebook 资源具体步骤如下进入 ModelScope 官方网站并登录账号点击左侧导航栏的我的 Notebook开启一个免费 GPU 实例提供 A10 显卡在 Notebook 中执行pip install ms-swift[all] -U完成安装即可开始愉快的模型训练与调试。这套路径特别适合零成本入门无需自购显卡即可在云端体验 SWIFT 的完整训练、推理链路配合 Web-UI 文档 甚至可以不写代码完成训练全流程。常见问题与注意事项场景建议T4/V100 上训练出现 NAN属于已知现象建议换用 A10/A100/H100 或 RTX 系列必要时调整torch_dtype与梯度累积策略Ascend NPU 算子不支持参考 NPU 最佳实践 与 Metax 最佳实践MPSApple 芯片部分算子存在兼容性问题参考官方 issue 中记录的已知限制与 workaround使用 CPU/NPU/MPS无需安装 CUDA 工具链uv pip install ms-swift --torch-backendauto会自动选择 CPU 版 torch需要 Megatron 大规模并行安装ms-swift[megatron]并参考 Megatron-SWIFT 文档 配置需要评测能力安装ms-swift[eval]评测后端为 EvalScope环境一致性/复现直接使用官方 Docker 镜像版本完全锁定想跟进 main 分支新特性源码安装pip install -e .随仓库同步更新至此无论你选择 Wheel 包、源码还是 Docker 镜像都可以依据本文在目标硬件上快速搭建起完整的 SWIFT 环境。安装完成后建议继续阅读 快速开始 跑通第一个训练任务再按需深入 命令行参数说明 与 自定义数据集文档。【免费下载链接】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），仅供参考 SWIFT（ms-swift）安装完全指南：pip / 源码 / Docker 三种方式与运行环境配置详解
SWIFTms-swift安装完全指南pip / 源码 / Docker 三种方式与运行环境配置详解【免费下载链接】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/swiftSWIFT 是模型即服务的可扩展轻量级微调基础设施Scalable lightWeight Infrastructure for Fine-Tuning当前仓库已支持 600 纯文本大模型与 300 多模态大模型Qwen、DeepSeek、GLM、InternLM、Llama 等的预训练、微调、RLHF/GRPO 强化学习、推理、评测与部署。本文以仓库内 SWIFT-installation.md 为骨架系统讲解 SWIFT 的 Wheel 包安装、源码安装、Docker 镜像三种方式并深入解读支持的硬件矩阵、运行环境版本约束、可选依赖构成与免费 Notebook 环境帮助你在 NVIDIA GPU、Ascend NPU、MPS 或 CPU 上快速搭建起可用环境并理解每一步背后的依赖实现。安装方式总览SWIFT 官方提供三种主流安装路径适用于不同的使用场景安装方式适用场景特点Wheel 包安装pip绝大多数用户、快速上手一键安装、自动解析依赖推荐方式源码安装git pip -e开发者、需要跟进最新特性或二次开发可修改源码即时生效与 main 分支同步Docker 镜像团队统一环境、生产部署、多机复现环境即代码版本完全锁定其中 Wheel 包与源码安装均支持按需选择全能力或专项能力依赖集Docker 镜像则按 SWIFT 版本 CUDA PyTorch vLLM 的组合预先构建开箱即用。方式一Wheel 包安装推荐使用 pip 即可完成安装安装包名为ms-swift-U表示升级到最新版本# 推荐 pip install ms-swift -U # 额外安装 Megatron 依赖 pip install ms-swift[megatron] -U # 额外安装评测依赖 pip install ms-swift[eval] -U # 全能力 pip install ms-swift[all] -Uextras 依赖集背后setup.py 如何组织从源码 setup.py 可以确认ms-swift的依赖分为基础依赖与可选 extras两层基础依赖解析自requirements.txt实际内容为-r requirements/framework.txt即 requirements/framework.txt包含transformers4.33,5.17.0、datasets3.0,4.8.5、peft0.11,0.21、trl0.15,1.0、modelscope1.23、deepspeed、accelerate、einops、sentencepiece、tiktoken等训练与推理必需组件。可选 extras见 setup.pymegatron解析 requirements/megatron.txt包含mcore-bridge1.6.3、megatron-core0.16、peft0.15用于 TP/PP/CP/EP 等 Megatron 并行训练eval解析 requirements/eval.txt包含evalscope1.0.0及evalscope[opencompass]、evalscope[vlmeval]用于模型评测swanlab解析 requirements/swanlab.txt提供 SwanLab 实验可视化ray解析 requirements/ray.txt提供 Ray 分布式调度支持all由install_requires eval swanlab ray拼合而成不包含 megatron即全能力安装。因此只需 SFT/推理pip install ms-swift即可需要 Megatron 大规模并行训练追加[megatron]需要 EvalScope 评测追加[eval]想一步到位直接pip install ms-swift[all] -U。使用 uv 安装uv 是更快的 Python 包管理器SWIFT 同样支持pip install uv uv pip install ms-swift --torch-backendauto--torch-backendauto会让 uv 根据当前 CUDA 环境自动选择对应的 PyTorch 构建版本简化了手动匹配 torch/CUDA 版本的过程。方式二源代码安装源码安装适合两类用户想第一时间体验 main 分支新特性的用户以及需要对 SWIFT 源码进行二次开发的用户pip install -e .为可编辑安装修改源码后无需重装即生效。安装 swift4.x当前 main 分支当前仓库main分支对应 swift4.x 版本swift/version.py 中__version__ 4.6.0.dev0也印证了这一点dev0表示开发版正式发布时才会更新为稳定版本号。# 从 git 直接安装等价于下面 clone 后 install # pip install githttps://github.com/modelscope/ms-swift.git # 全能力 # pip install ms-swift[all]githttps://github.com/modelscope/ms-swift.git # 推荐clone 到本地后以可编辑模式安装 git clone https://github.com/modelscope/ms-swift.git cd ms-swift pip install -e . # 使用 uv uv pip install -e . --torch-backendauto # 全能力 # pip install -e .[all]安装 swift3.x历史稳定分支如果需要使用 swift3.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 . # 全能力 # pip install -e .[all]提示3.x 与 4.x 在命令行参数、训练流程上有差异切换分支前请先阅读对应版本的 快速开始 与 命令行参数说明。方式三Docker 镜像对于需要统一团队环境、保证复现性、或避免本地依赖冲突的场景官方提供了预构建 Docker 镜像镜像命名直接体现了内部的软件栈版本组合。镜像命名规范解读以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为例tag 依次为系统版本-CUDA版本-Python版本-PyTorch版本-vLLM版本-ModelScope版本-SWIFT版本即Ubuntu 22.04 CUDA 13.0.3 Python 3.12 torch 2.13.0 vllm 0.28.0 modelscope 1.40.0 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 # swift4.4.3 modelscope-registry.cn-hangzhou.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda13.0.3-py312-torch2.11.0-vllm0.25.1-modelscope1.39.0-swift4.4.3 modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda13.0.3-py312-torch2.11.0-vllm0.25.1-modelscope1.39.0-swift4.4.3 modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda13.0.3-py312-torch2.11.0-vllm0.25.1-modelscope1.39.0-swift4.4.3 # swift4.4.1 modelscope-registry.cn-hangzhou.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda13.0.3-py312-torch2.11.0-vllm0.23.0-modelscope1.38.1-swift4.4.1 modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda13.0.3-py312-torch2.11.0-vllm0.23.0-modelscope1.38.1-swift4.4.1 modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda13.0.3-py312-torch2.11.0-vllm0.23.0-modelscope1.38.1-swift4.4.1 # swift4.3.2 modelscope-registry.cn-hangzhou.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda13.0.3-py312-torch2.11.0-vllm0.23.0-modelscope1.37.1-swift4.3.2 modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda13.0.3-py312-torch2.11.0-vllm0.23.0-modelscope1.37.1-swift4.3.2 modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda13.0.3-py312-torch2.11.0-vllm0.23.0-modelscope1.37.1-swift4.3.2每个版本均提供杭州cn-hangzhou、北京cn-beijing、美西us-west-1三个地域的仓库地址国内用户建议优先使用 cn-hangzhou / cn-beijing 以加快拉取速度。历史镜像swift4.x 早期版本与 swift3.x# swift4.2.3 modelscope-registry.cn-hangzhou.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda13.0.3-py312-torch2.11.0-vllm0.21.0-modelscope1.36.3-swift4.2.3 modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda13.0.3-py312-torch2.11.0-vllm0.21.0-modelscope1.36.3-swift4.2.3 modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda13.0.3-py312-torch2.11.0-vllm0.21.0-modelscope1.36.3-swift4.2.3 # swift4.1.3 modelscope-registry.cn-hangzhou.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.9.1-py312-torch2.10.0-vllm0.19.1-modelscope1.35.4-swift4.1.3 modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.9.1-py312-torch2.10.0-vllm0.19.1-modelscope1.35.4-swift4.1.3 modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.9.1-py312-torch2.10.0-vllm0.19.1-modelscope1.35.4-swift4.1.3 # swift4.0.3 modelscope-registry.cn-hangzhou.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.8.1-py311-torch2.10.0-vllm0.17.1-modelscope1.34.0-swift4.0.3 modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.8.1-py311-torch2.10.0-vllm0.17.1-modelscope1.34.0-swift4.0.3 modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.8.1-py311-torch2.10.0-vllm0.17.1-modelscope1.34.0-swift4.0.3 # swift3.12.5 modelscope-registry.cn-hangzhou.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.8.1-py311-torch2.9.0-vllm0.13.0-modelscope1.33.0-swift3.12.5 modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.8.1-py311-torch2.9.0-vllm0.13.0-modelscope1.33.0-swift3.12.5 modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.8.1-py311-torch2.9.0-vllm0.13.0-modelscope1.33.0-swift3.12.5 # swift3.11.3 modelscope-registry.cn-hangzhou.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.9.1-py311-torch2.8.0-vllm0.11.0-modelscope1.32.0-swift3.11.3 modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.9.1-py311-torch2.8.0-vllm0.11.0-modelscope1.32.0-swift3.11.3 modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.9.1-py311-torch2.8.0-vllm0.11.0-modelscope1.32.0-swift3.11.3 # swift3.10.3 / swift3.9.3 modelscope-registry.cn-hangzhou.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.8.1-py311-torch2.8.0-vllm0.11.0-modelscope1.31.0-swift3.10.3 modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.8.1-py311-torch2.8.0-vllm0.11.0-modelscope1.31.0-swift3.10.3 modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.8.1-py311-torch2.8.0-vllm0.11.0-modelscope1.31.0-swift3.10.3 # swift3.8.3 modelscope-registry.cn-hangzhou.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.6.3-py311-torch2.7.1-vllm0.10.1.1-modelscope1.29.2-swift3.8.3 modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.6.3-py311-torch2.7.1-vllm0.10.1.1-modelscope1.29.2-swift3.8.3 modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.6.3-py311-torch2.7.1-vllm0.10.1.1-modelscope1.29.2-swift3.8.3 # swift3.7.2 modelscope-registry.cn-hangzhou.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.6.3-py311-torch2.7.1-vllm0.10.0-modelscope1.28.2-swift3.7.2 modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.6.3-py311-torch2.7.1-vllm0.10.0-modelscope1.28.2-swift3.7.2 modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.6.3-py311-torch2.7.1-vllm0.10.0-modelscope1.28.2-swift3.7.2 # swift3.6.4 / swift3.5.3 modelscope-registry.cn-hangzhou.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.4.0-py310-torch2.6.0-vllm0.8.5.post1-modelscope1.28.1-swift3.6.4 modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.4.0-py310-torch2.6.0-vllm0.8.5.post1-modelscope1.28.1-swift3.6.4 modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.4.0-py310-torch2.6.0-vllm0.8.5.post1-modelscope1.28.1-swift3.6.4 # swift3.4.1.post1 modelscope-registry.cn-hangzhou.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.4.0-py311-torch2.6.0-vllm0.8.5.post1-modelscope1.26.0-swift3.4.1.post1 modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.4.0-py311-torch2.6.0-vllm0.8.5.post1-modelscope1.26.0-swift3.4.1.post1 modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.4.0-py311-torch2.6.0-vllm0.8.5.post1-modelscope1.26.0-swift3.4.1.post1 # swift3.3.0.post1 modelscope-registry.cn-hangzhou.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.4.0-py311-torch2.6.0-vllm0.8.3-modelscope1.25.0-swift3.3.0.post1 modelscope-registry.cn-beijing.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.4.0-py311-torch2.6.0-vllm0.8.3-modelscope1.25.0-swift3.3.0.post1 # swift3.2.2 modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.4.0-py311-torch2.5.1-modelscope1.25.0-swift3.2.2支持的硬件环境SWIFT 官方支持的硬件矩阵如下硬件环境备注A10/A100/H100主力训练/推理平台体验最佳RTX 20/30/40 系列消费级显卡支持 LoRA/QLoRA 等轻量微调T4/V100部分模型可能出现 NANAscend NPU部分模型可能出现 NAN 或算子不支持MPSApple 芯片M 系列具体限制参考官方 issueCPU可训练可推理速度较慢适合小模型调试几点实战提示A10/A100/H100 与 RTX 系列是官方推荐环境绝大多数模型可无障碍训练T4/V100属于较老架构部分新模型如对计算精度敏感的模型可能出现 NAN建议优先使用较新卡型或改用混合精度策略Ascend NPU使用昇腾生态官方提供了专门的 NPU 支持文档 与 Metax 支持文档部分算子可能不受支持需参考对应最佳实践排查CPU 环境无需安装 CUDA适合做数据预处理、小模型调试或 CI 验证硬件相关的安装细节可参考仓库内 requirements/npu.txt 等专项依赖文件。运行环境与版本约束SWIFT 对各基础组件有明确的版本范围与推荐值安装前请先对照下表确认环境组件支持范围推荐备注python3.103.12强烈建议 3.10/3.11/3.12cuda—12.8 / 13.0使用 CPU、NPU、MPS 则无需安装torch2.02.8.0 / 2.11.0与 CUDA 版本配套transformers4.334.57.6 / 5.12.1上限约束见 framework.txtmodelscope1.23—模型与数据集下载datasets3.0,4.8.53.6.0 / 4.8.4上限 4.8.5peft0.11,0.20—训练器与 tuner 依赖flash_attn—2.8.3 / 4.0.0b15显存与速度优化trl0.15,1.00.29.1RLHF 系列任务deepspeed0.140.18.9分布式训练vllm0.5.10.11.0 / 0.23.0推理/部署加速sglang0.4.6—推理/部署加速evalscope1.0—模型评测gradio—5.32.1Web-UI / App版本约束的源码依据这些约束并非凭空而来仓库的依赖文件是最终依据requirements/framework.txt 中写明了transformers4.33,5.17.0、datasets3.0,4.8.5、peft0.11,0.21、trl0.15,1.0、modelscope1.23等硬性约束安装时 pip 会自动解析注意文档表格中的peft 0.20与 framework.txt 中的0.21存在细微差异实际以当前仓库依赖文件0.21为准requirements/install_all.sh 给出了完整的一键环境搭建脚本其中命令pip install transformers5.17 trl1.0 peft0.21 datasets4.8.5 -U与 framework.txt 约束一致flash-attn2.8.3需要--no-build-isolation从源码编译若编译失败可尝试官方预编译 wheeldeepspeed0.19与文档推荐的 0.18.9 对应Megatron 相关依赖TransformerEngine、DeepGEMM、flash-linear-attention、causal-conv1d、fast-hadamard-transform 等同样在该脚本中给出需配合--no-build-isolation从源码安装。版本策略小结python3.10是硬性要求CUDA 12.8/13.0 为当前推荐如果使用 CPU/NPU/MPS 后端则完全不需要安装 CUDA 工具链。安装后的验证安装完成后可通过以下方式验证环境是否可用# 查看 SWIFT 版本 swift --version # 查看 CLI 子命令帮助 swift --help从源码 swift/cli/main.py 的入口路由可以看到swift命令内置了pt预训练、sft微调、rlhf人类对齐/强化学习、infer推理、deploy部署、eval评测、export导出量化、merge-lora权重合并、web-ui界面、sample数据采样等完整子命令安装成功后可立即用 快速开始 中的示例命令跑通第一个 SFT 任务CUDA_VISIBLE_DEVICES0 \ swift sft \ --model Qwen/Qwen3-4B-Instruct-2507 \ --tuner_type lora \ --dataset AI-ModelScope/alpaca-gpt4-data-zh#500 AI-ModelScope/alpaca-gpt4-data-en#500 swift/self-cognition#500小贴士模型与数据集默认通过 ModelScope 下载如需走 HuggingFace在命令中追加--use_hf true即可。Notebook 环境免费 A10 GPU 快速上手SWIFT 支持训练的绝大多数模型都可以在单张 A10 显卡上跑通配合 LoRA/QLoRA 等轻量微调技术。ModelScope 官方为注册用户提供免费的 GPU Notebook 资源具体步骤如下进入 ModelScope 官方网站并登录账号点击左侧导航栏的我的 Notebook开启一个免费 GPU 实例提供 A10 显卡在 Notebook 中执行pip install ms-swift[all] -U完成安装即可开始愉快的模型训练与调试。这套路径特别适合零成本入门无需自购显卡即可在云端体验 SWIFT 的完整训练、推理链路配合 Web-UI 文档 甚至可以不写代码完成训练全流程。常见问题与注意事项场景建议T4/V100 上训练出现 NAN属于已知现象建议换用 A10/A100/H100 或 RTX 系列必要时调整torch_dtype与梯度累积策略Ascend NPU 算子不支持参考 NPU 最佳实践 与 Metax 最佳实践MPSApple 芯片部分算子存在兼容性问题参考官方 issue 中记录的已知限制与 workaround使用 CPU/NPU/MPS无需安装 CUDA 工具链uv pip install ms-swift --torch-backendauto会自动选择 CPU 版 torch需要 Megatron 大规模并行安装ms-swift[megatron]并参考 Megatron-SWIFT 文档 配置需要评测能力安装ms-swift[eval]评测后端为 EvalScope环境一致性/复现直接使用官方 Docker 镜像版本完全锁定想跟进 main 分支新特性源码安装pip install -e .随仓库同步更新至此无论你选择 Wheel 包、源码还是 Docker 镜像都可以依据本文在目标硬件上快速搭建起完整的 SWIFT 环境。安装完成后建议继续阅读 快速开始 跑通第一个训练任务再按需深入 命令行参数说明 与 自定义数据集文档。【免费下载链接】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），仅供参考