微调框架 ms-swift 与 LLaMA-Factory

人工智能

发布日期: 2026-11-05

更新日期: 2026-11-05

文章字数: 3.8k

阅读时长: 14 分

阅读次数:

ms-swift 常被一句话介绍成”魔搭版的 LLaMA-Factory”。这个说法对了一半：功能清单层面两者确实高度重合；但对的另一半在清单之外——生态位、模型覆盖、大规模训练的集成度，这三处差异决定了”什么场景该选谁”，而不是”谁比谁好”。本文把两者从功能、命令、数据、显存到部署逐环节对齐，最后收敛成一张选型表。

一、功能清单：确实高度重合

把两边 README 的能力清单摆在一起：

维度	ms-swift（魔搭官方）	LLaMA-Factory（社区项目）
出身	魔搭社区（阿里）官方框架	北航开源的社区项目，ACL 2024 系统演示论文
起源	2023-08	2023-05
Star（2026-11）	约 1.6 万	约 7.6 万
训练任务	预训练、SFT、DPO/KTO/CPO/SimPO/ORPO/RM/GKD，另含 Embedding/Reranker/序列分类	预训练、（多模态）SFT、奖励建模、PPO/DPO/KTO/ORPO
强化学习	内置 GRPO 族：GRPO、DAPO、GSPO、SAPO、CISPO、CHORD、RLOO、Reinforce++	主仓库不内置，GRPO 拆给姊妹项目 EasyR1
轻量微调	LoRA/QLoRA/DoRA/LongLoRA/LLaMA-Pro/LoRA-GA/ReFT/LISA/GaLore/UnSloth/Liger 等	LoRA/QLoRA/DoRA/LongLoRA/LLaMA-Pro/OFT/GaLore/UnSloth/Liger 等
分布式	DDP、DeepSpeed ZeRO2/3、FSDP/FSDP2、Megatron（TP/PP/SP/CP/ETP/EP/VPP）	DDP、DeepSpeed、FSDP、Megatron-core（2025-10 经 mcore_adapter 接入）
推理与部署	集成 vLLM/SGLang/LMDeploy，`swift deploy` 起 OpenAI 兼容服务	vLLM/SGLang worker，OpenAI 风格 API
量化导出	AWQ/GPTQ/FP8/BNB	AWQ/GPTQ/BNB
交互	CLI、Web-UI、Python（兼容 PEFT 接口）	CLI、LLaMA Board WebUI、YAML 配置
硬件	NVIDIA、AMD ROCm、昇腾 NPU、MetaX、摩尔线程（MUSA）、Apple MPS、CPU	NVIDIA CUDA 为主，另适配 AMD、昇腾 NPU
许可证	Apache-2.0	Apache-2.0

单看这张表，”又一个微调框架”的第一印象得到了证实：任务面几乎完全重合，差异都是”多几个少几个”的量级。如果你只是要给一个 7B 模型跑一次 LoRA SFT，选哪个都不会错，从一个迁到另一个的成本低于一天。

二、重合的根因：同一副骨架

这不是巧合。两个框架都构建在 Hugging Face transformers 的 Trainer 体系上——训练循环、优化器、梯度累积、混合精度这些底层机制全是现成的，框架做的是封装：模型注册（model id 到配置的映射）、数据集接入、对话模板管理、分布式启动脚本。

这也解释了为什么两者的参数几乎一一对应：per_device_train_batch_size、gradient_accumulation_steps、learning_rate 两边同名同义，一份训练经验可以无损迁移。差异全部落在封装层——也就是下面几节要展开的地方：数据怎么喂、卡怎么开、模板怎么管、训完怎么接部署。

顺带一提，两家官方 QuickStart 撞了同一个示例任务：把模型微调成自称你起的名字（自我认知微调）。这不是巧合——它是验证”数据、训练、推理”链路通没通的最小任务，建议任何人上手新框架都从它开始。

三、同一件事，两条命令

同一次微调（Qwen2.5-7B 做 LoRA SFT），两边的最小命令长这样。先是 ms-swift：

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 \
    --gradient_accumulation_steps 16 \
    --learning_rate 1e-4 \
    --target_modules all-linear \
    --max_length 2048 \
    --output_dir output \
    --model_name swift-robot \
    --model_author halensea

