Peft 微调

使用 LoRA、QLoRA 及 25 种以上方法对 LLM 进行参数高效微调。适用于在 GPU 内存有限的情况下微调大模型（7B-70B），需要训练少于 1% 的参数且精度损失极小，或用于多适配器服务。HuggingFace 官方库，与 transformers 生态系统集成。

技能元数据


来源	可选 — 使用 `hermes skills install official/mlops/peft` 安装
路径	`optional-skills/mlops/peft`
版本	`1.0.0`
作者	Orchestra Research
许可证	MIT
依赖	`peft>=0.13.0`, `transformers>=4.45.0`, `torch>=2.0.0`, `bitsandbytes>=0.43.0`
平台	linux, macos, windows
标签	`Fine-Tuning`, `PEFT`, `LoRA`, `QLoRA`, `Parameter-Efficient`, `Adapters`, `Low-Rank`, `Memory Optimization`, `Multi-Adapter`

参考：完整 SKILL.md

정보

以下是该技能被触发时 Hermes 加载的完整技能定义。这是技能激活时 Agent 看到的指令。

PEFT（参数高效微调）

使用 LoRA、QLoRA 及 25 种以上适配器方法，通过训练少于 1% 的参数来微调 LLM。

何时使用 PEFT

在以下情况使用 PEFT/LoRA：

在消费级 GPU（RTX 4090、A100）上微调 7B-70B 模型
需要训练少于 1% 的参数（6MB 适配器 vs 14GB 完整模型）
需要快速迭代多个任务特定适配器
从一个基础模型部署多个微调变体

在以下情况使用 QLoRA（PEFT + 量化）：

在单张 24GB GPU 上微调 70B 模型
内存是主要限制因素
可以接受与全量微调相比约 5% 的质量折衷

在以下情况使用全量微调：

训练小模型（少于 1B 参数）
需要最高质量且有计算预算
显著的领域偏移需要更新所有权重

快速开始

安装

# 基础安装
pip install peft

# 带量化支持（推荐）
pip install peft bitsandbytes

# 完整安装
pip install peft transformers accelerate bitsandbytes datasets

LoRA 微调（标准）

from transformers import AutoModelForCausalLM, AutoTokenizer, TrainingArguments, Trainer
from peft import get_peft_model, LoraConfig, TaskType
from datasets import load_dataset

# 加载基础模型
model_name = "meta-llama/Llama-3.1-8B"
model = AutoModelForCausalLM.from_pretrained(model_name, torch_dtype="auto", device_map="auto")
tokenizer = AutoTokenizer.from_pretrained(model_name)
tokenizer.pad_token = tokenizer.eos_token

# LoRA 配置
lora_config = LoraConfig(
    task_type=TaskType.CAUSAL_LM,
    r=16,                          # 秩（8-64，越大容量越高）
    lora_alpha=32,                 # 缩放因子（通常为 2*r）
    lora_dropout=0.05,             # 用于正则化的丢弃率
    target_modules=["q_proj", "v_proj", "k_proj", "o_proj"],  # 注意力层
    bias="none"                    # 不训练偏置
)

# 应用 LoRA
model = get_peft_model(model, lora_config)
model.print_trainable_parameters()
# 输出：trainable params: 13,631,488 || all params: 8,043,307,008 || trainable%: 0.17%

# 准备数据集
dataset = load_dataset("databricks/databricks-dolly-15k", split="train")

def tokenize(example):
    text = f"### Instruction:\n{example['instruction']}\n\n### Response:\n{example['response']}"
    return tokenizer(text, truncation=True, max_length=512, padding="max_length")

tokenized = dataset.map(tokenize, remove_columns=dataset.column_names)

# 训练
training_args = TrainingArguments(
    output_dir="./lora-llama",
    num_train_epochs=3,
    per_device_train_batch_size=4,
    gradient_accumulation_steps=4,
    learning_rate=2e-4,
    fp16=True,
    logging_steps=10,
    save_strategy="epoch"
)

trainer = Trainer(
    model=model,
    args=training_args,
    train_dataset=tokenized,
    data_collator=lambda data: {"input_ids": torch.stack([f["input_ids"] for f in data]),
                                 "attention_mask": torch.stack([f["attention_mask"] for f in data]),
                                 "labels": torch.stack([f["input_ids"] for f in data])}
)

trainer.train()

# 仅保存适配器（6MB vs 16GB）
model.save_pretrained("./lora-llama-adapter")

QLoRA 微调（内存高效）

from transformers import AutoModelForCausalLM, BitsAndBytesConfig
from peft import get_peft_model, LoraConfig, prepare_model_for_kbit_training

