LLaMA-Factory — 百模千训的统一高效微调框架

GitHub: hiyouga/LLaMA-Factory
Stars: 72,200+ | Language: Python (99.7%) | License: Apache-2.0
最新版本: v0.9.5（2026 年 5 月）| 论文: ACL 2024

目录

1. 项目速览
2. 功能概述
3. 适用场景
4. 快速上手
5. 源码架构
6. 实操 Demo
7. 同类对比
8. 参考资源

项目速览

LLaMA-Factory 是目前 GitHub 上 Star 数最高的大模型微调框架（72.2k Star），由郑耀威（hiyouga）主导开发，其学术论文被 ACL 2024 录用。项目的核心定位是”统一高效微调”（Unified Efficient Fine-Tuning），用一个框架覆盖从预训练、指令微调、偏好对齐到推理部署的完整生命周期，支持 100+ 种大语言模型和视觉语言模型。

传统微调流程中，开发者需要为不同模型分别编写训练脚本、处理数据格式、配置分布式策略。LLaMA-Factory 通过统一的 YAML 配置驱动和 CLI 命令行接口，将这些重复工作抽象为可复用的配置文件，大幅降低了微调门槛。无论是单卡 LoRA 微调 Qwen3-4B，还是多卡全量训练 DeepSeek-V3，都只需要一条命令。

项目自 2023 年发布以来已迭代 36 个版本，社区贡献者超过 200 人。2026 年 5 月发布的 v0.9.5 已支持 Qwen3.5/3.6、Gemma 4 等最新模型，并跟进 Transformers v5。

功能概述

模型覆盖 — 100+ LLMs & VLMs

LLaMA-Factory 支持几乎所有主流开源模型家族：

厂商	模型系列
Meta	Llama, Llama 2, Llama 3-3.3, Llama 4, Llama 3.2 Vision
阿里	Qwen2, Qwen3, Qwen3.5, Qwen3.6, Qwen2-VL, Qwen2.5-VL, Qwen3-VL, Qwen2-Audio, Qwen2.5-Omni
谷歌	Gemma, Gemma 2, Gemma 3/3n, Gemma 4, PaliGemma, CodeGemma
DeepSeek	DeepSeek (LLM/Code/MoE), DeepSeek V3, DeepSeek R1 (Distill)
Mistral	Mistral, Mixtral, Ministral 3, Pixtral
智谱	GLM-4, GLM-Z1, GLM-4.5, GLM-4.6V
上海 AI Lab	InternLM 2-3, InternVL 2.5-3.5
微软	Phi-3/3.5, Phi-4, Phi-4-mini
其他	MiniCPM 4, MiniCPM-o/V 4.5, MiniMax-M1/M2, Falcon, StarCoder 2, TeleChat 2

训练方法矩阵

LLaMA-Factory 提供从预训练到强化学习的完整训练方法栈：

阶段	支持方法
预训练	Full-tuning, LoRA, QLoRA, GaLore, BAdam, APOLLO
指令微调 (SFT)	Full-tuning, Freeze-tuning, LoRA, QLoRA (2/3/4/5/6/8-bit), OFT, QOFT
奖励建模 (RM)	Full-tuning, LoRA, QLoRA
偏好对齐	DPO, KTO, ORPO, SimPO, PPO
多模态	LLaVA-NeXT, Qwen2-VL, Pixtral, 视频识别, 音频理解

LoRA 变体丰富：DoRA、LongLoRA、LoRA+、LoftQ、PiSSA、rsLoRA，以及量化后端 AQLM/AWQ/GPTQ/LLM.int8/HQQ/EETQ。

推理与部署

训练完成后，LLaMA-Factory 提供三种推理模式：

# 1. 命令行对话
llamafactory-cli chat examples/inference/qwen3_lora_sft.yaml

# 2. Gradio Web UI
llamafactory-cli webui

# 3. OpenAI 兼容 API（支持 vLLM/SGLang worker 加速）
API_PORT=8000 llamafactory-cli api examples/inference/qwen3.yaml

