核心内容摘要
乱女小芳：在秩序的裂缝里，活出一场惊心动魄的自由
保姆级教程Ubuntu系统安装ms-swift完整步骤
为什么需要这篇教程你是不是也遇到过这些情况想用ms-swift微调Qwen3-VL模型但卡在环境安装第一步看到官方文档里一堆命令却不知道该先装什么、后配什么在Ubuntu上反复尝试安装结果不是CUDA版本冲突就是Python依赖报错明明按教程操作了swift --version却提示命令未找到别担心这篇教程就是为你写的。
它不讲抽象概念不堆技术术语只告诉你在Ubuntu系统上从零开始安装ms-swift的每一步具体操作——包括哪些命令必须复制粘贴、哪些路径要手动修改、哪些错误怎么快速解决。
全文基于真实环境验证Ubuntu
2
04 LTS NVIDIA RTX 4090所有命令均可直接运行。
即使你没接触过CUDA、没配置过Python虚拟环境也能跟着一步步完成安装。
完成后你将拥有一个可立即用于模型微调、推理和部署的ms-swift工作环境。
安装前的必要准备
1 确认系统与硬件基础首先打开终端执行以下命令确认你的系统信息lsb_release -a确保输出中包含Ubuntu
2
04 LTS或Ubuntu
2
04 LTS。
ms-swift官方推荐使用
2
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 准备基础工具链我们先安装系统级依赖为后续编译和运行打下基础sudo apt update sudo apt upgrade -y sudo apt install -y \ git \ python3-pip \ python3-venv \ build-essential \ cmake \ libgl1-mesa-glx \ libglib
2.
\ wget \ curl \ unzip \ htop这些工具的作用很实在git下载源码和管理项目python3-pip和python3-venv安装Python包和创建隔离环境build-essential和cmake编译C/C扩展如FlashAttentionlibgl1-mesa-glx解决图形渲染相关报错常见于Web-UI启动失败htop方便监控GPU和内存使用安装完成后验证Python版本python3 --versionms-swift要求Python
9–
11。
如果输出是Python
3.
x或Python
3.
x请先升级或降级PythonUbuntu
2
04默认为
10通常无需操作。
CUDA与cuDNN安装GPU加速核心ms-swift的训练和推理性能高度依赖CUDA生态。
这里我们采用最稳定、兼容性最强的组合CUDA
1
8 cuDNN
9它能完美支持Qwen
InternLM
Llama4等主流模型。
1 验证并安装NVIDIA驱动运行以下命令查看当前驱动状态nvidia-smi重点关注右上角显示的Driver Version。
ms-swift要求驱动版本 ≥
450.
8
02。
如果你的版本低于此值请升级sudo apt install -y nvidia-driver-535 sudo reboot重启后再次运行nvidia-smi确认驱动已生效。
2 安装CUDA
1
8不要使用apt install nvidia-cuda-toolkit——它安装的是精简版缺少关键库。
我们必须安装完整CUDA Toolkit# 下载并安装CUDA密钥和源 wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_
1.
_all.deb sudo dpkg -i cuda-keyring_
1.
_all.deb sudo apt update # 安装CUDA
1
8仅核心组件避免冗余 sudo apt install -y cuda-toolkit-
安装完成后配置环境变量。
编辑用户级配置文件echo export PATH/usr/local/cuda-
1
8/bin:$PATH ~/.bashrc echo export LD_LIBRARY_PATH/usr/local/cuda-
1
8/lib64:$LD_LIBRARY_PATH ~/.bashrc source ~/.bashrc验证安装nvcc -V正确输出应为nvcc: NVIDIA (R) Cuda compiler driver Copyright (c)
NVIDIA Corporation Built on Wed_Sep_21_10:33:58_PDT_2022 Cuda compilation tools, release
1
8, V
11.
8.
8
3 安装cuDNN
9cuDNN是深度学习的加速库对ms-swift的训练速度影响极大sudo apt install -y libcudnn
88.
9.
2.
cuda
1
8 libcudnn8-dev
8.
9.
2.
cuda
1
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后重试。
Python环境与依赖安装
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 wheel
2 安装PyTorch带CUDA支持ms-swift底层依赖PyTorch。
必须安装与CUDA
1
8匹配的PyTorch版本pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118验证PyTorch是否识别GPUpython3 -c import torch; print(torch.__version__); print(torch.cuda.is_available()); print(torch.cuda.device_count())正确输出应为
2.
0cu118 True 1如果输出False说明CUDA路径未正确识别请检查
2节中的环境变量是否已生效可执行source ~/.bashrc再试。
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.
1
0即表示安装完成。
小技巧如果只想安装最小依赖例如仅做文本模型微调可改用pip install ms-swift不带[all]。
但首次安装建议用[all]避免后续功能缺失。
快速验证运行第一个SFT任务安装只是第一步我们必须验证环境能否真正工作。
下面用一个10秒即可完成的极简指令微调任务来测试整个流程。
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助手。
} ] } ] EOF
2 执行单步微调命令在已激活的虚拟环境中运行以下命令全程无需下载大模型使用轻量Qwen
5-
5Bswift sft \ --model qwen/Qwen
5-
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之后的训练会快很多。
3 查看训练日志与结果训练启动后你会看到实时滚动的日志类似Step 1/10: loss
145, learning_rate1e-04, epoch
1 Step 2/10: loss
872, learning_rate1e-04, epoch
2 ...当出现Saving model checkpoint to ...时说明训练已完成。
检查输出目录ls -lh ~/swift-test/output/你应该能看到checkpoint-1/文件夹里面包含微调后的LoRA权重。
4 进行一次简单推理用刚训练好的模型生成回答swift infer \ --adapters ~/swift-test/output/checkpoint-1 \ --stream false \ --max_new_tokens 64系统会进入交互模式输入你好回车。
如果看到类似你好我是AI助手。
的回复恭喜你——ms-swift已在你的Ubuntu系统上完全跑通
Web-UI界面安装与使用零代码体验对不熟悉命令行的用户ms-swift提供了开箱即用的Web界面。
只需一条命令swift web-ui稍等几秒终端会输出类似Running on local URL: http://
127.
0.
1:7860打开浏览器访问http://localhost:7860你将看到一个清晰的图形界面包含训练配置面板选择模型、数据集、微调方式LoRA/QLoRA/全参推理对话框上传图片、输入文字实时获得多模态回答模型管理区查看已训练模型、一键加载推理提示Web-UI默认只监听本地
127.
0.
1。
如需远程访问例如从另一台电脑访问启动时加参数swift web-ui --server-name
0.
0.
0 --server-port
78607.
常见问题与解决方案
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]并确保没有报错。
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 ~/.bashrc
3 训练时显存不足CUDA out of memory这是新手最常遇到的问题。
ms-swift提供了多种轻量方案场景推荐方案修改参数24GB显存RTX 4090LoRA FP16--train_type lora --torch_dtype fp1612GB显存RTX 3090QLoRA INT4--train_type qlora --quant_bits 48GB显存GTX 1080TiLoRA Gradient Checkpoint--train_type lora --gradient_checkpointing true
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/Qwen
B替换教程中的小模型体验更强性能将自定义数据集放入--dataset参数开始真实业务微调参考ms-swift官方examples运行DPO、GRPO等高级训练任务。
记住所有复杂的大模型工程都始于一个能正常运行的环境。
你已经跨过了最难的那道门槛。