# 4位量化配置
bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",           # NormalFloat4（最适合大语言模型）
    bnb_4bit_compute_dtype="bfloat16",   # 用 bf16 进行计算
    bnb_4bit_use_double_quant=True       # 嵌套量化
)

# 加载量化后的模型
model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-3.1-70B",
    quantization_config=bnb_config,
    device_map="auto"
)

# 准备训练（启用梯度检查点）
model = prepare_model_for_kbit_training(model)

# QLoRA 的 LoRA 配置
lora_config = LoraConfig(
    r=64,                              # 70B 模型使用更高秩
    lora_alpha=128,
    lora_dropout=0.1,
    target_modules=["q_proj", "v_proj", "k_proj", "o_proj", "gate_proj", "up_proj", "down_proj"],
    bias="none",
    task_type="CAUSAL_LM"
)

model = get_peft_model(model, lora_config)
# 70B 模型现在可以放入单张 24GB GPU！

LoRA 参数选择

秩（r）—— 容量 vs 效率

秩	可训练参数量	内存	质量	适用场景
4	~3M	极小	较低	简单任务、快速原型
8	~7M	低	较好	推荐起点
16	~14M	中等	更好	通用微调
32	~27M	较高	高	复杂任务
64	~54M	高	最高	领域适配、70B 模型

Alpha（lora_alpha）—— 缩放因子

# 经验法则：alpha = 2 * rank
LoraConfig(r=16, lora_alpha=32)  # 标准
LoraConfig(r=16, lora_alpha=16)  # 保守（学习率效果更低）
LoraConfig(r=16, lora_alpha=64)  # 激进（学习率效果更高）

按架构选择目标模块

# Llama / Mistral / Qwen
target_modules = ["q_proj", "v_proj", "k_proj", "o_proj", "gate_proj", "up_proj", "down_proj"]

# GPT-2 / GPT-Neo
target_modules = ["c_attn", "c_proj", "c_fc"]

# Falcon
target_modules = ["query_key_value", "dense", "dense_h_to_4h", "dense_4h_to_h"]

# BLOOM
target_modules = ["query_key_value", "dense", "dense_h_to_4h", "dense_4h_to_h"]

# 自动检测所有线性层
target_modules = "all-linear"  # PEFT 0.6.0+

加载与合并适配器

加载训练好的适配器

from peft import PeftModel, AutoPeftModelForCausalLM
from transformers import AutoModelForCausalLM

# 选项1：使用 PeftModel 加载
base_model = AutoModelForCausalLM.from_pretrained("meta-llama/Llama-3.1-8B")
model = PeftModel.from_pretrained(base_model, "./lora-llama-adapter")

# 选项2：直接加载（推荐）
model = AutoPeftModelForCausalLM.from_pretrained(
    "./lora-llama-adapter",
    device_map="auto"
)

将适配器合并到基模型

# 合并以便部署（无适配器开销）
merged_model = model.merge_and_unload()

# 保存合并后的模型
merged_model.save_pretrained("./llama-merged")
tokenizer.save_pretrained("./llama-merged")

# 推送到 Hub
merged_model.push_to_hub("username/llama-finetuned")

多适配器推理

from peft import PeftModel

# 加载基础模型及第一个适配器
model = AutoPeftModelForCausalLM.from_pretrained("./adapter-task1")

# 加载更多适配器
model.load_adapter("./adapter-task2", adapter_name="task2")
model.load_adapter("./adapter-task3", adapter_name="task3")

# 运行时切换适配器
model.set_adapter("task1")  # 使用 task1 适配器
output1 = model.generate(**inputs)

model.set_adapter("task2")  # 切换到 task2
output2 = model.generate(**inputs)

# 禁用适配器（使用基础模型）
with model.disable_adapter():
    base_output = model.generate(**inputs)

PEFT 方法对比

方法	可训练参数占比	内存	速度	最佳适用场景
LoRA	0.1-1%	低	快	通用微调
QLoRA	0.1-1%	极低	中等	内存受限场景
AdaLoRA	0.1-1%	低	中等	自动秩选择
IA3	0.01%	极小	最快	少样本适配
Prefix Tuning	0.1%	低	中等	生成控制
Prompt Tuning	0.001%	极小	快	简单任务适配
P-Tuning v2	0.1%	低	中等	NLU 任务

IA3（参数极少）

from peft import IA3Config

ia3_config = IA3Config(
    target_modules=["q_proj", "v_proj", "k_proj", "down_proj"],
    feedforward_modules=["down_proj"]
)
model = get_peft_model(model, ia3_config)
# Trains only 0.01% of parameters!

Prefix Tuning

from peft import PrefixTuningConfig

