Swift：阿里魔搭大模型微调框架安装与使用指南

官方信息

项目背景

Swift 是由阿里巴巴通义实验室开源的大模型轻量化微调框架，托管在魔搭社区（ModelScope）。它的设计目标是让普通开发者只需几行命令就能完成对 Qwen、Llama、DeepSeek、GLM 等主流大语言模型的全参数微调、LoRA/QLoRA 微调、人类偏好对齐（DPO/PPO/RLHF）以及推理部署。

在大模型落地过程中，企业和开发者面临的最大痛点是：训练框架五花八门、数据格式不统一、多卡分布式配置复杂、训练完的模型不知道怎么部署。Swift 把这些环节全部封装成了统一的命令行接口和 Python API，支持从数据预处理、模型选择、训练超参、分布式策略到推理导出的完整链路。

与 HuggingFace 的 transformers + peft + trl 组合相比，Swift 的优势在于：开箱即用的国内模型生态（Qwen 系列原生支持）、内置大量数据集模板、对国产 GPU（寒武纪、燧原、沐曦等）有适配、以及魔搭社区模型库直接拉取无需科学上网。

核心特性

• 支持上百种模型：原生支持 Qwen/Qwen2/Qwen3、Llama 3、DeepSeek-V2/V3、GLM-4、Yi、Baichuan、Mistral 等主流 LLM，同时支持视觉多模态模型（Qwen-VL、LLaVA）。
• 全参数 + 高效微调：同时支持全参数微调、LoRA、QLoRA、DoRA、GaLore、LoRA+ 等多种微调策略，一条命令切换。
• 对齐训练全家桶：内置 SFT（监督微调）、DPO（直接偏好优化）、PPO、RLHF、KTO、ORPO 等人类对齐算法，无需自己拼接奖励模型。
• 多卡分布式：开箱即用 DeepSpeed ZeRO-2/3、FSDP、Megatron-LM，支持张量并行、流水线并行。
• 量化训练：内置 bitsandbytes 4bit/8bit 量化加载，单张消费级显卡也能微调 70B 模型。
• 训练即部署：训练完成后一条命令导出为 vLLM、Ollama、GPTQ/AWQ 量化格式，直接起 OpenAI 兼容 API 服务。
• Web UI：内置 Gradio 可视化界面，点点鼠标就能选模型、传数据、配超参、开始训练。

环境要求

详细部署步骤

第一步：环境准备

首先创建独立的 Conda 虚拟环境，避免依赖冲突：

# 创建虚拟环境
conda create -n swift python=3.10 -y
conda activate swift

# 验证 CUDA 可用性
nvidia-smi
nvcc --version

# 安装 PyTorch（根据 CUDA 版本选择，以 CUDA 12.1 为例）
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

第二步：安装 Swift

方式一：pip 安装（推荐新手）

# 安装核心功能
pip install 'ms-swift'

# 安装全功能（包含 vLLM、DEEPSPEED、GPTQ 等）
pip install 'ms-swift[all]'

# 验证安装
swift --version

方式二：源码安装（开发者）

git clone https://github.com/modelscope/swift.git
cd swift
pip install -e '.[all]'

方式三：Docker 部署

# 拉取官方镜像
docker pull registry.cn-hangzhou.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.1.0-py310

# 启动容器并挂载 GPU
docker run -it --gpus all --shm-size 10g \
  -v /your/data/path:/workspace \
  registry.cn-hangzhou.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.1.0-py310 bash

# 容器内验证
swift --version

第三步：准备训练数据

Swift 支持两种数据格式：通用对话格式（jsonl）和 Alpaca 格式。推荐使用对话格式：

# data/train.jsonl 示例
{"messages": [{"role": "system", "content": "你是一个 helpful 的助手"}, {"role": "user", "content": "什么是大模型微调？"}, {"role": "assistant", "content": "大模型微调是在预训练模型基础上..."}]}
{"messages": [{"role": "user", "content": "如何学习 Python？"}, {"role": "assistant", "content": "学习 Python 建议从基础语法开始..."}]}

如果不想自己准备数据，Swift 内置了几百个数据集模板，直接指定名字即可：

# 内置数据集示例：使用 alpaca 数据集
--dataset ai2_arc:default

# 多个数据集用逗号分隔
--dataset ai2_arc:default,cmrc2018:default

第四步：开始 LoRA 微调

以 Qwen2.5-7B-Instruct 为例，执行 LoRA 微调：