LLaMA-Factory：

FORCE_TORCHRUN=1 \
llamafactory-cli train \
    --model_name_or_path Qwen/Qwen2.5-7B-Instruct \
    --stage sft \
    --finetuning_type lora \
    --template qwen \
    --dataset identity,alpaca_gpt4_zh \
    --lora_target all \
    --per_device_train_batch_size 1 \
    --gradient_accumulation_steps 16 \
    --learning_rate 1e-4 \
    --num_train_epochs 1 \
    --output_dir output

四个值得注意的工程差异：

数据的引用方式不同。ms-swift 的 --dataset 可以直接写魔搭数据集 ID，后缀 #500 表示只取前 500 条——线上数据集一条命令拉下来就能训。LLaMA-Factory 的数据集要先在 data/dataset_info.json 里注册（登记文件路径和格式），再用数据集名引用。前者上手快，后者显式可控，多人协作时不容易出现”悄悄用了哪个数据版本”的歧义。

模板的指定方式不同。LLaMA-Factory 要求显式传 --template qwen；ms-swift 从模型配置自动推断模板，必要时可覆盖。看起来 ms-swift 省事，但要注意：自动推断依赖它的模型注册表，冷门模型或自定义结构走不到时，还是得手动确认——模板这个坑下一节专门讲。

多卡的启动方式不同。ms-swift 用环境变量 NPROC_PER_NODE=2 控制进程数；LLaMA-Factory 用 FORCE_TORCHRUN=1 强制走 torchrun，配合 --deepspeed examples/deepspeed/ds_z2_config.json 指定 ZeRO 配置。语义等价，都是 torchrun 封装，但报错时排查栈不一样。

自检信息的存放方式不同。ms-swift 的每个 checkpoint 目录里存有完整的 args.json，后续 swift infer/export/deploy 只需 --adapters 指向 checkpoint，训练参数自动回读；LLaMA-Factory 靠你引用同一份 yaml 配置。两者都解决了”训完忘了当时参数”的问题，但 ms-swift 的方案跟 checkpoint 绑定，跨机器拷贝时更自洽。

四、训练环节的三个工程问题

数据格式

ms-swift 主推 OpenAI 风格的 messages 格式——一条 JSON 一组对话，与部署后的 API 请求结构一致，训练数据、系统提示词、多模态字段（图片路径等）都能放进同一 schema：

&#123;"messages": [&#123;"role": "system", "content": "你是一名测试工程师"&#125;,
              &#123;"role": "user", "content": "根据需求生成测试用例"&#125;,
              &#123;"role": "assistant", "content": "..."&#125;]&#125;

LLaMA-Factory 支持两种社区惯用格式：Alpaca（instruction/input/output 三字段，适合单轮任务）和 ShareGPT（conversations 数组，from: human/gpt 交替，适合多轮）。

两边迁移不难：messages 与 ShareGPT 是键名映射的关系，Alpaca 是它的单轮特例，20 行脚本的事。真正要过一遍的是 schema 漂移——role 的命名习惯、多模态图片字段的位置、工具调用消息的编码，这些在自动转换脚本里最容易漏。

显存与多卡

以 7B 模型为参照的量级（官方文档口径）：

QLoRA（4bit）：6~9GB，单卡 4090/3090 从容跑通，消费级显卡做微调实验的默认起点
LoRA（bf16）：约 16GB 上下，单卡 24GB 可用
全参 SFT：权重加 AdamW 优化器状态加梯度，约是权重体积的四五倍，单卡放不下——用 DeepSpeed ZeRO-2/3 或 FSDP 把状态摊到多卡，两个框架都支持，配置文件改一行的事

一个常被忽略的点：LoRA 合并之后，推理显存就等于模型本身的大小，与训练方式无关。省钱省在训练侧，部署侧的账要按合并后的完整模型算。

头号坑：对话模板一致性

微调领域最常见的翻车不是显存爆了，而是训练与推理用了不同的对话模板：训练时模板带思考标签、推理时不带，模型学到的是一种对话分布、上线后面对的是另一种，表现为答非所问或复读。排查这类问题先查模板，再查数据。

