源码走读路线图与生态

PEFT 仓库代码量约 2.7 万行（不算 tests / docs），整体结构清晰。 本章给一份"该按什么顺序读"的路线图，外加上下游生态、关键 commit、提 PR 指南。

13.1仓库目录全景

peft/                                 https://github.com/huggingface/peft
├── src/peft/                         ★ 核心库
│   ├── __init__.py                   公共 API 导出
│   ├── auto.py                       AutoPeftModel 自动选 task
│   ├── config.py                     PeftConfig 基类
│   ├── peft_model.py                 ★ PeftModel + 任务子类（CausalLM 等）
│   ├── mapping.py / mapping_func.py  ★ get_peft_model 入口
│   ├── mixed_model.py                同一 base 上挂多种 tuner
│   ├── functional.py                 一些纯函数 API
│   ├── helpers.py                    辅助工具
│   ├── tuners/                       ★ 40+ tuner 实现
│   │   ├── tuners_utils.py            BaseTuner / BaseTunerLayer
│   │   ├── lora/                     ★ LoRA + QLoRA + DoRA + 量化兼容
│   │   ├── adalora/                  AdaLoRA
│   │   ├── ia3/                       IA³
│   │   ├── loha/ / lokr/ / oft/ / boft/ / hra/  正交家族
│   │   ├── vera/ / fourierft/        实验性 LoRA 变种
│   │   ├── prompt_tuning/ / prefix_tuning/ / p_tuning/  Prompt 系
│   │   ├── multitask_prompt_tuning/
│   │   ├── poly/                     Polytropon
│   │   ├── adaption_prompt/          LLaMA-Adapter
│   │   ├── trainable_tokens/         扩词表用
│   │   ├── ...（还有 30+ 实验性 tuner）
│   ├── utils/                        loftq / pissa / hub / hf save_load
│   ├── optimizers/                   特定 PEFT 用的优化器（少）
│   └── import_utils.py               可选依赖判断
├── examples/                          ★ 80+ 跑得通的样例
│   ├── lora_finetuning/
│   ├── qlora_finetuning/
│   ├── int8_training/
│   ├── dora_finetuning/
│   ├── loftq_finetuning/
│   ├── pissa_finetuning/
│   ├── lora_dreambooth/
│   ├── multi_adapter_examples/
│   └── ...（很多）
├── tests/                             单元测试（也是好的"小例子"）
├── docs/source/                      官方文档源
├── method_comparison/                 PEFT 方法 benchmark
└── scripts/

13.2建议的阅读顺序

13.3核心调用栈一图速记

用户 import peft
   │
get_peft_model(base, LoraConfig(...))           ← mapping_func.py
   │
   ├── PEFT_TYPE_TO_TUNER_MAPPING[LORA] → LoraModel
   ├── PEFT_TYPE_TO_PEFT_MODEL_MAPPING[CAUSAL_LM][LORA] → PeftModelForCausalLM
   └── PeftModelForCausalLM(base, cfg, "default")
           │
           └── base_model = LoraModel(base, {default: cfg}, "default")
                   │
                   ├── BaseTuner.inject_adapter
                   │       └── for each module:
                   │             _check_target_module_exists?
                   │                → _create_and_replace
                   │                       → ScaleLoraLinear / Linear8bitLt / Linear4bit
                   ├── _mark_only_adapters_as_trainable
                   └── return

forward 路径:
   PeftModel.forward
       → base_model.forward
       → 原 transformer.forward 但 q_proj / v_proj 已替换为 LoraLinear
       → LoraLinear.forward = base_layer(x) + B(A(x)) * scaling

13.4关键 commit 时间线

13.5关联论文

13.6下游生态

可以说"装了 transformers 就有 PEFT"已经是事实标准。

13.7对照其他 PEFT 工具

结论：现在事实上的 PEFT 标准就是 HF PEFT。

13.8社区入口

• GitHub: https://github.com/huggingface/peft（21k+ ⭐）
• 官方文档: https://huggingface.co/docs/peft
• 论坛: HuggingFace Discuss / GitHub Issues
• 每周 PEFT digest: HF 博客
• 新方法征集: 关注 method_comparison/ 目录

13.9提 issue / PR 礼仪

1. 提 bug：附 最小复现代码 + transformers/peft/torch 版本；
2. 提 feature：先在 issue 里讨论范围；新方法要带论文链接；
3. PR：跑 make quality（ruff + mypy）；写测试到 tests/；
4. 新 tuner 的 PR 通常需要 review 2-4 周；
5. commit 风格：FEAT: ... / FIX: ... / DOC: ... / TST: ...。

13.10examples/ 55 子目录速查

仓库的 examples/ 已经有 55+ 个子目录，每个一份完整可跑脚本。按主题分类的查表：

新人最值得先打开的 5 份：

1. lora_finetuning/ — 最简 SFT；
2. loftq_finetuning/ — QLoRA + 不掉精度初始化；
3. dora_finetuning/ — DoRA 一键替换 LoRA；
4. multi_adapter_examples/ — 多 adapter add / set / weighted 全套；
5. pissa_finetuning/ — 快收敛 init 实战。

13.11method_comparison/：PEFT 方法基准

repos/peft/method_comparison/ 是 PEFT 团队维护的方法级 benchmark。当下覆盖：

每个方法的实验 config 是独立 JSON 文件，同 base + 同数据 + 不同方法跑出来公平对比。"我该选 LoRA 还是 DoRA？"——去这个 Space 看你的 base 模型 + 任务对应的 leaderboard。

13.12跟着测试读 API

PEFT 的 tests/ 不是单纯回归测试，是每个 tuner 用法的金标准最小例。下表是"想学 X，先 grep test_X.py"：

13.13给读者的下一步

1. 从 examples/lora_finetuning/ 跑通一个最小例子；
2. 读 tuners/lora/layer.py（不到 1000 行）把 LoRA 实现彻底搞懂；
3. 读 tuners/lora/bnb.py 理解量化兼容怎么做；
4. 读 peft_model.py::PeftModelForCausalLM.forward（看 prompt 系怎么注入）；
5. 挑一个你感兴趣的新方法（DoRA / PiSSA / VeRA）读它的 layer.py；
6. 按第 12 章实现一个属于自己的 PoC tuner。

13.11结语

PEFT 是当前 LLM 微调生态的中枢——你看 LLaMA-Factory、Axolotl、TRL、ms-swift、vLLM、Diffusers， 底层都在调它。理解 PEFT 的三层抽象、能读懂 LoRA 的 layer.py，就掌握了 90% 的 PEFT 实战需求。

剩下的 10% 是新方法、量化集成、多 adapter 服务化——本书已经把每条线的入口都给你指了。 剩下的功夫在源码里。