PEFT：参数高效微调

为什么需要 PEFT：全参微调的高门槛 → 1% 参数完成领域适配

全参微调的成本瓶颈体现在两方面。一是显存：以 7B 模型为例，用 Adam 优化器训练，需要同时驻留 fp16 权重（约 14GB）、梯度（约 14GB）和优化器状态（约 28GB），合计约 56GB 起步，单卡 A100（80GB）才够用，24GB 消费级显卡直接出局。二是效率与稳定性：全参微调会更新全部参数，在小数据量场景容易过拟合，并破坏预训练学到的通用能力，即灾难性遗忘；同时每微调一个任务就产出一份与基座等大的权重文件，存储和分发成本高。对 RAG、Agent、领域问答这类“基座能力够用、只需补齐领域知识”的任务，全参微调是明显的资源浪费。

PEFT 的核心思路是冻结预训练权重 W，在模型结构中插入或叠加少量可学习参数，只训练这部分参数。以 LoRA 为例，权重增量 ΔW 被分解为低秩矩阵 A 和 B 的乘积，7B 模型的可训练参数只有约 0.1%。训练显存从约 60GB 降到 24GB 以内；QLoRA 再把基座权重量化为 4-bit，显存进一步降到 12GB 左右，并配合分页优化器处理峰值显存。训练完成后，保存的不是完整模型而是一个几十 MB 的适配器（adapter），推理时叠加回基座即可。参数少还意味着过拟合风险更低，几千条数据也能稳定收敛。

与同类工具相比，PEFT 的气质是“方法全、够底层”。Unsloth 用自研内核把 LoRA 训练加速约 2 倍，但只专注 LoRA 家族；LLaMA-Factory 提供 WebUI 和全流程管理，底层调用的正是 PEFT；LitGPT 是 Lightning 团队独立维护的训练框架。PEFT 的定位是“标准 API + 方法多样性”，不绑定训练脚本和数据格式，适合作为工程化落地的底层组件。

安装与环境配置：4 步就绪

步骤一·安装 PEFT：推荐用 pip 安装稳定版，要求 Python 3.9+；需要最新开发特性时从 GitHub 主线安装。

步骤二·升级配套依赖：PEFT 依赖 transformers 负责模型加载与 Trainer，accelerate 管理设备，bitsandbytes 提供 QLoRA 的 4-bit 量化。三者需与 PEFT 保持兼容，建议一并升级。Windows 上使用 bitsandbytes 推荐 WSL2 环境。

步骤三·验证版本：打印 peft 与 transformers 版本号，确认安装成功。

步骤四·最小注入验证：加载一个 1.5B 小模型注入 LoRA，观察 print_trainable_parameters() 输出的可训练参数占比，应远低于 1%。

# 1) 安装pip install -U peftpip install -U transformers accelerate bitsandbytes # 2) 验证版本python -c "import peft, transformers; print(peft.__version__, transformers.__version__)"

# 3) 最小注入验证（可训练占比应 < 1%）from transformers import AutoModelForCausalLMfrom peft import LoraConfig, get_peft_model, TaskType model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2-1.5B", torch_dtype="auto")config = LoraConfig(    task_type=TaskType.CAUSAL_LM,   # 因果语言模型    r=8,                            # 低秩矩阵维度    lora_alpha=32,                  # 增量缩放系数    target_modules=["q_proj", "k_proj", "v_proj", "o_proj"],)peft_model = get_peft_model(model, config)peft_model.print_trainable_parameters()# trainable params: 2,752,512 || trainable%: 0.1783

快速上手：15 分钟跑通 LoRA 指令微调

最小可用流程为：加载基座模型 → 注入 LoRA → 用 transformers Trainer 训练 → 保存 adapter → 加载 adapter 推理。数据集使用任意指令式 JSONL（每行含 instruction、output 字段），无需搭建复杂训练框架。下面代码基于 PEFT 0.11+ 与 transformers 正式版，以 Qwen2-1.5B-Instruct 演示：

