LLaMA-Factory：一站式大模型微调 WebUI 安装与使用指南
一、官方信息
| 项目名称 | LLaMA-Factory |
| 仓库地址 | https://github.com/hiyouga/LLaMA-Factory |
| 官方文档 | https://llamafactory.readthedocs.io |
| 最新更新 | 持续高频迭代（2026-10-27） |
| Star 数 | 40k+ |
| 项目定位 | 清华王育弘开发的低代码大模型微调框架，支持全参数、LoRA、QLoRA、DPO/PPO/RLHF，自带 Gradio WebUI |
二、项目背景
LLaMA-Factory 由清华大学王育弘（hiyouga）发起，是目前国内最火的大模型微调开源项目。它把 LoRA、QLoRA、全参数微调、Prefix Tuning、DPO、PPO、KTO 等训练方法统一成一套配置，用户只需在 WebUI 上点选模型、数据集、学习率，一键开始训练，无需写一行 PyTorch 代码。
它支持 LLaMA、Qwen、ChatGLM、Baichuan、DeepSeek、Yi、Gemma、Phi 等几乎所有主流开源模型，内置 Alpaca、ShareGPT、Identity 等常见数据集格式，并且支持断点续训、多机多卡、DeepSpeed ZeRO、FlashAttention-2、Unsloth 加速。无论是学生毕设还是企业微调业务模型，LLaMA-Factory 都是入门首选。
三、核心特性
- WebUI 可视化：浏览器点点点即可完成数据处理→训练→合并→量化全流程。
- 全方法支持：LoRA / QLoRA / 全参数 / Freeze / P-Tuning / Prefix。
- 对齐算法：DPO / PPO / KTO / ORPO，开箱即用 RLHF。
- Unsloth 加速：开启后训练速度 2 倍、显存省 50%。
- 数据集丰富：内置 100+ 中英文数据集，一键加载；支持自定义 Alpaca/ShareGPT 格式。
- 多卡 DeepSpeed：ZeRO-2/3 配置一键切换。
- 导出 GGUF：训练完直接导出 GGUF 量化模型给 llama.cpp/Ollama 用。
四、环境要求
- Python：3.9 ~ 3.11
- GPU：NVIDIA 显卡 ≥ 8GB（QLoRA 7B）；全参数 7B 需 ≥ 4×24GB
- CUDA：11.8 / 12.1
- 磁盘：模型 + 训练中间产物 ≥ 100GB
五、详细部署步骤
方式一：pip 安装（推荐）
conda create -n llafactory python=3.10 -y
conda activate llafactory
# 安装 PyTorch（CUDA 12.1）
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
# 安装 LLaMA-Factory
pip install llamafactory
# 验证
llamafactory-cli version方式二：源码安装
git clone --depth 1 https://github.com/hiyouga/LLaMA-Factory.git
cd LLaMA-Factory
pip install -e ".[torch,metrics]"
# 验证
llamafactory-cli version方式三：Docker
docker pull hiyouga/llama-factory:latest
docker run -d \
--name llama-factory \
--gpus all \
-p 7860:7860 \
-v ~/models:/models \
-v ~/llafactory/output:/app/output \
hiyouga/llama-factory:latest启动 WebUI
llamafactory-cli webui
# 浏览器访问 http://服务器IP:7860
# 界面分四个标签：Chat / Train / Evaluate / Export命令行 LoRA 微调（以 Qwen2.5-7B 为例）
# 1. 创建配置文件 qwen_lora_sft.yaml
cat > qwen_lora_sft.yaml << 'EOF'
### 模型
model_name_or_path: /models/Qwen2.5-7B-Instruct
### 方法
stage: sft
do_train: true
finetuning_type: lora
lora_target: all
### 数据集
dataset: identity,alpaca_zh_demo
template: qwen
cutoff_len: 1024
max_samples: 1000
overwrite_cache: true
preprocessing_num_workers: 16
### 输出
output_dir: ./saves/qwen25-7b/lora/sft
logging_steps: 10
save_steps: 500
plot_loss: true
overwrite_output_dir: true
### 训练参数
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
### Unsloth 加速（可选）
use_unsloth: true
EOF
# 2. 开始训练
llamafactory-cli train qwen_lora_sft.yaml
# 3. 训练完成后 LoRA 权重在 ./saves/qwen25-7b/lora/sft合并 LoRA 权重为完整模型
# 创建 merge 配置
cat > merge.yaml << 'EOF'
model_name_or_path: /models/Qwen2.5-7B-Instruct
adapter_name_or_path: ./saves/qwen25-7b/lora/sft
template: qwen
finetuning_type: lora
export_dir: ./saves/qwen25-7b/full
export_size: 2
export_legacy_format: false
export_device: cpu
EOF
llamafactory-cli export merge.yaml
# 导出后得到完整 HF 格式模型，可直接用 vLLM / Ollama / llama.cpp 部署用 Unsloth 2 倍速训练
# 安装 unsloth
pip install unsloth
# 在 yaml 中加一行
use_unsloth: true
# 即可享受 2x 训练速度 + 50% 显存节省六、常见问题（FAQ）
Q1：显存不够跑 7B LoRA？
A：开启 QLoRA（在 yaml 加 quantization_bit: 4）+ Unsloth，8GB 显存即可。
Q2：自定义数据集怎么写？
A：Alpaca 格式 JSON：{"instruction":"...","input":"...","output":"..."}，放到 data/ 目录，在 dataset_info.json 注册后即可在 WebUI 选择。
Q3：训练 loss 不下降？
A：检查模板 template 是否与模型匹配（Qwen 用 qwen、Llama3 用 llama3），学习率是否过大（LoRA 通常 1e-4）。
Q4：如何多卡训练？
A：llamafactory-cli train my_config.yaml 默认单卡；多卡用 FORCE_TORCHRUN=1 llamafactory-cli train my_config.yaml，自动用 torchrun。
Q5：训练完如何转 GGUF？
A：Export 页面选 GGBF 量化格式，或用 llama.cpp 的 convert-hf-to-gguf.py + quantize 工具。