prefix_config = PrefixTuningConfig(
    task_type="CAUSAL_LM",
    num_virtual_tokens=20,      # 前置虚拟 token 数量
    prefix_projection=True      # 使用 MLP 投影
)
model = get_peft_model(model, prefix_config)

集成模式

与 TRL (SFTTrainer) 集成

from trl import SFTTrainer, SFTConfig
from peft import LoraConfig

lora_config = LoraConfig(r=16, lora_alpha=32, target_modules="all-linear")

trainer = SFTTrainer(
    model=model,
    args=SFTConfig(output_dir="./output", max_seq_length=512),
    train_dataset=dataset,
    peft_config=lora_config,  # 直接传入 LoRA 配置
)
trainer.train()

与 Axolotl (YAML 配置) 集成

# axolotl config.yaml
adapter: lora
lora_r: 16
lora_alpha: 32
lora_dropout: 0.05
lora_target_modules:
  - q_proj
  - v_proj
  - k_proj
  - o_proj
lora_target_linear: true  # 作用于所有线性层

与 vLLM (推理) 集成

from vllm import LLM
from vllm.lora.request import LoRARequest

# 加载支持 LoRA 的基础模型
llm = LLM(model="meta-llama/Llama-3.1-8B", enable_lora=True)

# 使用适配器提供服务
outputs = llm.generate(
    prompts,
    lora_request=LoRARequest("adapter1", 1, "./lora-adapter")
)

性能基准

内存使用 (Llama 3.1 8B)

方法	GPU 内存	可训练参数
全量微调	60+ GB	8B (100%)
LoRA r=16	18 GB	14M (0.17%)
QLoRA r=16	6 GB	14M (0.17%)
IA3	16 GB	800K (0.01%)

训练速度（A100 80GB）

方法	每秒Token数	对比全参数微调
Full FT	2,500	1x
LoRA	3,200	1.3x
QLoRA	2,100	0.84x

质量（MMLU基准）

模型	全参数微调	LoRA	QLoRA
Llama 2-7B	45.3	44.8	44.1
Llama 2-13B	54.8	54.2	53.5

常见问题

训练时CUDA内存不足

# Solution 1: Enable gradient checkpointing
model.gradient_checkpointing_enable()

# Solution 2: Reduce batch size + increase accumulation
TrainingArguments(
    per_device_train_batch_size=1,
    gradient_accumulation_steps=16
)

# Solution 3: Use QLoRA
from transformers import BitsAndBytesConfig
bnb_config = BitsAndBytesConfig(load_in_4bit=True, bnb_4bit_quant_type="nf4")

适配器未生效

# Verify adapter is active
print(model.active_adapters)  # Should show adapter name

# Check trainable parameters
model.print_trainable_parameters()

# Ensure model in training mode
model.train()

质量下降

# Increase rank
LoraConfig(r=32, lora_alpha=64)

# Target more modules
target_modules = "all-linear"

# Use more training data and epochs
TrainingArguments(num_train_epochs=5)

# Lower learning rate
TrainingArguments(learning_rate=1e-4)

最佳实践

从 r=8-16 开始，若质量不足则增加
使用 alpha = 2 * rank 作为起点
针对注意力层和MLP层，以获得最佳质量/效率
启用梯度检查点以节省内存
频繁保存适配器（文件小，易于回滚）
在保留数据上评估后再合并
在消费级硬件上对70B+模型使用QLoRA

参考

高级用法 - DoRA、LoftQ、秩稳定、自定义模块
故障排除 - 常见错误、调试、优化

资源

GitHub: https://github.com/huggingface/peft
文档: https://huggingface.co/docs/peft
LoRA论文: arXiv:2106.09685
QLoRA论文: arXiv:2305.14314
模型: https://huggingface.co/models?library=peft

技能元数据​

参考：完整 SKILL.md​

PEFT（参数高效微调）

何时使用 PEFT​

快速开始​

安装​

LoRA 微调（标准）​

QLoRA 微调（内存高效）​

LoRA 参数选择​

秩（r）—— 容量 vs 效率​

Alpha（lora_alpha）—— 缩放因子​

按架构选择目标模块​

加载与合并适配器​

加载训练好的适配器​

将适配器合并到基模型​

多适配器推理​

PEFT 方法对比​

IA3（参数极少）​

Prefix Tuning​

集成模式​

与 TRL (SFTTrainer) 集成​

与 Axolotl (YAML 配置) 集成​

与 vLLM (推理) 集成​

性能基准​

内存使用 (Llama 3.1 8B)​

训练速度（A100 80GB）​

质量（MMLU基准）​

常见问题​

训练时CUDA内存不足​

适配器未生效​

质量下降​

最佳实践​

参考​

资源​