1. 准备数据：构造 train.jsonl，每行 {"instruction": "…", "output": "…"}，随后用 tokenizer 拼成“问题 + 回答”文本，截断到 512 token。

2. 配置 LoRA：r=8、lora_alpha=32、target_modules 覆盖注意力四件套（q/k/v/o_proj），这是 7B 以内模型的安全起点。

3. 执行训练：直接用 transformers.Trainer 即可；想更省事可改用 peft.SFTTrainer（PEFT 0.11 起内置），传原始文本即可。

4. 保存与推理：save_pretrained 产出 adapter_config.json 与 adapter_model.safetensors；推理时用 PeftModel.from_pretrained 叠加回基座。

训练完成后，qwen-lora-final 目录只有两个文件，加载时用 PeftModel.from_pretrained(base, "qwen-lora-final") 即可对话。进阶技巧：先用 lora_alpha=32 跑通，再按需上调 r（8 → 16）；数据量小于 1000 条时把 num_train_epochs 降到 2 防止过拟合。

from datasets import load_datasetfrom transformers import AutoModelForCausalLM, AutoTokenizerfrom transformers import TrainingArguments, Trainer, DataCollatorForSeq2Seqfrom peft import LoraConfig, get_peft_model, TaskType MODEL_ID = "Qwen/Qwen2-1.5B-Instruct"tokenizer = AutoTokenizer.from_pretrained(MODEL_ID) def to_text(ex):  # 组装指令格式并分词    prompt = f"问题：{ex['instruction']}\n回答："    text = prompt + ex["output"] + tokenizer.eos_token    return tokenizer(text, max_length=512, truncation=True) ds = load_dataset("json", data_files="train.jsonl")ds = ds.map(to_text, remove_columns=ds["train"].column_names) base = AutoModelForCausalLM.from_pretrained(MODEL_ID, torch_dtype="auto")config = LoraConfig(task_type=TaskType.CAUSAL_LM, r=8, lora_alpha=32,                    target_modules=["q_proj", "k_proj", "v_proj", "o_proj"])model = get_peft_model(base, config)model.print_trainable_parameters() trainer = Trainer(    model=model,    args=TrainingArguments(output_dir="qwen-lora", per_device_train_batch_size=2,                           gradient_accumulation_steps=8, learning_rate=2e-4,                           num_train_epochs=3, bf16=True, save_strategy="epoch",                           logging_steps=10, report_to="none"),    train_dataset=ds["train"],    data_collator=DataCollatorForSeq2Seq(tokenizer, padding=True),)trainer.train()model.save_pretrained("qwen-lora-final")

核心能力详解：4 大支柱

支柱一·方法全家桶：LoRA 及其变体。 LoRA 冻结原权重 W、训练低秩矩阵 A 与 B，推理时叠加增量；QLoRA 将基座做 4-bit 量化（NF4 + 双重量化 + 分页优化器），显存再砍约一半；DoRA 把权重分解为幅度与方向、只对方向做低秩适配，小数据量下精度更接近全参；PiSSA 用 SVD 奇异值初始化 A、B，加速收敛；LoRA+ 给 A、B 设不同学习率；IA3 用逐 token 缩放激活。选择建议：默认 LoRA，显存吃紧上 QLoRA，追求精度上 DoRA。

支柱二·统一 API 与模型无关设计。 一套 LoraConfig / get_peft_model / PeftModel 适配所有方法，TaskType 声明任务类型（因果 LM、序列分类等）。适配器保存/加载与 Hugging Face Hub 打通：push_to_hub 一键发布，from_pretrained 从远端拉取，团队间共享 adapter 如同共享权重文件。更换方法只需改配置对象，训练代码不动。

