LlamaFactory

LlamaFactory 快速入门

「不写训练代码，把 100+ 开源大模型微调成你自己的模型」——LlamaFactory（hiyouga/LlamaFactory）是一个统一高效微调框架，一套接口覆盖 LLaMA、Qwen、Mistral、Gemma、ChatGLM 等上百个 LLM 与 VLM 的预训练、SFT、DPO/KTO/ORPO、PPO 与奖励模型训练，内置 LoRA/QLoRA、FlashAttention-2、Unsloth 加速与 LlamaBoard WebUI。Apache-2.0，ACL 2024 论文。2026-10-06 核验：GitHub 75,319★ / 9,226 fork，最近一次 push 为 2026-09-28，仍在活跃迭代。

这是什么？适合谁？

LlamaFactory 解决的是开源模型落地的「最后一公里」：基座模型能力强但不懂你的业务，需要在私有数据上微调。传统路径是给每个模型写一套 HuggingFace transformers 训练脚本，换模型就要改代码；LlamaFactory 把「模型 × 训练方法 × 精度 × 加速后端」全部做成配置项，同一套 YAML 或 WebUI 点选就能切换，官方 README 列出的支持矩阵覆盖 100+ 模型。

适合人群：

• 要在私有数据（客服对话、行业文档、代码库）上微调开源模型的工程团队
• 想用 LoRA/QLoRA 在单卡消费级 GPU 上低成本微调的个人开发者
• 需要快速对比「多个基座模型 × 多种训练算法」效果的算法工程师

不适合谁：只想调用云端 API、完全不碰本地模型的应用开发者（用托管 API 更省事）；需要从零预训练百亿级模型的研究团队（这是另一个量级的工程）。

准备工作

• 硬件：LoRA/QLoRA 微调 7B 级模型，单张 16-24 GB 显存即可起步（QLoRA 4-bit 更低）；全参数微调需按模型规模准备多卡。无 GPU 也可用 CPU 跑通小模型流程验证
• 软件：Python ≥3.9，PyTorch ≥2.0；Windows 官方推荐在 WSL2 或 Docker 中运行
• 时间预算：装环境 + 跑通第一个 LoRA 微调（小数据集）约 1-2 小时
• 前置知识：了解「SFT 监督微调 / LoRA 低秩适配 / DPO 直接偏好优化」的基本概念，会读 YAML
• 数据：SFT 用 alpaca 或 sharegpt 格式的 JSON 数据集；官方仓库 data/ 目录自带示例文件可直接试跑

快速上手

第一步：安装

git clone https://github.com/hiyouga/LlamaFactory.git
cd LlamaFactory
pip install -e ".[torch,metrics]" --no-build-isolation

第二步：起 WebUI（零代码路径）

llamafactory-cli webui

浏览器打开提示的地址（默认 6006 端口），在 LlamaBoard 界面里依次选模型、选数据集、选训练参数，点击开始即可。这是官方文档为新手推荐的首选路径。

第三步：命令行 LoRA 微调（可复现路径）

llamafactory-cli train examples/train_lora/llama3_lora_sft.yaml

官方 examples/ 目录为每种训练方式准备了现成 YAML（SFT/DPO/预训练/奖励模型等），改模型名与数据集路径即可复用。

第四步：合并与导出

llamafactory-cli export examples/merge_lora/llama3_lora.yaml

把 LoRA 权重合并回基座模型，导出完整的可部署模型目录。

预期产出：一个在你自己的数据集上完成 SFT、可直接用 transformers 或 vLLM 加载部署的模型。

常见踩坑

