LLaMA‑Factory 使用条件 + 学习手册

LLaMA‑Factory：一站式大模型微调框架，支持 SFT、DPO、ORPO、KTO、PPO、预训练，支持百种大模型，提供 WebUI 可视化，支持 LoRA / QLoRA 高效微调。

项目仓库：https://github.com/hiyouga/LLaMA‑Factory

官方中文文档：https://llamafactory.readthedocs.io/zh‑cn/latest/

一、使用所需条件

1. 硬件条件（NVIDIA GPU 为主）

微调方式	7B 模型	14B 模型	30B 模型	70B 模型	说明
LoRA(FP16/BF16)	16GB	32GB	64GB	160GB	普通 LoRA 微调
QLoRA‑8bit	10GB	20GB	40GB	80GB	量化微调
QLoRA‑4bit	6GB	12GB	24GB	48GB	消费显卡首选，RTX3060/4060 (12G) 可跑 7B
QLoRA‑2bit	4GB	8GB	16GB	24GB	效果会下降
全参数 Full‑16bit	160GB+	320GB+	600GB+	1200GB+	需要 A100/H100 企业卡

内存：≥32GB ，越大越好；磁盘：模型 + 数据集预留 \\≥100GB\\ 空间
Windows：建议 WSL2，原生 Windows 对 bitsandbytes 兼容性差；macOS (Apple Silicon) 仅适合小模型推理 / 轻量微调；首选 Ubuntu22.04 Linux

2. 软件依赖（官方）

必选

Python：3.9‑3.11，不要 3.12 （bitsandbytes 兼容问题），推荐3.10/3.11
torch ≥2.0.0，推荐 2.5+
transformers ≥4.41.2；datasets；accelerate；peft；trl

可选（训练增强）

CUDA：最低 11.6，推荐 12.2，驱动版本匹配 CUDA
bitsandbytes：QLoRA 量化必备
deepspeed：多卡显存优化
flash‑attn：加速注意力计算，大幅提速
vllm：推理部署加速

3. 网络与账号

HuggingFace 账号：部分模型需要授权，执行huggingface‑cli login登录；国内建议切换 ModelScope 魔搭下载模型，避免网络超时。
国内环境建议配置 hf 镜像，否则模型下载极易失败。

二、完整安装步骤

bash 复制代码

# 1.克隆代码
git clone --depth 1 https://github.com/hiyouga/LLaMA‑Factory.git
cd LLaMA‑Factory

# 2.创建conda虚拟环境
conda create -n llamafactory python=3.11 -y
conda activate llamafactory

# 3.安装pytorch（CUDA12.2示例，根据你的环境去pytorch官网复制命令）
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu122

# 4.安装llama‑factory主体
pip install -e ".[torch,metrics]"

# 如需deepspeed多卡训练
pip install -r requirements/deepspeed.txt

# 验证
llamafactory‑cli version

Docker 一键启动（适合不想折腾环境）

bash 复制代码

docker run -it --rm --gpus=all --ipc=host hiyouga/llamafactory:latest

三、两种使用模式：WebUI 可视化 + CLI 命令行

方式 1：WebUI（LLaMA‑Board，零代码，新手优先）

bash 复制代码

llamafactory‑cli webui

浏览器访问 http://127.0.0.1:7860

4 大面板：

训练：填写底座模型、微调方法 LoRA/QLoRA、数据集、超参、输出路径，点击开始训练。
评估与预测：训练结束后做测试集评估。
对话：加载底座 + LoRA 适配器，直接聊天看微调效果。
导出：合并 LoRA 权重导出完整模型，输出 HF 格式，用于后续部署。

自定义数据集：把 json 放到data/目录，修改data/dataset_info.json注册数据集。

方式 2：CLI 命令行（生产 / 脚本批量）

示例：Qwen2‑7B QLoRA SFT 监督微调

bash 复制代码

llamafactory‑cli train examples/train_qlora/qwen2_7b_sft.yaml

所有 yaml 配置样例在examples/文件夹，包含 sft、dpo、orpo、ppo、预训练模板。

最简命令行示例：

bash 复制代码

llamafactory‑cli train \
--stage sft \
--model_name_or_path Qwen/Qwen2‑7B‑Instruct \
--finetuning_type lora \
--quantization_bit 4 \
--dataset identity \
--template qwen2 \
--output_dir output/qwen2‑lora

四、数据集格式（最重要）

LLaMA‑Factory 标准对话格式，json 列表，每条 conversations：

json 复制代码

[
  {
    "conversations": [
      {"from":"human","value":"你是谁"},
      {"from":"gpt","value":"我是微调后的助手"}
    ]
  }
]

将 json 文件放入data/，在dataset_info.json增加条目即可在 WebUI 下拉框选择数据集。

五、完整学习路线手册

📘阶段 1：环境跑通（1‑2 天）

阅读官方 README\ $_zh.md$ (_zh.md)，理解概念：SFT 监督微调、LoRA、QLoRA、DPO 偏好对齐。
本地 / 云 GPU 完成安装，启动 webui 跑最小 demo：用 Qwen2‑0.5B + 内置 identity 数据集跑一遍完整训练‑对话‑导出全流程。

小模型测试，不要直接上 7B，先验证流程是否通。

📘阶段 2：数据处理（2‑3 天）

学习标准对话数据集格式；练习把自己业务数据转换成 LLaMA‑Factory 格式。
学习 dataset_info.json 注册自定义数据集；学会过滤、截断、数据采样。

📘阶段 3：微调实战（重点）

消费级显卡优先使用 QLoRA‑4bit，LoRA rank 一般 8‑16；学习超参：学习率、epoch、batch、梯度累积。
分别实践：
- SFT 监督微调（基础指令微调）
- DPO/ORPO 偏好对齐（不需要单独奖励模型，做人类偏好优化）
训练后：webui 对话验证效果；导出合并完整模型。

📘阶段 4：进阶

多卡训练：DeepSpeed ZeRO 配置；
RLHF 完整流程：SFT‑RM 奖励模型‑PPO；
模型导出、vLLM 部署 OpenAI 兼容 API；
多模态模型微调（LLaVA 系列）。

六、常用踩坑清单

bitsandbytes 报错：Windows WSL 使用；python 版本不要 3.12；
模型下载失败：国内切换 modelscope 源下载模型；
OOM 显存爆：降低 batch size，开启梯度累积，切换 QLoRA‑4bit；
微调输出乱码：template 参数必须和底座模型匹配（qwen2、llama3、chatglm 等），模板错效果直接报废；
数据集不显示：没有在 dataset_info.json 注册数据集。

七、官方文档资源

GitHub 中文 README：https://github.com/hiyouga/LLaMA‑Factory/blob/main/README\ $_zh.md$ (_zh.md)
ReadTheDocs 完整中文手册：https://llamafactory.readthedocs.io/zh‑cn/latest/
examples 目录：大量 yaml 配置样例，直接复制修改即可用。