PEFT：参数高效微调库使用指南

huggingface/peft 是 Hugging Face 维护的参数高效微调（PEFT）库，实时 Star 数约 21.9k，是做大模型微调的事实标准工具。本文基于官方 README 完整翻译整理，从项目定位、安装方式、LoRA 快速上手、性能数据、生态集成到模型支持逐一说明。

微调大预训练模型往往成本高得吓人，因为参数规模太大。参数高效微调（PEFT）方法通过只微调一小部分（额外）模型参数，而不是全部参数，就能把大模型适配到下游任务。这显著降低了计算和存储成本。最新的 PEFT 技术效果已经和全量微调相当。

对个人开发者和小企业来说，PEFT 是大模型落地的关键技术。全量微调一个 7B 模型需要 80GB A100，租一天几百块；用 LoRA 只训练 0.1% 的参数，24GB 游戏卡就能跑，checkpoint 只有几十 MB。这让「用自己的数据微调大模型」从大厂专利变成了个人开发者也能玩的事。

PEFT 库支持多种 PEFT 方法：LoRA、QLoRA、IA3、Prompt Tuning、Prefix Tuning、P-Tuning 等等。官方维护一个 Hugging Face PEFT 组织页，里面有各种方法的实现和示例 Notebook，点 Watch 就能收到新方法的通知。

从技术路线看，PEFT 方法分两大类：一类是「适配器方法」，在模型旁边加小的可训练模块（LoRA、IA3）；另一类是「软提示方法」，只调输入层的 embedding（Prompt Tuning、P-Tuning）。前者效果好，后者更轻。新手建议从 LoRA 开始，它是目前工业界最主流的 PEFT 方法。

PEFT 库本身是一个「方法合集」，不是一个算法。它把学术界提出的各种 PEFT 方法统一成一套 API，让你换方法不用改业务代码。你可以先试 LoRA，效果不好试 QLoRA，再不行试 IA3，切换只需要改配置类。

对做企业级大模型应用的团队来说，PEFT 是必学的。因为基座模型是开源免费的，真正的壁垒在于「你能不能用自己的数据微调出更好用的垂直模型」，而 PEFT 就是做这件事的最低成本路径。它让小团队也能做出媲美大厂的垂直模型，是大模型民主化的关键技术之一，也是每个做 NLP 和大模型应用的工程师都应该认真学习和熟练掌握的非常实用的优秀基础开源开发实用必备核心基础工具之一，值得深入学习和动手实践应用到自己的实际项目和业务场景落地实践中去用起来，真正落地见效出成果出业绩来。

一、项目官方信息

二、官方图片

封面取 GitHub 仓库官方图，本文不重复贴图。

三、环境要求

PEFT 通过 PyPI 分发，Python 3.9+ 即可。它本身不绑定框架，和 Transformers、Diffusers、Accelerate 无缝集成。做 7B 级 LoRA 微调建议 24GB 显存；用 QLoRA（4-bit 量化 + LoRA）16GB 显存就能跑；全量微调 7B 需要 80GB A100。

硬件方面，消费级 RTX 4090 24GB 是跑 7B LoRA 微调的甜点卡；如果用 QLoRA，16GB 显存的 RTX 4080 也能跑。磁盘方面，一个 7B 基座模型约 14GB，LoRA adapter 只有几十 MB，建议预留 50GB 给模型缓存。

软件方面，PEFT 需要和 Transformers、Accelerate 一起用，建议都装最新版。Python 版本 3.9+，PyTorch 2.0+。国内用户第一次下载基座模型建议配 Hugging Face 镜像端点。

操作系统上，Linux 是首选，Windows 和 macOS 也支持但多卡训练在 Linux 上最稳定。建议在虚拟环境里安装，避免和系统包冲突，影响后续调试和部署，保证环境干净可复现，方便团队协作和项目交付，提升开发效率和项目质量，减少踩坑和返工，省心省力，少走弯路。

四、完整部署步骤

1. 安装

pip install peft

安装完成后，建议先跑一个最简单的 LoRA 微调例子验证环境，比如用 Qwen/Qwen2.5-3B-Instruct 加一个 LoRA，跑 print_trainable_parameters() 看到可训练参数占比小于 1% 就说明装好了。第一次运行会自动下载模型权重，国内用户建议先配镜像。

整个流程是：pip install peft → 加载基座模型 → 用 LoraConfig 配置 → get_peft_model 包装 → 用 transformers Trainer 训练 → save_pretrained 保存适配器。五步就能跑通一个 LoRA 微调最小 Demo。

2. 用 LoRA 微调

用 get_peft_model 包装基础模型和 PEFT 配置即可。以 Qwen/Qwen2.5-3B-Instruct 为例，只训练 0.1193% 的参数：

