PEFT 中 PSOFT 微调实战：主元子空间上的高效正交微调（PsoftConfig 详解与 LLaMA 训练示例）

PEFT 中 PSOFT 微调实战主元子空间上的高效正交微调PsoftConfig 详解与 LLaMA 训练示例【免费下载链接】peft PEFT: State-of-the-art Parameter-Efficient Fine-Tuning.项目地址: https://gitcode.com/gh_mirrors/pe/peft本文围绕 PEFT 仓库中 PSOFTPrincipal Subspace adaptation Orthogonal Fine-Tuning主元子空间正交微调的官方示例 examples/psoft_finetuning/README.md 展开讲清楚 PSOFT 的核心思想把 LoRA 的低秩结构与 OFT 的正交性约束结合、PsoftConfig全部关键参数的语义与默认值并给出从 125M 小模型快速上手到 LLaMA-3.2-3B 完整训练的复现路径。读完本文你可以直接复制仓库中的训练脚本完成一次 PSOFT 微调并理解底层 A/B 分解缓存、Cayley 参数化与 Cayley–Neumann 近似的实现细节。1. PSOFT 是什么介于 LoRA 与 OFT 之间的正交微调PSOFT 的目标是在保持 OFTOrthogonal Fine-Tuning核心原则——保留预训练权重列向量之间的几何关系——的同时在参数、计算与内存三个维度上取得均衡。与依赖稀疏化设计的 OFT 变体如 OFTv2、BOFT、GOFT不同PSOFT 从低秩主元子空间的视角出发把正交变换限制在预训练权重的 top-r 主元子空间内从而在 LoRA 与 OFT 之间架起桥梁。官方文档页 PSOFT 参考文档 还给出了它在 GLUE、VTAB-1K、GSM8K、MATH 及常识推理等基准上的有效性说明。具体做法是对权重矩阵做 SVD$W_{\text{pre}} U S V^\top$取 top-r 奇异分量构造主元子空间 $W_{\text{pri}} U_r S_r V_r^\top AB$于是$$W_{\text{pre}} AB W_{\text{res}}$$训练中冻结 $A$、$B$ 与残差 $W_{\text{res}}$只训练中间的 $R$以及可选的幅值向量 $\alpha$、$\beta$。文档页区分两种模式PSOFT-SO严格正交$W_{\text{ps-tuned}} A R B W_{\text{res}}$PSOFT-RO放松正交$W_{\text{ps-tuned}} A, \mathrm{diag}(\alpha), R, \mathrm{diag}(\beta), B W_{\text{res}}$两个低维可调向量在训练中逐步放松正交约束以提升任务适应性。为兼容 PEFT 框架加法式权重更新的约定实现层面采用等价形式$$W_{\text{ps-tuned}} W_{\text{pre}} A (R - I_r) B$$这一实现细节可以从源码直接验证layer.py 中Linear.get_delta_weight计算的就是B (R - I) A * scaling。仓库对 PSOFT 的适用边界有两条明确限制仅支持nn.Linear层、不支持量化层见 model.py 的dispatch_default与 layer.py 中对权重的 dtype 检查。2. 快速上手四行配置接入 PSOFT以下是最小可运行流程继承自 README 的 Quick Start 章节使用 TRL 的SFTTrainer在 IMDB 数据上训练import torch from peft import PsoftConfig, get_peft_model from transformers import AutoTokenizer, AutoModelForCausalLM from trl import SFTConfig, SFTTrainer from datasets import load_dataset model_name facebook/opt-125m model AutoModelForCausalLM.from_pretrained(model_name) tokenizer AutoTokenizer.from_pretrained(model_name) tokenizer.pad_token_id tokenizer.eos_token_id psoft_config PsoftConfig( r32, psoft_alpha32, ) peft_model get_peft_model(model, psoft_config) peft_model.print_trainable_parameters() dataset load_dataset(imdb, splittrain[:1%]) training_args SFTConfig(dataset_text_fieldtext, max_length128) trainer SFTTrainer( modelpeft_model, argstraining_args, train_datasetdataset, processing_classtokenizer, ) trainer.train() peft_model.save_pretrained(psoft-opt-125m)关键点说明PsoftConfig在 config.py 中定义__post_init__会把peft_type固定为PeftType.PSOFT并做一系列参数合法性校验r 0、初始化方式与 SVD 后端枚举、Cayley–Neumann 参数范围等默认r32、psoft_alpha32二者相等使缩放因子scaling psoft_alpha / r 1与文档缩放因子通常设为 r的最佳实践一致scaling的计算见 layer.py 的update_layer;只传r与psoft_alpha时其余参数走默认值ab_svd_initpsoft_init、psoft_svdfull、psoft_orthTrue、psoft_mag_a/bTrue即默认开启放松正交RO模式。完整参数与文档化配置示例PSOFT 参考文档 给出了带完整注释的配置写法覆盖了所有核心开关config PsoftConfig( r32, # 可训练矩阵 R 的维度 psoft_alpha32, # 缩放因子通常设为 r target_modules[q_proj, v_proj], # 目标注意力投影层 ab_svd_initpsoft_init, # 主元子空间初始化 psoft_svdfull, # SVD 方法 psoft_orthTrue, # 启用正交 RCayley 参数化 psoft_mag_aTrue, # 启用可调向量 alpha psoft_mag_bTrue, # 启用可调向量 beta use_cayley_neumannFalse, # 关闭 Cayley–Neumann 近似 num_cayley_neumann_terms5, # Neumann 级数项数 cayley_neumann_epsNone, # 数值稳定性阈值 )结合 config.py 的字段定义各参数语义与默认值如下参数默认值说明r32正交变换 R 的维度决定适配器容量建议 32–128简单任务或 64–256复杂任务psoft_alpha32缩放因子语义同 LoRA alphascaling psoft_alpha / rpsoft_dropout0.0作用在 A 路径上的 Dropoutab_svd_initpsoft_initpsoft_initA 行正交的非对称 SVD 初始化严格正交PSOFT 默认pissa_initA/B 对称分解标准 PiSSA 风格psoft_svdfullfull用torch.linalg.svdlowrank用torch.svd_lowrankpsoft_svd_lowrank_niter10仅psoft_svdlowrank时生效的幂迭代次数random_seed0仅psoft_svdlowrank时用于固定随机投影保证保存/加载后结果可复现psoft_orthTrueTrue 时 R 经 Cayley 参数化保持正交False 时 R 为自由矩阵psoft_mag_a/psoft_mag_bTrue / True在 R 的输入/输出侧各学一个对角缩放向量RO 模式的 α、βuse_cayley_neumannFalse用 Neumann 级数代替矩阵求逆提升大 rank 下的计算效率num_cayley_neumann_terms5仅use_cayley_neumannTrue时生效项数越多正交近似误差越小cayley_neumann_epsNone对生成矩阵 Q 的 Frobenius 范数上界设为 (0,1) 内的值如 0.9会在范数超限时对 Q 重缩放fan_in_fan_outFalse被替换层以 (fan_in, fan_out) 存储权重时置 Truelayers_to_transform/layers_patternNone限定作用层与字符串形式的target_modules正则互斥__post_init__中会直接抛错这些校验并非纸面约束tests/test_initialization.py 中有对应测试逐一验证例如psoft_svdfull却修改了psoft_svd_lowrank_niter会触发 UserWarninguse_cayley_neumannTrue时num_cayley_neumann_terms0或cayley_neumann_eps不在 (0,1) 会直接抛出 ValueError。3. 底层实现正交层如何构造 RA/B 如何初始化3.1 OrthLayer用 r(r-1)/2 个参数表示 r×r 正交矩阵可训练的核心是 layer.py 中的OrthLayer。当psoft_orthTrue时它并不直接存储完整的 r×r 矩阵而是只存一个上三角向量r*(r-1)//2个参数由_skew_symmetric还原为反对称矩阵 Q再经Cayley 变换$R (IQ)(I-Q)^{-1}$ 得到正交矩阵——这就是通过 Cayley 参数化保证 R 正交的来源权重置零即对应 $RI$初始时更新量为零训练从预训练模型无损出发。两种求 R 的路径精确路径use_cayley_neumannFalse调用torch.linalg.solve(I-Q, IQ, leftFalse)半精度下会自动升 fp32 求解Cayley–Neumann 近似路径use_cayley_neumannTrue用级数 $R \approx I 2(Q Q^2 \cdots Q^{t-1}) Q^t$ 代替求逆num_cayley_neumann_terms控制截断项数 tcayley_neumann_eps非 None 时会先把 $|Q|_F$ 投影到该上界以内改善数值稳定性源码注释说明该思路借鉴自 OFT v2 的 Cayley/Neumann 参数化。随后get_matrix按开关把vector_b按行缩放与vector_a按列缩放乘到 R 上即 RO 模式的 α/β。reset_parameters中正交模式权重清零非正交模式初始化为单位阵两个幅值向量一律初始化为 1初始恒等。3.2 A/B 缓存主元子空间分解与两种初始化update_layer会先检查r min(in_features, out_features)然后调用_build_psoft_ab_cache_buffers见 layer.py构建 A、B 缓存把基座权重转成 fp32 并取 (out, in) 布局若基座权重不是 float32/float16/bfloat16 会抛 TypeError这正是不支持量化层的落点按psoft_svd选择后端full用torch.linalg.svd取前 r 个奇异分量lowrank用torch.svd_lowrank并在torch.random.fork_rng内用random_seed播种保证随机投影确定性因为torch.svd_lowrank不接受 generator 参数且必须覆盖 SVD 实际运行的设备按ab_svd_init组装psoft_initA U_h[:r]行正交B V_r diag(Sr / scaling)把缩放吸进 Bpissa_init取sqrt(Sr_scaled)A diag(s)U_h、B V_rdiag(s)得到对称 A/B无严格正交约束的 PiSSA 风格。A、B 存入BufferDict缓存并冻结训练只更新psoft_R。前向传播Linear.forward的增量计算为xa x A.T→xr R(xa)→delta_y (xr - xa) B.T * scaling再与基座输出相加——这正是加法式形式 $W_{pre} A(R-I)B$ 的逐元素实现。3.3 合并与 LoRA 转换Linear.merge/unmerge基于get_delta_weight把 $\Delta W$ 加减回基座权重支持safe_merge合并后检测 NaN。此外supports_lora_conversion返回 True即 PSOFT 适配器可转换为 LoRA 形式使用。4. 完整训练LLaMA-3.2-3B 上的复现命令仓库提供了带完整参数解析的训练脚本 psoft_finetuning.py其ScriptArguments继承SFTConfig把上述 PSOFT 参数全部暴露为命令行参数并额外处理了数据侧逻辑数据集若没有text列可用--dataset_field [input, output]自动拼成### USER: ...\n### ASSISTANT: ...的 SFT 文本。脚本开头还有一道防御性检查只接受bf16/fp16/fp32三种精度从源头杜绝误加载量化模型。README 中给出的 LLaMA-3.2-3B 命令可直接复制运行python psoft_finetuning.py \ --base_model_name_or_path meta-llama/Llama-3.2-3B \ --output_dir ./outputs/psoft-llama3.2-3b-imdb \ --data_path imdb \ --dataset_split train[:1%] \ --max_length 128 \ --num_train_epochs 1 \ --per_device_train_batch_size 1 \ --gradient_accumulation_steps 8 \ --learning_rate 5e-4 \ --bits bf16 \ --r 128 \ --psoft_alpha 128 \ --target_modules q_proj v_proj要点r128与psoft_alpha128成对出现scaling1目标模块限定为q_proj、v_proj脚本默认值也是这两个bitsbf16指定 bf16 精度加载基座device_mapauto自动分片。训练结束后适配器与 tokenizer 会保存到output_dir/psoft_ft下。脚本中各 PSOFT 相关参数的默认值与 config.py 保持一致ab_svd_initpsoft_init、psoft_svdfull、psoft_orthTrue、psoft_mag_a/bTrue、use_cayley_neumannFalse、num_cayley_neumann_terms5psoft_svd_lowrank_niter默认为 None仅在用户显式设置通常配合--psoft_svd lowrank时才传入配置。5. 官方最佳实践与适用建议以下五条 Best Practices 完整继承自 README并结合源码给出对应落点秩的选择Rank Choice较小秩32–128适合简单任务较大秩64–256表达力更强但参数与计算开销同步上升。r直接决定 R 的规模OFT 参数个数为 $r(r-1)/2$也受r min(in, out)约束。缩放因子Scaling Factorpsoft_alpha通常设为 r使scaling psoft_alpha / r 1学习率Learning Rate使用常规学习率区间如1e-4到5e-3即可获得稳定训练LLaMA 示例用的5e-4落在此区间SVD 初始化SVD Initializationlowrank后端比full更省内存与算力更适合大模型。注意lowrank结果依赖随机投影仓库通过random_seed参数默认 0保证保存的适配器在重新加载后可复现输出Cayley–Neumann 近似秩较大时开启use_cayley_neumannTrue可显著提升计算效率免去 r×r 求逆小秩时收益有限Neumann 级数项数取 5默认值通常能在精度与效率间取得平衡。需要更强数值稳定性时可设置cayley_neumann_eps如 0.9。6. 验证、测试与基准结果仓库内有多处可交叉验证 PSOFT 行为的证据配置校验测试tests/test_initialization.py 覆盖了非法参数terms 非正、eps 越界、niter/eps 在不适用场景下的告警以及配置构造模型级测试tests/test_custom_models.py 中包含{target_modules: [lin0], r: 4, psoft_alpha: 4, psoft_svd: lowrank, psoft_svd_lowrank_niter: 10}与use_cayley_neumannTrue等多种 PSOFT 配置的组合测试方法对比基准仓库 method_comparison/MetaMathQA 目录下有 PSOFT 在 LLaMA-3.2-3B 上的实测记录如 psoft--llama-3.2-3B-default.json 与 psoft--llama-3.2-3B-fast.json后者对应fast变体可对照本文的低秩/Cayley–Neumann 效率选项架构映射从 constants.py 看TRANSFORMERS_MODELS_TO_PSOFT_TARGET_MODULES_MAPPING直接复用了 LoRA 的模型-目标模块映射因此未显式指定target_modules时PSOFT 会按已知架构自动选择目标层未知架构则报错要求手动指定。7. 引用信息如在使用 PSOFT 时引用该方法可参考 README 中的 BibTeX 信息inproceedings{wu2026efficient, title{Efficient Orthogonal Fine-Tuning with Principal Subspace Adaptation}, author{Wu, Fei and Hu, Jia and Min, Geyong and Wang, Shiqiang}, booktitle{The Fourteenth International Conference on Learning Representations}, year{2026} }小结PSOFT 用SVD 主元子空间 冻结 A/B 可训练小尺寸正交 R可选 α/β 放松的组合把 OFT 的正交语义保留与 LoRA 式的低参数量结合起来。实操上记住三件事即可默认配置r32, psoft_alpha32, psoft_orthTrue, mag_a/bTrue适合快速实验大模型把psoft_svd切到lowrank大 rank 时打开use_cayley_neumann。注意其仅支持nn.Linear且不支持量化基座这两条硬边界。【免费下载链接】peft PEFT: State-of-the-art Parameter-Efficient Fine-Tuning.项目地址: https://gitcode.com/gh_mirrors/pe/peft创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考