PEFT 参数高效微调库（结合源码）

class PeftModel(PushToHubMixin, torch.nn.Module):
    def __init__(self, model, peft_config, adapter_name="default",
                 autocast_adapter_dtype=True, low_cpu_mem_usage=False):
        self.active_adapter = adapter_name          # 当前活跃适配器名
        self.peft_type = peft_config.peft_type      # PEFT类型(LoRA/AdaLora等)
        self._is_prompt_learning = peft_config.is_prompt_learning

if self._is_prompt_learning:
    # Prompt Learning方法（Prefix Tuning, Prompt Tuning等）
    # 直接在base_model上添加adapter
    self.base_model = model
    self.add_adapter(adapter_name, peft_config)
else:
    # Tuner类方法（LoRA, IA³等）
    # 通过映射表获取具体的Tuner类，包装基础模型
    cls = PEFT_TYPE_TO_TUNER_MAPPING[peft_config.peft_type]
    self.base_model = cls(model, {adapter_name: peft_config}, adapter_name)

class LoraModel(BaseTuner):
    prefix: str = "lora_"                                    # 参数名前缀
    tuner_layer_cls = LoraLayer                              # 适配器层类
    target_module_mapping = TRANSFORMERS_MODELS_TO_LORA_TARGET_MODULES_MAPPING  # 默认目标模块映射

class LoraLayer(BaseTunerLayer):
    adapter_layer_names = ("lora_A", "lora_B", "lora_embedding_A", "lora_embedding_B")

    def __init__(self, base_layer, ephemeral_gpu_offload=False):
        self.base_layer = base_layer        # 原始nn.Linear层
        self.r = {}                         # 每个adapter的秩 {adapter_name: r}
        self.lora_alpha = {}                # 每个adapter的alpha
        self.scaling = {}                   # 每个adapter的缩放因子 alpha/r
        self.lora_dropout = nn.ModuleDict({})  # Dropout层
        self.lora_A = nn.ModuleDict({})     # A矩阵: (in_features, r)
        self.lora_B = nn.ModuleDict({})     # B矩阵: (r, out_features)
        self.lora_embedding_A = nn.ParameterDict({})  # Embedding层的A
        self.lora_embedding_B = nn.ParameterDict({})  # Embedding层的B

def update_layer(self, adapter_name, r, lora_alpha, config):
    # 创建A和B矩阵
    self.lora_A[adapter_name] = nn.Linear(self.in_features, r, bias=False)
    self.lora_B[adapter_name] = nn.Linear(r, self.out_features, bias=lora_bias)

    # 计算缩放因子
    if use_rslora:
        self.scaling[adapter_name] = lora_alpha / math.sqrt(r)  # Rank-Stabilized
    else:
        self.scaling[adapter_name] = lora_alpha / r              # 标准LoRA

    # 权重初始化
    if init_lora_weights is True:
        nn.init.kaiming_uniform_(self.lora_A[adapter_name].weight, a=math.sqrt(5))
        nn.init.zeros_(self.lora_B[adapter_name].weight)  # B初始化为0，保证ΔW=0

def get_delta_weight(self, adapter):
    weight_A = self.lora_A[adapter].weight   # (r, in_features)
    weight_B = self.lora_B[adapter].weight   # (out_features, r)
    # ΔW = scaling * B @ A
    output_tensor = transpose(weight_B @ weight_A, self.fan_in_fan_out) * self.scaling[adapter]
    return output_tensor

def merge(self, safe_merge=False, adapter_names=None):
    for active_adapter in adapter_names:
        delta_weight = self.get_delta_weight(active_adapter)
        base_layer.weight.data += delta_weight   # W_merged = W_0 + (α/r) * BA

