【Hugging Face】PEFT 库中的 LoraConfig 常用的参数和说明

最新推荐文章于 2025-06-14 10:00:00 发布

原创最新推荐文章于 2025-06-14 10:00:00 发布 · 1.7k 阅读

30 ·

CC 4.0 BY-SA版权

文章标签：

#LoraConfig #LoRA #peft #Hugging Face #python

Hugging Face 专栏收录该内容

66 篇文章

订阅专栏

在 Hugging Face 的 PEFT（Parameter-Efficient Fine-Tuning）库中，LoraConfig 是用于配置 LoRA（Low-Rank Adaptation）方法的类。LoRA 是一种高效的微调技术，通过在预训练模型的权重矩阵上添加低秩分解矩阵（low-rank matrices）来实现参数高效的微调，大幅减少需要训练的参数数量，同时保持与全参数微调相当的性能。以下是对 LoraConfig 的详细讲解，包括其参数、用法、代码示例和注意事项。

1. LoraConfig 概述

LoraConfig 是 PeftConfig 的子类，用于指定 LoRA 微调的超参数。它定义了如何将 LoRA 适配器应用到模型的特定模块，以及 LoRA 的行为和特性。LoRA 的核心思想是将权重更新表示为两个低秩矩阵的乘积（即 $\Delta W = A \cdot B$ ），其中 $A$ 和 $B$ 的秩远小于原始权重矩阵，从而减少计算和存储成本。

2. LoraConfig 的主要参数

以下是 LoraConfig 中常用的参数及其说明：

peft_type（默认："LORA"）
- 指定 PEFT 方法类型，固定为 "LoraConfig"。
- 通常不需要手动设置，由类自动处理。
task_type（可选，字符串）
- 指定任务类型，帮助 PEFT 确定模型的结构和用途。常见选项包括：
  - "SEQ_CLS"：序列分类（如情感分析）。
  - "TOKEN_CLS"：token 分类（如 NER）。
  - "CAUSAL_LM"：因果语言模型（如 GPT）。
  - "SEQ_2_SEQ_LM"：序列到序列模型（如 T5）。
  - "FEATURE_EXTRACTION"：特征提取。
- 如果不明确任务类型，可以不设置。
r（整数，默认：8）
- LoRA 低秩矩阵的秩（rank）。秩越小，参数量越少，但模型表达能力可能受限。
- 典型值：4、8、16、32。选择时需平衡性能和效率。
lora_alpha（浮点数，默认：16）
- LoRA 的缩放因子，用于调整低秩矩阵对原始权重的贡献。公式为： $lora_alpha r ⋅ A ⋅ B \Delta W = \frac{\text{lora\_alpha}}{r} \cdot A \cdot B$ 。
- 通常设置为 r 的 2 倍（如 r=8 时，lora_alpha=16），但可以根据任务调整。
lora_dropout（浮点数，默认：0.1）
- LoRA 适配器中的 Dropout 概率，用于正则化，防止过拟合。
- 典型值：0.0 到 0.5。
target_modules（列表或字符串，可选）
- 指定应用 LoRA 的模型模块（通常是 Transformer 层的子模块）。
- 常见值（针对 Transformer 模型）：
  - ["query", "value"]：仅对注意力层的 query 和 value 矩阵应用 LoRA。
  - ["query", "key", "value", "dense"]：更广泛的应用。
- 如果不指定，PEFT 会根据模型类型选择默认模块（例如，LLaMA 模型默认包括 q_proj, v_proj 等）。
fan_in_fan_out（布尔值，默认：False）
- 是否适配特定模型的权重矩阵布局（fan-in/fan-out）。通常针对某些非标准 Transformer 架构（如 ConvNets）。
bias（字符串，默认："none"）
- 指定是否微调偏置参数。选项包括：
  - "none"：不微调偏置。
  - "all"：微调所有偏置。
  - "lora_only"：仅微调 LoRA 相关的偏置。
- 通常保持默认（"none"），因为偏置参数对性能影响较小。
modules_to_save（列表，可选）
- 指定需要全量微调的模块（不使用 LoRA）。例如，分类头的参数可以放入此列表。
- 示例：["classifier"]。
init_lora_weights（布尔值或字符串，默认：True）
- 指定 LoRA 权重初始化方式：
  - True：使用默认初始化（随机高斯分布）。
  - "gaussian"：高斯分布初始化。
  - False：零初始化（不推荐，可能影响性能）。
layers_to_transform（列表，可选）
- 指定应用 LoRA 的 Transformer 层索引（例如 [0, 1, 2] 表示仅对前三层应用 LoRA）。
- 默认：所有层。
layers_pattern（字符串，可选）
- 指定 Transformer 层的正则表达式模式，用于筛选需要应用 LoRA 的层。
- 示例："transformer.h.*"（针对特定模型结构）。

3. 使用 LoraConfig 的基本流程

以下是一个使用 LoraConfig 微调 BERT 模型（用于序列分类任务）的完整示例：

步骤 1：安装和导入库

pip install peft transformers torch datasets

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

步骤 2：加载模型和数据集

# 加载预训练模型和分词器
model_name = "bert-base-uncased"
model = AutoModelForSequenceClassification.from_pretrained(model_name, num_labels=2)
tokenizer = AutoTokenizer.from_pretrained(model_name)

# 加载数据集（以 GLUE 的 MRPC 为例）
dataset = load_dataset("glue", "mrpc")

