LLaMA-Factory这两年我前前后后用了不下十次，从一开始照抄官方命令到处报错，到如今能根据业务场景快速配出一套可用的微调方案，中间踩过的坑基本都踩完了。不少朋友问我大模型微调入门从哪开始，我的答案始终是同一个：先别急着啃源码，先用LLaMA-Factory把一个开源基座模型微调出肉眼可感知的效果，把全流程跑通，再回头理解背后的原理。这比我当初一头扎进底层实现效率高太多了。

这一篇算是我的“个人重制版”入门笔记。官方文档写得不算差，但对第一次接触微调的人来说，很多关键细节要么一笔带过，要么藏在issue区里。我把自己实际用得顺手的一套流程重新整理了一遍：从环境准备、数据构造、参数配置到训练、导出、推理验证，全部走一遍，并把高频踩坑和排查思路单独列出来。内容面向想用开源模型做领域定制、但还没跑通完整流程的实践者，包括刚入门的研究生、做内部工具的工程师，以及单纯想自己训练一个模型玩玩的爱好者。如果你已经相当熟悉transformers和LoRA原理，这篇可以当查缺补漏的速查手册看。

1. 项目思路拆解：为什么用LLaMA-Factory做微调

1.1 微调的本质需求

先说清楚一个问题：我们到底为什么要微调，而不是直接拿基座模型用？基座模型更像一个“受过通识教育的人”，它知识面很广，能聊常识、能写通用文本，但不懂你的业务黑话、不知道你的术语体系、也说不出你想要的那种口吻。微调做的事情，就像给这个人做一轮“入职培训”，用一批针对性数据让他快速适应某个岗位。

这种需求在实际项目中非常具体。比如你要做一个电商客服助手，通用模型能回答“什么是退货运费险”，但面对“用户收到破损商品但已经签收，按平台规则应该怎么处理”这种带业务约束的问题，基座模型往往答得似是而非。又比如你想让模型学会按特定模板生成周报，或者把技术文档改写成口语化的答疑内容，这些都靠微调来实现。相比从零训练一个大模型，微调在数据量、算力、时间上的开销都低了几个数量级，这也是微调能成为大模型落地主流路径的根本原因。

1.2 LLaMA-Factory的核心优势

市面上能做微调的工具不少，直接写transformers训练脚本也行，但LLaMA-Factory把整个流程的复杂度封装掉了很大一部分。我用的感受可以归纳成几点。

第一，微调算法覆盖面全。LoRA、QLoRA、全参数微调、冻结部分层微调、DoRA、RSLoRA这些主流方法都有现成实现，切换方法基本只需要改一个配置项，不用自己写训练循环。

第二，数据格式高度统一。无论原始数据长的什么样，你最终只需要整理成它规定的几种JSON格式，训练脚本会自动完成模板拼接和指令格式化。这一点对新手特别重要，因为我见过太多自己写数据加载逻辑然后翻车的情况。

第三，训练与推理链路完整。训练完可以直接用命令行做权重合并、量化导出，也能起一个推理接口快速验证效果。它甚至还带一个Web UI界面，不想写命令行的人也能在页面上点点点完成训练。我个人习惯用命令行和配置文件，更便于版本管理和复现，但Web UI对纯新手确实友好得多。

用一个类比说明它的定位：自己写transformers脚本训练，相当于为了喝口粥从种水稻开始；直接用LLaMA-Factory，相当于拿到了一个带预约功能的电饭煲，米和水放进去，按键就行。不是说底层原理不用学，而是入门阶段先把流程跑通，再去研究电饭煲内部结构，心理压力小很多。

2. 环境搭建与基础概念补课

2.1 硬件门槛到底多高

很多人在环境这一步就被劝退了，觉得“微调大模型肯定要好几张企业级显卡”。实际取决于模型规模和微调方法，门槛没有想象中那么夸张。

以7B参数量级的模型为例，我做过的估算大致是这样的：全参数微调时，需要保存的参数除了模型本身的权重，还有优化器状态（AdamW一般要存一阶动量和二阶动量）、梯度以及前向过程中的激活值，实际显存需求通常在60GB以上，单张消费级显卡基本没戏。LoRA只训练注入的低秩矩阵，原模型权重冻结且不计算梯度，显存需求能压到16GB左右，一张3090/4090级别的卡就能跑。QLoRA在LoRA基础上再把基座模型量化到4bit，进一步把显存需求压到8GB上下，这就让很多个人玩家用普通显卡也能跑起来。

不过这些数字都是估算，实际占用还受序列长度、batch size、梯度累积步数等因素影响。我的经验是，给显存留出至少30%的余量，训练过程中要盯nvidia-smi，否则很容易在中途OOM。

2.2 安装流程实录

