新手必看：ms-swift微调框架快速部署与LoRA合并教程

AllyBo

291人浏览 · 2026-03-25 00:23:36

AllyBo · 2026-03-25 00:23:36 发布

新手必看：ms-swift微调框架快速部署与LoRA合并教程

1. 引言

如果你正在寻找一个能轻松上手、功能强大的大模型微调工具，那么ms-swift绝对是你的不二之选。想象一下，你手头有一个不错的模型，但想让它在特定任务上表现更好——比如让模型学会你的产品知识，或者理解你的业务逻辑。传统微调方法动辄需要几十GB显存，对硬件要求极高，让很多开发者望而却步。

ms-swift的出现彻底改变了这个局面。这个由魔搭社区推出的微调框架，最大的特点就是简单易用和资源友好。它支持LoRA等轻量微调技术，让你用一张消费级显卡（比如RTX 3090）就能完成大模型的个性化训练。更棒的是，它提供了完整的训练、推理、评测、部署全链路支持，从开始到落地一气呵成。

在这篇教程里，我会手把手带你完成两件最重要的事：快速部署ms-swift环境和掌握LoRA权重合并技巧。无论你是刚接触大模型的新手，还是有一定经验的开发者，都能跟着步骤轻松上手。我们以Qwen2.5-7B-Instruct模型为例，让你在10分钟内看到实际效果。

2. 环境准备与快速安装

2.1 硬件与系统要求

在开始之前，我们先看看需要准备什么。ms-swift对硬件的要求相当友好：

显卡：至少8GB显存（推荐12GB以上），支持NVIDIA RTX系列、A10/A100/H100、T4/V100等
内存：建议16GB以上
存储：至少50GB可用空间（用于存放模型和数据集）
系统：Linux（推荐Ubuntu 20.04+或CentOS 7+）、macOS、Windows（WSL2）
Python：3.8-3.11版本

如果你用的是RTX 3090（24GB）这样的消费级显卡，完全够用。我就是在双卡RTX 4090的环境下测试的，但单卡也完全没问题。

2.2 三种安装方式任选其一

ms-swift提供了多种安装方式，你可以根据喜好选择：

方式一：pip直接安装（最推荐）

这是最简单快捷的方式，一行命令搞定：

# 创建虚拟环境（可选但推荐）
conda create -n swift python=3.10
conda activate swift

# 安装ms-swift及其所有依赖
pip install 'ms-swift[all]' -U -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：源码安装（适合想深入了解或贡献代码的开发者）

如果你想使用最新特性或修改源码，可以选择这种方式：

# 克隆仓库
git clone https://github.com/modelscope/swift.git
cd swift

# 安装开发版本
pip install -e '.[llm]' -i https://pypi.tuna.tsinghua.edu.cn/simple

方式三：Docker方式（适合快速部署）

如果你熟悉Docker，也可以用官方镜像：

docker pull registry.cn-hangzhou.aliyuncs.com/modelscope-repo/modelscope:ubuntu20.04-cuda11.8.0-py38-torch2.1.2-tf2.14.0-1.11.0

安装完成后，验证一下是否成功：

# 查看版本
swift --version

# 或者运行帮助命令
swift --help

如果看到版本信息和帮助文档，说明安装成功了。

2.3 额外依赖按需安装

根据你要使用的功能，可能需要安装一些额外依赖：

# 如果需要vLLM加速推理
pip install vllm

# 如果需要LMDeploy部署
pip install lmdeploy

# 如果需要使用Web-UI界面
pip install gradio

这些都不是必须的，你可以根据实际需求选择安装。

3. 快速体验：10分钟完成模型微调

3.1 理解LoRA微调的核心思想

在深入操作之前，我们先花2分钟理解一下LoRA（Low-Rank Adaptation）到底是什么。

想象一下，你要教一个已经读过很多书的大学生（预训练大模型）学习一门新技能（你的特定任务）。传统方法是让他重新学习所有知识，这既费时又费力。而LoRA就像给他一本薄薄的补充教材——只学习新知识相关的部分，原有知识基本不动。

LoRA的三大优势：

显存占用少：通常只需原模型1%的参数量
训练速度快：只训练新增的小参数
效果接近全参数微调：在很多任务上能达到90%以上的效果

ms-swift默认就使用LoRA进行微调，这对我们普通开发者太友好了。

3.2 单命令启动微调

现在我们来实际操练一下。用Qwen2.5-7B-Instruct模型做个自我认知微调，让模型知道自己是"swift-robot"：

