LLaMA-Factory 完整使用手册

版本: 2026年5月 | 适用版本: LLaMA-Factory v0.9+

LLaMA-Factory 是一个统一、高效且易用的大模型微调框架，支持 100+ 种模型（LLaMA、Qwen、ChatGLM、Baichuan 等）和多种微调方法（LoRA、QLoRA、全参数、冻结等）。

目录

1. 环境安装与部署
2. 快速开始：LoRA 微调
3. 数据集准备与格式
4. 微调方法详解
5. 核心参数详解
6. 各阶段训练配置
7. 模型导出与部署
8. WebUI 使用指南
9. 常见问题与排查

1. 环境安装与部署

1.1 硬件要求

1.2 环境安装

方式一：pip 安装（推荐）

# 创建 conda 环境
conda create -n llama_factory python=3.10 -y
conda activate llama_factory

# 克隆仓库
git clone https://github.com/hiyouga/LLaMA-Factory.git
cd LLaMA-Factory

# 安装依赖（包含评估指标）
pip install -e ".[metrics]"

# 如需量化训练，安装 bitsandbytes
pip install bitsandbytes

# 如需 Flash Attention 加速（Linux/Ampere架构GPU）
pip install flash-attn --no-build-isolation

方式二：Docker 部署

# 拉取官方镜像
docker pull nvcr.io/nvidia/pytorch:24.02-py3

# 运行容器
docker run --gpus all -it --rm   -v $(pwd)/LLaMA-Factory:/workspace   -v $(pwd)/data:/data   -p 7860:7860   nvcr.io/nvidia/pytorch:24.02-py3

# 在容器内安装
cd /workspace
pip install -e ".[metrics]"

1.3 环境验证

# 验证 LLaMA-Factory 安装
llamafactory-cli train -h

# 验证 PyTorch 和 CUDA
python -c "
import torch
print(f'PyTorch: {torch.__version__}')
print(f'CUDA可用: {torch.cuda.is_available()}')
print(f'GPU: {torch.cuda.get_device_name(0)}')
print(f'CUDA版本: {torch.version.cuda}')
"

1.4 模型下载

# 方式1：使用 HuggingFace（需网络环境）
# 模型会在首次使用时自动下载

# 方式2：使用 ModelScope（国内推荐）
pip install modelscope
export USE_MODELSCOPE=True

# 方式3：手动下载到本地
# 从 https://huggingface.co 或 https://modelscope.cn 下载模型文件
# 放置于 ./models/ 目录下

2. 快速开始：LoRA 微调

2.1 最简命令行训练

llamafactory-cli train     --stage sft     --do_train     --model_name_or_path meta-llama/Meta-Llama-3-8B-Instruct     --dataset alpaca_gpt4_en     --template llama3     --finetuning_type lora     --lora_target all     --output_dir saves/llama3-8b/lora/sft     --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     --logging_steps 10     --save_steps 500     --plot_loss

2.2 使用 YAML 配置文件

创建 train_lora.yaml：

### 模型配置
model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct
trust_remote_code: true

### 方法配置
stage: sft
do_train: true
finetuning_type: lora
lora_rank: 8
lora_alpha: 16
lora_target: all
lora_dropout: 0.05

### 数据集配置
dataset: identity,alpaca_en_demo
template: llama3
cutoff_len: 2048
max_samples: 1000
overwrite_cache: true
preprocessing_num_workers: 16

### 输出配置
output_dir: saves/llama3-8b/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

### 评估配置
val_size: 0.1
per_device_eval_batch_size: 1
eval_strategy: steps
eval_steps: 500

执行训练：

llamafactory-cli train train_lora.yaml

2.3 覆盖配置文件参数

llamafactory-cli train train_lora.yaml     learning_rate=5e-5     num_train_epochs=5     logging_steps=1

3. 数据集准备与格式

3.1 数据集目录结构