1. Windows 直接 pip 安装报编译错误：官方文档明确 Windows 需 WSL2 或 Docker，原生 cmd/PowerShell 下依赖编译（如 bitsandbytes）常失败，别在原生 Windows 硬装。
2. 显存不足 OOM：先降 per_device_train_batch_size、开 gradient_accumulation_steps；再切 QLoRA（4-bit 量化）把显存需求压到最低档。
3. 数据集格式不对被静默跳过或报错：alpaca 格式要求 instruction/input/output 字段、sharegpt 要求 conversations 字段，混用会解析失败；先跑官方自带 data/identity.json 验证流程，再换自己的数据。
4. 新模型报「模板不存在」：新发布的模型可能尚未内置 chat template，等上游更新或按官方文档为自己的模型注册模板。
5. --no-build-isolation 漏写导致装包失败：官方安装命令显式带此参数，缺了它会与已有环境冲突，照抄官方命令最稳。
6. LoRA 微调后效果没变化：常见原因是训练轮数太少或学习率不合适，先用极小的过拟合测试（同一条数据训几十轮，确认 loss 能降下去）排除流程问题，再调参。
7. 合并导出后模型答非所问：多半是推理时没套用与训练一致的 chat template；用 llamafactory-cli chat 先在框架内验证，再迁移到部署侧。

常见问题 FAQ

Q1：LlamaFactory 和 HuggingFace TRL / Axolotl / Unsloth 是什么关系？

A：定位互补。TRL 是训练算法库（要写代码）、Axolotl 是配置化训练框架、Unsloth 是加速后端；LlamaFactory 的差异点是「100+ 模型支持矩阵 + 零代码 WebUI + 全训练方法覆盖」打包在一起，且可以直接把 Unsloth 当加速后端启用。

Q2：没有高端显卡能玩吗？

A：能。QLoRA 4-bit 微调 7B 模型的显存门槛在消费级范围（官方 README 给出不同精度档位的显存需求表），再小的模型（1.5B-3B）更宽松；纯 CPU 也能跑通流程，只是慢。

Q3：微调出的模型怎么部署？

A：导出合并后的模型就是标准 HuggingFace 格式目录，用 transformers 加载、或按官方文档用 vLLM 起服务均可；LoRA 权重本身也可以用 PEFT 方式加载而不合并。

Q4：支持哪些训练方法？

A：官方 README 列出：增量预训练、（多模态）SFT、奖励模型训练、PPO、DPO、KTO、ORPO；优化算法上有 GaLore、BAdam、DoRA、LoRA+、PiSSA 等，按 YAML 开关启用。

Q5：商业使用有什么限制？

A：框架本身 Apache-2.0 可商用；但微调用的基座模型各有自己的许可证（如 Llama 系列社区许可、Qwen 多数 Apache-2.0），商用前要核对你所选基座的许可条款。

权限、安全、成本与限制

• 许可：框架 Apache-2.0；基座模型许可各自独立，商用需逐一核对。
• 安全：私有数据微调可全程不出本机；注意数据集本身不要包含需要外发的敏感内容。
• 成本：软件免费；成本主要是 GPU 算力（自有显卡或按量租用云 GPU）。
• 限制：Windows 需 WSL2/Docker；新模型支持依赖上游适配节奏。本文基于 2026-10-06 抓取的官方文档站、GitHub 仓库与 API 数据撰写，未在本机实际训练模型，具体行为以官方文档最新口径为准。

小技巧

1. 第一次跑通请全程用官方 data/identity.json 小数据集，把环境问题与数据问题分开排查。
2. WebUI 里调好的参数可以直接导出为 YAML，转成命令行可复现的流水线。
3. 显存吃紧时优先降 batch size + 开梯度累积，比直接换小模型保留更多效果。
4. 训练前用 llamafactory-cli chat 先和基座模型对话记录基线，微调后对比才知道有没有提升。
5. 长文本训练开 FlashAttention-2（配置项 flash_attn: fa2），官方文档列为主要加速手段之一。

进阶学习方向

• 多模态微调：仓库对 LLaVA 系等 VLM 提供图像-文本 SFT 支持，做视觉问答类私有模型可从官方多模态示例入手。
• DPO/KTO 偏好对齐：SFT 之后用偏好数据做 DPO，是把「会答」提升到「答得像样」的关键一步，官方 examples 有现成 YAML。
• GaLore/BAdam 全参低资源优化：显存不够全参微调时的替代路径，官方优化算法章节有专门配置说明。
• Megatron Bridge 与多机训练：项目文档新增了 Megatron Bridge 章节，面向大规模分布式训练场景。

参考链接

• 官方文档
• GitHub 仓库
• 安装指南
• SFT 教程
• FAQ（GitHub issue #4614）