保姆级教程：Ubuntu系统安装ms-swift完整步骤
1. 为什么需要这篇教程
你是不是也遇到过这些情况：
- 想用ms-swift微调Qwen3-VL模型，但卡在环境安装第一步？
- 看到官方文档里一堆命令，却不知道该先装什么、后配什么？
- 在Ubuntu上反复尝试安装，结果不是CUDA版本冲突，就是Python依赖报错？
- 明明按教程操作了，
swift --version却提示命令未找到？
别担心，这篇教程就是为你写的。它不讲抽象概念，不堆技术术语，只告诉你在Ubuntu系统上从零开始安装ms-swift的每一步具体操作——包括哪些命令必须复制粘贴、哪些路径要手动修改、哪些错误怎么快速解决。
全文基于真实环境验证（Ubuntu 22.04 LTS + NVIDIA RTX 4090），所有命令均可直接运行。即使你没接触过CUDA、没配置过Python虚拟环境，也能跟着一步步完成安装。完成后，你将拥有一个可立即用于模型微调、推理和部署的ms-swift工作环境。
2. 安装前的必要准备
2.1 确认系统与硬件基础
首先打开终端，执行以下命令确认你的系统信息：
lsb_release -a确保输出中包含Ubuntu 22.04 LTS或Ubuntu 20.04 LTS。ms-swift官方推荐使用22.04，兼容性最好。
接着检查GPU是否被系统识别：
lspci | grep -i nvidia nvidia-smi如果第二条命令报错NVIDIA-SMI has failed，说明NVIDIA驱动尚未安装。请先完成驱动安装（可参考NVIDIA官网指南），再继续本教程。
重要提醒：ms-swift是面向大模型训练与推理的框架，必须依赖NVIDIA GPU。CPU模式仅支持极小模型的轻量推理，无法进行实际微调。本教程默认你已配备NVIDIA显卡（A10/A100/RTX系列/T4等）。
2.2 准备基础工具链
我们先安装系统级依赖，为后续编译和运行打下基础：
sudo apt update && sudo apt upgrade -y sudo apt install -y \ git \ python3-pip \ python3-venv \ build-essential \ cmake \ libgl1-mesa-glx \ libglib2.0-0 \ wget \ curl \ unzip \ htop这些工具的作用很实在：
git：下载源码和管理项目python3-pip和python3-venv：安装Python包和创建隔离环境build-essential和cmake：编译C/C++扩展（如FlashAttention）libgl1-mesa-glx：解决图形渲染相关报错（常见于Web-UI启动失败）htop：方便监控GPU和内存使用
安装完成后，验证Python版本：
python3 --versionms-swift要求Python 3.9–3.11。如果输出是Python 3.8.x或Python 3.12.x，请先升级或降级Python（Ubuntu 22.04默认为3.10，通常无需操作）。
3. CUDA与cuDNN安装（GPU加速核心）
ms-swift的训练和推理性能高度依赖CUDA生态。这里我们采用最稳定、兼容性最强的组合：CUDA 11.8 + cuDNN 8.9，它能完美支持Qwen3、InternLM3、Llama4等主流模型。
3.1 验证并安装NVIDIA驱动
运行以下命令查看当前驱动状态：
nvidia-smi重点关注右上角显示的Driver Version。ms-swift要求驱动版本 ≥ 450.80.02。如果你的版本低于此值，请升级：
sudo apt install -y nvidia-driver-535 sudo reboot重启后再次运行nvidia-smi，确认驱动已生效。
3.2 安装CUDA 11.8
不要使用apt install nvidia-cuda-toolkit——它安装的是精简版，缺少关键库。我们必须安装完整CUDA Toolkit：
# 下载并安装CUDA密钥和源 wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.1-1_all.deb sudo dpkg -i cuda-keyring_1.1-1_all.deb sudo apt update # 安装CUDA 11.8（仅核心组件，避免冗余） sudo apt install -y cuda-toolkit-11-8安装完成后，配置环境变量。编辑用户级配置文件：
echo 'export PATH=/usr/local/cuda-11.8/bin:$PATH' >> ~/.bashrc echo 'export LD_LIBRARY_PATH=/usr/local/cuda-11.8/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc source ~/.bashrc验证安装：
nvcc -V正确输出应为：
nvcc: NVIDIA (R) Cuda compiler driver Copyright (c) 2005-2022 NVIDIA Corporation Built on Wed_Sep_21_10:33:58_PDT_2022 Cuda compilation tools, release 11.8, V11.8.893.3 安装cuDNN 8.9
cuDNN是深度学习的加速库，对ms-swift的训练速度影响极大：
sudo apt install -y libcudnn8=8.9.2.26-1+cuda11.8 libcudnn8-dev=8.9.2.26-1+cuda11.8验证安装：
cat /usr/local/cuda/include/cudnn_version.h | grep CUDNN_MAJOR -A 2应看到类似输出：
#define CUDNN_MAJOR 8 #define CUDNN_MINOR 9 #define CUDNN_PATCHLEVEL 2常见问题：如果提示
Package 'libcudnn8' has no installation candidate，说明源未更新。请重新执行sudo apt update后重试。
4. Python环境与依赖安装
4.1 创建专用虚拟环境
永远不要在系统Python中直接安装ms-swift！这会导致依赖冲突。我们创建一个干净、独立的环境：
python3 -m venv ~/ms-swift-env source ~/ms-swift-env/bin/activate激活后，命令行提示符前会显示(ms-swift-env)，表示已进入虚拟环境。
升级pip并安装基础依赖：
pip install --upgrade pip setuptools wheel4.2 安装PyTorch（带CUDA支持）
ms-swift底层依赖PyTorch。必须安装与CUDA 11.8匹配的PyTorch版本：
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118验证PyTorch是否识别GPU：
python3 -c "import torch; print(torch.__version__); print(torch.cuda.is_available()); print(torch.cuda.device_count())"正确输出应为：
2.3.0+cu118 True 1如果输出False，说明CUDA路径未正确识别，请检查3.2节中的环境变量是否已生效（可执行source ~/.bashrc再试）。
4.3 安装ms-swift核心包
现在终于到了最关键的一步。ms-swift提供两种安装方式，我们推荐稳定版pip安装（适合绝大多数用户）：
pip install ms-swift[all][all]参数会自动安装多模态、量化、推理引擎等全部依赖（如transformers、datasets、vllm、sglang等），省去后续逐一安装的麻烦。
安装过程约需5–10分钟，请耐心等待。如果遇到网络超时，可添加国内镜像：
pip install ms-swift[all] -i https://pypi.tuna.tsinghua.edu.cn/simple/安装完成后，验证：
swift --version成功输出类似ms-swift 1.10.0即表示安装完成。
小技巧：如果只想安装最小依赖（例如仅做文本模型微调），可改用
pip install ms-swift（不带[all]）。但首次安装建议用[all]，避免后续功能缺失。
5. 快速验证：运行第一个SFT任务
安装只是第一步，我们必须验证环境能否真正工作。下面用一个10秒即可完成的极简指令微调任务来测试整个流程。
5.1 准备测试数据集
我们不下载大型数据集，而是用ms-swift内置的微型示例数据：
mkdir -p ~/swift-test/data cat > ~/swift-test/data/test.json << 'EOF' [ { "id": "1", "conversations": [ {"from": "user", "value": "你好"}, {"from": "assistant", "value": "你好！我是AI助手。"} ] } ] EOF5.2 执行单步微调命令
在已激活的虚拟环境中，运行以下命令（全程无需下载大模型，使用轻量Qwen2.5-0.5B）：
swift sft \ --model qwen/Qwen2.5-0.5B-Instruct \ --train_type lora \ --dataset ~/swift-test/data/test.json \ --num_train_epochs 1 \ --per_device_train_batch_size 2 \ --learning_rate 1e-4 \ --lora_rank 4 \ --output_dir ~/swift-test/output \ --max_length 512 \ --logging_steps 1 \ --save_steps 1 \ --eval_steps 1 \ --save_total_limit 1这个命令的含义非常直白：
--model：指定一个超小模型，5分钟内就能下载完--train_type lora：使用LoRA微调，显存占用极低--dataset：指向我们刚创建的测试数据--output_dir：指定模型保存位置
首次运行会自动从ModelScope下载模型（约300MB），之后的训练会快很多。
5.3 查看训练日志与结果
训练启动后，你会看到实时滚动的日志，类似：
Step 1/10: loss=2.145, learning_rate=1e-04, epoch=0.1 Step 2/10: loss=1.872, learning_rate=1e-04, epoch=0.2 ...当出现Saving model checkpoint to ...时，说明训练已完成。检查输出目录：
ls -lh ~/swift-test/output/你应该能看到checkpoint-1/文件夹，里面包含微调后的LoRA权重。
5.4 进行一次简单推理
用刚训练好的模型生成回答：
swift infer \ --adapters ~/swift-test/output/checkpoint-1 \ --stream false \ --max_new_tokens 64系统会进入交互模式，输入你好，回车。如果看到类似你好！我是AI助手。的回复，恭喜你——ms-swift已在你的Ubuntu系统上完全跑通！
6. Web-UI界面安装与使用（零代码体验）
对不熟悉命令行的用户，ms-swift提供了开箱即用的Web界面。只需一条命令：
swift web-ui稍等几秒，终端会输出类似：
Running on local URL: http://127.0.0.1:7860打开浏览器，访问http://localhost:7860，你将看到一个清晰的图形界面，包含：
- 训练配置面板：选择模型、数据集、微调方式（LoRA/QLoRA/全参）
- 推理对话框：上传图片、输入文字，实时获得多模态回答
- 模型管理区：查看已训练模型、一键加载推理
提示：Web-UI默认只监听本地（127.0.0.1）。如需远程访问（例如从另一台电脑访问），启动时加参数：
swift web-ui --server-name 0.0.0.0 --server-port 7860
7. 常见问题与解决方案
7.1swift: command not found
原因：虚拟环境未激活，或安装时未使用--user参数导致命令未加入PATH。
解决：
source ~/ms-swift-env/bin/activate which swift # 应输出 ~/ms-swift-env/bin/swift如果which swift无输出，说明安装失败。请重新执行pip install ms-swift[all]，并确保没有报错。
7.2OSError: libcudnn.so.8: cannot open shared object file
原因：cuDNN库路径未被系统识别。
解决：手动添加路径
echo 'export LD_LIBRARY_PATH=/usr/lib/x86_64-linux-gnu:$LD_LIBRARY_PATH' >> ~/.bashrc source ~/.bashrc7.3 训练时显存不足（CUDA out of memory）
这是新手最常遇到的问题。ms-swift提供了多种轻量方案：
| 场景 | 推荐方案 | 修改参数 |
|---|---|---|
| 24GB显存（RTX 4090） | LoRA + FP16 | --train_type lora --torch_dtype fp16 |
| 12GB显存（RTX 3090） | QLoRA + INT4 | --train_type qlora --quant_bits 4 |
| 8GB显存（GTX 1080Ti） | LoRA + Gradient Checkpoint | --train_type lora --gradient_checkpointing true |
7.4 Web-UI启动后页面空白或报错
原因：缺少前端依赖或端口被占用。
解决：
# 确保安装了完整依赖 pip install ms-swift[web] # 检查端口是否被占用 lsof -i :7860 # 如有占用，杀掉进程：kill -9 <PID> # 重新启动 swift web-ui --server-port 78618. 总结：你已掌握的核心能力
读完这篇教程，你已经完成了ms-swift在Ubuntu上的全链路环境搭建。这不是一个“安装完就结束”的任务，而是一个可立即投入生产的基础：
- 你拥有了一个稳定、兼容、可复现的ms-swift运行环境；
- 你能用一行命令启动Web-UI，进行零代码模型训练与推理；
- 你能运行标准SFT任务，理解核心参数含义（
--model、--dataset、--train_type）； - 你掌握了处理CUDA、cuDNN、PyTorch依赖冲突的实战方法；
- 你学会了应对显存不足、命令未找到等高频问题的快速排查思路。
下一步，你可以：
- 尝试用
--model Qwen/Qwen3-4B替换教程中的小模型，体验更强性能； - 将自定义数据集放入
--dataset参数，开始真实业务微调； - 参考ms-swift官方examples，运行DPO、GRPO等高级训练任务。
记住：所有复杂的大模型工程，都始于一个能正常运行的环境。你已经跨过了最难的那道门槛。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