PeftModel.from_pretrained(
    model,                  # transformers.PreTrainedModel: 基础模型
    model_id,               # str: 适配器路径或HuggingFace Hub ID
    adapter_name="default", # str: 适配器名称
    is_trainable=False,     # bool: 是否可训练（False=推理模式）
    config=None,            # PeftConfig: 手动指定配置（可选）
    autocast_adapter_dtype=True,  # bool: 自动将fp16/bf16适配器权重转为fp32
    ephemeral_gpu_offload=False,  # bool: CPU/GPU临时卸载
    low_cpu_mem_usage=False,      # bool: 在meta device上创建空权重加速加载
)

model.merge_and_unload(
    progressbar=False,      # bool: 是否显示进度条
    safe_merge=False,       # bool: 安全合并模式（检查NaN）
    adapter_names=None,     # List[str]: 要合并的适配器列表，None=所有活跃适配器
)

from peft import get_peft_model

model = get_peft_model(
    model,                      # PreTrainedModel: 基础模型
    peft_config,                # PeftConfig: 适配器配置
    adapter_name="default",     # str: 适配器名称
    mixed=False,                # bool: 是否允许混合不同类型的适配器
    autocast_adapter_dtype=True,# bool: 自动类型转换
    revision=None,              # str: 基础模型的版本
    low_cpu_mem_usage=False,    # bool: 低CPU内存模式
)

from peft import LoraConfig, TaskType

config = LoraConfig(
    r=8,                        # int: LoRA秩（低秩维度），越大表达力越强但参数越多
    lora_alpha=16,              # int: 缩放因子，实际缩放 = lora_alpha / r
    target_modules=["q_proj", "v_proj"],  # 要替换的模块名列表或正则表达式
                                # 特殊值 "all-linear" 自动选择所有线性层
    lora_dropout=0.0,           # float: Dropout概率
    bias="none",                # "none"/"all"/"lora_only": 偏置处理方式
    task_type=TaskType.CAUSAL_LM,  # 任务类型
    fan_in_fan_out=False,       # bool: Conv1D权重格式(GPT-2)
    init_lora_weights=True,     # True/False/"gaussian"/"pissa"/"olora"/"loftq"/"eva"/"orthogonal"等
    use_rslora=False,           # bool: 使用Rank-Stabilized LoRA，缩放改为alpha/sqrt(r)
    use_dora=False,             # bool: 启用DoRA（权重分解方向+幅度）
    modules_to_save=None,       # List[str]: 额外需要训练和保存的模块（如分类头）
    layers_to_transform=None,   # List[int]/int: 只变换指定层索引
    layers_pattern=None,        # str: 层模式名（配合layers_to_transform使用）
    rank_pattern={},            # dict: 层名→秩的映射，覆盖默认r
    alpha_pattern={},           # dict: 层名→alpha的映射，覆盖默认lora_alpha
    exclude_modules=None,       # List[str]: 排除的模块名
    loftq_config=None,          # LoftQConfig: LoftQ量化初始化配置
    eva_config=None,            # EvaConfig: EVA数据驱动初始化配置
    corda_config=None,          # CordaConfig: CorDA初始化配置
    lora_ga_config=None,        # LoraGAConfig: LoRA-GA梯度近似初始化配置
    layer_replication=None,     # List[Tuple[int,int]]: 层复制范围（扩展模型）
    trainable_token_indices=None,  # 选择性训练特定token的embedding
    lora_bias=False,            # bool: 是否为LoRA B参数启用偏置
    target_parameters=None,     # List[str]: 直接指定参数名（用于MoE等）
    ensure_weight_tying=False,  # bool: 确保权重共享后适配器也共享
)

from peft import AdaLoraConfig, TaskType

