PEFT：Hugging Face 参数高效微调库 LoRA / QLoRA / Adapter 全家桶｜部署与使用全指南

项目仓库： https://github.com/huggingface/peft

开源协议：Apache 2.0 · 交付形态：Python 库（peft PyPI 包）· 主要语言：Python · 部署方式：pip install peft · 无独立 Web 服务端口 · 官方文档：huggingface.co/docs/peft

1 项目简介

PEFT（Parameter-Efficient Fine-Tuning）是 Hugging Face 维护的参数高效微调库。大模型全量微调需要更新所有参数，显存与存储成本极高；PEFT 只训练少量（额外）参数（例如 LoRA 的低秩矩阵），在大量下游任务上达到接近全量微调的效果，而 checkpoint 通常只有几 MB。PEFT 与 Transformers、Diffusers、Accelerate、TRL 深度集成。

非官方 / 商业产品边界声明：PEFT 由 Hugging Face 团队维护；文中出现的 Qwen、Llama、Mistral、Stable Diffusion 等模型名称仅用于示例，模型权重归各自作者所有。

1.1 核心信息一览

1.2 适用场景

• 在消费级 GPU（如 16GB 显存）上微调 7B / 12B 级别的大模型（QLoRA）。
• 为同一基座模型训练多个下游任务的小 adapter（几 MB），推理时动态切换。
• 对 Stable Diffusion 做 DreamBooth / LoRA 微调，最终 checkpoint 仅几 MB。
• 与 TRL 配合做 DPO、RLHF、SFT，在小显存上训练大模型。

1.3 能力边界（官方口径）

• 官方 README 自述：通过只微调少量额外参数，显著降低计算与存储成本，性能可逼近全量微调。
• 官方给出的参考数据：A100 80GB 上，bigscience/mt0-xxl（12B）全量微调 OOM，PEFT-LoRA 占 56GB GPU / 3GB CPU，PEFT-LoRA + DeepSpeed CPU Offload 占 22GB GPU / 52GB CPU。
• 模型支持以 PEFT methods Space 与文档为准；未列出的模型可手动配置 target_modules 启用 PEFT。
• PEFT 本身不提供训练循环，训练用 Transformers Trainer、Accelerate、TRL 或自研脚本。

2 功能特性

2.1 主流 PEFT 方法

• LoRA / QLoRA：低秩适配，QLoRA 结合 4-bit 量化进一步降显存。
• IA3：通过加权激活向量微调。
• AdaLoRA：自适应分配 LoRA 秩。
• Prefix Tuning / Prompt Tuning / P-Tuning：在输入端加可训练 soft prompt。
• 完整方法列表见 PEFT Adapters API 参考 与 Adapters 概念指南。

2.2 生态集成

• Transformers：加载模型后调用 add_adapter / load_adapter / set_adapter 动态切换 adapter。
• Diffusers：对 Stable Diffusion 做 LoRA，DreamBooth 示例见 examples/lora_dreambooth/train_dreambooth.py，最终 checkpoint 仅 8.8MB。
• Accelerate：PEFT 模型开箱即用地支持多卡、多机、Apple Silicon 等分布式训练。
• TRL：在 RLHF、DPO、SFT 流程中使用 PEFT。

2.3 量化与显存优化

• 与 bitsandbytes 4/8-bit 量化配合，在 16GB 消费级 GPU 上微调 7B 模型。
• 与 DeepSpeed CPU Offload 配合，把优化器状态卸载到内存。

3 官方界面预览

PEFT 是 Python 库，没有图形界面。官方提供 PEFT methods Space 用于查询模型对各 PEFT 方法的支持情况。

4 官方跳转链接汇总

• 仓库地址：https://github.com/huggingface/peft
• 官方文档：https://huggingface.co/docs/peft
• Adapters 概念指南：https://huggingface.co/docs/peft/en/conceptual_guides/adapter
• Soft prompts：https://huggingface.co/docs/peft/en/conceptual_guides/prompting
• IA3：https://huggingface.co/docs/peft/en/conceptual_guides/ia3
• PEFT methods Space：https://stevhliu-peft-methods.hf.space
• Transformers PEFT 集成：https://huggingface.co/docs/transformers/main/en/peft
• PEFT 组织：https://huggingface.co/PEFT

5 前置要求与服务器配置

5.1 软件前提

• Python 3.8+（与所装 Transformers 版本兼容）。
• PyTorch 已安装；GPU 训练需 CUDA 可用。
• 推荐同时安装：transformers、accelerate、trl、bitsandbytes（QLoRA）。

5.2 硬件建议

