hiyouga/LlamaFactory · 上手攻略

  • 仓库：hiyouga/LlamaFactory
  • 链接：https://github.com/hiyouga/LlamaFactory
  • 分类：ai
  • 作者：Tom
  • 更新：2026-07-09

这是什么

LLaMA Factory 是一个统一的大模型微调框架，支持对 100+ 开源 LLM 与 VLM（视觉语言模型）进行高效微调。项目源自学术论文（ACL 2024），定位为工程级生产工具，在 GitHub 已积累超过 7.3 万 Stars，是目前最活跃的 LLM 微调开源项目之一。

其核心定位是：让微调大模型变得像"跑训练命令"一样简单——即便是 7B 参数的模型，用 QLoRA 在单卡消费级 GPU 上也能跑起来，同时支持从预训练、SFT、RLHF（PPO/DPO/KTO/ORPO）到增量更新等全链路训练方法。

解决什么问题

从零训练大模型成本极高，绝大多数场景下是在已有开源模型基础上做领域适配或任务定制。LLaMA Factory 解决了以下几个痛点：

  • 框架碎片化：不同模型往往需要不同的微调代码和参数配置；LLaMA Factory 用一套统一入口覆盖所有主流模型。
  • 硬件门槛高：通过量化微调（QLoRA）和各种低显存优化（FlashAttention、Unsloth、Liger Kernel 等），让 7B 模型用一张 4090 就能微调。
  • 方法论门槛高：集成了 GaLore、BAdam、APOLLO、Muon 等前沿优化器，普通用户无需从零实现。
  • 可复现性差：通过 YAML 配置文件声明式描述训练流程，结果可存档、可对比。

快速安装

方式一：pip 快速安装（推荐用于已有环境）

pip install llamafactory

⚠️ 注意：包名为 llamafactory（全小写），不是 LLaMA-Factory。

安装完成后可验证：

llamafactory-cli version   # 确认安装成功

方式二：从源码安装（推荐用于开发或自定义场景）

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

方式三：Docker（零依赖）

docker pull hiyouga/llamafactory:latest
docker run -d --gpus all -p 7860:7860 \
  -v ./data:/app/data \
  -v ./output:/app/output \
  hiyouga/llamafactory:latest

免费云端试用

  • Google Colab（T4 免费 GPU）：https://colab.research.google.com/drive/1eRTPn37ltBbYsISy9Aw2NuI2Aq5CQrD9
  • 阿里云 PAI-DSW（免费试用额度）：https://gallery.pai-ml.com/#/preview/deepLearning/nlp/llama_factory

核心用法

1. 数据准备

LLaMA Factory 支持 JSONL 格式数据集，示例：