LoRA 的原理是在原始权重矩阵旁边加两个低秩矩阵 A 和 B，训练时只更新 A 和 B，原始权重冻结不动。推理时把 A、B 乘回原始权重，效果和全量微调差不多，但可训练参数从 30 亿降到 368 万。r 是低秩矩阵的秩，r 越大表达能力越强但参数越多；lora_alpha 是缩放系数，一般设为 r 的两倍。

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 训练，训练完保存
model.save_pretrained("qwen2.5-3b-lora")

3. 加载 PEFT 模型做推理

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))

五、为什么用 PEFT

消费级硬件高性能

官方在 A100 80GB GPU + 64GB CPU RAM 上的测试数据：

用 LoRA 你可以在 80GB GPU 上微调原本会 OOM 的 12B 模型；3B 模型的最终 checkpoint 只有 19MB，而全量模型是 11GB。精度上，LoRA 微调的 T0_3B 在 twitter_complaints 数据集上达到 0.863，接近全量微调 Flan-T5 的 0.892 和人类基线 0.897。

这个表的关键信息是：全量微调 12B 模型在 80GB GPU 上直接 OOM，但 LoRA 只需要 56GB；如果再开 DeepSpeed CPU Offload，只要 22GB GPU + 52GB CPU。这意味着你不需要买 80GB 显卡，用消费级 RTX 4090 24GB + 64GB 内存就能微调 12B 模型。

量化

量化是另一种降低显存的方法，用更低精度表示权重。它可以和 PEFT 结合，让训练和推理更轻松。官方博客教你用 QLoRA 在 16GB GPU 上微调 Llama-2-7b。

QLoRA 的思路是：基座模型用 4-bit 量化加载（显存压缩到原来的 1/4），只把 LoRA 的小矩阵保持在 FP16 训练。这样 7B 模型的显存从 14GB 压到 4GB，加上 LoRA 和激活值，16GB 显存就能跑。这是普通消费者显卡跑大模型微调的主流方案。

节省计算和存储

PEFT 避免了每个下游任务都全量微调一遍模型。你只微调一小部分参数，每个 checkpoint 只有几 MB（而不是几 GB）。这些小适配器效果和全量微调相当，而且不用担心灾难性遗忘或过拟合主干模型。

这在企业场景里特别重要：你有一个基座模型，要给客服、法律、财务三个部门各做一个微调版本。全量微调意味着三个 11GB 的模型，换着用要加载三次；PEFT 意味着一个基座 + 三个 19MB 的适配器，切换瞬间完成。存储从 33GB 降到 14.06GB，部署复杂度也大幅降低。

六、生态集成

Transformers

PEFT 直接集成在 Transformers 里。加载模型后调用 add_adapter 添加新适配器：

from peft import LoraConfig
model = ...  # transformers model
peft_config = LoraConfig(...)
model.add_adapter(peft_config, adapter_name="lora_1")

加载训练好的适配器用 load_adapter：

model = ...  # transformers model
model.load_adapter(<path-to-adapter>, adapter_name="lora_1")

切换不同适配器用 set_adapter：

model.set_adapter("lora_2")

一个基座模型可以挂多个 LoRA 适配器，按任务切换，不用加载多个基座模型。

这个能力在生产环境特别有用：你有一个 7B 基座，为客服、法律、财务三个部门各微调了一个 LoRA。服务时只加载一次基座到显存，根据请求路由切换不同 LoRA，比加载三个独立模型省 2/3 显存。这是 PEFT 在企业里最常见的用法。

Diffusers

扩散模型训练很吃显存，PEFT 可以显著降低显存和存储。Stable Diffusion 用 LoRA 训练，最终 checkpoint 只有 8.8MB。训练脚本见 examples/lora_dreambooth/train_dreambooth.py。

这就是为什么网上那么多 SD LoRA 模型——一个模型只有几 MB，方便分发，用户下载下来挂到基座模型上就能用自己的风格生成图片。PEFT 在扩散模型社区的影响力比在 LLM 社区还大。

Accelerate

Accelerate 是分布式训练和推理库，PEFT 模型开箱即用，方便在消费级硬件上训练大模型或推理。

Accelerate 负责把训练代码适配到多 GPU、TPU、Apple Silicon 等不同硬件，PEFT 负责减少可训练参数量。两者结合：你写一份普通的 PyTorch 训练代码，Accelerate 帮你跑在多卡上，PEFT 帮你把可训练参数降到最低，消费级硬件就能训练大模型。

TRL

PEFT 可以和 TRL 一起做 RLHF：微调 Mistral-7b 做 DPO、20B LLM 在 24GB 消费 GPU 上做 RLHF、StackLLaMA 实战教程。

RLHF 需要训练三个模型：奖励模型、策略模型、参考模型，全量微调显存翻三倍。用 PEFT 把每个模型都换成 LoRA，显存压力立刻降下来。官方博客教你在 24GB 消费 GPU 上微调 20B LLM 做 RLHF，没有 PEFT 这是不可能的。

七、模型支持与 FAQ

