UniLoRA

Uni-LoRA 是一种 PEFT 方法，它在低秩适配器权重之间共享一个紧凑的可训练向量库。UniLoRA 不会独立学习每个 LoRA 矩阵元素，而是将条目确定性地投影到共享的 theta_d 值上，并学习适配器更新所使用的共享参数。

快速入门

from peft import UniLoraConfig, get_peft_model
from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained("meta-llama/Llama-3.2-3B")

config = UniLoraConfig(
    r=32,
    theta_d_length=256,
    proj_seed=42,
    target_modules=["q_proj", "v_proj"],
    unilora_dropout=0.0,
    init_weights=True,
    task_type="CAUSAL_LM",
)

peft_model = get_peft_model(model, config)
peft_model.print_healthcheck()

重要参数

r 控制低秩适配器的维度。较大的值会增加适配器的容量和内存使用量。

theta_d_length 控制共享的 UniLoRA 向量库的长度。这是由投影的适配器条目共享的主要可训练存储。

proj_seed 控制固定投影到 theta_d 的确定性索引生成。复用相同的种子和配置可使生成的适配器索引可复现。

target_modules 用于选择哪些模块接收 UniLoRA 适配器。可以使用模块后缀（例如 ["q_proj", "v_proj"]）、正则表达式字符串，或者在模型架构支持时使用 "all-linear"。

unilora_dropout 在训练期间于 UniLoRA 适配器层内部应用 dropout。

init_weights 控制 UniLoRA 参数的初始化。如果需要手动管理初始化，请将其设置为 False，以保留 theta_d 的随机初始化。

save_indices 控制 UniLoRA 检查点是否将生成的索引和缩放张量与共享的 theta_d 参数一起保存。保持此选项禁用可生成更小的检查点，并从 proj_seed 重新生成索引；启用它则使保存的适配器独立于未来的索引生成变更。

基准测试概览

API

UniLoraConfig

类 peft.UniLoraConfig

< source >

( task_type: Optional[Union[str, TaskType]] = Nonepeft_type: Optional[Union[str, PeftType]] = Noneauto_mapping: Optional[dict] = Nonepeft_version: Optional[str] = Nonebase_model_name_or_path: Optional[str] = Nonerevision: Optional[str] = Noneinference_mode: bool = Falser: int = 4proj_seed: int = 42theta_d_length: int = 256target_modules: list[str] | str | None = Noneunilora_dropout: float = 0.0fan_in_fan_out: bool = Falsebias: str = 'none'modules_to_save: list[str] | None = Noneinit_theta_d_bound: float = 0.02init_weights: bool = Truesave_indices: bool = Falselayers_to_transform: list[int] | int | None = Nonelayers_pattern: list[str] | str | None = None )

参数

r (int) — 低秩适配的秩。它控制 UniLora 更新的表达能力。
proj_seed (int) — 用于生成固定索引分配的随机种子。这确保了跨运行的可复现性。
theta_d_length (int) — 共享 UniLora 向量 theta_d 的长度。
target_modules (Union[list[str], str], 可选) — 应用 UniLora 适配器的模块名称或模式。
- 如果提供的是字符串，则将其视为正则表达式。
- 如果提供了列表，模块将按精确名称或后缀进行匹配。
- 特殊值 ‘all-linear’ 会将 UniLora 应用于除输出层之外的所有 Linear / Conv1D 层。如果未指定，模块将根据模型架构进行推断。如果架构不受支持，则会引发错误。
unilora_dropout (float) — 应用于 UniLora 层内的 Dropout 概率。
fan_in_fan_out (bool) — 被替换的层是否以 (fan_in, fan_out) 格式存储权重。对于使用 Conv1D 层的模型（例如 GPT-2），应将其设置为 True。
bias (str) — 指定哪些偏置项是可训练的：
- ‘none’：不更新任何偏置参数
- ‘all’：更新所有偏差参数
- ‘unilora_only’：仅更新 UniLora 层内的偏置注意：启用偏置更新后，即使适配器处于禁用状态，模型的输出也会发生变化。
modules_to_save (list[str], 可选) — 除 UniLora 层之外，需要保持可训练状态并在最终检查点中保存的额外模块。这通常用于分类器等特定任务头。
init_theta_d_bound (float) — UniLora 向量库的初始化边界。向量从 [-init_theta_d_bound, init_theta_d_bound] 区间内均匀采样。为避免梯度消失，不建议使用零初始化。推荐较小的值（例如 0.02）以实现稳定训练。
init_weights (bool) — 是否使用默认的 UniLora 初始化来初始化 theta_d。如果设置为 False，theta_d 将保持随机初始化。
save_indices (bool) — 是否将生成的 UniLora 索引和缩放缓冲区与 theta_d 一起保存。这会增加检查点的大小，但可使保存的适配器独立于索引生成例程的后续更改。
layers_to_transform (Union[list[int], int], 可选) — 应用 UniLora 的 transformer 层索引。如果指定，则仅修改这些层。此选项仅在 target_modules 为列表时有效。
layers_pattern (Union[list[str], str]，可选) — 当模型不遵循标准层命名约定时，与 layers_to_transform 一起使用的自定义层名称模式。仅当 target_modules 为列表时，此选项才有效。

UniLora 适配器的配置类。

此类定义了初始化并在 PEFT 框架中应用 UniLora 层所需的所有超参数。该配置刻意保持精简，仅包含当前 UniLora 实现中实际使用的参数。

Reference: Uni-LoRA: One Vector Is All You Need https://arxiv.org/abs/2506.00799

UniLoraModel

类 peft.UniLoraModel

< source >

( modelconfigadapter_namelow_cpu_mem_usage: bool = Falsestate_dict: dict[str, torch.Tensor] | None = None )

在预训练模型周围创建一个 UniLora 适配器。

generate_index

< source >

( lora_param_count: inttheta_d_length: intproj_seed: int )

为展平的 UniLora 参数空间分配确定性的 theta_d 索引。

普通的 np.random.choice(np.arange(theta_d_length), size=lora_param_count) 会独立地采样每个位置，这可能导致在较小的适配器中，部分 theta_d 条目未被使用。UniLora 则采用一种均衡的确定性分配方式：每个索引出现的次数为 floor(D / d) 或 ceil(D / d)，其中 D 是展平后的 LoRA 参数数量，d 是 theta_d_length。这种方式在保持每个索引归一化稳定的同时，仍可通过 proj_seed 对分配进行随机打乱。

Update on GitHub