支柱三·与训练生态无缝集成。 与 transformers Trainer、TRL 的 SFTTrainer、accelerate、DeepSpeed、bitsandbytes 全面兼容，支持多卡训练与 ZeRO-3 下的 LoRA 分片。不局限于文本：diffusers 生态中可对 Stable Diffusion 注入 LoRA 做概念定制，视觉生成模型使用同一套 API。

支柱四·适配器组合与动态装卸。 同一基座可并行挂载多个 adapter，训练互不干扰；推理时可 merge_and_unload() 把增量写回基座、导出一份完整权重，做到零额外推理延迟；也可保留 adapter，由 vLLM 等推理引擎在运行时动态加载/卸载，实现一套基座多任务切换。

生产部署与监控：从上线到运维

部署方式一：merge 后标准部署。 适合单模型服务。将训练好的 adapter 合入基座并导出标准 safetensors，交给 vLLM/TGI 或 transformers pipeline 部署，无额外推理延迟。合并前先做一次生成质量回归，确认无精度回退。

部署方式二：vLLM 动态 LoRA 服务。 适合多租户/多任务。vLLM 0.4+ 原生支持 LoRA：启动时开启 enable_lora，请求时携带 LoRARequest 指定要加载的适配器。每个 adapter 磁盘仅几十 MB、显存按 rank 计，服务端按需唤起，一套基座服务多个领域模型。

可观测性。 训练期：TrainingArguments(report_to="wandb") 记录 loss、grad norm、token/s 与显存水位，把 r、alpha、数据集规模记入模型卡；升级依赖或换基座时用固定评测集（如 200 条领域 QA）做回归。部署期：merge 形态监控单实例 QPS 与首 Token 延迟；动态形态额外监控 adapter 切换耗时、并发 adapter 数与显存占用，max_loras 超限会导致排队或 OOM。

<p class="para-label">避坑清单：</p>

<ul class="dash-list"><li>版本兼容：PEFT 与 transformers/accelerate 同步迭代，报 module 'peft' 无 LoraConfig 属性或 save_pretrained 失败时先对齐三者版本，生产环境锁定版本组合。</li><li>target_modules 写错：模块名不匹配时 LoRA 注入 0 个模块，可训练占比接近 100%，等于全参训练。用 print_trainable_parameters() 确认占比 ≤ 1%。</li><li>r 值过拟合：r=8 起步，并非越大越好；r 超过任务复杂度反而过拟合训练集，且 adapter 体积线性膨胀。</li><li>merge 精度损失：fp16 下 merge_and_unload() 可能引入微小误差，上线前做生成质量回归，不要反复 merge 累积误差。</li><li>多 adapter 显存叠加：动态切换时 adapter 权重常驻显存，数量过多会 OOM；用 max_loras 控制上限并持续监控显存水位。</li></ul>

from peft import PeftModelfrom transformers import AutoModelForCausalLM base = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2-1.5B-Instruct", torch_dtype="auto")peft_model = PeftModel.from_pretrained(base, "qwen-lora-final")merged = peft_model.merge_and_unload()   # 增量合入基座，卸载 adapter 包装merged.save_pretrained("qwen-merged")    # 导出标准模型，交给 vLLM/TGI

from vllm import LLM, LoRARequestllm = LLM(model="Qwen/Qwen2-1.5B-Instruct", enable_lora=True, max_loras=4)out = llm.generate(    ["请解释劳动合同法第 47 条"],    LoRARequest(name="legal-lora", lora_int_id=1, lora_path="/models/legal-lora"),)

版本迭代

PEFT 自 2023 年开源后，主线是从“LoRA 单点工具”发展为“参数高效微调方法全家桶”，0.11 起内置 SFTTrainer，正式从注入工具演化为可独立完成训练闭环的框架。后续版本主要围绕新方法（DoRA）、量化适配（GPTQ）与稳定性改进展开。（截至训练数据，最新为 0.14.0，可能已有更新版本）

AI 应用场景

常见误区

面试题