swift sft \
  --model Qwen/Qwen2.5-7B-Instruct \
  --train_type lora \
  --lora_rank 16 \
  --lora_alpha 32 \
  --dataset 'your_dataset:train' \
  --num_train_epochs 3 \
  --per_device_train_batch_size 2 \
  --gradient_accumulation_steps 8 \
  --learning_rate 1e-4 \
  --warmup_ratio 0.05 \
  --save_steps 500 \
  --eval_steps 500 \
  --logging_steps 10 \
  --output_dir output/qwen25-7b-lora \
  --bf16 True \
  --gradient_checkpointing True \
  --use_flash_attn True

参数说明：

• --model：魔搭模型 ID，首次运行会自动下载；也可填本地路径。
• --train_type lora：使用 LoRA 高效微调；改为 full 则全参数微调。
• --lora_rank 16 --lora_alpha 32：LoRA 秩和缩放系数，alpha 一般是 rank 的 2 倍。
• --per_device_train_batch_size 2：单卡 batch size，显存不够就调小。
• --gradient_accumulation_steps 8：梯度累积，等效 batch = 2×8×GPU数。
• --bf16 True：使用 BF16 混合精度，A100/4090 都支持。

第五步：多卡分布式训练

使用 DeepSpeed ZeRO-3 进行多卡训练：

NPROC_PER_NODE=2 swift sft \
  --model Qwen/Qwen2.5-72B-Instruct \
  --train_type lora \
  --dataset 'your_dataset:train' \
  --deepspeed zero3 \
  --per_device_train_batch_size 1 \
  --gradient_accumulation_steps 16 \
  --learning_rate 1e-4 \
  --output_dir output/qwen25-72b-lora \
  --bf16 True

第六步：合并 LoRA 权重并导出

# 合并 LoRA 到基础模型
swift export \
  --model Qwen/Qwen2.5-7B-Instruct \
  --adapters output/qwen25-7b-lora/checkpoint-xxx \
  --merge_lora true \
  --output_dir output/qwen25-7b-merged

第七步：启动推理服务

# 方式一：命令行交互推理
swift infer \
  --model output/qwen25-7b-merged \
  --stream true

# 方式二：启动 OpenAI 兼容 API 服务（基于 vLLM）
swift deploy \
  --model output/qwen25-7b-merged \
  --served_model_name my-qwen \
  --api_server_port 8000

测试 API：

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "my-qwen",
    "messages": [{"role": "user", "content": "你好，请介绍一下你自己"}]
  }'

常见坑与解决

• CUDA out of memory：调小 per_device_train_batch_size，开启 --gradient_checkpointing true，或改用 QLoRA（--quantization_bit 4）。
• 模型下载慢：设置环境变量 export MODELSCOPE_CACHE=/path/to/cache，或提前用 modelscope download --model Qwen/Qwen2.5-7B-Instruct 下载。
• Flash Attention 安装失败：先 pip install flash-attn --no-build-isolation，需要匹配 CUDA 版本。
• DeepSpeed 初始化卡住：确保 --shm-size 足够（Docker 中至少 10g），并关闭防火墙。

使用方法示例

训练完成后，你会在 output/qwen25-7b-merged 目录看到完整的模型权重文件，包括：

• config.json：模型配置
• model-00001-of-xxxxx.safetensors：模型权重分片
• tokenizer.json / tokenizer_config.json：分词器

该目录可直接被 vLLM、Ollama、text-generation-webui 等工具加载使用。默认部署的 API 服务监听 0.0.0.0:8000，无需鉴权即可调用，生产环境务必加 Nginx 反代和访问密钥。

常见问题 FAQ

Q1：Swift 和 LLaMA-Factory 有什么区别？
A：Swift 是阿里官方维护，对 Qwen 系列支持最及时，多模态和国产 GPU 适配更好；LLaMA-Factory 社区更活跃，Web UI 更友好。两者功能高度重合，选一个即可。

Q2：7B 模型 LoRA 微调需要多少显存？
A：BF16 全量加载约需 16GB；4bit QLoRA 约需 6-8GB；开启 gradient checkpointing 可再省 30%。

Q3：训练 loss 不下降怎么办？
A：检查学习率（LoRA 一般 1e-4 ~ 5e-4）、数据格式是否正确、是否开启了 overflow 导致梯度为 0。先用小数据集跑 100 步验证 loss 曲线。

Q4：如何继续训练中断的任务？
A：加 --resume_from_checkpoint output/qwen25-7b-lora/checkpoint-xxx 参数即可恢复。

Q5：支持哪些量化格式导出？
A：支持 GPTQ、AWQ、BNB 4bit/8bit，通过 --quant_method gptq 等参数指定。

跳转链接

• GitHub 仓库：https://github.com/modelscope/swift
• 官方文档：https://modelscope.cn/docs/swift
• 魔搭模型库：https://modelscope.cn/models
• Swift GitHub 示例：examples 目录