LLaMA-Factory 完整解读：100+ 模型一站式微调框架

主流语言模型（精选）

多模态模型

显存需求参考（7B 模型）

3.1 src/ 目录结构

src/
├── api.py                    # OpenAI 兼容 API 服务入口
├── train.py                  # 训练主入口
├── webui.py                  # Gradio WebUI 启动入口
└── llamafactory/             # 核心包
    ├── cli.py                # CLI 命令分发（train/chat/export/eval/api/webui）
    ├── launcher.py           # 分布式训练启动器（torchrun/deepspeed 封装）
    │
    ├── hparams/              # 超参数定义（dataclass 形式）
    │   ├── data_args.py      # 数据相关参数
    │   ├── finetuning_args.py # 微调方法参数（LoRA/QLoRA/Full 等）
    │   ├── generating_args.py # 生成推理参数
    │   └── model_args.py     # 模型加载参数
    │
    ├── data/                 # 数据处理模块
    │   ├── template.py       # Chat Template 定义（所有模型的对话模板）
    │   ├── dataset_info.json # 内置数据集注册表
    │   ├── loader.py         # 数据集加载（HF/ModelScope/本地）
    │   ├── processor/        # 数据预处理（SFT/PT/RM/RLHF 格式）
    │   └── collator.py       # DataCollator（序列填充、打包训练）
    │
    ├── model/                # 模型加载与适配模块
    │   ├── loader.py         # 模型加载（AutoModel/AutoTokenizer）
    │   ├── patcher.py        # 模型 Patch（注入 Flash Attention、RoPE 等）
    │   ├── adapter.py        # PEFT 适配器（LoRA/QLoRA/OFT 初始化）
    │   └── model_utils/      # 工具函数（量化、合并、导出等）
    │
    ├── train/                # 训练流程（按任务类型拆分）
    │   ├── sft/trainer.py    # CustomSeq2SeqTrainer (SFT)
    │   ├── dpo/trainer.py    # CustomDPOTrainer (DPO/ORPO/SimPO/BCO)
    │   ├── kto/trainer.py    # CustomKTOTrainer
    │   ├── ppo/trainer.py    # CustomPPOTrainer (PPOTrainer + Trainer 多重继承)
    │   └── grpo/trainer.py   # CustomGRPOTrainer
    │
    ├── chat/                 # 推理与对话模块
    │   ├── hf_engine.py      # HuggingFace 推理引擎
    │   ├── vllm_engine.py    # vLLM 推理引擎
    │   └── sglang_engine.py  # SGLang 推理引擎
    │
    ├── api/                  # OpenAI 兼容 REST API（FastAPI）
    ├── webui/                # Gradio Web UI（LLaMA Board）
    └── extras/               # 常量、日志、回调（SwanLab/WandB/TensorBoard）

3.2 核心依赖

4.1 SFT（监督微调）

用有标注的输入-输出对，最大化正确回答的对数似然。损失只计算 回答部分的 token，忽略 prompt 部分（通过 IGNORE_INDEX=-100 实现）。

# 核心损失（标准交叉熵）
loss = cross_entropy(logits, labels)  # labels 中 prompt 部分设为 -100

# 可选：ASFT 损失（参考冻结模型）
ref_logits = ref_model(input_ids).logits
loss = asft_loss(logits, labels, ref_logits, alpha)

4.2 DPO / ORPO / SimPO

绕过 Reward Model，直接用偏好对数据优化策略，使好回答相对差回答的 log 概率差更大。

# 标准 DPO 损失（beta * log_ratio_diff → sigmoid）
logits = beta * (chosen_logps - ref_chosen_logps) \
       - beta * (rejected_logps - ref_rejected_logps)
loss = -log_sigmoid(logits)

# ORPO：无需 Ref Model（log_odds 形式）
# SimPO：长度归一化 + margin，无需 Ref Model

4.3 KTO（Kahneman-Tversky Optimization）

只需二元标签（好/坏），无需配对数据，标注成本最低。利用前景理论的损失函数。

# 数据格式：(prompt, response, kto_tag: True/False)
kl = mean(policy_logps - ref_logps)  # KL 散度项
chosen_loss = 1 - sigmoid(beta * (chosen_logps - ref_chosen_logps) - beta * kl)
rejected_loss = 1 - sigmoid(beta * kl - beta * (rejected_logps - ref_rejected_logps))
loss = mean(chosen_loss) + mean(rejected_loss)

4.4 PPO（完整 RLHF）

完整在线强化学习流程：先训 Reward Model，再用 PPO 在线采样更新策略。效果最强，但流程最复杂、算力消耗最大。

# 两阶段：
# 1. 训练 RM：llamafactory-cli train  stage=rm
# 2. PPO 强化学习：
for step in steps:
    responses = model.generate(queries)        # 生成回答
    rewards = reward_model(query + response)   # RM 打分
    # PPO 更新：clipped surrogate + value loss + KL 惩罚
    L = -min(r_t * A_t, clip(r_t, 1-ε, 1+ε) * A_t) + β * KL(π || π_ref)

4.5 GRPO（DeepSeek-R1 同款）

对每个 prompt 采样 G 个回答，组内相对奖励归一化为优势值，无需 Critic / Value Head，比 PPO 更简单。

# 每个 prompt 采样 G 个回答
completions = [model.generate(prompt) for _ in range(G)]
rewards = reward_func(prompts, completions)  # 规则函数 or RM

# 组内归一化（无需 Critic！）
advantages = (rewards - mean(rewards)) / (std(rewards) + 1e-8)