环境安装我只推荐一套组合，自己用了很多次，在Ubuntu系统上最稳。先创建独立的conda环境，别直接装在base环境里，否则后面依赖冲突会非常痛苦。

conda create -n llama_factory python=3.10 -y conda activate llama_factory

接着安装PyTorch。如果没有特殊需求，直接装官方稳定版即可；如果本机CUDA版本比较旧，要去对应版本索引安装匹配的预编译包。然后装CUDA版的torch后一定要顺手验证一下：

python -c "import torch; print(torch.cuda.is_available())"

输出True再继续。很多人后面报错“找不到GPU”都是在这一步就埋下的隐患。

然后拉取LLaMA-Factory源码并安装依赖：

git clone https://github.com/hiyouga/LLaMA-Factory.git cd LLaMA-Factory pip install -e .

这一条命令会把项目依赖（transformers、peft、datasets、accelerate等）一起装上。需要说明的是，我建议用源码方式而不是pip直接装包，因为后续可能要看源码排查问题，而且插件式数据集注册也要用到仓库里的data目录结构。

装完之后建议初始化一下目录，确认data和output这类关键目录存在。模型权重文件不需要提前下载到某个固定位置，训练配置里指定路径后，工具会自动从模型仓库拉取，也可以自己拷贝到本地再指定本地路径。国内网络环境不太稳定时，我一般提前把模型下载好放在/data/models/下面，训练时直接写本地路径，省去下载环节的等待和不确定性。

3. 数据准备：决定微调效果的关键环节

3.1 三种数据集格式

数据格式是新手翻车重灾区。LLaMA-Factory主要支持三种数据格式：alpaca格式、sharegpt格式、预训练格式。我平常用的最多的是前两种。

alpaca格式适合单轮指令问答。每条数据包含instruction（指令）、input（可选输入）、output（期望输出）三个字段。input字段可以为空，当它为空时，训练模板会把“人类指令”和“模型回答”拼接成一段标准对话；当它不为空时，相当于在指令后面再加一段输入内容，适合“给定材料生成答案”这种场景。

sharegpt格式适合多轮对话。核心是一个conversations数组，每轮对话用from和value标明发言角色。from可以取human、gpt等，分别对应人和模型。现在很多基座模型自带聊天模板，sharegpt格式能更好地保留多轮上下文结构。如果你要微调的是一个对话助手模型，我强烈建议用sharegpt格式，而不要硬把所有多轮对话压成单轮的alpaca格式。

{ "conversations": [ { "from": "human", "value": "你好，我手机丢了，怎么找回？" }, { "from": "gpt", "value": "请您别着急。建议您先通过设备管理功能尝试定位或锁定设备，同时联系运营商挂失手机号。请问设备是开启了查找功能的吗？" } ] }

3.2 构造一个实际可用的数据集

光看格式定义还不够，我拿一个很常见的场景举例：给企业内部做一个客服助手，让它按照规则问答。假设我们收集到了10条真实问答对，整理成JSON后，就是这种样子：

[ { "instruction": "用户反馈商品有质量问题，要求退款，但已经超过七天无理由退货时效，如何处理？", "input": "", "output": "您好，非常理解您的心情。由于商品已超过七天无理由退货期限，我这边无法直接为您操作退款。不过我可以为您申请售后维修或换货服务，您可以先把商品问题照片发给我，我为您登记处理。" }, { "instruction": "重复问题：用户之前已申请过一次维修，现在又提出同样的问题怎么办？", "input": "", "output": "您好，我们系统里查看到您之前的维修记录，本次可以再次为您提交售后申请，同时会将上次维修工单关联到本次申请中，方便售后同事快速定位问题。" } ]

实际训练中10条当然不够，通常几百条起步效果才明显，几千到几万条就能看到比较稳定的能力变化。但我见过不少刚入门的朋友数据规模比别人大十倍，效果却不如别人，原因就出在数据质量上。构造数据有几个原则想重点强调一下：

第一，任务意图必须足够聚焦。不要在一份数据集里混着“写诗”“翻译”“做数学题”三种完全无关的任务，模型会学成一个四不像。第二，输出要风格统一。如果目标是客服场景，所有回答都要保持同一套称呼、语气、处理流程结构，不能一半是口语聊天，一半是书面公文。第三，注意覆盖边界情况。比如“七天无理由”和“三包政策”这类容易混淆的规则，要在数据里有意识地区分呈现。第四，别把不该教的东西喂进去。内部审核步骤、未公示的赔付底线等敏感业务信息，一旦进入模型参数就很难抹掉，数据安全这条红线不能碰。

数据文件准备好后，还需要在data/dataset_info.json中注册，给数据集起个名字并指定路径和格式。这一步漏掉的话，训练启动时会直接报错说找不到数据集。