• 7B 模型 LoRA 微调：建议 16GB+ 显存；QLoRA 可降到 10–12GB。
• 12B+ 模型：建议 A100 40/80GB 或使用 DeepSpeed CPU Offload。
• 消费级 GPU（RTX 3090 / 4090 / A10G）是 PEFT 最常见的目标硬件。

6 方式一：Docker / 容器化使用

PEFT 官方不单独提供 Docker 镜像，推荐在官方 PyTorch 容器内安装：

docker pull pytorch/pytorch:2.3.0-cuda12.1-cudnn8-devel

docker run -it --rm --gpus all --shm-size=16g \
  -v /data:/workspace \
  pytorch/pytorch:2.3.0-cuda12.1-cudnn8-devel bash

# 容器内
pip install peft transformers accelerate trl bitsandbytes

7 方式二：源码 / 本地运行

7.1 安装

pip install peft

源码安装：

git clone https://github.com/huggingface/peft.git
cd peft
pip install -e .

7.2 用 LoRA 微调（最小示例）

import torch
from transformers import AutoModelForCausalLM
from peft import LoraConfig, TaskType, get_peft_model

device = torch.accelerator.current_accelerator().type if hasattr(torch, "accelerator") else "cuda"
model_id = "Qwen/Qwen2.5-3B-Instruct"
model = AutoModelForCausalLM.from_pretrained(model_id, device_map=device)

peft_config = LoraConfig(
    r=16,
    lora_alpha=32,
    task_type=TaskType.CAUSAL_LM,
    # target_modules=["q_proj", "v_proj"],  # 可选，手动指定目标模块
)
model = get_peft_model(model, peft_config)
model.print_trainable_parameters()
# 示例输出：trainable params: 3,686,400 || all params: 3,089,625,088 || trainable%: 0.1193

# 用 Transformers Trainer 或 Accelerate 训练后保存
model.save_pretrained("qwen2.5-3b-lora")

7.3 推理时加载 adapter

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer
from peft import PeftModel

device = torch.accelerator.current_accelerator().type if hasattr(torch, "accelerator") else "cuda"
model_id = "Qwen/Qwen2.5-3B-Instruct"
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(model_id, device_map=device)
model = PeftModel.from_pretrained(model, "qwen2.5-3b-lora")

inputs = tokenizer("Preheat the oven to 350 degrees and place the cookie dough", return_tensors="pt")
outputs = model.generate(**inputs.to(device), max_new_tokens=50)
print(tokenizer.decode(outputs[0], skip_special_tokens=True))

7.4 Transformers 原生 adapter API

from peft import LoraConfig
model = ...  # transformers model
peft_config = LoraConfig(...)
model.add_adapter(peft_config, adapter_name="lora_1")
model.load_adapter("<path-to-adapter>", adapter_name="lora_1")
model.set_adapter("lora_2")

8 配置项说明

以 LoraConfig 为例，常见字段（完整字段以官方文档为准）：

9 常用运维命令

# 查看已安装版本
pip show peft

# 升级
pip install --upgrade peft transformers accelerate

# 训练时查看 GPU 占用
nvidia-smi

# 查看 adapter 大小
ls -lh qwen2.5-3b-lora/

# 训练日志按 Trainer 配置输出

备份：PEFT adapter 目录通常只有几 MB（README 举例 T0_3B 的最终 checkpoint 为 19MB，对比全量 11GB），直接拷贝目录即可；基座模型可从 Hugging Face Hub 重新下载。

10 常见故障排查

• CUDA out of memory：降低 batch_size，开启梯度检查点，使用 QLoRA（4-bit 量化），或用 DeepSpeed CPU Offload。
• trainable% 异常大：检查 target_modules 是否误把全模型列入；默认只对注意力模块注入 LoRA。
• 模型不在官方支持列表：按 New transformers architecture 指南手动配置 target_modules。
• QLoRA 训练报 bitsandbytes 错误：确认 bitsandbytes 已安装且与 CUDA 版本匹配；CPU 机器不能跑 4-bit 量化。
• adapter 加载后输出与训练不一致：确认 tokenizer、device_map、torch_dtype 与训练时一致；PeftModel.from_pretrained 不要漏传基座模型。
• 与 Diffusers 配合：参考 examples/lora_dreambooth/train_dreambooth.py；Stable Diffusion LoRA 最终 checkpoint 官方示例仅 8.8MB。

11 风险与合规说明

• PEFT 采用 Apache 2.0 协议，允许商用与二次开发。
• 基座模型（Qwen、Llama、Mistral、Stable Diffusion 等）的许可按各自仓库条款执行；adapter 衍生品受原模型许可约束。
• 训练数据版权、隐私与合规责任由使用者承担。
• 本文所有命令、参数、示例模型均来自官方 README；后续版本演进以官方文档为准。