实验监控支持 TensorBoard、Wandb、MLflow、SwanLab，以及自带的 LlamaBoard 可视化面板。

适用场景

1. 快速模型微调验证：研究人员切换模型做对比实验，只需修改 YAML 中的 model_name_or_path 字段，无需重写训练脚本。
2. 生产级垂直领域适配：企业将开源基座模型微调到医疗、法律、金融等垂直领域，LoRA 合并后通过 API 部署上线。
3. 多模态指令微调：统一框架同时处理文本 SFT 和 VLM 指令微调（如 Qwen2-VL 的图像理解和视频识别）。
4. 偏好对齐实验：在同一框架内对比 DPO、KTO、ORPO、SimPO 等对齐方法的效果差异。
5. 教育资源受限场景：QLoRA 4-bit 模式下，7B 模型仅需 6GB 显存即可训练，适合个人开发者。

快速上手

安装

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

如果需要国内镜像加速，设置环境变量 export USE_MODELSCOPE_HUB=1 从 ModelScope 下载模型。

训练配置

以 Qwen3-4B-Instruct 的 LoRA 微调为例，配置文件 examples/train_lora/qwen3_lora_sft.yaml：

### model
model_name_or_path: Qwen/Qwen3-4B-Instruct-2507
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
report_to: none

### 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
ddp_timeout: 180000000

执行训练

# 单卡 LoRA 训练
llamafactory-cli train examples/train_lora/qwen3_lora_sft.yaml

# 多卡 DeepSpeed 训练
deepspeed --num_gpus=4 llamafactory-cli train examples/train_lora/qwen3_lora_sft.yaml

# 导出合并 LoRA 权重
llamafactory-cli export examples/merge_lora/qwen3_lora_sft.yaml

显存需求参考

训练方法	量化位数	7B	14B	30B	70B
Full (bf16)	32	120GB	240GB	600GB	1200GB
LoRA	16	16GB	32GB	64GB	160GB
QLoRA	8	10GB	20GB	40GB	80GB
QLoRA	4	6GB	12GB	24GB	48GB
QLoRA	2	4GB	8GB	16GB	24GB

源码架构

LLaMA-Factory 的仓库结构清晰，核心逻辑集中在 src/llamafactory/ 下：

src/llamafactory/
├── api/                # OpenAI 兼容 API 服务
├── chat/               # 对话推理（CLI + Gradio WebUI）
├── data/               # 数据加载、预处理、模板系统
│   ├── template/       # 各模型的对话模板（qwen3_nothink, llama3 等）
│   └── processor/      # 多模态数据处理器（图像、视频、音频）
├── extract/            # 模型导出与 LoRA 合并
├── hparams/            # 超参数定义（训练参数、模型参数、数据参数）
├── model/              # 模型加载器（支持 100+ 种架构）
│   ├── adapter.py      # LoRA/QLoRA 适配器
│   └── patcher.py      # 模型补丁（FlashAttention、RoPE 缩放等）
├── train/              # 训练器（SFT/RM/DPO/KTO/PPO 等）
│   ├── sft/            # 监督微调训练器
│   ├── dpo/            # DPO/KTO 训练器
│   └── ppo/            # PPO 训练器
├── webui/              # LlamaBoard 可视化面板
└── launcher.py         # CLI 入口

核心设计模式：

1. 配置驱动：所有训练参数通过 YAML 文件声明式配置，CLI 仅负责解析和分发。
2. 模板系统：通过 template_name 字段自动匹配不同模型的对话格式，无需手动拼接 ChatML/Prompt 模板。
3. 插件化训练器：SFT、DPO、PPO 等训练器共享统一的模型加载和数据管线，通过 stage 字段切换。
4. 模型补丁机制：FlashAttention-2、Unsloth 加速、Liger Kernel 等优化通过运行时打补丁注入，不修改模型源码。

实操 Demo

以下演示一个完整的 Qwen3-4B 医疗问答微调流程。

步骤 1：准备自定义数据集

将医疗问答数据整理为 LLaMA-Factory 支持的 JSON 格式 medical_qa.json：