{ "my_custom_dataset": { "file_name": "my_custom_dataset.json", "formatting": "alpaca", "columns": { "prompt": "instruction", "query": "input", "response": "output" }, "tags": { "prompt_tag": "### Instruction:", "response_tag": "### Response:" } } }

注册文件里有两个细节容易踩坑：一是columns映射要写对，别把instruction和input搞反，否则训练时模型读到的指令和输入是错位的；二是alpaca格式默认会按列名推断字段，如果你自定义了列名，必须在dataset_info.json里显式指定映射关系，不然工具会按默认列名去找数据。

4. 实操记录：LoRA微调全流程

4.1 配置文件逐项解析

我强烈建议用YAML配置文件来管理训练参数，而不是把参数堆在命令行里。这样做的好处是，每次实验都是一份可复现的配置记录，跑完还能对着一排yaml回溯“哪次改了什么”，排查效果变化时特别方便。

下面是我常用的一份LoRA训练配置，以中文客服助手场景为例：

model_name_or_path: /data/models/llama-2-7b-hf dataset: my_custom_dataset template: llama2 finetuning_type: lora lora_rank: 16 lora_alpha: 32 lora_dropout: 0.05 learning_rate: 1e-4 num_train_epochs: 3 per_device_train_batch_size: 4 gradient_accumulation_steps: 8 lr_scheduler_type: cosine warmup_ratio: 0.03 logging_steps: 10 save_steps: 500 output_dir: output/llama2-lora-2024

几个关键参数逐个说清楚。

finetuning_type选lora，表示训练方式为LoRA。lora_rank是低秩矩阵的秩，可以理解为“注入的可训练参数的规模”。rank越大，可训练参数量越多，模型对新任务的拟合能力越强，但显存占用和过拟合风险也会上升。7B模型我一般从8或16开始试，如果数据量比较大、任务复杂度高，再调到32甚至64。lora_alpha是缩放因子，它的作用是调节LoRA路径在最终输出中的权重，通常设置为lora_rank的1到2倍。learning_rate是训练步长，LoRA微调一般用1e-4到2e-5区间，比全参数微调大一些是正常的，因为LoRA本身只影响一部分参数。我个人习惯初始跑1e-4，如果发现loss震荡剧烈，再降一半重跑。

per_device_train_batch_size和gradient_accumulation_steps需要放到一起理解。batch size太大显存容易爆，太小则梯度估计噪声大。实际有效batch size等于两者乘积。我这里单卡batch size设4，累积8步，相当于一次参数更新实际看了32条样本，既稳定又不吃显存。num_train_epochs的取值和数据集规模密切相关，数据量少容易过拟合，我用几百条的小数据集时，3轮左右就够，数据量上万可以适当降到1到2轮。

4.2 启动训练与显存监控

配置写好后，一行命令即可启动训练：

llamafactory-cli train lora.yaml

训练开始后，日志里会依次出现加载模型、tokenizer、数据集的信息。第一次跑的时候一定要盯着几个关键点：日志中是否显示样本数量与预期一致；显存占用是否在合理范围；前几十步loss是否在正常下降。

我习惯在另一个终端窗口跑一个实时显存监控：

watch -n 2 nvidia-smi

如果你发现显存占用持续逼近显存上限，且接近峰值，那就要警惕了。此时优先降低per_device_train_batch_size，或者调低max_length（如果不设置，默认会按模型最大长度计算，很容易默默吃满显存）。在训练脚本里显式设置max_length，比如设成1024或2048，可以大幅减少激活值缓存，缓解显存压力。

训练过程中loss曲线是最直接的反馈。如果loss是平稳下降的，基本可以安心等它跑完；如果loss出现突然飙高，多半是学习率过大或训练数据里混入了异常长文本。这里我遇到过一种情况：某条样本非常长，其他样本都几百字，它一下子冲到接近模型最大长度，导致该步的loss异常抬升。这种数据最好在预处理阶段就切掉或过滤掉，不要留着炸训练。

训练结束以后，输出目录里会出现一系列checkpoint文件夹，用save_steps配置的间隔保存。如果训练中断了，你还可以用--resume_from_checkpoint继续接着跑，不用从头再来。

4.3 模型导出与推理验证

训练完的LoRA权重还挂在adapter文件里，要学会合并回原模型再使用。尤其在部署阶段，很多推理框架需要的是完整的模型文件，不支持单独加载peft适配器。合并操作同样一条命令搞定：

llamafactory-cli export \ --model_name_or_path /data/models/llama-2-7b-hf \ --adapter_name_or_path output/llama2-lora-2024/checkpoint-500 \ --template llama2 \ --finetuning_type lora \ --export_dir output/llama2-lora-2024/merged

