LLaMA-Factory 是由国内开发者 hiyouga（郑远航）主导开源的 LLM 全流程微调框架，目标是让「把开源基础模型调成自己想要的模型」这件事从写训练代码变成配参数。它把数据加载、对话模板、参数高效微调、评估、导出到部署的完整链路封装成 Web 图形界面与命令行工具，用户只需指定「模型 + 数据集 + 训练参数」三个输入即可发起训练。截至 2025 年初，项目在 GitHub 获得 4 万以上 star，是中文社区使用最广泛的微调框架之一，长期位列 PyPI 热门工具包。 框架内置 100 多个主流模型族的适配层（LLaMA、Qwen、Mistral、DeepSeek、ChatGLM、Phi 等），内置 100 余个公开数据集，支持全参微调、LoRA、QLoRA、DoRA 以及 SFT、DPO、ORPO、KTO、PPO 等多种训练阶段与对齐算法，并提供 OpenAI 兼容的推理 API 和权重导出能力。本文从安装配置讲起，带你用 Web UI 和命令行各跑通一次 LoRA 微调，再深入核心能力、生产部署与常见坑位，最后用对比表说明它与 Unsloth、axolotl、MS-Swift 的选型差异。
掌握 LLaMA-Factory，等于拿到一条从开源基础模型到垂直领域私有模型的低成本微调流水线。这是企业 LLM 落地中最常被考察的工程技能之一，也是数据、算法、部署三类工程师的通用协作底座。
目录
速览卡是工具类内容的固定首屏模块：30 秒判断「这工具是什么、能不能商用、适不适合我」。
为什么需要 LLaMA-Factory：把微调从写代码变成配参数
传统方式下，微调一个开源大模型需要自己写训练循环、处理数据加载与对话模板、配置梯度累积与学习率调度，还要应对 transformers 库升级带来的兼容问题。这套样板工程通常要耗费数天，且极易在细节上出错——对大多数团队而言，真正想做的只是「用领域数据让模型变强」，而不是维护一套训练基建。
LLaMA-Factory 把这一过程收敛为「模型 + 数据集 + 训练参数」三个输入。模型侧内置 100 多个主流模型族的适配层；数据侧内置 100 余个公开数据集，按 alpaca、sharegpt 两种通用对话格式统一解析；训练侧支持全参微调、LoRA、QLoRA、DoRA 等主流方法。用户通过 LlamaBoard 图形界面或一份 YAML 配置发起训练，框架自动处理梯度检查点（用计算换显存的技术）、混合精度、断点续训等底层细节，训练产物还能一键启动 OpenAI 兼容的推理接口或导出为 GGUF 等部署格式。
与同类工具相比，LLaMA-Factory 的气质差异在于「全流程 + 低门槛」：Unsloth 专注训练加速，axolotl 是面向资深用户的 YAML 驱动工具，而 LLaMA-Factory 同时覆盖训练、评估、推理与导出，且文档和社区以中文为主，是国内团队落地微调的首选起点。
安装与环境配置：3 步就绪
步骤一·准备 Python 环境：要求 Python 3.9+，推荐 3.10/3.11。用 conda 或 venv 创建独立虚拟环境，避免与系统 Python 包冲突。若使用 NVIDIA GPU，确保已安装匹配的 CUDA 驱动，PyTorch 安装时会自动检测。
步骤二·安装框架：pip install llama-factory 安装 PyPI 稳定版；源码安装则克隆 GitHub 仓库后执行 pip install -e .，可拿到最新特性、示例配置与文档，官方教程默认推荐源码安装。
步骤三·验证安装：无参数运行 llamafactory-cli，能打印出 train、export、api、webui 等子命令列表即表示安装成功。
# 1. 创建虚拟环境conda create -n llama-factory python=3.11 -yconda activate llama-factory # 2. 方式一：安装 PyPI 稳定版pip install llama-factory # 方式二：源码安装（推荐，含示例配置）git clone https://github.com/hiyouga/LLaMA-Factory.gitcd LLaMA-Factorypip install -e . # 3. 验证llamafactory-cli
快速上手：10 分钟跑通第一个 LoRA 微调
最省心的路径是 Web UI（LlamaBoard）。它只是训练引擎的图形入口，底层与命令行完全一致，适合第一次跑通全流程；需要批量、可复现的训练时，再改用 YAML 配置加命令行。
1. 启动界面：执行 CUDA_VISIBLE_DEVICES=0 llamafactory-cli webui，浏览器打开 http://localhost:7860。
2. 在「模型名称」下拉框选择一个内置模型（如 Qwen2.5-7B-Instruct），第一次运行会自动从 Hugging Face 或 ModelScope 下载权重，也可直接填写本地模型路径。
3. 「微调方法」选 LoRA（低秩适配，冻结基座只训练少量参数的方法），「训练阶段」保持 sft（有监督指令微调），「数据集」勾选 alpaca_zh_demo、identity 这类内置小数据集。
4. 在「训练参数」区设置学习率 2e-4、训练轮数 1，输出目录填 saves/qwen2.5-7b/lora。
5. 点击「预览命令」检查无误后点「开始」，界面实时输出训练日志与损失曲线；训练完成后在「Chat」标签页可立即对话验证效果。
6. 命令行等价做法：把上述配置写成一份 YAML 文件。
训练完成后，如果只想快速验证效果，不必合并权重，可直接带 adapter（训练出的 LoRA 适配器目录）启动对话式验证。
model_name_or_path: Qwen/Qwen2.5-7B-Instructstage: sftfinetuning_type: loradataset: identity, alpaca_zh_demotemplate: qwenoutput_dir: saves/qwen2.5-7b/loranum_train_epochs: 1.0learning_rate: 2.0e-4
llamafactory-cli train lora_sft.yaml核心能力详解：5 大支柱
支柱一·训练方法与量化策略：支持全参微调、LoRA、QLoRA、DoRA。LoRA 冻结基座权重、只训练低秩适配矩阵，QLoRA 再把基座量化到 4bit，显存需求大幅下降——7B 模型在单张 24GB 消费级显卡上即可完成 QLoRA 微调。框架还集成 GaLore、BAdam、PiSSA 等进阶训练算法。
支柱二·多阶段训练与对齐算法：除 sft 外支持 pt（继续预训练）、rm（奖励模型）、ppo（强化学习）、dpo、orpo、kto、simpo（偏好优化）等阶段，可让模型从「会说话」进阶到「符合人类偏好」，例如用 DPO 减少幻觉、提升拒答质量。
支柱三·模型与数据集生态：模型侧覆盖 LLaMA、Qwen、Mistral、DeepSeek、ChatGLM、Yi、Phi、Gemma 等 100 多个模型族；数据侧内置 100 余个公开数据集，自定义数据集只需按 alpaca 或 sharegpt 格式整理成 JSON 文件，并在 data/dataset_info.json 中注册一行。
支柱四·三种使用形态：LlamaBoard Web 图形界面、llamafactory-cli 命令行、OpenAI 兼容 HTTP 推理 API。三者共用同一训练引擎：UI 面向交互调试，CLI 面向脚本化生产，API 面向快速接入现有应用。
支柱五·模型导出与部署衔接：llamafactory-cli export 可把 LoRA adapter 合并回基座权重、按 4bit 等精度量化导出，配合 llama.cpp、Ollama 等工具生成 GGUF 格式实现本地部署，满足数据不出域的私有化诉求。
生产部署与监控：从上线到运维
训练规模化：单机多卡训练通过 CUDA_VISIBLE_DEVICES=0,1,2,3 指定 GPU，配合 DeepSpeed 或 accelerate 启动分布式训练；训练中断后框架支持断点续训（checkpoint 内保存优化器状态），配合 --report_to wandb 把损失、学习率、显存占用实时上报到 WandB，便于团队协作监控。
推理部署路径：两条路线可选。路线一是 LoRA 不合并、直接由 llamafactory-cli api 启动带 adapter 的推理服务；路线二是先 export 合并导出全量模型，再交给 vLLM、SGLang 等高吞吐推理引擎或 Ollama 做边缘部署。前者适合快速验证，后者适合正式上线：
可观测性：训练阶段盯损失曲线与学习率调度，用 llamafactory-cli eval 在离线测试集上评估指令跟随与知识问答指标；上线后监控首 token 延迟、吞吐量、拒绝率及业务侧人工抽检比例。微调模型与基座模型的输出差异抽样对比，是发现灾难性遗忘（模型学会新任务却忘掉旧能力的现象）最直接的手段。
<p class="para-label">避坑清单：</p>
<ul class="dash-list"><li>版本兼容坑：LLaMA-Factory 对 transformers、torch 版本有要求，混装新旧版本会报模型加载或算子错误，务必用官方 requirements.txt 或源码安装锁定依赖。</li><li>数据集格式坑：alpaca 格式字段为 instruction/input/output，sharegpt 格式为 conversations，两种结构不能混用，格式错误会导致 loss 异常或训练不收敛。</li><li>模板选择坑：--template 必须与模型族匹配（如 Qwen 选 qwen、Llama 3 选 llama3），选错时训练能跑通，但推理时特殊 token 缺失、对话格式错乱。</li><li>量化基座合并坑：在 4bit 量化基座上训练的 LoRA 无法直接 merge 回量化权重，会得到错误结果；需要以全精度/半精度基座做合并，或保留 adapter 目录动态加载。</li><li>显存 OOM 坑：多卡训练时 batch size、梯度累积与显存需联动调整，优先开启梯度检查点（gradient checkpointing），再考虑 QLoRA 量化降显存。</li></ul>
llamafactory-cli api \ --model_name_or_path Qwen/Qwen2.5-7B-Instruct \ --adapter_name_or_path saves/qwen2.5-7b/lora \ --template qwen \ --finetuning_type lora
curl http://localhost:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"messages": [{"role": "user", "content": "你好"}]}'
| 维度 | LLaMA-Factory | MS-Swift | Unsloth | axolotl |
|---|---|---|---|---|
| 定位 | 全流程低代码微调框架（国产开源） | 阿里开源的训练-推理-部署全链路工具 | 专注 LoRA/QLoRA 训练加速的轻量库 | 资深用户向的 YAML 配置驱动微调工具 |
| 编排范式 | Web UI + CLI + YAML 配置三入口 | CLI 与 Python 脚本为主 | Python API / Notebook 驱动 | 纯 YAML 配置驱动 |
| 类型约束 | Python 3.9+，transformers 生态，单卡到多卡均可 | Python，适配阿里云与国产加速卡生态 | 依赖自研 CUDA 内核，适配主流 NVIDIA GPU | 强依赖 HuggingFace 生态与较新 transformers |
| 学习曲线 | 低（图形界面 + 中文文档） | 中（文档较全，需熟悉 CLI 约定） | 低（pip 安装即用，但需环境匹配） | 高（需理解 YAML schema 与 HF 底层机制） |
| 生态集成 | 100+ 模型族、100+ 内置数据集、GGUF 导出 | 自家 Qwen/通义系列支持最好，集成 vLLM | 速度对比基准完善，社区插件多 | 与 HF 生态深度绑定，实验复现方便 |
| 生产部署 | API 推理 + 合并导出接 vLLM/Ollama | 训练到部署端到端打通 | 训练产物需自行接外部推理框架 | 训练产物需自行接外部推理框架 |
| License | Apache 2.0 | Apache 2.0 | Apache 2.0（代码） | Apache 2.0 |
| 适合谁 | 中文场景、需要图形界面、快速交付的团队 | 阿里云生态、要覆盖训练到服务全链路 | 追求训练速度与显存极限的个体开发者 | 熟悉 HF 生态、要精细控制训练流程的资深团队 |
选型建议：中文业务场景、团队里算法与工程分工明确，优先 LLaMA-Factory——界面调试、脚本生产、导出部署一条龙；训练成本敏感、追求极致速度选 Unsloth；依赖阿里云且需要端到端服务选 MS-Swift；做研究复现、需要精细控制每个训练细节选 axolotl。
版本迭代
LLaMA-Factory 自 2023 年开源以来，从面向单模型的训练脚本逐步演进为全流程微调框架：0.8.x 阶段完成多模型适配与 Web 界面雏形；0.9.0 起统一 llamafactory-cli 命令入口、重构配置系统，确立了「Web UI + CLI 双入口」形态；此后以高频小版本跟进开源模型的发布节奏，并持续扩展对齐算法与导出能力（截至训练数据，可能已有更新版本，以 GitHub Releases 为准）。
| 版本 | 时间 | 变化 | 提升 |
|---|---|---|---|
| v0.8.4 | 2024-07 | 多模型与多模态适配扩充 | 完善主流模型族的训练适配，优化训练稳定性与 checkpoint 管理 |
| v0.9.0 | 2024-10 | 里程碑版本：CLI 与配置重构 | 统一 `llamafactory-cli` 命令入口，训练配置体系重写，LlamaBoard 能力增强 |
| v0.9.2 | 2024-12 | 新模型跟进与对齐算法完善 | 适配 LLaMA-3.1、Qwen2.5 等新发布模型，完善 DPO/ORPO 等偏好优化流程 |
| v0.9.3 | 2025-02 | 蒸馏模型与模板适配 | 跟进 DeepSeek-R1 蒸馏系列等新模型的训练与推理链路，新增配套对话模板 |
| v0.9.6 | 2025-04 | 模型覆盖与导出能力扩充 | 适配最新开源模型族变体，优化 GGUF 导出与 API 推理的多模型支持 |
LLaMA-Factory 本身是训练框架而非模型，官方不维护 MMLU 之类的模型能力榜单，因此无评测分数可列。版本间的实际差异体现在新模型适配速度、训练稳定性与工具链完整度上——选型时应重点确认它是否已支持你计划使用的基础模型版本，以及社区对该版本的反馈是否稳定。
AI 应用场景
垂直领域指令微调（法律/医疗/金融问答）
阶段：数据准备与 SFT 指令微调
解决的问题：通用模型不懂领域术语与业务规范，直接对话会出现编造法条、错误用药等风险。传统做法是收集数据后从零训练，成本高；用 LLaMA-Factory 只需把清洗好的问答对按 alpaca 格式整理，跑 LoRA 微调即可注入领域知识。
具体案例：某客服场景用 5000 条脱敏问答构成的 SFT 数据集，在两张 RTX 4090 上以 QLoRA 方式训练数小时完成一轮迭代，训练显存从全参微调的数十 GB 量级降至单卡 24GB 以内，一周内完成「数据清洗—微调—效果验证」闭环。
偏好对齐与幻觉抑制（DPO）
阶段：模型对齐（偏好优化）
解决的问题：SFT 只教模型「怎么答」，不教「什么该答」。面对不确定的问题，微调模型容易一本正经地编造答案。用 DPO（直接偏好优化）在「好回答/差回答」对上进行对齐，可显著降低幻觉与不当输出。
具体案例：在公开的偏好数据集（如 alpaca-gpt4 系列）上对 7B 级模型跑 DPO，单卡数小时即可完成一轮对齐，实测中模型对不确定问题的拒答率提升、编造率下降，且无需为 DPO 单独维护强化学习环境。
私有化部署与模型导出（数据不出域）
阶段：模型导出与边缘部署
解决的问题：金融、政务等场景要求数据与模型全部内网运行，不能调用公有云 API。微调产物需要脱离 Python 训练环境、以轻量格式运行。
具体案例：内部知识库模型微调完成后，用 llamafactory-cli export 把 LoRA 合并回基座、导出为 GGUF 格式，交给 Ollama 在内部服务器运行，单张推理卡即可承载业务访问，省去 GPU 训练集群的常驻成本。
常见误区
误区我从网上爬了几十万条数据，模型肯定能变聪明，训练久一点效果就上来了。
正解LLaMA-Factory 的官方最佳实践恰恰相反——数据质量、去重与格式规范远重要于数量。内置的 alpaca_zh_demo 只有百余条数据，用来验证流程可以，但直接用于生产会带来领域噪音与重复导致的过拟合。推荐从 1000～5000 条高质量、覆盖业务边界的数据起步，逐轮迭代。
为何常见：大模型预训练动辄 TB 级数据的印象被迁移到了微调阶段，而微调的本质是「教规矩」而非「灌知识」，两者数据策略完全不同。
误区LLaMA-Factory 是国产工具，应该只支持 Qwen、ChatGLM 这些国产模型。
正解框架的模型适配层覆盖 100 多个模型族，包括 LLaMA、Mistral、Phi、Gemma 等海外主流开源模型，以及 LLaVA 等多模态模型，适配方式统一为「模型名称 + 模板」配置，与模型来源无关。
为何常见：项目中文文档与国产模型案例曝光度高，容易让人忽略其模型适配的广度，实际其 GitHub 仓库的模型列表长期与 HuggingFace 热门榜同步。
误区4bit 量化肯定会严重损失精度，QLoRA 微调后的模型比全参微调差一大截。
正解QLoRA 论文及大量复现表明，4bit 量化 + LoRA 在多数下游任务上能逼近 16bit 全参微调的效果，差距通常在可接受范围内。LLaMA-Factory 的社区案例中，QLoRA 是资源受限团队的主流选择，显存节省约 3/4 而效果损失有限。
为何常见：把「量化推理有精度损失」的经验直接套到「量化训练」上，忽略了 QLoRA 通过分块量化与 LoRA 高精度适配器补偿了大部分量化误差。
误区训练完的 LoRA 权重是残片，必须 merge 回原模型，否则没法用。
正解完全可以直接用——推理时通过 --adapter_name_or_path 加载 adapter 目录即可，LLaMA-Factory 的 api 和 chat 命令都支持。合并导出主要是为了兼容 vLLM、Ollama 等外部推理引擎和简化部署形态，不是使用 LoRA 的前置条件。
为何常见：看到教程都在「导出合并后的模型」，误以为这是唯一用法；实际上保留 adapter 目录便于多个 LoRA 按任务切换，是更灵活的工程实践。
误区LlamaBoard 只适合新手点着玩，正式训练还得手写命令行才专业。
正解LlamaBoard 与 CLI 共用同一套训练引擎和配置项，界面上的每个参数最终都会映射为等价的命令行参数，它不是阉割版。真正的生产差异在于「交互 vs 脚本」：定时任务、多组超参实验用 YAML + CLI 更可复现，而调试、试跑用 Web UI 效率更高。
为何常见：图形界面常常与「演示工具」划等号，忽略了它只是训练引擎的前端封装这一事实。
面试题
Q1. LLaMA-Factory 的核心定位是什么？
- A.RAG 应用开发脚手架
- B.大模型微调与训练框架← 正确答案
- C.向量数据库管理系统
- D.边缘端模型推理引擎
答案：B。LLaMA-Factory 的主战场是模型训练与微调，覆盖 SFT、DPO 等训练阶段和 LoRA、全参等训练方法。它虽附带 OpenAI 兼容推理 API，但该能力服务于微调产物的快速验证，其本身不是 RAG 框架、向量数据库或推理引擎。
Q2. 启动图形化训练界面（LlamaBoard）的正确命令是？
- A.llamafactory-cli train --stage sft
- B.llamafactory-cli api --port 8000
- C.llamafactory-cli export --export_dir out
- D.llamafactory-cli webui← 正确答案
答案：D。webui 子命令启动 Gradio 服务，默认地址为 http://localhost:7860。train 是训练入口，api 是推理服务入口，export 是权重导出入口，三者功能不同，不能混淆。
Q3. 下列哪项不属于 LLaMA-Factory 内置能力？
- A.指令微调 SFT
- B.偏好对齐 DPO
- C.数据自动标注← 正确答案
- D.LoRA 微调
答案：C。LLaMA-Factory 消费已整理好的 alpaca/sharegpt 格式数据集，本身不提供数据标注服务，数据清洗与标注需要借助外部工具完成。SFT、DPO、LoRA 均为框架内置的训练能力。
Q4. 命令行训练时，将训练阶段指定为「有监督微调」的 --stage 参数值是？
- A.sft← 正确答案
- B.rm
- C.dpo
- D.pt
答案：A。stage 参数决定训练阶段：sft 为有监督指令微调，pt 为继续预训练，rm 为奖励模型训练，dpo 为偏好优化。这也是 LLaMA-Factory 中最常用的训练阶段配置。
Q5. QLoRA 相比 LoRA 的核心差异是？
- A.必须多卡并行训练
- B.训练时冻结全部参数
- C.基座权重量化至低位宽← 正确答案
- D.推理无需加载基座
答案：C。QLoRA 的核心是把基座模型权重量化到 4bit，只让 LoRA 适配器保持高精度训练，从而大幅降低显存占用。训练时并非冻结全部参数，LoRA 部分仍参与更新；推理时仍需加载量化后的基座权重。
Q6. LLaMA-Factory 采用的开源协议是？
- A.MIT 开源许可
- B.Apache 2.0 协议← 正确答案
- C.GPL 3.0 协议
- D.双许可含商业版
答案：B。项目采用 Apache 2.0 协议，允许商用、修改与再分发，且无 GPL 的传染性约束，也没有独立的商业版。这对企业集成到内部系统是友好的许可选择。
Q7. 在 4bit 量化基座上训练 LoRA 后直接执行权重合并会发生什么？
- A.合并失败或得到错误权重← 正确答案
- B.正常合并且无任何影响
- C.自动转为 8bit 后合并
- D.仅合并适配器即可
答案：A。merge 操作要求全精度或半精度的基座权重参与计算，量化基座上的 LoRA 无法直接合并出正确的全量模型。正确做法是保留原始全精度基座用于合并，或直接以 adapter 目录动态加载推理。
Q8. 训练配置中 --template 参数的作用是？
- A.仅影响日志格式
- B.用于指定学习率
- C.只影响界面显示
- D.决定对话模板格式← 正确答案
答案：D。template 对应模型的对话模板与特殊 token 组（如 qwen、llama3），训练时用于正确构造输入格式，推理时决定如何组织 system、user、assistant 消息。选错模板时训练未必报错，但推理输出会格式错乱。
Q9. 下列属于 LLaMA-Factory 官方提供接入方式的有？
- A.LlamaBoard 图形界面← 正确答案
- B.命令行工具 CLI← 正确答案
- C.移动端原生 App
- D.微信小程序入口
答案：AB。官方提供 LlamaBoard（Web UI）、llamafactory-cli（命令行）与 OpenAI 兼容 HTTP API 三种接入形式。项目不提供移动端 App 或小程序，这三种形态已覆盖调试、脚本化与生产接入。
Q10. 关于 LoRA 微调产物的使用，正确的做法有？
- A.动态加载 adapter 推理← 正确答案
- B.合并回基座后部署← 正确答案
- C.删除基座只留适配器
- D.LoRA 可无条件任意叠加
答案：AB。adapter 必须与基座权重配合才能推理，删除基座无法使用；不同 LoRA 叠加需考虑任务相关性与秩的匹配，不能无条件混用。动态加载（A）与合并部署（B）是官方支持的两条标准路径，前者适合多任务切换，后者适合对接外部推理引擎。
参考来源
- webpageLLaMA-Factory GitHub 仓库源码、Releases 更新日志与示例配置