# PPO-clip 风格梯度更新 + KL 惩罚
ratio = exp(policy_logps - old_logps)
loss = -min(ratio * advantages, clip(ratio, 1-ε, 1+ε) * advantages) + beta * kl

4.6 如何选择训练方法

5.1 Alpaca 格式（SFT 单轮）

[{
  "instruction": "将下面的句子翻译为英文。",
  "input": "今天天气真好。",         // 可选，与 instruction 拼接
  "output": "The weather is really nice today.",
  "system": "你是翻译助手。",        // 可选
  "history": [["Q1", "A1"], ["Q2", "A2"]]  // 可选历史对话
}]

5.2 ShareGPT 格式（多轮对话）

[{
  "conversations": [
    {"from": "human",        "value": "查询北京今天的天气"},
    {"from": "function_call","value": "{\"name\": \"get_weather\", ...}"},
    {"from": "observation",  "value": "{\"temperature\": \"25°C\"}"},
    {"from": "gpt",          "value": "北京今天天气晴，25°C，适合出行。"}
  ],
  "system": "你是天气助手。",
  "tools": "[{\"name\": \"get_weather\", ...}]"
}]

5.3 偏好数据格式（DPO/RLHF）

// Alpaca 偏好格式（ranking: true）
[{
  "instruction": "写一首关于春天的诗",
  "input": "",
  "chosen": "春风送暖入屠苏，万紫千红总是春...",  // 更好的回复
  "rejected": "春天来了，花开了，很好看。"         // 更差的回复
}]

// KTO 格式（只需好/坏标签）
[{
  "conversations": [{"role": "user", "content": "..."}, {"role": "assistant", "content": "..."}],
  "kto_tag": true   // true = 好回复，false = 差回复
}]

5.4 dataset_info.json 配置

所有数据集通过 data/dataset_info.json 注册，是 LLaMA-Factory 的数据集注册中心。

{
  // 最简 Alpaca（使用默认列名）
  "my_sft": {
    "file_name": "my_data.json"
  },

  // 自定义列名
  "my_custom": {
    "file_name": "data.json",
    "columns": {
      "prompt": "question",    // 默认 instruction
      "response": "answer"     // 默认 output
    }
  },

  // ShareGPT 多轮对话
  "my_chat": {
    "file_name": "chat.json",
    "formatting": "sharegpt",
    "columns": {"messages": "conversations", "tools": "tools"}
  },

  // DPO 偏好数据
  "my_dpo": {
    "file_name": "dpo.json",
    "ranking": true,           // 必须 true
    "formatting": "sharegpt",
    "columns": {"messages": "conversations", "chosen": "chosen", "rejected": "rejected"}
  },

  // 从 HuggingFace 加载
  "openorca": {
    "hf_hub_url": "Open-Orca/OpenOrca",
    "columns": {"prompt": "question", "response": "response", "system": "system_prompt"}
  }
}

快速准备自定义数据集（5 步）

6.1 安装

git clone --depth 1 \
  https://github.com/hiyouga/LlamaFactory.git
cd LlamaFactory
pip install -e .

docker run -it --rm \
  --gpus=all --ipc=host \
  hiyouga/llamafactory:latest

uv run llamafactory-cli webui

可选依赖

6.2 第一次训练（Qwen3-4B LoRA SFT）

### model
model_name_or_path: Qwen/Qwen3-4B-Instruct
trust_remote_code: true

### method
stage: sft
do_train: true
finetuning_type: lora
lora_rank: 8
lora_target: all

### dataset
dataset: identity,alpaca_en_demo
template: qwen3_nothink     # 必须与模型对应
cutoff_len: 2048
max_samples: 1000

### output
output_dir: saves/qwen3-4b/lora/sft
logging_steps: 10
save_steps: 500
plot_loss: true
overwrite_output_dir: true

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

CUDA_VISIBLE_DEVICES=0 llamafactory-cli train train_qwen3_lora_sft.yaml

llamafactory-cli chat examples/inference/qwen3_lora_sft.yaml

llamafactory-cli export examples/merge_lora/qwen3_lora_sft.yaml
# ⚠️ 合并时不要使用 quantization_bit

6.3 核心 YAML 配置字段详解

模型配置

训练方法配置

训练超参数

6.4 CLI 命令速查

# 常用训练命令
CUDA_VISIBLE_DEVICES=0 llamafactory-cli train config.yaml                        # 单 GPU
CUDA_VISIBLE_DEVICES=0,1 llamafactory-cli train config.yaml                      # 多 GPU
FORCE_TORCHRUN=1 llamafactory-cli train config.yaml                              # torchrun
FORCE_TORCHRUN=1 llamafactory-cli train config_ds3.yaml                          # DeepSpeed ZeRO-3

# 命令行覆盖 YAML 参数
llamafactory-cli train config.yaml learning_rate=5e-5 num_train_epochs=5

LLaMA Board WebUI

llamafactory-cli webui   # 本地访问 http://localhost:7860

vLLM 高性能推理（推荐生产）

# 启动 OpenAI 兼容 API Server（vLLM backend）
API_PORT=8000 llamafactory-cli api infer.yaml infer_backend=vllm

# 使用 OpenAI SDK 调用
from openai import OpenAI
client = OpenAI(base_url="http://localhost:8000/v1", api_key="0")
response = client.chat.completions.create(
    model="your-model",
    messages=[{"role": "user", "content": "你好！"}]
)

# 先合并 LoRA 再用 vLLM 直接加载（性能最优）
llamafactory-cli export merge.yaml
vllm serve /path/to/merged_model --served-model-name my-ft-model

实验监控集成

# W&B
report_to: wandb

# SwanLab（国产，支持中文）
use_swanlab: true
swanlab_api_key: YOUR_KEY