# 数据预处理
def tokenize_function(examples):
    return tokenizer(examples["sentence1"], examples["sentence2"], truncation=True, padding="max_length", max_length=128)

tokenized_dataset = dataset.map(tokenize_function, batched=True)

步骤 3：配置 LoraConfig

# 配置 LoRA
lora_config = LoraConfig(
    task_type="SEQ_CLS",           # 序列分类任务
    r=8,                           # 低秩矩阵的秩
    lora_alpha=16,                 # 缩放因子
    lora_dropout=0.1,              # Dropout 概率
    target_modules=["query", "value"],  # 应用 LoRA 的模块
    bias="none",                   # 不微调偏置
    modules_to_save=["classifier"]  # 全量微调分类头
)

# 将 LoRA 应用到模型
peft_model = get_peft_model(model, lora_config)

# 查看可训练参数
peft_model.print_trainable_parameters()

输出示例：

trainable params: 294,912 || all params: 109,483,778 || trainable%: 0.269

这表明只有约 0.27% 的参数需要训练。

步骤 4：训练模型

# 配置训练参数
training_args = TrainingArguments(
    output_dir="./results",
    evaluation_strategy="epoch",
    learning_rate=2e-5,
    per_device_train_batch_size=16,
    per_device_eval_batch_size=16,
    num_train_epochs=3,
    weight_decay=0.01,
)

# 初始化 Trainer
trainer = Trainer(
    model=peft_model,
    args=training_args,
    train_dataset=tokenized_dataset["train"],
    eval_dataset=tokenized_dataset["validation"],
)

# 开始训练
trainer.train()

步骤 5：保存和加载 LoRA 模型

# 保存 LoRA 适配器
peft_model.save_pretrained("./lora_model")

# 加载 LoRA 模型
from peft import PeftModel
base_model = AutoModelForSequenceClassification.from_pretrained(model_name, num_labels=2)
loaded_model = PeftModel.from_pretrained(base_model, "./lora_model")

步骤 6：推理

# 准备输入
inputs = tokenizer("This is a positive sentence.", return_tensors="pt")

# 推理
loaded_model.eval()
outputs = loaded_model(**inputs)
logits = outputs.logits
print(logits)

4. LoraConfig 的优化建议

选择 r：
- 小模型（如 BERT）：r=4 或 r=8 通常足够。
- 大模型（如 LLaMA）：可能需要 r=16 或更高。
- 实验不同 r 值，观察性能和效率的权衡。
调整 lora_alpha：
- 通常设置为 r 的 2 倍，但可以尝试更大的值（如 32 或 64）以增强 LoRA 的影响。
选择 target_modules：
- 对于 Transformer 模型，["query", "value"] 是常见选择，参数量少且效果好。
- 如果性能不足，可以扩展到 ["query", "key", "value", "dense"]。
- 检查模型结构（model.named_modules()）以确定模块名称。
内存优化：
- 使用 4-bit 或 8-bit 量化（结合 QLoRA）以进一步减少内存占用。
- 启用梯度检查点：model.gradient_checkpointing_enable()。
- 减小 batch size 或 r 值。
任务类型：
- 确保 task_type 与模型和任务匹配。例如，LLaMA 使用 "CAUSAL_LM"，T5 使用 "SEQ_2_SEQ_LM"。

5. 常见问题与解答

Q1：如何确定 target_modules？
- 使用 model.named_modules() 查看模型的层结构，找到注意力或前馈层的名称。
- 对于 Hugging Face 模型，PEFT 通常会提供默认值（例如，LLaMA 的 q_proj, v_proj）。
Q2：LoRA 是否支持所有模型？
- 是的，LoRA 支持所有 Hugging Face Transformers 模型，包括 BERT、RoBERTa、LLaMA、T5 等。但需要正确配置 target_modules。
Q3：如何调试 LoRA 性能不佳的问题？
- 增加 r 或 lora_alpha 以增强 LoRA 的表达能力。
- 扩展 target_modules 覆盖更多层。
- 检查数据集质量和预处理步骤。
- 延长训练时间或调整学习率。
Q4：LoRA 与 QLoRA 的区别？
- QLoRA 是 LoRA 的量化版本，结合 4-bit 或 8-bit 量化，进一步减少内存占用。
- LoraConfig 可通过设置 use_qa_lora=True（未来版本可能支持）启用 QLoRA。

6. 进阶用法

多任务 LoRA：

为不同任务创建多个 LoraConfig 和适配器，使用 peft_model.add_adapter() 动态切换：

from peft import LoraConfig, get_peft_model

lora_config_task1 = LoraConfig(r=8, task_type=" SEQ_CLS", target_modules=["query", "value"])
lora_config_task2 = LoraConfig(r=16, task_type=" SEQ_CLS", target_modules=["query", "value"])

peft_model = get_peft_model(model, lora_config_task1, adapter_name="task1")
peft_model.add_adapter("task2", lora_config_task2)
peft_model.set_adapter("task1")  # 切换到 task1 适配器

保存到 Hugging Face Hub：

peft_model.push_to_hub("your-username/lora-model")

与量化结合：
使用 bitsandbytes 库进行 4-bit 量化：

pip install bitsandbytes

from transformers import AutoModelForCausalLM, BitsAndBytesConfig

quantization_config = BitsAndBytesConfig(load_in_4bit=True)
model = AutoModelForCausalLM.from_pretrained(model_name, quantization_config=quantization_config)
peft_model = get_peft_model(model, lora_config)