项目背景与定位
1.1 一句话定位
LLaMA-Factory（旧名 LLaMA-Efficient-Tuning）是北航博士生郑耀威（hiyouga）维护的、中文社区使用最广的"大模型一体化微调框架"。它把 100+ 主流模型、SFT/RM/DPO/PPO 等十多种训练方法、LoRA/QLoRA/GaLore 等高效微调算法、Web UI / CLI / YAML 三种入口，统统装在一个仓库里。
如果你在国内 LLM 社区里看过"训一个属于你自己 7B 模型"的教程，那概率有八九成会指向 LLaMA-Factory。它在 GitHub 上常年 70k+ stars，是开源 LLM 微调领域事实上的中文一号位。
1.2 为什么它会成为中文圈首选
2023 年初 Llama 1 泄露之后，社区涌现了大量"怎么训一个自己的 Llama"教程。当时面临的现实问题：
- 官方 PEFT + transformers + accelerate 组合配起来要写 200+ 行 Python；
- DeepSpeed + Megatron 等专业框架对单卡微调场景过于重；
- 早期社区方案对中文模型（ChatGLM / Baichuan / Qwen）支持有限；
- 文档基本英文，初学者上手成本高。
hiyouga 给出的答案是："我做一个统一的训练入口，把所有这些技术都封装到一份 YAML / 一个 WebUI 后面。" 第一版 ChatGLM-Efficient-Tuning 在 2023 年 4 月发布，扩展到 Llama 后改名 LLaMA-Factory，再后来支持模型越来越多，变成现在这个"模型 + 训练方法 + 加速后端"三维都铺满的样子。
它的成功离不开两个关键决策：
- 拥抱中文模型一等公民地位：Qwen、DeepSeek、Yi、ChatGLM、Baichuan、InternLM 都是第一时间适配；
- Web UI 让"没写过 PyTorch 的人也能微调"：拖拉拽即可启动 SFT，对纯应用层用户特别友好。
1.3 它和这些项目是什么关系
| 项目 | 关系 | 区别 |
|---|---|---|
| HF transformers | 底座 | LLaMA-Factory 重度调用，加了一层"训练管线" |
| HF Trainer | 底座 | 大部分 Trainer 继承自 HF Trainer，加了 LoRA/DPO/PPO 等 |
| PEFT | 直接依赖 | LoRA / QLoRA 都走 PEFT |
| DeepSpeed | 可选后端 | 提供配置，用户选用 |
| Unsloth | 可选后端 | 提供集成，加速 LoRA 训练 |
| Axolotl | 同类竞品 | 英文社区主流，配置风格类似 |
| ms-swift | 同类竞品 | 阿里魔搭出品，模型支持更激进 |
可以理解成：LLaMA-Factory = transformers + PEFT + TRL + 加速后端 + WebUI 的精装版本，专门为"想要 90% 主流场景 5 分钟跑起来"的用户优化。
1.4 设计哲学：覆盖广度 + 中文体验
读 LLaMA-Factory 源码会感受到几个特征：
- "模板系统"是核心：每个对话模型都有自己的 prompt 模板（Llama-2 用
[INST]、Qwen 用 ChatML、ChatGLM 用<|user|>），LLaMA-Factory 在src/llamafactory/data/template.py里维护了一份庞大的模板字典，让数据自动适配模型格式。 finetuning_args/training_args/model_args/data_args四套参数对象，每套都是@dataclass，把"模型选择 / 训练算法 / 加速后端 / 数据集"四个维度解耦。- Web UI 走 Gradio，前端代码不算多，但提供了完整的"训练 → 评测 → 对话试用 → 模型导出"闭环。
这种"广而全 + 中文为先"路线让它特别适合应用层团队和教学场景；缺点是仓库代码量比较大，新功能上线快但稳定性偶尔会受版本影响。
1.5 它适合用来做什么、不适合做什么
| 判断 | 典型场景 |
|---|---|
| ✅ 适合 | 中文 / 行业模型微调（电商问答、法律助手、医疗对话） |
| 单机 1-8 卡环境下做 SFT / DPO / LoRA / QLoRA | |
| 想用 WebUI 训练，不想写训练代码 | |
| 想在同一个工具内做"训练 → 评测 → 导出 → 部署"全流程 | |
| ❌ 不适合 | 千卡集群 + 千亿参数从零预训练 —— Megatron-LM / NeMo 更合适 |
| 想完全 PyTorch 原生、不引大量依赖 —— TorchTitan 更合适 | |
| 业务模型结构非常奇怪不在支持列表里 —— 自己写 transformers + TRL 更灵活 |
1.6 本书将怎么带你走完这趟旅程
本书的节奏会非常贴近"实战 + 配置项理解"：
- 第 2-3 章让你从安装到打开 Web UI 跑通第一个 LoRA SFT，给你信心；
- 第 4 章讲清楚数据格式，这是入门用户最容易踩坑的地方；
- 第 5 章逐字段拆解 YAML 配置；
- 第 6-8 章核心训练方法：SFT、DPO 系列、PPO/GRPO；
- 第 9 章多模态微调（很多人冲着 Qwen2-VL / LLaVA 而来）；
- 第 10 章怎么把 DeepSpeed / FSDP / Unsloth 等加速后端接上；
- 第 11-12 章踩坑合集 + 模型导出量化部署；
- 第 13 章源码导读，让你下次给项目提 PR 时知道改哪里。
读完之后你应该能从"看着 README 跑命令"升级到"理解每个参数为什么这么填，能对自己的业务做合理裁剪"。
1.7 LLaMA-Factory 在 2025 的演进时间线
仓库根目录 README.md 顶部一长串的 "Changelog" 是写得最严肃的"我们做了什么"清单。下表按时间倒序整理本书基线 commit 01398eb18dd4 当时已合入的关键节点，每条都给你绑后续章节：
| 时间 | 特性 / 模型 | 说明 | 本书章节 |
|---|---|---|---|
| 2025-10-26 | Megatron-core 训练后端 | 通过 mcore_adapter 接入；千亿/万亿模型走 Megatron 路径 | ch10.10 / ch13.10 |
| 2025-08-22 | OFT / OFTv2 适配方法 | 正交微调，PEFT 体系内 LoRA 之外的新选择 | ch06.10 / ch10.6 |
| 2025-08-20 | Intern-S1-mini 支持 | 书生 S1 系列小模型 | ch05.2 模型矩阵 |
| 2025-08-06 | GPT-OSS 模型族 | OpenAI 开源模型支持 | — |
| 2025-07-02 | GLM-4.1V-9B-Thinking | 视觉思考链 VLM | ch09 |
| 2025-04-28 | Qwen3 Day-0 支持 | Qwen3 发布当天即可微调 | ch03 / ch05 默认基座 |
| 2025-04-21 | Muon 优化器 | 非 Adam 的新优化器，长训练更省显存 | ch10.7 |
| 2025-04-16 | InternVL3 | OpenGVLab 视觉语言模型 | ch09.6 |
| 2025-04-06 | Llama 4 多模态 | Day-1 支持 MoE + VLM | ch09 / ch10 |
| 2025-03-31 | Qwen2.5 Omni（音视频） | 原生音频 / 视频输入 | ch09.7 |
| 2025-03-15 | SGLang 推理后端 | 较 vLLM 部分场景快 25–270% | ch12.8 |
| 2025-03-12 | Gemma 3 | Day-0 支持 | ch05.2 |
| 2025-02-24 | EasyR1 / GRPO | R1 风格 RL 训练框架接入 | ch08.8 |
| 2025-02-11 | Ollama modelfile 导出 | 训完直接出 Ollama 兼容包 | ch12.9 |
| 2025-02-05 | 音频理解（Qwen2-Audio / MiniCPM-o） | — | ch09.7 |
| 2025-01-31 | DeepSeek-R1 / Qwen2.5-VL | Day-1 R1；Day-0 Qwen2.5-VL | ch09 / ch12 |
| 2025-01-15 | APOLLO 优化器 | Hessian-aware 低秩优化 | ch10.7 |
| 2025-01-10 | Phi-4 支持 | — | — |
整体趋势："模型 Day-0 支持 + 训练后端不断扩 + 量化推理后端不断扩"。这本书把 2026 春以前进的所有特性梳到对应章节，新手读完 ch04–ch10 这条主线就能跟上节奏。