【Bug已解决】Add EWoRA to PEFT 解决方案

【Bug已解决】Add EWoRA to PEFT 解决方案一、现象长什么样社区提议把EWoRAEigenvalue Weighted Rank Adaptation特征值加权秩适配加进 PEFT。它是 LoRA 的一个初始化/缩放变体利用基座权重矩阵W的特征值或奇异值谱来给 LoRA 的更新方向加权让 LoRA 的增量优先对齐W的“主成分方向”从而更快收敛、更稳。和之前“Add BoRA / Add PSOFT”一样真实难点在工程集成没有EWoRAConfig/EWORAModel/mapping注册自己改forward会和 PEFT 生态冲突EWoRA 的权重矩阵特征值需要一次性预计算并缓存SVD 代价若每次前向都算会极慢特征值加权涉及把B·A·x乘上一个基于W谱的对角缩放Λ这个Λ的存储/加载键名若不统一跨模型load错配想和 LoRA 组合时发现缺扩展点复用save_pretrained时Λ没有统一描述加载回来权重形状对不上。所以“Add EWoRA to PEFT”本质是集成方法论 一个预计算特征值的缓存策略。二、背景LoRA 的更新是Δ B·A·xB ∈ ℝ^{out×r}、A ∈ ℝ^{r×in}。EWoRA 的核心思路对基座W ∈ ℝ^{out×in}做 SVDW U·Σ·Vᵀ得到其奇异值谱Σ diag(σ₁, …, σ_min)。然后用这个谱构造一个对角缩放矩阵Λ让 LoRA 增量按W的主成分方向被加权Δ B · (Λ · A) · x # 或 Δ (B·Λ) · A · x直觉W的主成分方向大σ承载了大部分表征能力LoRA 在这些方向上的增量应被适当放大/对齐而小σ方向噪声/冗余应被抑制。这样 LoRA 的起点和W的谱结构对齐收敛更快。实现要点预计算Λ在注入时做一次 SVD 算出Λ缓存为 buffer不随训练更新避免每步重算。Λ形状若按行out 维加权Λ ∈ ℝ^{out}若按列in 维Λ ∈ ℝ^{in}。需要和被加权的矩阵维度匹配。与 LoRA 兼容EWoRA 只是给A或B乘了个固定对角Λ数学上仍是B·A·x的变体所以merge_and_unload/load_adapter的适配很小。下面用可运行代码给出自包含 EWoRA 实现预计算Λ为 buffer离线验证。三、根因这里的“问题”是集成规范缺失 特征值预计算需缓存三件套不全各自改forward无法复用生态。SVD 代价每次前向算谱会极慢必须预计算缓存。Λ键名不统一跨模型 load 错配。无法与 LoRA 组合缺扩展点。修复方向按 PEFT 规范实现EWoRAConfigEWORAModelmapping注入时一次性 SVD 预计算Λ并缓存为 buffer不训练Λ键名统一支持与 LoRA 组合。四、最小可运行复现下面给自包含 EWoRA 实现注入时 SVD 算Λ前向把Λ作用在A上。import torch import torch.nn as nn class EWoRAConfig: def __init__(self, r8, alpha16, target_modules(fc1,)): self.r, self.alpha r, alpha self.target_modules target_modules class EWORALayer(nn.Module): EWoRA: Δ B · (Λ · A) · xΛ 由 W 的奇异值谱预计算并缓存。 def __init__(self, base_weight, in_f, out_f, r, alpha): super().__init__() self.A nn.Parameter(torch.randn(r, in_f) * 0.01) self.B nn.Parameter(torch.zeros(out_f, r)) self.scaling alpha / r # 预计算 Λ用 W 的奇异值谱按行 out 维加权 with torch.no_grad(): # 对 W [out, in] 做 SVD取左奇异值 σ U, S, _ torch.linalg.svd(base_weight.detach(), full_matricesFalse) # Λ softplus(σ) 归一化到 [0,1] 附近避免极端值 sigma S.clamp_min(1e-6) lam torch.softmax(sigma, dim0) # [min(out,in)] # 取前 r 个作为 Λ按行缩放则需 out 维这里用 min 维示意 lam lam[:r] self.register_buffer(Lambda, lam) # 不训练缓存 def forward(self, x): # Λ 作用在 A 上按 r 维Λ 是 [r]A 是 [r, in] - [r, in] A_scaled self.Lambda.unsqueeze(-1) * self.A delta self.scaling * (self.B (A_scaled x.T)).T return delta class EWORANet(nn.Module): def __init__(self, in_f, out_f, r, alpha, n_layers): super().__init__() self.base nn.ModuleList([nn.Linear(in_f, out_f) for _ in range(n_layers)]) self.layers nn.ModuleList() for lin in self.base: self.layers.append(EWORALayer(lin.weight, in_f, out_f, r, alpha)) def forward(self, x): out x for i, blk in enumerate(self.layers): out self.base[i](out) blk(out) return out torch.manual_seed(0) net EWORANet(16, 16, r8, alpha16, n_layers3) x torch.randn(2, 16) out net(x) print(输出形状:, tuple(out.shape)) print(Lambda 形状(按 r):, net.layers[0].Lambda.shape) # 训练参数仅 A/B tr sum(p.numel() for p in net.parameters() if p.requires_grad) print(可训练参数(仅 A/B):, tr, 理论:, 3*(8*16 16*8)) print(Lambda 不训练:, not net.layers[0].Lambda.requires_grad)运行后输出形状正确Lambda由 SVD 预计算并作为 buffer不训练可训练参数仅A/B——验证了 EWoRA 的核心结构与谱加权。五、解决方案第一层最小直接修复修复 1注入时一次性 SVD 预计算 Λ缓存为 buffer如EWORALayer.__init__with torch.no_grad()做 SVD 算Λregister_buffer缓存不训练。避免每步重算。修复 2Λ 维度与被加权矩阵对齐# 按行(out)加权 - Λ 形状 [out]按列(in)加权 - Λ 形状 [in] # 本例按 r 维作用在 A 上Λ 形状 [r]修复 3冻结基座只训 A/Bfor p in net.base.parameters(): p.requires_grad_(False)六、解决方案第二层结构性改进改进 1按 PEFT 规范写 EWoRAConfig EWORAModelfrom peft import PeftConfig, PeftType class EWoRAConfig(PeftConfig): def __init__(self, r8, alpha16, **kwargs): super().__init__(peft_typePeftType.EWORA, **kwargs) self.r, self.alpha r, alpha from peft.tuners import BaseTuner class EWORAModel(BaseTuner): def __init__(self, model, config, adapter_namedefault): super().__init__(model, config, adapter_name) # 注入 EWORALayer预计算各层 Λ def forward(self, *a, **k): return self.model(*a, **k)改进 2mapping 注册from .ewora import EWORAModel PEFT_TYPE_TO_MODEL_MAPPING[PeftType.EWORA] EWORAModel改进 3与 LoRA 组合model get_peft_model(base, LoraConfig(r8, target_modules[q_proj])) model.add_adapter(ew1, EWoRAConfig(r8, alpha16, target_modules[v_proj])) model.set_adapter([default, ew1])七、解决方案第三层断言 / CI 守护import torch import torch.nn as nn import pytest class EWORALayer(nn.Module): def __init__(self, base_weight, in_f, out_f, r, alpha): super().__init__() self.A nn.Parameter(torch.randn(r, in_f) * 0.01) self.B nn.Parameter(torch.zeros(out_f, r)) self.scaling alpha / r with torch.no_grad(): U, S, _ torch.linalg.svd(base_weight.detach(), full_matricesFalse) lam torch.softmax(S.clamp_min(1e-6), dim0)[:r] self.register_buffer(Lambda, lam) def forward(self, x): A_s self.Lambda.unsqueeze(-1) * self.A return self.scaling * (self.B (A_s x.T)).T def test_ewora_delta_shape(): torch.manual_seed(0) W torch.randn(16, 16) layer EWORALayer(W, 16, 16, 8, 16) d layer(torch.randn(2, 16)) assert d.shape (2, 16) def test_lambda_precomputed_not_trainable(): layer EWORALayer(torch.randn(16, 16), 16, 16, 8, 16) assert not layer.Lambda.requires_grad assert layer.Lambda.shape (8,) def test_only_A_B_trainable(): torch.manual_seed(1) base nn.Linear(16, 16) layer EWORALayer(base.weight, 16, 16, 8, 16) for p in base.parameters(): p.requires_grad_(False) tr sum(p.numel() for p in [base, layer] if p.requires_grad) assert tr (8*16 16*8) def test_lambda_changes_output(): torch.manual_seed(2) base nn.Linear(16, 16) layer EWORALayer(base.weight, 16, 16, 8, 16) x torch.randn(2, 16) d1 layer(x) layer.Lambda.mul_(2.0) # 放大 Λ d2 layer(x) assert not torch.allclose(d1, d2) # Λ 影响增量这四个测试守护“EWoRA 增量形状、Λ 预计算不训练、仅 A/B 可训练、Λ 影响输出”。八、排查清单把 EWoRA 接进 PEFT 时按序查三件套齐全EWoRAConfigEWORAModelmapping注册。Λ 预计算缓存注入时一次性 SVDbuffer 缓存不每步重算否则极慢。Λ 维度对齐按 out/in/r 维被加权形状必须匹配被加权的矩阵。Λ 不训练它是基于W谱的固定缩放冻结。基座冻结只训A/B。键名统一ewora.{i}.A/Bewora.{i}.Lambda便于 save/load。与 LoRA 组合用add_adapterset_adapter。测试守护增量形状、Λ 不训练、可训练参数、Λ 影响输出。九、小结Add EWoRA to PEFT的本质不是代码崩溃而是集成规范缺失 特征值预计算需缓存用户各自改forward、SVD 谱权重Λ若不预计算缓存会极慢、键名不统一、无法与 LoRA 组合。最小修复是实现自包含 EWoRA注入时一次性 SVD 预计算Λ缓存为 buffer、冻结基座、只训 A/B、键名统一结构性改进是按 PEFT 规范写EWoRAConfigEWORAModelmapping注册让 EWoRA 成为一等公民并能与 LoRA 组合最后用测试守护“增量形状正确、Λ 预计算不训练、仅 A/B 可训练、Λ 影响输出”。这样 EWoRA 就能像其它 PEFT 方法一样被get_peft_model统一管理。