[
  {
    "instruction": "患者出现持续性头痛和视力模糊，可能是什么原因？",
    "input": "",
    "output": "持续性头痛伴视力模糊可能与以下原因有关：1）偏头痛，常伴视觉先兆；2）颅内压增高，需排除颅内占位性病变；3）青光眼急性发作。建议尽快前往神经内科和眼科就诊，进行头颅CT和眼压检查。"
  },
  {
    "instruction": "二甲双胍的常见副作用有哪些？",
    "input": "",
    "output": "二甲双胍常见副作用包括：1）胃肠道反应：恶心、腹泻、食欲减退，多见于用药初期，随餐服用可减轻；2）乳酸酸中毒：罕见但严重，肾功能不全者禁用；3）长期使用可能导致维生素B12缺乏。建议定期监测肾功能和维生素B12水平。"
  }
]

步骤 2：注册数据集

在 data/dataset_info.json 中添加：

{
  "medical_qa": {
    "file_name": "medical_qa.json",
    "columns": {
      "prompt": "instruction",
      "query": "input",
      "response": "output"
    }
  }
}

步骤 3：配置训练参数

创建 examples/train_lora/medical_lora_sft.yaml：

### model
model_name_or_path: Qwen/Qwen3-4B-Instruct-2507

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

### dataset
dataset: medical_qa
template: qwen3_nothink
cutoff_len: 2048

### output
output_dir: saves/medical-qa-lora
logging_steps: 10
save_steps: 200
save_total_limit: 2
report_to: tensorboard

### train
per_device_train_batch_size: 2
gradient_accumulation_steps: 4
learning_rate: 5.0e-5
num_train_epochs: 5.0
lr_scheduler_type: cosine
warmup_ratio: 0.05
bf16: true

步骤 4：训练与评估

# 启动训练
llamafactory-cli train examples/train_lora/medical_lora_sft.yaml

# TensorBoard 监控
tensorboard --logdir saves/medical-qa-lora

# 测试对话
llamafactory-cli chat examples/train_lora/medical_lora_sft.yaml

同类对比

维度	LLaMA-Factory	Axolotl	unsloth
Star 数	72.2k	12k	66.6k
模型覆盖	100+ LLMs & VLMs	80+ LLMs & VLMs	通过 HuggingFace 通用适配
训练方法	SFT/RM/DPO/KTO/ORPO/PPO/SimPO	SFT/DPO/IPO/KTO/ORPO/GRPO/GDPO	SFT/GRPO/Pretrain
配置方式	YAML CLI 驱动	YAML CLI 驱动	Python Notebook / Studio WebUI
多模态	图像、视频、音频	图像、音频	视觉（VLM GRPO）
显存优化	QLoRA 2/3/4/5/6/8-bit	QLoRA, QAT, FP8	自研 Triton Kernel，2x 加速
学习曲线	中等	中等	低（Notebook 交互式）
特色功能	LlamaBoard 面板、vLLM API	GRPO 强化学习、agent-docs	Unsloth Studio 可视化训练
许可证	Apache-2.0	Apache-2.0	Apache-2.0 + AGPL-3.0

LLaMA-Factory 的核心优势在于”最广覆盖”：模型数量、训练方法种类、部署模式都领先同类。如果你需要在一个框架内完成从预训练到对齐再到 API 部署的全流程，LLaMA-Factory 是最全面的选择。Axolotl 在强化学习（GRPO）方面更激进，unsloth 则在显存优化和易用性上更极致。

参考资源

• GitHub 仓库： https://github.com/hiyouga/LLaMA-Factory
• 官方文档： https://llamafactory.readthedocs.io
• 技术博客： https://blog.llamafactory.net
• 学术论文： “LLaMA-Factory: Unified Efficient Fine-Tuning of 100+ Language Models” (ACL 2024)
• Hugging Face 组织： https://huggingface.co/hiyouga
• 预置配置示例： examples/ — 覆盖 LoRA/QLoRA/Full/DPO/PPO 等全部训练方法