大概在半年前我第一次把hiyouga/LlamaFactory这个仓库拉到本地。当时正被一堆微调脚本折腾得够呛——不同模型要写不同的加载逻辑LoRA、全参微调各搞一套代码数据格式稍微不一样就得改半天。看到这个项目之后我第一反应是竟然有人把LoRA、QLoRA、全参微调、甚至DPO偏好对齐全部塞进同一个框架还能用一行命令启动可视化界面。后来我在多个垂直场景里用 LlamaFactory 跑了十几轮微调实验从中文指令优化到领域知识注入越用越觉得这套工具解决了很多实际痛点。如果你正在折腾大模型微调想快速验证某个基座模型在特定任务上的表现或者想给团队内部做一个私有化的指令助手又不想从零去写训练、评估、导出这一整套胶水代码LlamaFactory 基本上是目前社区里最顺手的方案之一。它对新手友好对老手也够用底层支持大量开源模型内置多种训练方式数据集准备和导出流程都被高度封装。你只需要准备一份符合规范的数据文件选好基座模型剩下的训练、评测、导出它都给你安排得明明白白。要顺利上手 LlamaFactory你最好先有一点大模型微调的基础概念比如知道 SFT 是什么意思LoRA 是在做什么再有一点 Linux 和 Python 的使用经验就足够了。下面我会从项目设计思路、核心功能拆解、实际微调流程和踩坑记录这些角度把这一路实操下来的经验完整梳理一遍希望能帮你少走弯路。1. LlamaFactory 项目整体与设计思路1.1 为什么需要这样一个统一微调框架如果自己去搭建大模型微调流程通常会遇到几个绕不开的麻烦首先是模型加载方式不统一HuggingFace Transformers 的 AutoModel 虽然能省点事但不同模型族的对话模板、tokenizer 细节差异很大处理不好很容易出现训练时正常、推理时胡言乱语的问题。其次是训练方式分散LoRA 要用 PEFT全参微调要自己写 Trainer 的 wrapperDPO 又需要额外的数据格式和loss实现每个模块都是独立的坑。LlamaFactory 的核心贡献在于把这些散落的东西整合到了一起。它基于 HuggingFace Transformers、PEFT、TRL、Datasets 等成熟库做了一层封装对外提供统一的数据接口和训练入口。你在配置里声明一下“我要用 LoRA 训练这个模型”它就会自动帮你加载 base model、初始化 LoRA adapter、设置好 optimizer 和 scheduler然后把训练循环跑起来。这种封装的好处是你不必关心 PEFT 的版本冲突不必自己拼接 tokenizer 的 chat template也不必为了一个 DPO 实验去翻 TRL 的文档。更重要的是LlamaFactory 把实验管理也考虑进去了。它的输出目录里会自动保存训练参数、模型权重、评估结果方便你对比不同实验。这一点在实际项目中非常有用因为微调往往不是一次就能成功的你可能要试不同的学习率、不同的 LoRA rank、不同的数据混合比例没有统一的结构化输出乱七八糟的实验文件夹会让人崩溃。1.2 支持的模型家族与可扩展性LlamaFactory 的模型支持矩阵非常广。它支持 LLaMA 系列、Qwen 系列、Baichuan 系列、ChatGLM 系列、Mistral/Llama2 衍生系列、Phi 系列、Yi 系列、DeepSeek 系列等等基本覆盖了主流开源基座模型。而且它的模型注册机制做得不错新增一个模型族通常只需要在src/llamafactory/model/下补上对应的 config复用已有训练逻辑即可。社区里也有不少人用它对 Baichuan、Qwen 做领域微调跑起来很顺畅。多模型支持的意义在于你可以方便地做基座选型实验。同一个数据集分别用 Qwen、Yi、Baichuan 跑一遍 LoRA比较它们在目标任务上的表现最终选出最合适的基座。这在以前是件挺麻烦的事因为每个模型的加载代码、对话模板都要单独适配而 LlamaFactory 把这一层全部标准化了。切换模型基本上就是改一行配置的事我实测下来从 Qwen 切到 Baichuan除了下载权重需要花时间代码层面几乎零改动。它还支持来自 ModelScope 的模型权重这对国内用户非常友好。因为直接从 HuggingFace 拉权重经常遇到网络问题通过 ModelScope 可以把下载速度提升不少而且 LlamaFactory 也支持本地权重目录你提前下好模型文件放到本地路径训练时直接指定即可。1.3 生态位置与典型应用场景LlamaFactory 在开源大模型微调工具链中的位置有点像“统一训练入口”。它既不自己实现底层算子也不去搞分布式的极端优化而是把现有成熟组件拼装得更顺手。这也决定了它最适合的场景是中小团队和个人开发者在单卡或多卡环境下对开源模型做指令微调、增量预训练、偏好对齐以快速获得一个可用模型原型。我实际用下来主要有三类场景很典型一是垂直领域问答模型比如企业内部知识库问答用业务数据微调一个基础模型让它的输出风格更贴合企业口径二是角色化对话或写作风格迁移通过几百到几千条风格样本让模型学会特定语气三是任务型模型的定制比如信息抽取、文本分类把下游任务转换成指令格式之后微调效果通常比直接 prompt 稳定得多。 LlamaFactory 在这些场景下都能很好地覆盖整个闭环数据准备、训练、评估、导出一个工具走完。2. 核心功能解析与关键概念2.1 LoRA、QLoRA、全参微调到底怎么选LlamaFactory 内置了多种训练方式最常用的三个是 LoRA、QLoRA 和全参微调。很多人第一次接触会纠结选哪个我的经验是先看显存再看数据量最后看你对效果的需求。全参微调Full Fine-Tuning是最朴素的方法更新模型全部参数效果上限最高但显存开销也最大。以 7B 模型为例全参微调的峰值显存通常需要 80GB 以上即便用闪存优化单卡也不容易跑起来。它适合你有充足的多卡资源并且数据量足够大的情况比如几十万条以上指令数据。如果数据量不大全参微调反而容易过拟合而且微调后的模型可能存在灾难性遗忘把原有的通用能力毁掉。LoRA 是现在的主流选择。它的原理是在原始权重旁边插入低秩分解的可训练矩阵训练时冻结原模型大部分参数只更新这些小矩阵。原始权重不变所以推理时可以把 LoRA 权重合并回原模型也可以单独保存为一个几十到几百 MB 的 adapter。对于 7B 模型LoRA 微调的单卡显存需求可以降到 16GB 到 24GB 之间效果在很多任务上与全参微调差距不大是性价比极高的方案。LlamaFactory 的 LoRA 实现做得比较成熟各目标模块比如 q_proj, v_proj 等可以灵活配置。QLoRA 则是 LoRA 的一种极限优化。它先把基座模型量化到 4-bit 或 8-bit再在量化后的模型上插入 LoRA 适配器进行训练。这样 7B 模型的训练显存可以压到 6GB 到 10GB 左右很多消费级显卡都能跑。代价是训练速度比普通 LoRA 慢一些量化过程也可能带来轻微精度损失。但如果你只有一块 8GB 或 12GB 显存的卡QLoRA 基本上是把大模型微调变成现实的最可靠路径。我自己的建议是能用 LoRA 就不碰全参显卡吃紧就上 QLoRA。两者在 LlamaFactory 里只是配置项不同并不影响数据准备和后续导出流程所以可以先从 QLoRA 跑通流程再把参数升级到 LoRA 看效果。2.2 数据集格式与指令微调的数据准备LlamaFactory 对数据格式做了统一约定。最常用的是指令微调Supervised Fine-Tuning数据支持这样的 JSON 格式每一条样本是一个对象包含instruction、input和output字段。当有额外上下文输入时放到input里没有 context 时input可以为空字符串。多个样本组成一个 JSON 数组保存成.json或.jsonl文件。它还可以用system字段指定系统提示词以及history字段传递多轮对话历史。实际构造数据的时候很多新手会犯一个错误把 prompt 写得太复杂甚至把整个背景知识都塞到每一条instruction里这样数据集会非常臃肿。更合理的做法是把指令设计得简洁明确把背景资料放到input字段让模型学会结合上下文回答问题。比如你要做一个客服问答数据集指令可以是“基于以下商品信息回答用户的问题”商品信息放input期望输出放output。这样训练出来的模型泛化性会更好。另外很重要的一点数据量并不是越多越好。指令微调的核心是让模型学会格式和风格而不是从零灌输知识。对于风格迁移或格式学习几千条高质量样本就足够了对于领域知识注入也要先考虑数据覆盖率和答案质量而不是盲目堆数量。我见过有人用 100 万条自动扒来的弱标注数据微调结果模型反而变傻了就是因为噪声太大了。LlamaFactory 的配置文件里通过dataset字段指定数据集目录下的文件列表你可以同时加载多个数据集并且用dataset_mixer按比例混合。这在实践中很关键。比如我经常会把一个通用指令数据比如 alpaca 风格和一个领域业务数据按 1:3 混合既保留模型的对话能力又让它在具体业务上更聚焦。2.3 训练参数背后的核心逻辑LlamaFactory 暴露了很多训练参数但绝大多数时候你只需要关注几个关键值学习率、训练轮数、LoRA rank、batch size、max length、lr scheduler。很多朋友一开始直接抄别人的参数效果不好也不知道该调什么。理解这几个参数背后的逻辑会很有帮助。学习率是微调里最敏感的超参数。全参微调一般用 1e-5 到 2e-5LoRA 微调通常可以调到 1e-4 到 2e-4QLoRA 有时还会更高一点。因为 LoRA 只更新低秩矩阵可学习的参数量很小需要更大的学习率才能在目标任务上产生足够幅度的更新。如果学习率太大Loss 会震荡不定生成结果会开始胡说八道如果太小模型几乎没有变化微调等于白做。我通常的做法是先跑 100 步小实验观察 Loss 曲线如果前几十步 Loss 没明显下降就把学习率翻倍反之则减半。训练轮数num_train_epochs决定了数据被过几遍。指令微调常见的范围是 3 到 10 轮关键看数据量和数据质量。数据量少时过拟合风险很大轮数要相应减少数据量大时可以多加几轮但仍要监控验证集上的表现。对于几千条的垂直领域数据集我一般从 5 轮开始调观察 loss 和生成结果是否稳定。LoRA rank 决定了低秩矩阵的维度类似一个“容量旋钮”。rank 越大可学习的参数量越多表达能力越强但过拟合风险和显存占用也会上升。对于 7B 模型rank 8 到 64 都是常用区间。我经常先用 rank 16 跑通基线再尝试 rank 32 或 64 看效果有没有明显提升。如果 rank 从 16 加到 64效果提升很有限那就没必要为了稳妥增加过多参数。batch size 和 max length 更多是受显存约束。LlamaFactory 支持梯度累积gradient accumulation实际效果相当于增大 batch size但会牺牲一点训练吞吐。max length 控制输入序列的最大长度太长会显著占用显存和计算量太短会截断关键上下文。建议先统计一下自己数据集的长度分布再设置一个刚好覆盖绝大多数样本的值而不是无脑拉满。3. 实操用 LlamaFactory 微调一个自己的问答模型3.1 环境安装与依赖准备LlamaFactory 的安装非常友好。官方推荐pip install -e .的方式从源码安装克隆仓库后进入项目根目录执行git clone https://github.com/hiyouga/LlamaFactory.git cd LlamaFactory pip install -e .如果你是国内网络环境下载 GitHub 仓库可能比较慢可以用镜像或者直接下载 zip 包。依赖方面它会自动安装 torch、transformers、datasets、peft、trl、accelerate 等如果你之前装过旧版本的 torch建议先确认版本匹配避免后面训练时报奇怪的错。我建议使用 Python 3.10 以上的环境PyTorch 版本用 2.1 或 2.2 都比较稳妥。如果你希望能够更精确地控制依赖而不是被安装脚本带着走可以手动创建一个 conda 环境conda create -n llama-factory python3.10 conda activate llama-factory pip install torch2.1.2 pip install -e .这样至少能确保 PyTorch 版本是你指定的。LlamaFactory 依赖的 transformers 版本会跟着项目走建议不要轻易锁定过老版本。3.2 构造一份可用的微调数据集实际项目中我经常会写一段 Python 脚本把业务数据转换成 LlamaFactory 的标准格式。比如要做产品问答原始数据是问题-答案对可以直接写成 JSON[ { instruction: 你是公司内部的智能客服助手请根据产品文档回答用户问题。, input: 产品支持哪些支付方式, output: 我们支持微信支付、支付宝和银联卡支付企业客户还可以申请月结付款。 }, { instruction: 你是公司内部的智能客服助手请根据产品文档回答用户问题。, input: 订单发货后多久能到, output: 一般在付款后 48 小时内发货同城配送大约 1-2 天跨省配送 3-5 天。 } ]然后把文件保存到项目根目录的data/文件夹下比如叫product_qa.json。接下来需要修改data/dataset_info.json注册这个数据集。通常只需增加一个条目{ product_qa: { file_name: product_qa.json, columns: { prompt: instruction, query: input, response: output } } }如果数据量比较大建议用 JSONL 格式每行一条样本方便并行读取。LlamaFactory 的数据加载底层用的是 HuggingFace Datasets所以也支持直接从 HuggingFace Hub 或 ModelScope 数据集加载这给团队协作和数据版本管理带来很大方便。构造数据时还有一个小技巧给每条数据加一个均匀分布的system字段。如果你的业务场景需要模型在回答风格上保持一致可以通过在数据里加入少量系统提示词变化让模型学会遵循不同场景的角色设定。但注意变化不要太多否则模型会困惑。3.3 命令行方式启动训练LlamaFactory 的核心入口是llamafactory-cli命令或者直接调用项目内的src/train_bash.py。它支持在 YAML 配置文件中写清楚所有训练参数然后用一条命令启动训练。举个例子我想用 QLoRA 微调一个 Qwen2-7B 模型数据集用上面注册的product_qa配置可以写成model_name_or_path: /path/to/Qwen2-7B template: qwen stage: sft finetuning_type: lora dataset: product_qa cutoff_len: 1024 learning_rate: 2e-4 num_train_epochs: 5 lora_rank: 16 lora_target: all per_device_train_batch_size: 2 gradient_accumulation_steps: 8 output_dir: output/product_qa_qwen logging_steps: 10 save_steps: 500 fp16: true quantization_bit: 4然后用命令行启动llamafactory-cli train config.yaml这里的几个参数需要重点说明一下。template: qwen指定了对话模板不同模型族的模板不一样用错了会导致训练时正常但推理时输出格式混乱。lora_target: all表示对所有线性层注入 LoRA覆盖面更广效果往往比只注入 attention 层更稳。quantization_bit: 4开启 QLoRA 的 4-bit 量化显存能大幅降低。cutoff_len设置为 1024会让超过长度的部分被截断我这里设定的依据是业务问答普遍不超过 500 字。训练过程中日志会输出如loss、learning_rate、epoch等信息。如果看到 loss 稳定下降说明训练正常。如果你显存足够也可以把quantization_bit去掉用普通 LoRA 跑效果通常会更好一点。3.4 WebUI 方式操作对于不太习惯命令行配置的人来说LlamaFactory 自带的 WebUI 是非常友好的入口。启动方式极简单llamafactory-cli webui它会自动打开一个浏览器页面里面是一个表单式的界面从上到下依次是模型名称、模型路径、微调方法、数据集、训练参数、输出目录等。填好参数后点击“开始”训练过程就会在后台执行页面会实时显示日志和 loss 曲线。WebUI 模式下我比较推荐用来做快速验证和教学演示。因为你可以直接在一个页面上切换 LoRA/QLoRA、修改 epoch、查看显存占用非常直观。但它也有个小问题在某些配置下如果浏览器页面意外关闭后端训练进程可能不会自动停止需要去终端手动杀掉进程。所以如果是长时间训练我一般还是用命令行后台跑WebUI 适合小规模实验。值得一提的是 WebUI 还集成了 Chat 功能也就是训练完成后可以在同一个页面加载模型权重直接对话测试。这个流程非常顺滑省去另外写推理脚本或部署服务的麻烦。我在调优阶段经常训练完立刻在 WebUI 里问几个测试用例判断模型风格是否符合预期再决定要不要继续调参。3.5 模型导出与本地推理微调完成后LoRA adapter 会保存在output_dir下面。如果只是临时测试可以直接在 WebUI 或者命令行中用加载 adapter 的方式推理。但如果你要部署上线或者把模型给其他同事使用通常需要把 LoRA 权重合并到原模型导出一个完整的模型文件。LlamaFactory 提供了导出命令。通过配置可以导出合并后的模型llamafactory-cli export \ --model_name_or_path /path/to/Qwen2-7B \ --adapter_name_or_path output/product_qa_qwen \ --template qwen \ --finetuning_type lora \ --export_dir output/merged_model \ --export_size 4 \ --export_legacy_format falseexport_size是分片大小按 GB 为单位4 就是每个分片 4GB。导出后你会得到一个标准的 HuggingFace 格式模型目录里面包含config.json、model.safetensors分片、tokenizer等文件。这个目录可以直接被 vLLM、TGI 等推理框架加载也可以继续用 Transformers 的pipeline做推理。这里有一条重要经验导出前一定要确认模板一致。如果你训练时用的是qwen模板导出时仍要指定同一个模板否则最终模型的对话格式可能错乱。另外如果你后续还想用 LoRA 做增量实验记得保留最初的 adapter不要轻易覆盖。4. 训练效果评估与调优经验4.1 从 Loss 和生成结果判断微调效果训练日志里的 loss 是一个重要信号但千万别只盯着 loss 看。我见过不少次训练 loss 降到了 0.5 以下结果模型生成完全是复读机或者输出质量很差。Loss 下降只能说明模型在拟合训练集至于泛化能力好不好必须通过验证集或实际推理来检验。更好的做法是预留一批“金标准”测试问题训练完成后立刻在 WebUI 或脚本里测试。注意这批测试问题最好和训练数据分布相似但不完全相同。比如我做客服问答时会准备 20 个用户可能问但训练集里没有类似表述的问题测试生成的回答是否语义正确、格式是否规范。如果生成内容可靠、逻辑自洽、风格稳定那就说明微调效果是好的。我也喜欢对比微调前后的输出。同一个问题在基座模型和微调模型上分别提问观察差异。微调后的模型应该更贴合业务口径而不是完全忘掉通用能力。如果微调后模型连“你好”都回答得怪怪的那很可能过拟合或者学习率过大了。LlamaFactory 还提供了llamafactory-cli eval的简单评估入口可以在标准评测集上跑一下模型效果不过我日常用得不多。因为垂直领域的业务效果往往自定义测试集比通用 benchmark 更有参考价值。4.2 数据质量比数据量更关键兼谈过拟合与灾难性遗忘微调大模型经常会遇到两个问题过拟合和灾难性遗忘。过拟合的表现是模型在训练数据上表现很好但换个表述就答非所问灾难性遗忘则是微调之后模型原有的通用知识出现明显退化比如不会写诗了或者基本的常识问题都答乱。防止这两种问题最有效的杠杆不是精调超参数而是清洗数据。你要确保训练数据里的每条output都是高质量、无噪声、格式统一的。如果有人工标注团队最好制定详细的标注规范定期抽检。如果是自动生成的伪标签一定要做一轮过滤规则把短答案、重复答案、明显错误答案去掉。我通常会在数据进入训练之前写几个脚本检查长度分布、去重、检查 JSON 有效性。另外混合通用数据是一个缓解遗忘的实用技巧。在领域数据里掺入一部分通用指令数据比如 10% 到 30% 的通用问答或对话样本可以在学习领域知识的同时保持通用能力。LlamaFactory 的dataset_mixer参数就是为这个设计的。我会把dataset配成多个数据集并用混合比例控制领域数据和通用数据的配比。4.3 显存和速度的平衡技巧显存不足是微调中最常见的拦路虎。除了用 QLoRA 之外LlamaFactory 还支持多个实用技巧。第一个是gradient_checkpointing开启后会在反向传播时重新计算前向激活值而不是全部保存能省下不少显存代价是训练速度变慢。配置里设为true即可。第二个是优化器选择如果显存紧张可以使用adafactor或adamw_torch_fused后者相比标准 AdamW 能减少部分显存占用。第三个是flash_attn如果显卡支持且安装好 flash-attn可以显著降低 attention 部分的显存和加速训练。不过 flash-attn 安装有时比较折腾需要编译环境建议在 Linux 环境装配。训练速度方面我的经验是优先保证 batch size 不要太小。如果单卡 batch size 只能设 1就通过gradient_accumulation_steps累积到等效 batch size 16 或 32。太小的等效 batch size 会导致 loss 波动大训练不稳定。另外packing参数也很有效它可以把多个短样本拼接成一个长序列充分利用训练资源短文本场景下训练速度能提升不少。5. 常见问题与排查技巧实录我把实际使用 LlamaFactory 过程中遇到的高频问题整理成了一份速查表方便大家对照排查。问题现象可能原因解决办法启动训练时报CUDA out of memory显存不足以支撑当前模型/量化/batch size改用 QLoRA降低 batch size开启 gradient checkpointing或使用更小的基座模型训练 loss 不下降学习率过小或数据格式错误导致模型在学习无用模式检查数据格式适当增大学习率先跑几十步观察 loss 曲线生成结果全是重复文本学习率过大或训练轮数过多导致过拟合降低学习率减少 epoch或清洗低质量数据对话模板错乱输出包含 im_start 等特殊符号加载本地模型路径报错路径写错或模型目录结构不完整检查模型目录是否包含config.json和权重文件路径不要包含中文和空格训练速度很慢未开启 packing 或 flash attention数据过长开启packing尝试安装并开启flash_attn合理设置cutoff_len微调后通用能力下降严重领域数据占比过大或学习率过大混合通用数据降低学习率适当减少 epochWebUI 无法打开端口被占用或依赖未安装完整检查启动日志更换端口重新执行pip install -e .除了表格中的问题还有几个小坑值得单独提一下。第一个是dataset_info.json的配置格式必须严格。如果不小心把 JSON 写错一个逗号加载数据集时会直接报错而且报错信息往往指向内部库新手很容易懵。建议修改文件后用python -m json.tool dataset_info.json验证一下格式。第二个是不同版本之间行为差异。LlamaFactory 迭代很快一些参数名或默认值在不同 commit 之间会有变化。如果你照着一篇老教程配置可能在新版本里会提示参数不存在。这时候以项目内的 README 和examples目录为准不要死记硬背参数。第三个是多卡训练时accelerate的用法。如果有多张卡建议使用 LlamaFactory 提供的多卡启动脚本比如类似llamafactory-cli train config.yaml --multi_gpu或通过accelerate launch启动。不要自己手动去设置CUDA_VISIBLE_DEVICES然后期望自动分布式除非你清楚自己在做什么。排查问题的时候我最常用的就是看完整日志。LlamaFactory 的日志输出比较详细会打印数据加载情况、模型参数数量、训练配置等。报错时先看最后 50 行很多问题都能在日志里找到直接线索而不是漫无目的地改参数。6. 最后分享一点我个人对 LlamaFactory 的使用体会用了这么久我最大的感受是LlamaFactory 把微调大模型这件事的“工程门槛”降到了一个很合理的水平。以前我要为每个项目重新搭训练脚本调试 LoRA 的 target_modules、处理 tokenizer 的 padding 和 truncation 行为、为 DPO 单独写数据转换逻辑现在这些全部可以在统一的框架内解决。你可以把精力集中在真正重要的地方数据质量、任务设计、效果评测。如果你完全没接触过大模型微调我的建议是先从最小的实验跑起来。找一台显卡哪怕 8GB 显存用 QLoRA 微调一个最小的开源模型比如 Qwen2-0.5B 或 Qwen2-1.5B数据集就用几十条自己写的问答对完整跑一遍训练、导出、推理。这个流程走通之后再逐步扩大数据量和模型规模遇到问题也更容易定位。最后再分享一个小技巧每次开始实验前把配置文件、数据版本、基座模型路径都记录清楚甚至可以用 Git 管理配置文件和数据集。这样当你微调出好几个版本时才能准确知道哪个配置产出了哪个模型避免陷入“原来那个效果好的模型是怎么来的”这种尴尬。LlamaFactory 本身已经帮你管理好了训练产物但实验的“元数据”还是要靠良好的习惯来支撑。希望这篇实操梳理能给你一些参考少走我当初走过的弯路。
LlamaFactory实战：从LoRA到QLoRA的大模型微调指南
大概在半年前我第一次把hiyouga/LlamaFactory这个仓库拉到本地。当时正被一堆微调脚本折腾得够呛——不同模型要写不同的加载逻辑LoRA、全参微调各搞一套代码数据格式稍微不一样就得改半天。看到这个项目之后我第一反应是竟然有人把LoRA、QLoRA、全参微调、甚至DPO偏好对齐全部塞进同一个框架还能用一行命令启动可视化界面。后来我在多个垂直场景里用 LlamaFactory 跑了十几轮微调实验从中文指令优化到领域知识注入越用越觉得这套工具解决了很多实际痛点。如果你正在折腾大模型微调想快速验证某个基座模型在特定任务上的表现或者想给团队内部做一个私有化的指令助手又不想从零去写训练、评估、导出这一整套胶水代码LlamaFactory 基本上是目前社区里最顺手的方案之一。它对新手友好对老手也够用底层支持大量开源模型内置多种训练方式数据集准备和导出流程都被高度封装。你只需要准备一份符合规范的数据文件选好基座模型剩下的训练、评测、导出它都给你安排得明明白白。要顺利上手 LlamaFactory你最好先有一点大模型微调的基础概念比如知道 SFT 是什么意思LoRA 是在做什么再有一点 Linux 和 Python 的使用经验就足够了。下面我会从项目设计思路、核心功能拆解、实际微调流程和踩坑记录这些角度把这一路实操下来的经验完整梳理一遍希望能帮你少走弯路。1. LlamaFactory 项目整体与设计思路1.1 为什么需要这样一个统一微调框架如果自己去搭建大模型微调流程通常会遇到几个绕不开的麻烦首先是模型加载方式不统一HuggingFace Transformers 的 AutoModel 虽然能省点事但不同模型族的对话模板、tokenizer 细节差异很大处理不好很容易出现训练时正常、推理时胡言乱语的问题。其次是训练方式分散LoRA 要用 PEFT全参微调要自己写 Trainer 的 wrapperDPO 又需要额外的数据格式和loss实现每个模块都是独立的坑。LlamaFactory 的核心贡献在于把这些散落的东西整合到了一起。它基于 HuggingFace Transformers、PEFT、TRL、Datasets 等成熟库做了一层封装对外提供统一的数据接口和训练入口。你在配置里声明一下“我要用 LoRA 训练这个模型”它就会自动帮你加载 base model、初始化 LoRA adapter、设置好 optimizer 和 scheduler然后把训练循环跑起来。这种封装的好处是你不必关心 PEFT 的版本冲突不必自己拼接 tokenizer 的 chat template也不必为了一个 DPO 实验去翻 TRL 的文档。更重要的是LlamaFactory 把实验管理也考虑进去了。它的输出目录里会自动保存训练参数、模型权重、评估结果方便你对比不同实验。这一点在实际项目中非常有用因为微调往往不是一次就能成功的你可能要试不同的学习率、不同的 LoRA rank、不同的数据混合比例没有统一的结构化输出乱七八糟的实验文件夹会让人崩溃。1.2 支持的模型家族与可扩展性LlamaFactory 的模型支持矩阵非常广。它支持 LLaMA 系列、Qwen 系列、Baichuan 系列、ChatGLM 系列、Mistral/Llama2 衍生系列、Phi 系列、Yi 系列、DeepSeek 系列等等基本覆盖了主流开源基座模型。而且它的模型注册机制做得不错新增一个模型族通常只需要在src/llamafactory/model/下补上对应的 config复用已有训练逻辑即可。社区里也有不少人用它对 Baichuan、Qwen 做领域微调跑起来很顺畅。多模型支持的意义在于你可以方便地做基座选型实验。同一个数据集分别用 Qwen、Yi、Baichuan 跑一遍 LoRA比较它们在目标任务上的表现最终选出最合适的基座。这在以前是件挺麻烦的事因为每个模型的加载代码、对话模板都要单独适配而 LlamaFactory 把这一层全部标准化了。切换模型基本上就是改一行配置的事我实测下来从 Qwen 切到 Baichuan除了下载权重需要花时间代码层面几乎零改动。它还支持来自 ModelScope 的模型权重这对国内用户非常友好。因为直接从 HuggingFace 拉权重经常遇到网络问题通过 ModelScope 可以把下载速度提升不少而且 LlamaFactory 也支持本地权重目录你提前下好模型文件放到本地路径训练时直接指定即可。1.3 生态位置与典型应用场景LlamaFactory 在开源大模型微调工具链中的位置有点像“统一训练入口”。它既不自己实现底层算子也不去搞分布式的极端优化而是把现有成熟组件拼装得更顺手。这也决定了它最适合的场景是中小团队和个人开发者在单卡或多卡环境下对开源模型做指令微调、增量预训练、偏好对齐以快速获得一个可用模型原型。我实际用下来主要有三类场景很典型一是垂直领域问答模型比如企业内部知识库问答用业务数据微调一个基础模型让它的输出风格更贴合企业口径二是角色化对话或写作风格迁移通过几百到几千条风格样本让模型学会特定语气三是任务型模型的定制比如信息抽取、文本分类把下游任务转换成指令格式之后微调效果通常比直接 prompt 稳定得多。 LlamaFactory 在这些场景下都能很好地覆盖整个闭环数据准备、训练、评估、导出一个工具走完。2. 核心功能解析与关键概念2.1 LoRA、QLoRA、全参微调到底怎么选LlamaFactory 内置了多种训练方式最常用的三个是 LoRA、QLoRA 和全参微调。很多人第一次接触会纠结选哪个我的经验是先看显存再看数据量最后看你对效果的需求。全参微调Full Fine-Tuning是最朴素的方法更新模型全部参数效果上限最高但显存开销也最大。以 7B 模型为例全参微调的峰值显存通常需要 80GB 以上即便用闪存优化单卡也不容易跑起来。它适合你有充足的多卡资源并且数据量足够大的情况比如几十万条以上指令数据。如果数据量不大全参微调反而容易过拟合而且微调后的模型可能存在灾难性遗忘把原有的通用能力毁掉。LoRA 是现在的主流选择。它的原理是在原始权重旁边插入低秩分解的可训练矩阵训练时冻结原模型大部分参数只更新这些小矩阵。原始权重不变所以推理时可以把 LoRA 权重合并回原模型也可以单独保存为一个几十到几百 MB 的 adapter。对于 7B 模型LoRA 微调的单卡显存需求可以降到 16GB 到 24GB 之间效果在很多任务上与全参微调差距不大是性价比极高的方案。LlamaFactory 的 LoRA 实现做得比较成熟各目标模块比如 q_proj, v_proj 等可以灵活配置。QLoRA 则是 LoRA 的一种极限优化。它先把基座模型量化到 4-bit 或 8-bit再在量化后的模型上插入 LoRA 适配器进行训练。这样 7B 模型的训练显存可以压到 6GB 到 10GB 左右很多消费级显卡都能跑。代价是训练速度比普通 LoRA 慢一些量化过程也可能带来轻微精度损失。但如果你只有一块 8GB 或 12GB 显存的卡QLoRA 基本上是把大模型微调变成现实的最可靠路径。我自己的建议是能用 LoRA 就不碰全参显卡吃紧就上 QLoRA。两者在 LlamaFactory 里只是配置项不同并不影响数据准备和后续导出流程所以可以先从 QLoRA 跑通流程再把参数升级到 LoRA 看效果。2.2 数据集格式与指令微调的数据准备LlamaFactory 对数据格式做了统一约定。最常用的是指令微调Supervised Fine-Tuning数据支持这样的 JSON 格式每一条样本是一个对象包含instruction、input和output字段。当有额外上下文输入时放到input里没有 context 时input可以为空字符串。多个样本组成一个 JSON 数组保存成.json或.jsonl文件。它还可以用system字段指定系统提示词以及history字段传递多轮对话历史。实际构造数据的时候很多新手会犯一个错误把 prompt 写得太复杂甚至把整个背景知识都塞到每一条instruction里这样数据集会非常臃肿。更合理的做法是把指令设计得简洁明确把背景资料放到input字段让模型学会结合上下文回答问题。比如你要做一个客服问答数据集指令可以是“基于以下商品信息回答用户的问题”商品信息放input期望输出放output。这样训练出来的模型泛化性会更好。另外很重要的一点数据量并不是越多越好。指令微调的核心是让模型学会格式和风格而不是从零灌输知识。对于风格迁移或格式学习几千条高质量样本就足够了对于领域知识注入也要先考虑数据覆盖率和答案质量而不是盲目堆数量。我见过有人用 100 万条自动扒来的弱标注数据微调结果模型反而变傻了就是因为噪声太大了。LlamaFactory 的配置文件里通过dataset字段指定数据集目录下的文件列表你可以同时加载多个数据集并且用dataset_mixer按比例混合。这在实践中很关键。比如我经常会把一个通用指令数据比如 alpaca 风格和一个领域业务数据按 1:3 混合既保留模型的对话能力又让它在具体业务上更聚焦。2.3 训练参数背后的核心逻辑LlamaFactory 暴露了很多训练参数但绝大多数时候你只需要关注几个关键值学习率、训练轮数、LoRA rank、batch size、max length、lr scheduler。很多朋友一开始直接抄别人的参数效果不好也不知道该调什么。理解这几个参数背后的逻辑会很有帮助。学习率是微调里最敏感的超参数。全参微调一般用 1e-5 到 2e-5LoRA 微调通常可以调到 1e-4 到 2e-4QLoRA 有时还会更高一点。因为 LoRA 只更新低秩矩阵可学习的参数量很小需要更大的学习率才能在目标任务上产生足够幅度的更新。如果学习率太大Loss 会震荡不定生成结果会开始胡说八道如果太小模型几乎没有变化微调等于白做。我通常的做法是先跑 100 步小实验观察 Loss 曲线如果前几十步 Loss 没明显下降就把学习率翻倍反之则减半。训练轮数num_train_epochs决定了数据被过几遍。指令微调常见的范围是 3 到 10 轮关键看数据量和数据质量。数据量少时过拟合风险很大轮数要相应减少数据量大时可以多加几轮但仍要监控验证集上的表现。对于几千条的垂直领域数据集我一般从 5 轮开始调观察 loss 和生成结果是否稳定。LoRA rank 决定了低秩矩阵的维度类似一个“容量旋钮”。rank 越大可学习的参数量越多表达能力越强但过拟合风险和显存占用也会上升。对于 7B 模型rank 8 到 64 都是常用区间。我经常先用 rank 16 跑通基线再尝试 rank 32 或 64 看效果有没有明显提升。如果 rank 从 16 加到 64效果提升很有限那就没必要为了稳妥增加过多参数。batch size 和 max length 更多是受显存约束。LlamaFactory 支持梯度累积gradient accumulation实际效果相当于增大 batch size但会牺牲一点训练吞吐。max length 控制输入序列的最大长度太长会显著占用显存和计算量太短会截断关键上下文。建议先统计一下自己数据集的长度分布再设置一个刚好覆盖绝大多数样本的值而不是无脑拉满。3. 实操用 LlamaFactory 微调一个自己的问答模型3.1 环境安装与依赖准备LlamaFactory 的安装非常友好。官方推荐pip install -e .的方式从源码安装克隆仓库后进入项目根目录执行git clone https://github.com/hiyouga/LlamaFactory.git cd LlamaFactory pip install -e .如果你是国内网络环境下载 GitHub 仓库可能比较慢可以用镜像或者直接下载 zip 包。依赖方面它会自动安装 torch、transformers、datasets、peft、trl、accelerate 等如果你之前装过旧版本的 torch建议先确认版本匹配避免后面训练时报奇怪的错。我建议使用 Python 3.10 以上的环境PyTorch 版本用 2.1 或 2.2 都比较稳妥。如果你希望能够更精确地控制依赖而不是被安装脚本带着走可以手动创建一个 conda 环境conda create -n llama-factory python3.10 conda activate llama-factory pip install torch2.1.2 pip install -e .这样至少能确保 PyTorch 版本是你指定的。LlamaFactory 依赖的 transformers 版本会跟着项目走建议不要轻易锁定过老版本。3.2 构造一份可用的微调数据集实际项目中我经常会写一段 Python 脚本把业务数据转换成 LlamaFactory 的标准格式。比如要做产品问答原始数据是问题-答案对可以直接写成 JSON[ { instruction: 你是公司内部的智能客服助手请根据产品文档回答用户问题。, input: 产品支持哪些支付方式, output: 我们支持微信支付、支付宝和银联卡支付企业客户还可以申请月结付款。 }, { instruction: 你是公司内部的智能客服助手请根据产品文档回答用户问题。, input: 订单发货后多久能到, output: 一般在付款后 48 小时内发货同城配送大约 1-2 天跨省配送 3-5 天。 } ]然后把文件保存到项目根目录的data/文件夹下比如叫product_qa.json。接下来需要修改data/dataset_info.json注册这个数据集。通常只需增加一个条目{ product_qa: { file_name: product_qa.json, columns: { prompt: instruction, query: input, response: output } } }如果数据量比较大建议用 JSONL 格式每行一条样本方便并行读取。LlamaFactory 的数据加载底层用的是 HuggingFace Datasets所以也支持直接从 HuggingFace Hub 或 ModelScope 数据集加载这给团队协作和数据版本管理带来很大方便。构造数据时还有一个小技巧给每条数据加一个均匀分布的system字段。如果你的业务场景需要模型在回答风格上保持一致可以通过在数据里加入少量系统提示词变化让模型学会遵循不同场景的角色设定。但注意变化不要太多否则模型会困惑。3.3 命令行方式启动训练LlamaFactory 的核心入口是llamafactory-cli命令或者直接调用项目内的src/train_bash.py。它支持在 YAML 配置文件中写清楚所有训练参数然后用一条命令启动训练。举个例子我想用 QLoRA 微调一个 Qwen2-7B 模型数据集用上面注册的product_qa配置可以写成model_name_or_path: /path/to/Qwen2-7B template: qwen stage: sft finetuning_type: lora dataset: product_qa cutoff_len: 1024 learning_rate: 2e-4 num_train_epochs: 5 lora_rank: 16 lora_target: all per_device_train_batch_size: 2 gradient_accumulation_steps: 8 output_dir: output/product_qa_qwen logging_steps: 10 save_steps: 500 fp16: true quantization_bit: 4然后用命令行启动llamafactory-cli train config.yaml这里的几个参数需要重点说明一下。template: qwen指定了对话模板不同模型族的模板不一样用错了会导致训练时正常但推理时输出格式混乱。lora_target: all表示对所有线性层注入 LoRA覆盖面更广效果往往比只注入 attention 层更稳。quantization_bit: 4开启 QLoRA 的 4-bit 量化显存能大幅降低。cutoff_len设置为 1024会让超过长度的部分被截断我这里设定的依据是业务问答普遍不超过 500 字。训练过程中日志会输出如loss、learning_rate、epoch等信息。如果看到 loss 稳定下降说明训练正常。如果你显存足够也可以把quantization_bit去掉用普通 LoRA 跑效果通常会更好一点。3.4 WebUI 方式操作对于不太习惯命令行配置的人来说LlamaFactory 自带的 WebUI 是非常友好的入口。启动方式极简单llamafactory-cli webui它会自动打开一个浏览器页面里面是一个表单式的界面从上到下依次是模型名称、模型路径、微调方法、数据集、训练参数、输出目录等。填好参数后点击“开始”训练过程就会在后台执行页面会实时显示日志和 loss 曲线。WebUI 模式下我比较推荐用来做快速验证和教学演示。因为你可以直接在一个页面上切换 LoRA/QLoRA、修改 epoch、查看显存占用非常直观。但它也有个小问题在某些配置下如果浏览器页面意外关闭后端训练进程可能不会自动停止需要去终端手动杀掉进程。所以如果是长时间训练我一般还是用命令行后台跑WebUI 适合小规模实验。值得一提的是 WebUI 还集成了 Chat 功能也就是训练完成后可以在同一个页面加载模型权重直接对话测试。这个流程非常顺滑省去另外写推理脚本或部署服务的麻烦。我在调优阶段经常训练完立刻在 WebUI 里问几个测试用例判断模型风格是否符合预期再决定要不要继续调参。3.5 模型导出与本地推理微调完成后LoRA adapter 会保存在output_dir下面。如果只是临时测试可以直接在 WebUI 或者命令行中用加载 adapter 的方式推理。但如果你要部署上线或者把模型给其他同事使用通常需要把 LoRA 权重合并到原模型导出一个完整的模型文件。LlamaFactory 提供了导出命令。通过配置可以导出合并后的模型llamafactory-cli export \ --model_name_or_path /path/to/Qwen2-7B \ --adapter_name_or_path output/product_qa_qwen \ --template qwen \ --finetuning_type lora \ --export_dir output/merged_model \ --export_size 4 \ --export_legacy_format falseexport_size是分片大小按 GB 为单位4 就是每个分片 4GB。导出后你会得到一个标准的 HuggingFace 格式模型目录里面包含config.json、model.safetensors分片、tokenizer等文件。这个目录可以直接被 vLLM、TGI 等推理框架加载也可以继续用 Transformers 的pipeline做推理。这里有一条重要经验导出前一定要确认模板一致。如果你训练时用的是qwen模板导出时仍要指定同一个模板否则最终模型的对话格式可能错乱。另外如果你后续还想用 LoRA 做增量实验记得保留最初的 adapter不要轻易覆盖。4. 训练效果评估与调优经验4.1 从 Loss 和生成结果判断微调效果训练日志里的 loss 是一个重要信号但千万别只盯着 loss 看。我见过不少次训练 loss 降到了 0.5 以下结果模型生成完全是复读机或者输出质量很差。Loss 下降只能说明模型在拟合训练集至于泛化能力好不好必须通过验证集或实际推理来检验。更好的做法是预留一批“金标准”测试问题训练完成后立刻在 WebUI 或脚本里测试。注意这批测试问题最好和训练数据分布相似但不完全相同。比如我做客服问答时会准备 20 个用户可能问但训练集里没有类似表述的问题测试生成的回答是否语义正确、格式是否规范。如果生成内容可靠、逻辑自洽、风格稳定那就说明微调效果是好的。我也喜欢对比微调前后的输出。同一个问题在基座模型和微调模型上分别提问观察差异。微调后的模型应该更贴合业务口径而不是完全忘掉通用能力。如果微调后模型连“你好”都回答得怪怪的那很可能过拟合或者学习率过大了。LlamaFactory 还提供了llamafactory-cli eval的简单评估入口可以在标准评测集上跑一下模型效果不过我日常用得不多。因为垂直领域的业务效果往往自定义测试集比通用 benchmark 更有参考价值。4.2 数据质量比数据量更关键兼谈过拟合与灾难性遗忘微调大模型经常会遇到两个问题过拟合和灾难性遗忘。过拟合的表现是模型在训练数据上表现很好但换个表述就答非所问灾难性遗忘则是微调之后模型原有的通用知识出现明显退化比如不会写诗了或者基本的常识问题都答乱。防止这两种问题最有效的杠杆不是精调超参数而是清洗数据。你要确保训练数据里的每条output都是高质量、无噪声、格式统一的。如果有人工标注团队最好制定详细的标注规范定期抽检。如果是自动生成的伪标签一定要做一轮过滤规则把短答案、重复答案、明显错误答案去掉。我通常会在数据进入训练之前写几个脚本检查长度分布、去重、检查 JSON 有效性。另外混合通用数据是一个缓解遗忘的实用技巧。在领域数据里掺入一部分通用指令数据比如 10% 到 30% 的通用问答或对话样本可以在学习领域知识的同时保持通用能力。LlamaFactory 的dataset_mixer参数就是为这个设计的。我会把dataset配成多个数据集并用混合比例控制领域数据和通用数据的配比。4.3 显存和速度的平衡技巧显存不足是微调中最常见的拦路虎。除了用 QLoRA 之外LlamaFactory 还支持多个实用技巧。第一个是gradient_checkpointing开启后会在反向传播时重新计算前向激活值而不是全部保存能省下不少显存代价是训练速度变慢。配置里设为true即可。第二个是优化器选择如果显存紧张可以使用adafactor或adamw_torch_fused后者相比标准 AdamW 能减少部分显存占用。第三个是flash_attn如果显卡支持且安装好 flash-attn可以显著降低 attention 部分的显存和加速训练。不过 flash-attn 安装有时比较折腾需要编译环境建议在 Linux 环境装配。训练速度方面我的经验是优先保证 batch size 不要太小。如果单卡 batch size 只能设 1就通过gradient_accumulation_steps累积到等效 batch size 16 或 32。太小的等效 batch size 会导致 loss 波动大训练不稳定。另外packing参数也很有效它可以把多个短样本拼接成一个长序列充分利用训练资源短文本场景下训练速度能提升不少。5. 常见问题与排查技巧实录我把实际使用 LlamaFactory 过程中遇到的高频问题整理成了一份速查表方便大家对照排查。问题现象可能原因解决办法启动训练时报CUDA out of memory显存不足以支撑当前模型/量化/batch size改用 QLoRA降低 batch size开启 gradient checkpointing或使用更小的基座模型训练 loss 不下降学习率过小或数据格式错误导致模型在学习无用模式检查数据格式适当增大学习率先跑几十步观察 loss 曲线生成结果全是重复文本学习率过大或训练轮数过多导致过拟合降低学习率减少 epoch或清洗低质量数据对话模板错乱输出包含 im_start 等特殊符号加载本地模型路径报错路径写错或模型目录结构不完整检查模型目录是否包含config.json和权重文件路径不要包含中文和空格训练速度很慢未开启 packing 或 flash attention数据过长开启packing尝试安装并开启flash_attn合理设置cutoff_len微调后通用能力下降严重领域数据占比过大或学习率过大混合通用数据降低学习率适当减少 epochWebUI 无法打开端口被占用或依赖未安装完整检查启动日志更换端口重新执行pip install -e .除了表格中的问题还有几个小坑值得单独提一下。第一个是dataset_info.json的配置格式必须严格。如果不小心把 JSON 写错一个逗号加载数据集时会直接报错而且报错信息往往指向内部库新手很容易懵。建议修改文件后用python -m json.tool dataset_info.json验证一下格式。第二个是不同版本之间行为差异。LlamaFactory 迭代很快一些参数名或默认值在不同 commit 之间会有变化。如果你照着一篇老教程配置可能在新版本里会提示参数不存在。这时候以项目内的 README 和examples目录为准不要死记硬背参数。第三个是多卡训练时accelerate的用法。如果有多张卡建议使用 LlamaFactory 提供的多卡启动脚本比如类似llamafactory-cli train config.yaml --multi_gpu或通过accelerate launch启动。不要自己手动去设置CUDA_VISIBLE_DEVICES然后期望自动分布式除非你清楚自己在做什么。排查问题的时候我最常用的就是看完整日志。LlamaFactory 的日志输出比较详细会打印数据加载情况、模型参数数量、训练配置等。报错时先看最后 50 行很多问题都能在日志里找到直接线索而不是漫无目的地改参数。6. 最后分享一点我个人对 LlamaFactory 的使用体会用了这么久我最大的感受是LlamaFactory 把微调大模型这件事的“工程门槛”降到了一个很合理的水平。以前我要为每个项目重新搭训练脚本调试 LoRA 的 target_modules、处理 tokenizer 的 padding 和 truncation 行为、为 DPO 单独写数据转换逻辑现在这些全部可以在统一的框架内解决。你可以把精力集中在真正重要的地方数据质量、任务设计、效果评测。如果你完全没接触过大模型微调我的建议是先从最小的实验跑起来。找一台显卡哪怕 8GB 显存用 QLoRA 微调一个最小的开源模型比如 Qwen2-0.5B 或 Qwen2-1.5B数据集就用几十条自己写的问答对完整跑一遍训练、导出、推理。这个流程走通之后再逐步扩大数据量和模型规模遇到问题也更容易定位。最后再分享一个小技巧每次开始实验前把配置文件、数据版本、基座模型路径都记录清楚甚至可以用 Git 管理配置文件和数据集。这样当你微调出好几个版本时才能准确知道哪个配置产出了哪个模型避免陷入“原来那个效果好的模型是怎么来的”这种尴尬。LlamaFactory 本身已经帮你管理好了训练产物但实验的“元数据”还是要靠良好的习惯来支撑。希望这篇实操梳理能给你一些参考少走我当初走过的弯路。
