LLaMA-Factory 详解：YAML 与 WebUI 微调工厂

LLaMA-Factory 是目前使用最广的开源 LLM 微调一体化框架之一：用 YAML/CLI 或 LlamaBoard WebUI 完成 SFT、LoRA、QLoRA、DPO 等，无需手写 SFTTrainer 脚本。横向选型见 03-00 框架对比。

段末注释：LlamaBoard 是 LLaMA-Factory 自带的 Gradio Web 界面，用于可视化配置训练、监控 loss 与管理数据集。

系列索引：微调技术路线导读

---

一、定位与适用场景

适合	不太适合
快速验证数据与超参	深度自定义 loss / collator
非开发同事通过 WebUI 训练	复杂 GRPO + 自写 reward
一套配置复现多轮实验	与现有 Python 训练流水线强耦合

编程向深度定制见 03-01 SFTTrainer。

---

二、安装

git clone https://github.com/hiyouga/LLaMA-Factory.git
cd LLaMA-Factory
pip install -e ".[torch,metrics]"

依赖与 transformers、peft、datasets、trl 版本绑定，建议按官方 requirements.txt 锁定。

---

三、数据格式

在 data/dataset_info.json 注册数据集，常见格式：

Alpaca

{"instruction": "分类情绪", "input": "今天真好", "output": "joy"}

ShareGPT / messages

{
  "conversations": [
    {"from": "human", "value": "..."},
    {"from": "gpt", "value": "..."}
  ]
}

与 01-01 Chat Template 一致：配置里 template: llama3 / qwen 等必须和推理时一致。

---

四、YAML 配置示例（LoRA SFT）

examples/train_lora/llama3_lora_sft.yaml 风格摘要：

### model
model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct
trust_remote_code: true

### method
stage: sft
do_train: true
finetuning_type: lora
lora_rank: 16
lora_alpha: 32
lora_target: all

### dataset
dataset: my_emotion
template: llama3
cutoff_len: 1024
overwrite_cache: true

### output
output_dir: saves/llama3-emotion-lora
logging_steps: 10
save_steps: 500

### train
per_device_train_batch_size: 2
gradient_accumulation_steps: 8
learning_rate: 1.0e-4
num_train_epochs: 3.0
lr_scheduler_type: cosine
warmup_ratio: 0.1
bf16: true

启动：

llamafactory-cli train examples/train_lora/llama3_lora_sft.yaml

LoRA 参数含义见 02-01。

---

五、WebUI（LlamaBoard）

llamafactory-cli webui

浏览器中可完成：选模型、选数据集、设 LoRA rank/lr、启动训练、看 loss 曲线、导出。适合探路；上线前建议把最终参数固化为 YAML 纳入版本管理（08-02）。

---

六、DPO / 对齐

将 stage 改为 dpo，准备偏好数据集（chosen/rejected 字段），并配置 pref_beta 等。底层调用 TRL 类逻辑，与 06-01 DPOTrainer 目标相同，自定义空间小于手写 TRL。

---

七、导出与部署

操作	命令/方式
保留 adapter	默认 output_dir 含 LoRA
合并全量	llamafactory-cli export 或配置 export_dir
GGUF	部分版本支持导出；亦可 merge 后用 llama.cpp 工具链

部署见 02-04 merge、本地部署。

---

八、与 SFTTrainer 对照

项	LLaMA-Factory	SFTTrainer
配置	YAML / WebUI	Python SFTConfig
completion_only_loss	train_on_prompt: false 等	completion_only_loss=True
评估	内置部分指标	需自写 04 系列
GRPO	随版本更新	TRL 原生 06-02

---

九、常见踩坑

现象	对策
template 与模型不匹配	查官方支持的 template 列表
显存 OOM	降 cutoff_len、batch；开 flash_attn；QLoRA
数据未注册	检查 dataset_info.json 路径与 dataset 名
微调后格式乱	WebUI 改的 template 与导出推理不一致

---

十、小结

LLaMA-Factory = 低代码微调工厂；适合快速实验与演示。生产深度定制、GRPO、复杂评估仍建议 03-01 TRL。

横向对比：03-00 | 国产生态：03-03 ms-swift