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 2

---

4. 多模态训练参数：图文、视频任务特别注意

如果你在训练 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星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。