两个框架的解法一致但强制性不同：ms-swift 把模板选择写进 args.json，推理部署时自动沿用；LLaMA-Factory 需要你在训练、chat、API 三个环节传入同一个 --template。无论哪个框架，把模板当成和数据同等级的契约来管理——它是训练与部署之间的接口。

五、训练之后：合并、部署、评测的衔接

微调的产出是一个 adapter，不是可上线的服务。全链路的五条命令，两边对照：

环节	ms-swift	LLaMA-Factory
训练	`swift sft`	`llamafactory-cli train`
试推理	`swift infer --adapters output/vXX/checkpoint-XXX`	`llamafactory-cli chat --adapter_name_or_path ...`
合并权重	`swift export --adapters ... --merge_lora true`	`llamafactory-cli export --adapter_name_or_path ...`
起服务	`swift deploy --model merged_dir`	`llamafactory-cli api --model_name_or_path merged_dir`
跑评测	`swift eval --eval_dataset mmlu`	`llamafactory-cli evaluate --task mmlu`

三点工程提醒：

合并还是动态加载。adapter 可以不合并直接挂载推理（省存储、一个基座挂多个 adapter），但推理引擎对动态 LoRA 的支持与性能都弱于合并后的完整权重；生产环境默认合并，然后用 vLLM/SGLang 起服务。推理引擎本身的选型（吞吐、并发、量化方案）是另一个话题，见《大模型推理部署：vLLM、SGLang 与 Ollama 对比》。

别用公开基准验证微调效果。框架内置的 eval 跑 MMLU/CEval 只能证明”模型没训坏”，证明不了”业务上变好了”。验证微调效果要用与训练数据同分布的留出集，最好在训练前就切好、冻结住——数据泄漏进训练集的评测是自欺，这个问题在《大模型评测：公开基准、数据污染与自建评测集》里展开过。

数据量级先说清。50~200 条数据能把链路跑通，验证的是工程不是效果；正式微调建议 1k 条以上起步。框架解决的是”训练怎么跑”，而后训练工作的大头在数据构造与效果验证——《后训练模型的产生：基座 SFT 对齐推理部署》讲的就是这条流水线全景。

六、真正的分野在哪

前三节讲的是重合的部分，这一节讲分野。

1. 生态位：官方框架与社区框架不是一个活法

ms-swift 是魔搭（ModelScope）的官方训练框架，背后是阿里的全职团队。最直接的体现是硬件清单：README 里明列 NVIDIA、AMD ROCm、昇腾 NPU、MetaX、摩尔线程 MUSA、Apple MPS、CPU——国产算力是官方适配的义务而非社区 PR。数据集与模型走魔搭 Hub，国内网络下加载速度与合规性都是现成的。

LLaMA-Factory 是北航开源的社区项目，7.6 万 star、ACL 2024 论文、被多家大厂采用，HF 生态里的默认微调入口。它跟模型的速度也不慢（README 里有 Day-N 支持表，Qwen3 发布次日即支持），但驱动方式是社区热情而非商业义务。

选型含义：你的模型、数据、算力如果主要在魔搭生态或国产硬件上，ms-swift 是顺路的；如果是 HF 生态加 CUDA 集群，LLaMA-Factory 是顺路的。逆着生态走也能用，只是每个环节都多一点摩擦。

2. 模型覆盖：多模态上差了一个数量级

ms-swift README 口径：600+ 纯文本大模型、400+ 多模态大模型，覆盖 Qwen3-VL、Qwen3-Omni、Kimi-K3、InternVL3.5、GLM4.5-V、DeepSeek-VL2、Ovis2.5 等，直到 All-to-All 全模态模型；LLaMA-Factory 口径是 100+ 模型，多模态覆盖 Qwen-VL 系、InternVL、GLM-4.1V 等主流款。

数量差异的背后是模态工程的深度：视频、音频、全模态任务的训练样例、数据格式、显存优化，在 ms-swift 的文档里是一等公民；LLaMA-Factory 的多模态更像”支持了主流几款”。如果你的目标是微调一个多模态模型，ms-swift 大概率先撞不到墙。

