01 - 项目总览与设计理念

本篇为整套文档的"总"之开篇。先用一张全景图建立对 HuggingFace PEFT 的整体认知，再分点展开背景、原理、设计哲学与生态定位，最后以一句话收束——为后续 9 篇"分"的深入剖析奠定基础。

一、总览：PEFT 是什么

🤗 PEFT（Parameter-Efficient Fine-Tuning，参数高效微调） 是 HuggingFace 开源的参数高效微调方法库，位于 [src/peft/](file:///workspace/src/peft)，当前版本 0.19.2.dev0，采用 Apache 2.0 协议。

一句话定位：它是一个"在冻结大模型主干的前提下，只训练极少量额外参数即可完成下游任务适配"的统一框架，同时是 40+ 种主流 PEFT 方法的参考实现。

核心价值（来自项目 [README.md](file:///workspace/README.md)）：

PEFT 与 HuggingFace 生态深度集成：Transformers（训练/推理入口）、Diffusers（扩散模型多适配器管理）、Accelerate（大模型分布式训练/推理）、TRL（RLHF/DPO 训练）。

二、分述

2.1 为什么需要参数高效微调

大模型（LLM、扩散模型等）参数量动辄数十亿到数千亿。全量微调一座 12B 模型，在 80GB A100 上直接 OOM；而保存 N 个下游任务的 checkpoint 意味着 N × 模型体积的存储成本——这在工程上不可持续。

PEFT 的核心洞察来自一个经验假设：“预训练模型在适配下游任务时，本征维度（intrinsic dimension）远小于参数总量”。换言之，权重的有效变化  可以被投影到一个低维子空间而几乎不损失表达力。于是：

冻结 ，只训练  和 ，参数量从  降到 。当 、 时，参数量减少约 250 倍。

2.2 三大方法族

PEFT 库将 40+ 种方法归为三大族（参见 [docs/source/methods/overview.md](file:///workspace/docs/source/methods/overview.md)）：

1. Prompt-based（提示类）
   ：在输入端拼接可学习的"虚拟 token"或操控 KV-cache。代表：Prompt Tuning、Prefix Tuning、P-Tuning、CPT、Cartridge。参数量极小但表达力受限。
2. Layer Tuning（层调优类）
   ：只针对某一类层做微调。代表：LayerNorm Tuning、Trainable Tokens、BEFT。粒度细、开销小。
3. Adapter（适配器类）
   ：在原权重旁并联小可训练模块。代表：LoRA 及其变体（DoRA、AdaLoRA、VeRA、QLoRA）、LoHa、LoKr、OFT、IA³、HRA、FourierFT、XLora、Poly。表达力最强、最主流。

2.3 设计哲学

PEFT 库的代码组织体现了 5 条清晰的设计原则：

• 组合优于继承
  ：用户入口 [PeftModel](file:///workspace/src/peft/peft_model.py) 不继承 BaseTuner，而是组合一个 tuner 实例（self.base_model）。这样同一 PeftModel 可承载任意 tuner，且 tuner 之间可替换。
• 注册制扩展
  ：每新增一个 PEFT 方法，只需在其 __init__.py 调用一次 [register_peft_method](file:///workspace/src/peft/utils/peft_types.py#L125)，即可被 get_peft_model、PeftModel.from_pretrained、PeftMixedModel 自动发现——无需修改核心代码。
• 量化无关（Quantization-Agnostic）
  ：通过抽象基类 [QuantizationBackend](file:///workspace/src/peft/utils/quantization_utils.py#L43)，把"取权重/写回权重"的细节封装在后端里；任意 tuner 的 merge/unmerge 都能复用同一套逻辑，无需为每种量化方案重写合并代码。
• 模板方法 + Dispatcher
  ：[BaseTuner.inject_adapter](file:///workspace/src/peft/tuners/tuners_utils.py) 定义"注入适配器"的统一 13 步骨架，子类只需实现 _create_and_replace 钩子；具体层创建由 _create_new_module 按"第一个非 None 命中"的 dispatcher 顺序决定。
• PyTorch-first
  ：所有适配器层都是标准 torch.nn.Module，可与 torch.compile、accelerate、DeepSpeed、FSDP、Tensor Parallel 无缝协作。

2.4 生态定位

PEFT 在 HuggingFace 技术栈中处于"适配器层"：它不重新实现训练循环，而是把"如何把适配器塞进任意 transformers/Diffusers 模型"这件事做透。

图 2-1 PEFT 在 HuggingFace 生态中的定位：PEFT 以"组合"方式接入上游训练框架，以"冻结+注入"方式作用于预训练主干，并通过量化后端与各类低比特方案协作。它本身不替代训练循环，而是把"适配器编排"做成了可插拔的中间件。

2.5 方法分类全景

图 2-2 PEFT 三大方法族与代表方法：Prompt-based 作用于输入/KV-cache；Layer Tuning 锁定单一层类型；Adapter 在权重旁并联模块——其中 LoRA 系是绝对主流，PEFT 库为它实现了最完整的变体与量化支持。

三、小结

PEFT 的本质是**“用 0.1% 的可训练参数，换取接近全量微调的效果”**，其工程价值由三件事撑起：① 冻结主干大幅降低显存与存储；② 适配器即插即用、可热切换、可合并；③ 统一框架容纳 40+ 方法，让选型与对比成本极低。

理解了"为什么"与"整体在哪"之后，下一篇 02-核心架构剖析.md 将进入"怎么实现"——拆解 PeftModel / BaseTuner / BaseTunerLayer 三大支柱的类层次、注册机制与端到端数据流。