hiyouga/LLaMA-Factory · 上手攻略

  • 仓库：hiyouga/LLaMA-Factory
  • 链接：https://github.com/hiyouga/LLaMA-Factory
  • 分类：ai / llm-infra / engineering
  • 作者：Jay
  • 更新：2026-07-07

👋 是什么

LLaMA Factory（LlamaFactory）是一个统一的大模型微调平台，能对超过 100 种预训练 LLM 和 VLM（视觉语言模型）进行高效微调，且无需编写代码。项目发表面向 ACL 2024论文，并被广泛用于学术和工业场景。

其核心定位是：让微调大模型变得像"运行一个命令"一样简单。

🔍 解决什么问题

从零预训练大模型成本极高，普通开发者无法承受。而直接使用通用大模型，在垂直领域任务上往往表现不佳。LLaMA Factory 解决的是微调门槛高的问题：

  • 传统微调需要写大量训练代码，配环境、调参耗时数天
  • 不同模型需要不同的微调实现，切换成本大
  • 消费级 GPU（甚至 24GB 显存）难以微调大参数模型

LLaMA Factory 将以上问题一站式解决，支持 QLoRA 等低显存技术，单卡 24GB 显存即可微调 70B 模型。

⚡ 快速安装

方式一：pip 安装（推荐）

pip install llamafactory

方式二：Docker（零依赖）

docker pull hiyouga/llamafactory:latest
docker run -it --rm \
  -v ./dataset:/app/data \
  -v ./output:/app/output \
  hiyouga/llamafactory:latest \
  llamafactory-cli train examples/train_full/qwen3_full.yaml

方式三：Colab 免费体验

https://colab.research.google.com/drive/1eRTPn37ltBbYsISy9Aw2NuI2Aq5CQrD9

基本依赖

  • Python >= 3.8
  • PyTorch >= 1.13.0
  • 最低显存：QLoRA 7B 模型约 6GB，70B 模型约 24GB（QLoRA）

🎯 核心用法

1. WebUI 可视化微调（最适合新手）

安装后一键启动图形界面：

llamafactory-cli webui

浏览器打开 http://localhost:7860，即可通过拖拽配置模型、数据集、训练参数，完全不碰代码。

🔗 在线 Demo：https://huggingface.co/spaces/hiyouga/LLaMA-Board

2. 命令行快速微调

准备数据集格式（JSON）：

[
  {
    "messages": [
      {"role": "user", "content": "请用中文解释什么是量子计算"},
      {"role": "assistant", "content": "量子计算是一种利用量子力学原理进行信息处理的计算方式..."}
    ]
  }
]

创建训练配置 train.yaml：

### LLaMA Factory QLoRA 微调配置示例
model_name_or_path: Qwen/Qwen2.5-7B-Instruct
dataset: my_dataset          # 自定义数据集名（需先注册）
stage: sft                   # supervised fine-tuning
do_train: true
output_dir: ./output/qwen2.5-7b-sft
per_device_train_batch_size: 2
gradient_accumulation_steps: 8
fitler: null
max_steps: 1000
logging_steps: 10
save_steps: 500
learning_rate: 1.0e-4
num_train_epochs: 3.0
bf16: true                    # A100/H100 用 bf16；V100 用 fp16
optim: paged_adamw_32bit
lora_dim: 16
lora_alpha: 32
lora_dropout: 0.05
lora_target: all              # 所有 Linear 层应用 LoRA

启动训练：

llamafactory-cli train examples/train_lora/qwen2.5_lora_sft.yaml

⚠️ 注意：实际使用时，dataset 字段需要在 data/llama_factory_factory_config.yaml 中预先注册。示例配置可参考 examples 目录。

3. LoRA 合并与导出

微调得到的 LoRA 权重可合并回原模型：

llamafactory-cli export \
  --merge_lora true \
  --model_name_or_path Qwen/Qwen2.5-7B-Instruct \
  --adapter_name_or_path ./output/qwen2.5-7b-sft \
  --output_dir ./output/merged_model

4. 推理部署（vLLM / SGLang 加速）

llamafactory-cli inference \
  --model_name_or_path ./output/merged_model \
  --infer_backend vllm \
  --template qwen2

或直接启动 OpenAI 风格 API：

llamafactory-cli api \
  --model_name_or_path ./output/merged_model \
  --api_host 0.0.0.0 \
  --api_port 8000

📊 支持的训练方法

方法 说明 显存需求（7B）
Full SFT 全参数微调 ~14GB
LoRA 低秩适配，最常用 ~6GB
QLoRA 量化+LoRA，显存最低 ~5GB
DoRA 增强版 LoRA ~6GB
PiSSA 改进版 LoRA ~6GB
GaLore 梯度低秩投影 ~8GB
DPO 偏好对齐 ~8GB
PPO RLHF ~16GB
KTO 认知对齐 ~8GB
ORPO 偏好对齐 ~8GB

支持的量化格式：AWQ / GPTQ / AQLM / LLM.int8 / HQQ / EETQ，支持 2/3/4/5/6/8 比特。

💡 典型适用场景

  1. 垂直领域定制：用金融、医疗、法律等专有数据微调，打造专属领域模型
  2. 角色扮演/对话模型：微调 LLaMA/Qwen 实现个性化角色对话
  3. 工具调用 Agent：微调使模型学会使用 API 和工具
  4. 多模态任务：配合 LLaVA 等 VLM 微调图像理解能力
  5. DeepSeek-R1 蒸馏：复现推理能力的小模型（如 DeepSeek-R1-Distill-Qwen-7B）
  6. 偏好对齐：用 DPO/KTO/ORPO 优化模型输出质量

⚠️ 坑与注意

  1. 数据集格式严格：必须严格遵循指定格式（messages 数组 + role/content 字段），格式错误会静默失败
  2. 显存估算：QLoRA 7B 最低 6GB，但实际视 batch_size 和序列长度可能需要 8-10GB；70B QLoRA 需 24GB+
  3. Chinese-Alpaca 模板：用中文数据微调时，template 参数要选对（如 qwen2、chatglm3），否则输出乱码
  4. DeepSpeed 配置复杂：多卡训练时 DeepSpeed 配置容易出错，建议先用单卡验证
  5. **模型认领（ModelScope）：国内用户可从魔搭社区下载，速度更快 bash export MODELSCOPE_SDK_TOKEN="your_token"
  6. vLLM 版本兼容：最新 vLLM 偶有 breaking change，建议用 README 推荐的版本组合

🔄 与同类对比

工具 定位 优势 劣势
LLaMA Factory 全能微调平台 支持 100+模型，算法最全，WebUI 友好 文档对新手仍有门槛
Axolotl 专注微调 轻量，YAML 配置简单 模型支持较少，无 WebUI
PEFT (HuggingFace) LoRA 微调库 官方轻量库，生态好 需自行写训练循环
Unsloth 高速微调 训练速度最快（170%+），显存优化好 模型和算法支持较少
LLaMA-X 专业微调 学术向，支持多种前沿算法 维护不积极

一句话推荐：如果你需要同时支持多种模型、多种算法（从 SFT 到 DPO/PPO），且希望有 WebUI 降低门槛，LLaMA Factory 是目前最全面的选择。

✅ 一句话推荐结论

LLaMA Factory 是大模型微调的"一站式航母"——100+ 模型全覆盖、主流微调算法全集成、最少一行命令即可启动训练，是打造垂直领域模型的性价比最高方案。

来源：GitHub README、中文文档、官方博客