{"messages": [{"role": "user", "content": "你好"}, {"role": "assistant", "content": "你好！有什么可以帮你的吗？"]}
{"messages": [{"role": "user", "content": "解释量子纠缠"}, {"role": "assistant", "content": "量子纠缠是……"}]}

在 data/ 目录下放置数据集后，还需在 dataset_info.json 中注册：

{
  "my_dataset": {
    "file_name": "my_dataset.jsonl",
    "formatting": "sharegpt",
    "columns": {
      "messages": "messages"
    }
  }
}

2. 配置文件示例（QLoRA 微调 Qwen3-7B）

创建 qwen3_qlora.yaml：

### 模型
model_name_or_path: Qwen/Qwen2.5-7B-Instruct
quantization_bit: 4                    # 4bit QLoRA，显存占用最低

### 训练方法
stage: sft                             # supervised fine-tuning
do_train: true
finetuning_type: lora                  # LoRA 微调

### LoRA 配置
lora_rank: 8
lora_alpha: 16
lora_dropout: 0.05
lora_target: all                       # 对所有权重应用 LoRA

### 数据集（需提前在 dataset_info.json 注册）
dataset: my_dataset
template: qwen2
cutoff_len: 2048
max_samples: 1000

### 训练参数
output_dir: ./output/qwen3_qlora
per_device_train_batch_size: 1
gradient_accumulation_steps: 16
learning_rate: 1.0e-4
num_train_epochs: 3.0
lr_scheduler_type: cosine
logging_steps: 10
save_steps: 500
warmup_ratio: 0.1

### 优化（降低显存）
use_flash_attn: true
enable_liger_kernel: true             # LinkedIn Liger Kernel，加速且省显存

⚠️ llamafactory-cli 命令的具体参数格式请以项目 examples/ 目录下的实际 YAML 文件为准，README 中示例可能存在细微差异。

3. 开始训练

llamafactory-cli train examples/train_full/qwen3_full.yaml
# 或直接指定 YAML 路径
llamafactory-cli train ./qwen3_qlora.yaml

4. LLaMA Board 可视化微调

llamafactory-cli webchat examples/inference/llama3_full.yaml
# 启动后访问 http://localhost:7860

内置 Gradio 可视化界面，支持监控训练曲线、调整 LoRA 权重、实时对话测试。

5. 模型导出与部署

训练完成后，将 LoRA 权重合并回原模型并导出：

llamafactory-cli export examples/inference/llama3_full.yaml

支持导出为 Ollama 格式（modelfile），可直接用 Ollama 运行微调后的模型。

6. OpenAI 风格 API 部署（搭配 vLLM）

# 使用 vLLM worker 启动 API 服务
llamafactory-cli serve examples/inference/llama3_full.yaml \
  --worker vllm

API 接口风格与 OpenAI ChatGPT 兼容，可直接替换现有应用中的模型后端。

典型适用场景

场景 推荐配置
领域问答助手（医疗/法律/金融） QLoRA + 领域数据集 + SFT
角色扮演/对话模型 LoRA + DPO/ORPO 对比学习
多模态视觉问答 LLaVA 系列 + Qwen2.5-VL + 全参数 SFT
推理能力强化（Math/Code） DeepSeek-R1 系列 + GRPO/EasyR1
企业知识库微调 Qwen3 + 知识蒸馏 + KTO

坑与注意

  1. GitHub URL 大小写问题：README 链接为 https://github.com/hiyouga/LlamaFactory，但仓库实际名称为 LLaMA-Factory（两个大写 A）。克隆时建议用 https://github.com/hiyouga/LLaMA-Factory.git 避免歧义。

  2. GPU 显存估算：7B QLoRA（4bit）约需 6-8 GB；7B 全参数约需 14-16 GB；70B 全参数需多卡。训练前建议参考官方显存计算表。

  3. 模型版权与许可：LLaMA 系列的许可证经历多次变更，微调前务必确认基础模型当前许可证（Meta LLaMA 已转为可商用，但部分版本有限制）。

  4. 数据集格式踩坑：如果用 sharegpt 格式，role 字段必须是 system、user、assistant 三种之一，不能自定义。

  5. enable_liger_kernel: true 是可选优化，开启后训练速度提升约 20-30%，但部分 CUDA 版本可能不兼容，遇到报错可关闭。

  6. vLLM 推理后端：需要提前安装 vllm>=0.4.0（pip install vllm），否则默认使用 HuggingFace 推理，速度较慢。

  7. 国内下载模型慢：推荐使用 ModelScope（魔搭）或 Modelers Hub（魔乐）下载，README 中有对应配置示例。

与同类对比

特性 LLaMA Factory Axolotl SWIFT（魔搭） PEFT（仅库）
模型覆盖 100+ 30+ 100+ 所有 HF 模型
训练方法 SFT/DPO/PPO/KTO/ORPO/GRPO SFT/DPO/PPO SFT/DPO/PPO 仅 LoRA/prefix
量化支持 AQLM/AWQ/GPTQ/llm.int8/HQQ AWQ/GPTQ AWQ/GPTQ 依赖 transformers
多模态 LLaVA/Qwen2.5-VL 等 有限 较全 有限
可视化 LLaMA Board（Gradio） 无 DSW 集成 无
中文文档 较全（README_zh） 无 丰富 无
Stars 73k 12k 28k 核心依赖库

一句话结论：如果你需要在一个统一环境里微调尽可能多种类的模型（尤其是中文模型 Qwen、GLM、DeepSeek），且希望有 GUI 界面和完整的 RLHF 链路，LLaMA Factory 是目前最省心的选择。

推荐结论

需要快速微调开源大模型（尤其是 Qwen、DeepSeek、GLM 等中文友好模型），又不想折腾各自独立的训练代码？LLaMA Factory 是一站式解法——pip 安装、一个 YAML 文件、单卡 QLoRA 跑起来，生产和研究两相宜。