config = AdaLoraConfig(
    target_r=8,             # int: 目标平均秩（所有层的秩之和 / 层数 ≈ target_r）
    init_r=12,              # int: 初始秩（训练开始时每层的秩）
    tinit=0,                # int: 初始预热步数（不做秩调整）
    tfinal=0,               # int: 最终微调步数（不再调整秩）
    deltaT=1,               # int: 秩调整的时间间隔
    beta1=0.85,             # float: EMA平滑系数（敏感性估计）
    beta2=0.85,             # float: EMA不确定性量化系数
    orth_reg_weight=0.5,    # float: 正交正则化权重
    total_step=1000,        # int: 总训练步数（必须指定）
    rank_pattern=None,      # dict: 预设的秩分配模式

    # 继承自LoraConfig
    lora_alpha=8,
    lora_dropout=0.0,
    target_modules=["q_proj", "v_proj"],
    task_type=TaskType.CAUSAL_LM,
)

from peft import IA3Config, TaskType

config = IA3Config(
    target_modules=["q_proj", "v_proj", "down_proj"],  # 要替换的模块
    feedforward_modules=["down_proj"],  # 前馈模块（缩放作用于输入而非输出）
    fan_in_fan_out=False,       # Conv1D权重格式
    modules_to_save=None,       # 额外训练模块
    init_ia3_weights=True,      # 是否初始化IA³向量
    task_type=TaskType.CAUSAL_LM,
)

from peft import PromptTuningConfig, TaskType

config = PromptTuningConfig(
    num_virtual_tokens=20,                  # int: 虚拟token数量
    prompt_tuning_init=PromptTuningInit.TEXT,  # "TEXT"/"RANDOM"/"SAMPLE_VOCAB"
    prompt_tuning_init_text="Classify the following:",  # str: 初始化文本（TEXT模式）
    tokenizer_name_or_path="meta-llama/Llama-2-7b",     # str: 分词器路径（TEXT模式）
    task_type=TaskType.CAUSAL_LM,
)

from peft import PrefixTuningConfig, TaskType

config = PrefixTuningConfig(
    num_virtual_tokens=20,           # int: 前缀token数量
    encoder_hidden_size=768,         # int: 前缀编码器的隐藏维度
    prefix_projection=False,         # bool: 是否投影前缀embedding
    init_weights=None,               # "zero"或None: 初始化方式
    task_type=TaskType.CAUSAL_LM,
)

from peft import TaskType

class TaskType(str, enum.Enum):
    SEQ_CLS = "SEQ_CLS"                # 文本分类
    SEQ_2_SEQ_LM = "SEQ_2_SEQ_LM"      # 序列到序列语言模型（如T5）
    CAUSAL_LM = "CAUSAL_LM"            # 因果语言模型（如LLaMA, GPT）
    TOKEN_CLS = "TOKEN_CLS"            # Token分类（如NER）
    QUESTION_ANS = "QUESTION_ANS"       # 问答
    FEATURE_EXTRACTION = "FEATURE_EXTRACTION"  # 特征提取

from transformers import BitsAndBytesConfig

bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",           # 使用NF4量化
    bnb_4bit_compute_dtype=torch.bfloat16,  # 计算精度
    bnb_4bit_use_double_quant=True,       # 启用双重量化
)

# 手动实现LoRA+的学习率分组
lora_a_params = [p for n, p in model.named_parameters() if "lora_A" in n]
lora_b_params = [p for n, p in model.named_parameters() if "lora_B" in n]

optimizer = torch.optim.AdamW([
    {"params": lora_a_params, "lr": 1e-4},
    {"params": lora_b_params, "lr": 1e-3},  # B的学习率是A的10倍
])

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer
from peft import LoraConfig, get_peft_model, TaskType

# 加载基础模型
model_name = "meta-llama/Llama-2-7b-hf"
model = AutoModelForCausalLM.from_pretrained(
    model_name,
    torch_dtype=torch.bfloat16,
    device_map="auto",
)
tokenizer = AutoTokenizer.from_pretrained(model_name)