data/
├── dataset_info.json      # 数据集注册文件
├── identity.json          # 自定义数据集
├── alpaca_en_demo.json    # 示例数据集
└── ...

3.2 注册数据集

编辑 data/dataset_info.json：

{
  "identity": {
    "file_name": "identity.json",
    "formatting": "alpaca",
    "columns": {
      "prompt": "instruction",
      "query": "input",
      "response": "output"
    }
  },
  "my_dataset": {
    "file_name": "my_dataset.json",
    "formatting": "sharegpt",
    "columns": {
      "messages": "messages",
      "system": "system"
    },
    "tags": {
      "role_tag": "role",
      "content_tag": "content",
      "user_tag": "user",
      "assistant_tag": "assistant"
    }
  }
}

3.3 数据格式详解

格式一：Alpaca 格式（单轮指令）

[
  {
    "instruction": "解释什么是机器学习",
    "input": "",
    "output": "机器学习是人工智能的一个分支，它使计算机能够从数据中学习模式...",
    "system": "你是一个有帮助的AI助手"
  },
  {
    "instruction": "翻译以下句子",
    "input": "今天天气真好",
    "output": "The weather is nice today."
  }
]

格式二：ShareGPT 格式（多轮对话）

[
  {
    "messages": [
      {"role": "system", "content": "你是一个专业的翻译助手。"},
      {"role": "user", "content": "翻译：你好世界"},
      {"role": "assistant", "content": "Hello World"},
      {"role": "user", "content": "翻译成法语"},
      {"role": "assistant", "content": "Bonjour le monde"}
    ]
  }
]

格式三：预训练格式（纯文本）

[
  {"text": "这是第一个文档的内容。可以是任意长度的纯文本。"},
  {"text": "这是第二个文档。预训练只需要纯文本，不需要指令或回复。"}
]

3.4 对话模板（Template）

不同模型需要不同的对话模板：

⚠️ 重要: template 必须与模型匹配，否则训练效果会严重下降！

4. 微调方法详解

4.1 方法对比

4.2 LoRA 微调

finetuning_type: lora
lora_rank: 8              # 秩，通常 4-64
lora_alpha: 16            # 缩放因子，通常为 rank 的 1-2 倍
lora_dropout: 0.05        # Dropout 比例，防止过拟合
lora_target: all          # 目标模块：all / q_proj,v_proj / 自定义
lora_rank_pattern: {}     # 为不同层设置不同 rank
lora_alpha_pattern: {}     # 为不同层设置不同 alpha
use_rslora: false         # 是否使用 RS-LoRA（秩稳定 LoRA）

LoRA 目标模块选择：

# 仅注意力层（最轻量）
lora_target: q_proj,v_proj

# 注意力 + FFN（平衡）
lora_target: q_proj,k_proj,v_proj,o_proj,gate_proj,up_proj,down_proj

# 所有线性层（效果最好，参数量最大）
lora_target: all

4.3 QLoRA 微调（量化 + LoRA）

finetuning_type: lora
quantization_bit: 4          # 4-bit 量化（可选 4 或 8）
quantization_method: bitsandbytes  # 量化方法
double_quantization: true    # 嵌套量化，进一步节省显存
quantization_type: nf4       # 4-bit 量化类型：nf4 / fp4

4.4 全参数微调

finetuning_type: full
# 需要配合 DeepSpeed 使用
# deepspeed: examples/deepspeed/ds_z3_config.json

DeepSpeed Zero 配置示例 (ds_z3_config.json)：

{
  "train_batch_size": "auto",
  "train_micro_batch_size_per_gpu": "auto",
  "gradient_accumulation_steps": "auto",
  "gradient_clipping": "auto",
  "zero_optimization": {
    "stage": 3,
    "offload_optimizer": {
      "device": "cpu"
    },
    "offload_param": {
      "device": "cpu"
    },
    "overlap_comm": true,
    "contiguous_gradients": true
  },
  "fp16": {
    "enabled": "auto"
  },
  "bf16": {
    "enabled": "auto"
  }
}