# 单卡3090/4090就能运行，显存约22GB
CUDA_VISIBLE_DEVICES=0 \
swift sft \
    --model Qwen/Qwen2.5-7B-Instruct \
    --train_type lora \
    --dataset 'AI-ModelScope/alpaca-gpt4-data-zh#500' \
              'AI-ModelScope/alpaca-gpt4-data-en#500' \
              'swift/self-cognition#500' \
    --torch_dtype bfloat16 \
    --num_train_epochs 1 \
    --per_device_train_batch_size 1 \
    --per_device_eval_batch_size 1 \
    --learning_rate 1e-4 \
    --lora_rank 8 \
    --lora_alpha 32 \
    --target_modules all-linear \
    --gradient_accumulation_steps 16 \
    --eval_steps 50 \
    --save_steps 50 \
    --save_total_limit 2 \
    --logging_steps 5 \
    --max_length 2048 \
    --output_dir output \
    --system 'You are a helpful assistant.' \
    --warmup_ratio 0.05 \
    --dataloader_num_workers 4 \
    --model_author swift \
    --model_name swift-robot

让我解释一下关键参数：

--model：指定要微调的模型，这里用Qwen2.5-7B-Instruct
--train_type lora：使用LoRA微调方式
--dataset：训练数据集，这里混合了中英文指令数据和自我认知数据
--lora_rank 8：LoRA的秩，值越小参数量越少
--output_dir output：输出目录，训练结果会保存到这里

运行这个命令后，你会看到训练进度条。在RTX 3090上，大约需要6-7分钟就能完成。训练完成后，在output目录下会生成类似这样的检查点：

output/
└── vx-xxx/
    └── checkpoint-xxx/
        ├── adapter_model.safetensors  # LoRA权重文件
        ├── args.json                   # 训练参数
        ├── README.md                   # 模型卡片
        └── ...

3.3 使用自定义数据集

如果你想用自己的数据训练，也很简单。首先准备数据集，格式参考：

// train.json
[
  {
    "instruction": "解释什么是人工智能",
    "input": "",
    "output": "人工智能是..."
  },
  {
    "instruction": "将以下英文翻译成中文",
    "input": "Hello, world!",
    "output": "你好，世界！"
  }
]

然后修改--dataset参数指向你的数据文件：

swift sft \
    --model Qwen/Qwen2.5-7B-Instruct \
    --train_type lora \
    --dataset /path/to/your/train.json \
    # ... 其他参数保持不变

4. LoRA权重合并的两种方法

训练完成后，我们得到了LoRA权重文件。但这时候模型还不能直接使用，需要把LoRA权重合并到原始模型中。ms-swift提供了两种合并方式，都很简单。

4.1 方法一：推理时自动合并（推荐给新手）

这是最简单的方式，在推理时自动完成合并。适合想快速测试效果的场景。

# 使用vLLM加速推理，同时合并LoRA权重
CUDA_VISIBLE_DEVICES=0 \
swift infer \
    --adapters output/vx-xxx/checkpoint-xxx \
    --stream true \
    --merge_lora true \
    --infer_backend vllm \
    --vllm_max_model_len 8192 \
    --temperature 0 \
    --max_new_tokens 2048

关键参数说明：

--adapters：指定LoRA权重目录
--merge_lora true：启用权重合并
--infer_backend vllm：使用vLLM加速推理
--stream true：流式输出，可以看到生成过程

运行后，你会看到合并过程：

[INFO:swift] Merge LoRA...
[INFO:swift] Saving merged weights...
[INFO:swift] Successfully merged LoRA and saved in /data/model/sft/qwen2-7b-instruct-sft/qwen2-7b-instruct/v1-20240901-141800/checkpoint-873-merged.

合并后的模型会保存在checkpoint-xxx-merged目录中，包含完整的模型权重。

4.2 方法二：单独合并权重（适合生产部署）

如果你需要把合并后的模型部署到生产环境，或者分享给他人使用，建议用这种方式单独合并。

# 专门执行合并操作
swift export \
    --ckpt_dir /data/model/sft/qwen2-7b-instruct-sft/qwen2-7b-instruct/v1-20240901-141800/checkpoint-873 \
    --merge_lora true

这个命令会做三件事：

加载原始模型和LoRA权重
将两者合并
保存完整的模型到新目录

合并完成后，你会得到这样的目录结构：

checkpoint-873-merged/
├── config.json
├── generation_config.json
├── model.safetensors
├── special_tokens_map.json
├── tokenizer.json
├── tokenizer_config.json
└── ...

现在这个就是完整的、可以直接使用的模型了。

4.3 两种方法的对比与选择

为了帮你更好地选择，我整理了一个对比表格：

特性	推理时合并	单独合并
使用场景	快速测试、临时使用	生产部署、模型分享
执行速度	每次推理都需要合并	一次合并，多次使用
磁盘空间	需要保留原始模型+LoRA权重	只需要合并后的完整模型
易用性	最简单，一条命令搞定	需要额外执行合并命令
推荐给	初学者、快速验证	需要部署的正式项目

我的建议：

如果你是第一次尝试，用方法一快速看到效果
如果效果满意，需要长期使用，用方法二生成完整模型
团队协作时，分享方法二生成的完整模型更方便

5. 合并后的模型使用与验证

5.1 加载合并后的模型进行推理

合并完成后，我们可以用多种方式使用新模型：

