ms-swift命令行参数大全：新手避坑必备手册
1. 引言：为什么你需要这份参数指南？
你是不是也遇到过这种情况：兴致勃勃地打开终端，准备用ms-swift微调一个大模型，结果面对一堆命令行参数一头雾水？--train_type和--lora_rank到底怎么配？deepspeed zero2是什么鬼？训练中途显存爆炸了怎么办？
别急，这篇手册就是为你写的。
ms-swift是魔搭社区推出的一站式大模型微调框架，支持600+文本模型和300+多模态模型的训练、推理、评测与部署。它功能强大，但命令行参数繁多，新手很容易“踩坑”。本文不讲高深理论，只聚焦最常用、最容易出错的命令行参数，帮你快速上手，少走弯路。
我们不会照搬文档，而是从实际使用场景出发，把参数分类讲解，告诉你：
- 哪些是必填项？
- 哪些参数组合最容易出问题？
- 如何根据你的硬件选择合适的配置？
读完这篇，你就能自信地敲下每一条swift sft或swift rlhf命令。
2. 核心命令概览：ms-swift 的“主干命令”有哪些？
在深入参数细节前，先搞清楚ms-swift提供了哪些核心命令。它们是你所有操作的起点。
2.1 训练类命令
| 命令 | 用途 | 典型场景 |
|---|---|---|
swift pt | 预训练（Pre-Training） | 从零开始训练模型或继续预训练 |
swift sft | 监督微调（Supervised Fine-Tuning） | 最常用的指令微调，如 Alpaca 格式数据 |
swift rlhf | 基于人类反馈的强化学习 | DPO、KTO、GRPO 等偏好学习算法 |
提示：90% 的用户从
swift sft开始。如果你只是想让模型学会某种回答风格或任务，用它就够了。
2.2 推理与部署类命令
| 命令 | 用途 | 关键参数 |
|---|---|---|
swift infer | 本地推理 | --adapters加载 LoRA 权重 |
swift app | 启动 Web 交互界面 | --lang zh切换中文界面 |
swift deploy | 生产环境部署 | --infer_backend vllm启用加速 |
2.3 模型处理类命令
| 命令 | 用途 | 实用技巧 |
|---|---|---|
swift export | 导出/合并模型 | --merge_lora true合并权重 |
swift eval | 模型评测 | --eval_dataset ARC_c指定评测集 |
swift sample | 批量采样生成 | --num_return_sequences 5多结果对比 |
记住这三类命令，你就掌握了ms-swift的“操作地图”。接下来，我们重点拆解swift sft这个最常用的训练命令。
3. swift sft 参数详解：从零到跑通的第一步
swift sft是你微调模型的主力命令。下面这个例子包含了最常见的参数：
CUDA_VISIBLE_DEVICES=0 \ swift sft \ --model Qwen/Qwen2.5-7B-Instruct \ --train_type lora \ --dataset 'AI-ModelScope/alpaca-gpt4-data-zh#500' \ --output_dir output \ --num_train_epochs 1 \ --per_device_train_batch_size 1 \ --learning_rate 1e-4 \ --lora_rank 8 \ --max_length 2048我们逐个拆解这些参数的实际意义和常见误区。
3.1 必填参数：少了它们，命令直接报错
--model
指定你要微调的模型 ID 或本地路径。支持 Hugging Face 和 ModelScope 的模型。
--model Qwen/Qwen2.5-7B-Instruct # HF 风格 --model qwen2-7b-instruct # MS 风格 --model /path/to/local/model # 本地路径避坑提示：如果模型下载慢，可以提前用
modelscope download --model-id xxx下载好。
--train_type
训练方式。最常用的是lora，适合资源有限的用户。
| 类型 | 显存需求 | 适用场景 |
|---|---|---|
lora | 低 | 单卡微调 7B 模型 |
full | 极高 | 全参数微调，需多卡 |
qlora | 最低 | 4-bit 量化，显存紧张时用 |
建议：新手从
lora开始，稳定又省显存。
--dataset
指定训练数据集。可以是公开数据集 ID，也可以是本地 JSON/JSONL 文件路径。
--dataset AI-ModelScope/alpaca-gpt4-data-zh # 公开数据集 --dataset ./my_data.json # 本地文件 --dataset 'data1#500 data2#300' # 多数据集混合，数字为样本数注意：数据集格式必须符合
ms-swift要求（见后文数据格式说明）。
--output_dir
训练过程中保存 checkpoint 的目录。务必确保路径可写。
--output_dir ./output/qwen2-lora训练完成后，LoRA 权重就保存在这里，后续推理要用到。
3.2 批大小与显存控制：避免 OOM 的关键
显存不够是训练失败的头号原因。以下参数直接影响显存占用。
--per_device_train_batch_size
单张 GPU 的训练 batch size。越大越占显存。
- 7B 模型 + LoRA：建议设为
1或2 - 如果显存溢出，优先降低此值
--gradient_accumulation_steps
梯度累积步数。当 batch size 太小影响训练效果时，可以用它“凑”出更大的有效 batch。
--per_device_train_batch_size 1 --gradient_accumulation_steps 16 # 等效于 global batch size = 1 * 16 = 16技巧：先设
batch_size=1，再通过调整accumulation_steps控制总 batch。
--max_length
输入序列的最大长度。越长越占显存，尤其是显存占用呈平方增长（因为 attention）。
- 一般设为
2048或4096 - 如果训练时报
CUDA out of memory，优先尝试降到1024
3.3 LoRA 专属参数：调不好就学不会
LoRA 是轻量微调的核心技术，但它的参数设置很讲究。
--lora_rank
LoRA 的秩（rank），控制新增参数的维度。越大模型容量越高，但也越占显存。
| rank | 适用场景 |
|---|---|
| 8 | 快速实验，小数据集 |
| 32~64 | 正式训练，大数据集 |
| 128+ | 高精度任务，显存充足 |
经验：Qwen2-7B-Instruct 通常用
32或64。
--lora_alpha
LoRA 的缩放系数。一般设为lora_rank的 2~4 倍。
--lora_rank 8 --lora_alpha 32 # 常见搭配--target_modules
指定哪些模块应用 LoRA。默认all-linear会作用于所有线性层。
- 如果只想在注意力层加 LoRA，可用
--target_modules q_proj,v_proj - 多模态模型可能需要
--target_modules all包含视觉编码器
3.4 学习率与优化器：影响收敛速度的关键
--learning_rate
学习率。LoRA 微调通常用1e-4到5e-4。
- 太小：收敛慢
- 太大：loss 震荡甚至发散
建议：从
1e-4开始试，观察 loss 曲线。
--warmup_ratio
学习率预热比例。建议设为0.05到0.1，防止初期梯度爆炸。
--warmup_ratio 0.05 # 前 5% 的 step 线性增加学习率--optimizer
优化器类型。默认是AdamW，一般不用改。
3.5 日志与保存：方便调试和恢复
--logging_steps
每多少步打印一次 loss。
--logging_steps 5 # 每 5 步输出一次，便于观察训练状态--save_steps
每多少步保存一个 checkpoint。
--save_steps 50 # 频繁保存，防止单次训练中断损失进度--save_total_limit
最多保留几个 checkpoint。建议设为2或3，避免磁盘爆满。
--save_total_limit 24. 多模态训练参数：图文、视频任务特别注意
如果你在训练 Qwen-VL、InternVL 等多模态模型，以下参数必须关注。
4.1 图像相关参数
--max_pixels
单张图片的最大像素数。直接影响显存。
--max_pixels 518400 # 约 720x720，平衡清晰度与显存避坑：不要设太大！
1024x1024=1M像素很容易炸显存。
--vision_tower
视觉编码器名称。通常设为auto自动识别。
--vision_tower auto # 推荐，自动匹配模型除非你知道确切名称，否则别手动指定。
4.2 数据格式要求：必须符合 JSON 结构
ms-swift要求多模态数据为如下格式：
{ "id": "sample_0001", "messages": [ { "role": "user", "content": [ {"type": "image", "image": "/path/to/img.jpg"}, {"type": "text", "text": "图中有什么？"} ] }, { "role": "assistant", "content": [ {"type": "text", "text": "有一只猫。"} ] } ] }重要区别：这和
self-llm等教程的格式不同，不能直接混用。
格式转换脚本（Python）
import json def convert_self_llm_to_swift(input_file, output_file): with open(input_file, 'r', encoding='utf-8') as f: data = json.load(f) converted = [] for i, item in enumerate(data): new_item = { "id": f"sample_{i:04d}", "messages": [] } for conv in item["conversations"]: if conv["role"] == "user": content = [ {"type": "image", "image": conv["value"]}, {"type": "text", "text": "请描述这张图片。"} ] else: content = [{"type": "text", "text": conv["value"]}] new_item["messages"].append({"role": conv["role"], "content": content}) converted.append(new_item) with open(output_file, 'w', encoding='utf-8') as f: json.dump(converted, f, ensure_ascii=False, indent=2) # 使用示例 convert_self_llm_to_swift("input.json", "output_swift.json")5. 分布式与高级训练：进阶用户看这里
当你有更多 GPU 或想训练更大模型时，这些参数就派上用场了。
5.1 DeepSpeed 支持
--deepspeed zero2 # ZeRO-2 优化，减少显存 --deepspeed zero3 # ZeRO-3，更激进的显存优化需要配合 DeepSpeed 配置文件使用，适合多卡训练。
5.2 Megatron 并行
NPROC_PER_NODE=2 megatron sft --model ... --train_type lora适用于大规模集群训练，支持 TP/PP/CP 等并行策略。
5.3 量化训练（QLoRA）
--train_type qlora --quant_method bnb # 使用 bitsandbytes 4-bit 量化能让 7B 模型在 9GB 显存下训练，极致节省资源。
6. 总结：一份实用的参数检查清单
为了避免踩坑，每次运行swift sft前，建议对照这份清单检查：
6.1 基础配置检查
- [ ]
--model是否正确？ - [ ]
--train_type是否选对（lora/qlora/full）？ - [ ]
--dataset路径是否存在？格式是否正确？ - [ ]
--output_dir是否可写？
6.2 显存安全检查
- [ ]
--per_device_train_batch_size≤ 2？ - [ ]
--max_length≤ 2048？ - [ ]
--lora_rank≤ 64？ - [ ] 多模态任务
--max_pixels≤ 518400？
6.3 训练稳定性检查
- [ ]
--learning_rate在 1e-4 左右？ - [ ]
--warmup_ratio≥ 0.05？ - [ ]
--logging_steps和--save_steps设置合理？
只要按这个流程来，你的第一次ms-swift训练大概率能顺利跑通。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