4.5 冻结微调

finetuning_type: freeze
freeze_trainable_layers: 8        # 训练最后 N 层
freeze_trainable_modules: "mlp"   # 训练指定模块
freeze_extra_modules: "embed"     # 额外训练的模块
use_llama_pro: false             # 是否使用 LLaMA Pro 扩展

5. 核心参数详解

5.1 模型与数据参数

5.2 微调方法参数

5.3 训练参数

5.4 输出与保存参数

5.5 评估参数

5.6 优化器参数

5.7 高级参数

6. 各阶段训练配置

6.1 监督微调 (SFT)

stage: sft
do_train: true
finetuning_type: lora
lora_rank: 8
lora_alpha: 16
lora_target: all

dataset: alpaca_gpt4_zh
template: qwen
cutoff_len: 2048

per_device_train_batch_size: 2
gradient_accumulation_steps: 4
learning_rate: 5e-5
num_train_epochs: 3
lr_scheduler_type: cosine
warmup_ratio: 0.1
bf16: true

6.2 预训练 (PT)

stage: pt
do_train: true
finetuning_type: lora

# 预训练使用纯文本数据
dataset: wiki_text
template: default
cutoff_len: 2048

per_device_train_batch_size: 1
gradient_accumulation_steps: 8
learning_rate: 2e-4
num_train_epochs: 1

6.3 奖励模型训练 (RM)

stage: rm
do_train: true
finetuning_type: lora

# RM 需要偏好数据
dataset: comparison_gpt4
template: llama3

# 使用 SFT 后的模型作为基础
model_name_or_path: saves/llama3-8b/lora/sft

6.4 PPO 强化学习

stage: ppo
do_train: true
finetuning_type: lora

# PPO 需要奖励模型
reward_model: saves/llama3-8b/lora/rm
ppo_epochs: 4
ppo_buffer_size: 1
ppo_target: 6.0

6.5 DPO 直接偏好优化

stage: dpo
do_train: true
finetuning_type: lora

# DPO 需要偏好数据（chosen/rejected）
dataset: dpo_en_demo
template: llama3

# DPO 特有参数
dpo_beta: 0.1
dpo_loss: sigmoid  # sigmoid/ipo/kto_pair/simpo
label_smoothing: 0.0

6.6 KTO 优化

stage: kto
do_train: true
finetuning_type: lora

# KTO 需要二元反馈数据
dataset: kto_en_demo
template: llama3

# KTO 特有参数
desirable_weight: 1.0
undesirable_weight: 1.0

7. 模型导出与部署

7.1 合并 LoRA 权重

llamafactory-cli export     --model_name_or_path meta-llama/Meta-Llama-3-8B-Instruct     --adapter_name_or_path saves/llama3-8b/lora/sft     --template llama3     --export_dir merged_model     --export_size 2     --export_device cpu

7.2 量化导出

llamafactory-cli export     --model_name_or_path meta-llama/Meta-Llama-3-8B-Instruct     --adapter_name_or_path saves/llama3-8b/lora/sft     --template llama3     --export_dir merged_gguf     --export_quantization_bit 4     --export_quantization_dataset data/c4_demo.json

7.3 启动 API 服务

# 使用 LoRA 适配器启动
llamafactory-cli api     --model_name_or_path meta-llama/Meta-Llama-3-8B-Instruct     --adapter_name_or_path saves/llama3-8b/lora/sft     --template llama3

# 访问 http://localhost:8000/docs 查看 API 文档

7.4 启动 CLI 聊天

llamafactory-cli chat     --model_name_or_path meta-llama/Meta-Llama-3-8B-Instruct     --adapter_name_or_path saves/llama3-8b/lora/sft     --template llama3

8. WebUI 使用指南

8.1 启动 WebUI