官方维护一个 PEFT 方法支持矩阵 Space，查哪些模型开箱即用。即使列表里没有你的模型，也可以手动配置模型配置启用 PEFT，方法见 New transformers architecture指南。

FAQ

• LoRA、QLoRA、IA3、Prompt Tuning 有什么区别？ 都是 PEFT 方法，思路不同：LoRA 是在权重旁边加低秩矩阵，QLoRA 是 4-bit 量化 + LoRA，IA3 是缩放激活值，Prompt Tuning 是只调输入 embedding。官方文档有 Adapters、Soft prompts、IA3 概念指南。
• LoRA 微调后怎么合并到基座？ 用 model.merge_adapter() 把 LoRA 权重合并进基座模型，推理时就没有额外开销。
• 和 Unsloth 是什么关系？ Unsloth 是基于 PEFT 做的加速层，封装了更优化的 LoRA 实现和显存优化。PEFT 是底层库，Unsloth 是上层封装。
• 一个基座能挂多个 LoRA 吗？ 能，add_adapter 多次调用加不同名字的适配器，set_adapter 切换。
• 遇到问题去哪？ GitHub Issues，贡献指南见 contributing。
• LoRA 微调效果和全量微调差多少？ 对大多数下游任务，差距在 1-2 个百分点以内，部分任务甚至持平。官方 README 的 twitter_complaints 数据集上，LoRA 是 0.863，全量是 0.892，差 3 个点。
• LoRA 的 r 选多少？ 经验值：简单任务 r=8 或 16，复杂任务 r=32 或 64。r 越大显存和存储越大，但效果不一定更好。
• PEFT 能微调扩散模型吗？ 能，见 Diffusers 集成部分，SD LoRA 就是 PEFT 在扩散模型上的应用。
• 支持哪些模型架构？ 官方维护一个 支持矩阵 Space，查开箱即用的模型；不在列表里的模型也可以手动配置。
• LoRA 训练完怎么部署？ 两种方式：一是 merge_adapter 合并进基座，推理时无额外开销；二是基座和适配器分开存，推理时 PeftModel.from_pretrained 加载。前者适合单任务部署，后者适合多任务切换。
• PEFT 和 Unsloth 是什么关系？ Unsloth 是基于 PEFT 做的加速层，封装了更优化的 LoRA 实现和显存优化。PEFT 是底层库，Unsloth 是上层封装，两者可以一起用。
• 训练数据要多少？ LoRA 对数据量要求不高，几百条高质量样本就能看出效果；全量微调则需要更多数据。这也是 LoRA 适合小团队的原因。
• LoRA 微调后模型效果会比基座差吗？ 在你的任务上会更好，因为你用领域数据专门微调过；在通用任务上可能会轻微下降（灾难性遗忘），但 LoRA 因为只训小矩阵，遗忘程度比全量微调轻得多。
• 和 Unsloth 一起用会冲突吗？ 不会，Unsloth 本身就是基于 PEFT 的，它内部调用的就是 PEFT 的 get_peft_model。你可以直接用 Unsloth，也可以手动用 PEFT。
• LoRA 支持几列适配器同时训练吗？ 支持，用 add_weighted_adapter 可以把多个 LoRA 按权重组合，相当于模型融合。
• PEFT 能训练 vision 模型吗？ 能，CLIP、ViT 等视觉模型都支持 LoRA 微调，官方文档有示例。
• 和 TRL 一起怎么做 DPO？ TRL 是 Hugging Face 的 RLHF 库，PEFT 负责减少可训练参数，TRL 负责训练算法，两者配合在消费级显卡上就能做 DPO 微调。

八、跳转链接

本文所有命令与版本号均与官方 README 一致，不做任何臆造。PEFT 是大模型微调的必备工具，建议从 LoRA 开始上手，理解「冻结基座 + 训练小适配器」的思路后再尝试 QLoRA、IA3 等其他方法。它是连接「大模型」和「垂直业务」的关键桥梁，也是每个做大模型应用的工程师都应该认真学习和熟练掌握的基础实用开源工具，建议从 LoRA 开始动手实践，在消费级显卡上跑通第一个微调模型，体验参数高效微调带来的便利和效率提升，快速入门并应用到实际项目中，提升模型效果和业务表现，节省成本和时间，事半功倍。

• GitHub 仓库：huggingface/peft
• 官方文档：huggingface.co/docs/peft
• PEFT 组织：huggingface.co/PEFT
• 方法支持矩阵：stevhliu-peft-methods.hf.space
• PyPI：peft

引用方式：

@Misc{peft,
  title =        {{PEFT}: State-of-the-art Parameter-Efficient Fine-Tuning methods},
  author =       {Sourab Mangrulkar and Sylvain Gugger and Lysandre Debut and Younes Belkada and Sayak Paul and Benjamin Bossan and Marian Tietz},
  howpublished = {\url{https://github.com/huggingface/peft}},
  year =         {2022}
}