3. RL 与 Megatron：集成与拆分两种哲学

这是两者技术路线差异最大的地方，也是最容易被清单掩盖的地方。

强化学习：ms-swift 把 GRPO 族算法全集内置——GRPO、DAPO、GSPO、SAPO、CISPO、CHORD、RLOO、Reinforce++，配同步/异步 vLLM 推理引擎做 rollout，奖励函数、多轮调度器、环境都用插件扩展。LLaMA-Factory 的主仓库保留 PPO/DPO/KTO/ORPO 等对齐训练，GRPO 在 2025 年初拆给了姊妹项目 EasyR1——一个专注 RL 的独立框架，支持多模态 GRPO。一个是”全家桶”，一个是”专项工具箱”，两种哲学没有高下，但决定了你的 RL 工程长在哪个仓库里。

大规模训练：两边都接了 Megatron，但成熟度不同。ms-swift 的 Megatron-SWIFT 是主线能力，并行策略覆盖 TP/PP/SP/CP/ETP/EP/VPP，从 2025 年 7 月支持 LoRA、9 月支持多模态、11 月支持 GRPO（外加 Mcore-Bridge 降低使用门槛），到 2026 年已有 DeepSeek-V4.1 级别 MoE 模型全参训练的官方实战文档；官方称在 MoE 模型上提速显著。LLaMA-Factory 的 Megatron-core 后端 2025 年 10 月才经 mcore_adapter 接入，还在早期。结论：数百亿以上的 MoE 多机训练，ms-swift 的路更宽、文档更厚；单机两卡的常规微调，这条差异与你无关。

4. 一处反向差异：教程生态

ms-swift 的文档（readthedocs，中英双语）写得规整，但社区声量明显小于 LLaMA-Factory——后者中文教程铺天盖地，踩坑一搜就有前人答案。用 ms-swift 遇到边角问题，更多时候要自己啃源码和 issue。选社区声量小的框架，要接受这份隐性成本。另外 ms-swift 的大版本切换有过破坏性变更（2 到 3），生产环境记得锁版本。

七、选型决策表

你的场景	建议
第一次微调，单卡，靠搜索教程过坑	LLaMA-Factory
微调多模态模型（图像/视频/音频/全模态）	ms-swift
MoE 大模型的多机全参或 GRPO 训练	ms-swift（Megatron-SWIFT）
RAG 场景微调 Embedding/Reranker	ms-swift
昇腾、MetaX、摩尔线程等国产算力	ms-swift
团队深度绑定 HF 生态，已有成熟流水线	LLaMA-Factory，不必迁移
RL 训练想要工程化拆分	LLaMA-Factory 主仓库加 EasyR1

两行背景判断：单机 LoRA/SFT 的常规场景下，两者迁移成本很低，选哪个都不亏，别让选型占用超过半天；需要换框架的信号通常不是功能缺失，而是你撞上了它的封装边界——模型注册表里没有你的模型，或者数据格式拧不过来。

八、局限

时效性。本文数字取自两个仓库 2026 年 11 月的 README，两边都在快速互抄长板——LLaMA-Factory 接入了 Megatron，ms-swift 在补易用性（Mcore-Bridge、Web-UI）——这些差异窗口会持续收窄，读本文时建议以仓库现状为准。

没有跑对照实验。Megatron 提速幅度、RL 训练效率这类性能结论引自官方文档口径，本文未做独立基准；涉及大规模训练的决策，建议以自己场景的实测为准。

视角偏工程选型。两个框架的源码架构、二次开发成本没有展开；如果你要改框架本身而不只是用它，需要另做调研。

参考

modelscope/ms-swift — 魔搭官方微调部署框架（Apache-2.0）
ms-swift 官方文档 — 含 Quick-Start、Megatron-SWIFT、GRPO 全套中文文档
hiyouga/LLaMA-Factory — 社区微调框架，ACL 2024 系统演示论文（Apache-2.0）
hiyouga/EasyR1 — LLaMA-Factory 官方推荐的多模态 RL 训练框架
LLaMA-Factory 论文 — LLaMA-Factory: A Unified No-code Fine-tuning Framework for Large Language Models