合并完需要自测一下，最好的方式不是看loss，而是真正把模型加载起来，问几条训练集里的“同类问题”。写一个简单的推理demo：

from transformers import AutoModelForCausalLM, AutoTokenizer model_dir = "output/llama2-lora-2024/merged" model = AutoModelForCausalLM.from_pretrained(model_dir, device_map="auto") tokenizer = AutoTokenizer.from_pretrained(model_dir) prompt = "用户要求七天无理由退款，但购买时间已超过30天，如何处理？" messages = [{"role": "user", "content": prompt}] input_ids = tokenizer.apply_chat_template( messages, add_generation_prompt=True, return_tensors="pt" ).to(model.device) outputs = model.generate(input_ids, max_new_tokens=256, do_sample=True, temperature=0.7) response = tokenizer.decode(outputs[0][input_ids.shape[1]:], skip_special_tokens=True) print(response)

我训练出来的一个7B客服模型，微调前回答这类问题完全是通用套话，微调后能主动引用平台规则、按流程给出处理步骤，说明数据里的业务约束确实进入了模型参数。如果你测了半天发现输出和基座模型一模一样，那几乎可以肯定是训练环节出了问题，最常见的原因是训练时忘了指定数据集注册名，实际跑的是基座模型本身。

5. 避坑指南与常见问题实录

5.1 高频问题清单

5.2 我踩过的三个坑

第一个坑是训练完发现模型没有任何变化。当时日志显示loss在降，我以为是自己在微调，后来回头看配置才发现，dataset那栏写的数据集名字在dataset_info.json里没注册，工具fallback到了一个默认的空数据集，相当于我空跑了一整轮训练。从那以后我养成一个习惯：训练启动后的第一件事就是看日志里的数据结构摘要，确认加载样本数和预期一致。

第二个坑是学习率设得太奔放。我第一次跑LoRA直接用1e-3，结果loss像过山车一样上下翻滚，数值还偶尔飞上几位数。后来翻源码才意识到LoRA虽然只训练一小部分参数，但AdamW对低秩矩阵的学习依然很敏感，乖乖把学习率调回1e-4，loss曲线立刻平稳了。现在不管换什么模型，我第一优先级的操作都是先跑一个几十步的“小实验”，看loss是否下降，再铺开完整训练。

第三个坑是多轮对话的system字段丢失。用sharegpt格式做客服数据时，我想让模型开场先固定一个身份设定，于是在每条对话前加了system消息。跑完测试才发现部分样本的回答风格不稳定，后来排查发现有些多轮数据在转成训练样本时system消息没有正确写入模板。解决方式是直接把身份设定揉进第一条human消息里，或者确保dataset_info.json中tags配置的system字段名称与数据一致。这里没有一劳永逸的办法，唯一可靠的校验方式是拿一条训练数据走一遍tokenize流程，肉眼检查拼接出来的完整prompt是不是符合预期。

5.3 推理与部署阶段的几个细节

训练完成了不等于可以上线。我处理过几次“训练时效果很好，一部署就回答质量明显下降”的情况，问题往往出在推理设置上。一个是解码参数，训练时用的teacher forcing，模型每一步都看到正确答案，推理时只能靠自回归生成，如果你的temperature设得过高或repetition_penalty过低，就会出现跑题和重复词死循环。另一个是模板不匹配，模型的chat template如果和LoRA训练时用的template不一致，生成效果也会大打折扣。我的做法是导出合并后，用同一套tokenizer和template先做一次离线批量测试，确认没问题再进部署流程。

如果你打算用vLLM或TGI这类推理框架部署，务必先确认框架支持用本地方向的模型文件启动，并且权重要合并好，不要直接塞peft适配器路径给推理后端。我之前栽过一次跟头，适配器和基座模型不匹配导致启动服务时cuDNN报错，后来才发现是合并时用错了一个不同版本的checkpoint。

结尾

说实话，微调这件事没有想象中那么玄，本质上就是数据、配置、验证这三件事来回转。LLaMA-Factory把训练流程的复杂度几乎全部封装掉了，剩下的就是你和数据、参数的反复磨合。以我个人的体会，拿到任何模型都先不要急着堆数据、调参数，先用一份干净、目标明确的小数据集跑通最小闭环，确认从训练到推理的链路没问题，再逐步加数据量、改超参。把第一条训练日志完整读一遍，比收藏十篇教程都管用。最后再分享一个小技巧：我为每个实验单独建一个目录，里面放配置文件、训练日志、loss截图和测试对话记录，一个月后你回看这些实验记录，能很清楚地判断什么改动真正奏效。技术更新再快，这套工作习惯反而是长期通用的。希望这份个人重制版能帮你少走一些我当时走过的弯路。