# 配置LoRA
lora_config = LoraConfig(
    r=8,                                    # LoRA秩
    lora_alpha=16,                          # 缩放因子
    target_modules=["q_proj", "k_proj",     # 目标模块
                    "v_proj", "o_proj",
                    "gate_proj", "up_proj",
                    "down_proj"],
    lora_dropout=0.05,                      # Dropout
    bias="none",                            # 不训练偏置
    task_type=TaskType.CAUSAL_LM,           # 因果语言模型
)

# 注入LoRA适配器
model = get_peft_model(model, lora_config)

# 查看可训练参数
model.print_trainable_parameters()
# 输出示例: trainable params: 13,107,200 || all params: 6,738,415,616 || trainable%: 0.1945

# 训练循环（简化示例）
optimizer = torch.optim.AdamW(model.parameters(), lr=2e-4)
for batch in train_dataloader:
    outputs = model(**batch)
    loss = outputs.loss
    loss.backward()
    optimizer.step()
    optimizer.zero_grad()

# 保存适配器
model.save_pretrained("./lora-adapter")
tokenizer.save_pretrained("./lora-adapter")

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

# 配置4-bit量化
bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,                      # 4-bit加载
    bnb_4bit_quant_type="nf4",              # NF4量化类型
    bnb_4bit_compute_dtype=torch.bfloat16,  # 计算精度
    bnb_4bit_use_double_quant=True,         # 双重量化
)

# 加载4-bit量化模型
model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-2-7b-hf",
    quantization_config=bnb_config,
    device_map="auto",
)

# 准备量化模型训练
model = prepare_model_for_kbit_training(model)

# 配置LoRA
lora_config = LoraConfig(
    r=16,                                   # QLoRA通常使用较大的r
    lora_alpha=32,
    target_modules=["q_proj", "k_proj", "v_proj", "o_proj",
                    "gate_proj", "up_proj", "down_proj"],
    lora_dropout=0.05,
    bias="none",
    task_type=TaskType.CAUSAL_LM,
)

# 注入LoRA
model = get_peft_model(model, lora_config)
model.print_trainable_parameters()
# 显存占用大幅降低: 7B模型全参数约28GB(fp16), QLoRA约5-6GB

import torch
from transformers import AutoModelForCausalLM
from peft import PeftModel, LoraConfig, get_peft_model, TaskType

# 加载基础模型
model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-2-7b-hf",
    torch_dtype=torch.bfloat16,
    device_map="auto",
)

# 添加第一个适配器（摘要任务）
summary_config = LoraConfig(
    r=8, lora_alpha=16,
    target_modules=["q_proj", "v_proj"],
    task_type=TaskType.CAUSAL_LM,
)
model = get_peft_model(model, summary_config, adapter_name="summary")

# 添加第二个适配器（翻译任务）
translation_config = LoraConfig(
    r=16, lora_alpha=32,
    target_modules=["q_proj", "k_proj", "v_proj", "o_proj"],
    task_type=TaskType.CAUSAL_LM,
)
model.add_adapter("translation", translation_config)

# 添加第三个适配器（从预训练加载）
model.load_adapter("./lora-qa-adapter", adapter_name="qa")

# 切换适配器
model.set_adapter("summary")   # 使用摘要适配器
model.set_adapter("translation")  # 切换到翻译适配器

# 禁用适配器（退回基础模型）
with model.disable_adapter():
    outputs = model.generate(**inputs)  # 纯基础模型推理

# 删除适配器
model.delete_adapter("qa")

# 查看所有适配器
print(model.peft_config.keys())  # dict_keys(['summary', 'translation'])

from transformers import AutoModelForCausalLM, AutoTokenizer
from peft import PeftModel

# 加载基础模型
base_model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-2-7b-hf",
    torch_dtype=torch.bfloat16,
    device_map="auto",
)

# 加载LoRA适配器
model = PeftModel.from_pretrained(base_model, "./lora-adapter")

# 合并权重（安全模式，检查NaN）
merged_model = model.merge_and_unload(safe_merge=True)