方式一：使用swift直接推理

# 使用合并后的完整模型
CUDA_VISIBLE_DEVICES=0 \
swift infer \
    --model /path/to/merged-model \
    --stream true \
    --max_new_tokens 2048

方式二：使用原生PyTorch加载

如果你想在自己的代码中使用：

from transformers import AutoModelForCausalLM, AutoTokenizer

# 加载合并后的模型
model_path = "/path/to/checkpoint-873-merged"
model = AutoModelForCausalLM.from_pretrained(model_path, torch_dtype=torch.bfloat16)
tokenizer = AutoTokenizer.from_pretrained(model_path)

# 推理
input_text = "你是谁？"
inputs = tokenizer(input_text, return_tensors="pt")
outputs = model.generate(**inputs, max_new_tokens=100)
response = tokenizer.decode(outputs[0], skip_special_tokens=True)
print(response)

方式三：使用vLLM加速服务

对于生产环境，推荐使用vLLM部署：

# 启动API服务
python -m vllm.entrypoints.openai.api_server \
    --model /path/to/merged-model \
    --served-model-name qwen2.5-7b-instruct-lora \
    --port 8000

# 然后就可以通过OpenAI兼容的API调用了
curl http://localhost:8000/v1/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "qwen2.5-7b-instruct-lora",
        "prompt": "你是谁？",
        "max_tokens": 100
    }'

5.2 验证微调效果

训练和合并完成后，最重要的一步是验证效果。我们可以问模型几个问题：

# 启动交互式对话
CUDA_VISIBLE_DEVICES=0 \
swift infer \
    --model /path/to/merged-model \
    --stream true

# 然后输入问题测试
用户> 你是谁？
模型> 我是swift-robot，一个由swift开发的AI助手...

用户> 你的作者是谁？
模型> 我的作者是swift...

如果模型能正确回答"我是swift-robot"和"作者是swift"，说明自我认知微调成功了。

5.3 常见问题排查

在实际操作中，你可能会遇到一些问题。这里我总结了一些常见情况和解决方法：

问题1：显存不足

CUDA out of memory

解决：减小--per_device_train_batch_size（比如从2改为1），或者使用--gradient_checkpointing true启用梯度检查点。

问题2：合并时找不到模型

Error: Model path does not exist

解决：检查--ckpt_dir路径是否正确，确保目录下有adapter_model.safetensors文件。

问题3：推理速度慢

生成很慢，等待时间长

解决：使用--infer_backend vllm启用vLLM加速，或者使用--infer_backend lmdeploy。

问题4：合并后的模型太大

磁盘空间不足

解决：可以使用量化减小模型大小：

swift export \
    --model /path/to/merged-model \
    --quant_bits 4 \
    --quant_method awq \
    --output_dir qwen2.5-7b-instruct-awq

6. 进阶技巧与最佳实践

6.1 LoRA参数调优指南

LoRA的效果很大程度上取决于参数设置。这里给你一些实践经验：

rank（秩）的选择：

rank=8：通用推荐，平衡效果和效率
rank=16：需要更好效果时使用，参数量增加但效果提升
rank=4：显存紧张时使用，效果可能略有下降
rank=32：追求极致效果，但参数量大幅增加

alpha参数：

alpha=32：通常设置为rank的2-4倍
公式：缩放因子 = alpha / rank
如果rank=8，alpha=32，那么缩放因子就是4

target_modules选择：

all-linear：作用于所有线性层，效果最好但参数量最大
q_proj,v_proj：只作用于注意力层的Q、V投影，参数量减少约一半
根据任务复杂度选择，简单任务用后者即可

6.2 多卡训练配置

如果你有多张显卡，可以加速训练过程：

# 使用2张显卡训练
CUDA_VISIBLE_DEVICES=0,1 \
NPROC_PER_NODE=2 \
swift sft \
    --model Qwen/Qwen2.5-7B-Instruct \
    --train_type lora \
    --dataset 'your-dataset' \
    --deepspeed zero2 \
    # ... 其他参数

或者使用Megatron并行技术获得更大加速：

# 使用Megatron加速
NPROC_PER_NODE=2 \
CUDA_VISIBLE_DEVICES=0,1 \
megatron sft \
    --model Qwen/Qwen2.5-7B-Instruct \
    --dataset your-dataset \
    --train_type lora \
    --save output \
    # ... 其他参数

6.3 模型推送与分享

训练好的模型可以推送到ModelScope或HuggingFace，方便团队共享：

# 推送到ModelScope
swift export \
    --adapters output/vx-xxx/checkpoint-xxx \
    --push_to_hub true \
    --hub_model_id 'your-username/your-model-name' \
    --hub_token 'your-token'

# 或者推送到HuggingFace
swift export \
    --adapters output/vx-xxx/checkpoint-xxx \
    --push_to_hub true \
    --hub_model_id 'your-username/your-model-name' \
    --hub_token 'your-hf-token' \
    --use_hf true