# 本地启动
llamafactory-cli webui

# 指定端口和监听地址
GRADIO_SHARE=1 llamafactory-cli webui --server_name 0.0.0.0 --server_port 7860

# 使用 Docker
docker run --gpus all -p 7860:7860 hiyouga/llama-factory:latest

8.2 WebUI 功能模块

8.3 WebUI 配置示例

1. 选择模型: 在"模型名称"下拉框选择或输入模型路径
2. 配置微调方法: 选择 LoRA/QLoRA/Full/Freeze
3. 配置数据集: 选择已注册的数据集
4. 设置训练参数: 学习率、轮数、批次大小等
5. 点击预览数据集: 确认数据格式正确
6. 开始训练: 点击"开始"按钮

9. 常见问题与排查

9.1 OOM（显存不足）

解决方案：

1. 减小 per_device_train_batch_size（设为 1）
2. 增大 gradient_accumulation_steps
3. 减小 cutoff_len（如 1024 或 512）
4. 启用 gradient_checkpointing: true
5. 使用 QLoRA（quantization_bit: 4）
6. 使用 DeepSpeed ZeRO-3 + CPU Offload

9.2 训练速度过慢

优化建议：

1. 增大 per_device_train_batch_size（显存允许时）
2. 安装 Flash Attention（pip install flash-attn）
3. 关闭 gradient_checkpointing（显存充足时）
4. 使用 bf16 而非 fp16（Ampere 架构）
5. 增加 dataloader_num_workers

9.3 loss 不下降或发散

排查步骤：

1. 检查学习率是否过大（LoRA 建议 1e-4 ~ 5e-4）
2. 检查数据集格式是否正确
3. 检查 template 是否与模型匹配
4. 增加 warmup_ratio（如 0.1）
5. 减小 lora_rank 或增大 lora_alpha
6. 检查数据是否有大量重复或噪声

9.4 模型生成重复内容

解决方案：

# 在推理时设置生成参数
generation_config:
  do_sample: true
  temperature: 0.7
  top_p: 0.9
  repetition_penalty: 1.1
  max_new_tokens: 512

9.5 多卡训练配置

# 指定 GPU
CUDA_VISIBLE_DEVICES=0,1,2,3 llamafactory-cli train train.yaml

# 使用 DeepSpeed
llamafactory-cli train train.yaml --deepspeed ds_config.json

# 使用 FSDP
torchrun --nnodes 1 --nproc_per_node 4 src/train.py train.yaml

9.6 训练中断恢复

# 在配置文件中设置
resume_from_checkpoint: saves/llama3-8b/lora/sft/checkpoint-500

附录 A：推荐配置速查表

A.1 消费级显卡 (24GB)

# 7B/8B 模型 LoRA
model_name_or_path: Qwen/Qwen2.5-7B-Instruct
finetuning_type: lora
lora_rank: 16
lora_alpha: 32
quantization_bit: null  # 或 4 用于更大模型

per_device_train_batch_size: 1
gradient_accumulation_steps: 8
learning_rate: 1e-4
bf16: true

A.2 专业级显卡 (48GB)

# 13B 模型 LoRA
model_name_or_path: Qwen/Qwen2.5-14B-Instruct
finetuning_type: lora
lora_rank: 32
lora_alpha: 64

per_device_train_batch_size: 2
gradient_accumulation_steps: 4
learning_rate: 5e-5
bf16: true

A.3 多卡 A100 (80GB × 8)

# 70B 模型全参数微调
model_name_or_path: meta-llama/Meta-Llama-3-70B-Instruct
finetuning_type: full
deepspeed: ds_z3_config.json

per_device_train_batch_size: 4
gradient_accumulation_steps: 2
learning_rate: 2e-5
bf16: true

附录 B：CLI 命令汇总

📌 提示: 更多高级功能（多模态训练、MoE 模型、长上下文扩展等）请参考 LLaMA-Factory 官方文档。