# 保存合并后的完整模型
merged_model.save_pretrained("./merged-model")
tokenizer = AutoTokenizer.from_pretrained("meta-llama/Llama-2-7b-hf")
tokenizer.save_pretrained("./merged-model")

# 合并后的模型与原始架构完全相同，可直接用于推理
# 无需安装PEFT，也不存在推理延迟

from peft import PeftModel

# 加载基础模型
base_model = AutoModelForCausalLM.from_pretrained("./base-model", ...)

# 依次加载并合并多个适配器
model = PeftModel.from_pretrained(base_model, "./adapter-1", adapter_name="adapter_1")
model.load_adapter("./adapter-2", adapter_name="adapter_2")

# 合并所有活跃适配器
merged_model = model.merge_and_unload()

# 或只合并指定适配器
merged_model = model.merge_and_unload(adapter_names=["adapter_1"])

import torch
from transformers import AutoModelForCausalLM, TrainingArguments, Trainer
from peft import AdaLoraConfig, get_peft_model, TaskType

# 加载模型
model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-2-7b-hf",
    torch_dtype=torch.bfloat16,
    device_map="auto",
)

# 配置AdaLora
adalora_config = AdaLoraConfig(
    target_r=8,                 # 目标平均秩
    init_r=12,                  # 初始秩
    tinit=100,                  # 预热100步
    tfinal=200,                 # 最后200步固定
    deltaT=10,                  # 每10步调整一次秩
    beta1=0.85,                 # EMA平滑系数
    beta2=0.85,                 # EMA不确定性系数
    orth_reg_weight=0.5,        # 正交正则化权重
    total_step=1000,            # 总训练步数
    lora_alpha=16,
    lora_dropout=0.05,
    target_modules=["q_proj", "k_proj", "v_proj", "o_proj",
                    "gate_proj", "up_proj", "down_proj"],
    task_type=TaskType.CAUSAL_LM,
)

model = get_peft_model(model, adalora_config)
model.print_trainable_parameters()

# 在训练回调中更新预算分配器
class AdaLoraCallback:
    def __init__(self, model, total_step):
        self.model = model
        self.total_step = total_step

    def on_step_end(self, args, state, control, **kwargs):
        # 更新AdaLora的预算分配器
        if hasattr(self.model, "update_and_allocate"):
            self.model.update_and_allocate(state.global_step)

# 使用自定义Trainer
trainer = Trainer(
    model=model,
    args=TrainingArguments(
        output_dir="./adalora-output",
        num_train_epochs=3,
        per_device_train_batch_size=4,
        learning_rate=2e-4,
    ),
    train_dataset=train_dataset,
    callbacks=[AdaLoraCallback(model, total_step=1000)],
)
trainer.train()

# 保存
model.save_pretrained("./adalora-adapter")

from transformers import AutoModelForCausalLM, AutoTokenizer
from peft import PeftModel

# 方式1: 先加载基础模型，再加载适配器
base_model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-2-7b-hf",
    torch_dtype=torch.bfloat16,
    device_map="auto",
)
model = PeftModel.from_pretrained(base_model, "./lora-adapter")

# 方式2: 加载为可训练模型
model = PeftModel.from_pretrained(
    base_model,
    "./lora-adapter",
    is_trainable=True,  # 启用训练模式
)

# 方式3: 使用AutoPeftModel自动加载
from peft import AutoPeftModelForCausalLM
model = AutoPeftModelForCausalLM.from_pretrained(
    "./lora-adapter",
    torch_dtype=torch.bfloat16,
    device_map="auto",
)

# 方式4: 加载量化基础模型+适配器
from transformers import BitsAndBytesConfig
bnb_config = BitsAndBytesConfig(load_in_4bit=True, bnb_4bit_quant_type="nf4")
base_model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-2-7b-hf",
    quantization_config=bnb_config,
    device_map="auto",
)
model = PeftModel.from_pretrained(base_model, "./lora-adapter")