PEFT FRoD 实战指南：基于 Transformers Trainer 的文本与图像分类微调

PEFT FRoD 实战指南基于 Transformers Trainer 的文本与图像分类微调【免费下载链接】peft PEFT: State-of-the-art Parameter-Efficient Fine-Tuning.项目地址: https://gitcode.com/gh_mirrors/pe/peftFRoDFull-Rank Efficient Fine-Tuning with Rotational Degrees全秩旋转自由度高效微调是 PEFT 库中一类以共享全秩基 稀疏可学习旋转自由度为核心的新型参数高效微调方法。本文以 examples/frod_finetuning/README.md 为骨架结合 FRoD 源码 与 单元测试完整讲解如何在 TransformersTrainer下用两个开箱即用的脚本完成文本分类BERT GLUE SST-2与图像分类CLIP ViT Stanford Cars微调并深入剖析FrodConfig每个配置项、三段式学习率设计以及投影张量共享与保存的底层机制。读完本文你将能独立复现这两个示例、按需调整FrodConfig参数并把 FRoD 迁移到自己的模型与数据集上。FRoD 是什么全秩更新与稀疏旋转的平衡FRoD 论文提出的核心思路是适配器更新不再被限制在低秩子空间中而是通过固定的投影张量 可训练系数来表达全秩更新。从 tuners/frod/layer.py 的实现可以清晰看到它的数学形式S S_sparse.to_dense() L torch.diag_embed(lambda_l) frod_weight U (S L) V.T其中V与U是由基础模型权重推导出的固定投影张量不可训练仅参与前向L是对角系数矩阵对应可训练参数frod_lambda_lS是稀疏旋转矩阵只保留非对角位置上按sparse_rate随机采样的一小部分可训练条目对应参数frod_lambda_s_values。由于对角系数覆盖了所有输出维度FRoD 在每个被适配的线性层内可以表达全秩更新同时训练参数量却很小——这正是在低秩更新过于受限时的一种替代方案。相比 LoRAFRoD 的代价是注入适配器时需要基于基础权重执行矩阵分解来构建投影张量因此初始化更慢、对模型层的支持面更窄目前仅支持nn.Linear与transformers.pytorch_utils.Conv1D。环境准备安装示例依赖两个示例脚本的外部依赖集中在 examples/frod_finetuning/requirements.txt 中peft transformers accelerate1.0.0 datasets numpy Pillow安装依赖后即可直接运行任一脚本pip install -r examples/frod_finetuning/requirements.txt python examples/frod_finetuning/frod_text_classification.py python examples/frod_finetuning/frod_image_classification.py两个脚本都只依赖标准组件datasets加载数据、TransformersTrainer训练、PEFTget_peft_model注入适配器没有额外框架要求。文本分类示例BERT GLUE SST-2frod_text_classification.py 在google-bert/bert-base-uncased上以nyu-mll/glue数据集的sst2配置做二分类微调。参数定义与默认值脚本通过HfArgumentParser同时解析自定义的FrodTextArguments与 Transformers 的FrodTextTrainingArguments核心参数如下参数默认值说明model_name_or_pathgoogle-bert/bert-base-uncased序列分类基础模型dataset_namenyu-mll/glue数据集名或本地数据集路径task_namesst2数据集配置名GLUE 子任务target_modules[query, value]替换为 FRoD 适配器的模块名sparse_rate0.02稀疏 FRoD 矩阵中参与训练的非对角条目占比frod_dropout0.0FRoD 适配器分支前应用的 dropout 概率frod_lambda_l_lr2e-2可训练对角系数frod_lambda_l的学习率frod_lambda_s_lr2e-3可训练稀疏系数frod_lambda_s_values的学习率classifier_lr1e-2分类头学习率runtime_offload_base_weightFalse激活的 FRoD 路径不需要基础权重时将其保持在 CPU 上训练参数中值得注意的默认设置learning_rate2e-2、per_device_train_batch_size32、num_train_epochs1、eval_strategyepoch、load_best_model_at_endTrue、metric_for_best_modelaccuracy。三段式学习率FRoD 示例的关键设计README 明确指出两个脚本都为FRoD 对角系数、FRoD 稀疏系数、分类头分别设置了独立学习率。代码通过自定义 AdamW 参数分组实现optimizer torch.optim.AdamW( [ { params: [p for n, p in model.named_parameters() if frod_lambda_l in n], lr: frod_args.frod_lambda_l_lr, }, { params: [p for n, p in model.named_parameters() if frod_lambda_s_values in n], lr: frod_args.frod_lambda_s_lr, }, {params: [p for n, p in model.named_parameters() if classifier in n], lr: frod_args.classifier_lr}, ] )分组依据来自 layer.py 中定义的两个可训练参数容器frod_lambda_l对角系数与frod_lambda_s_values稀疏 COO 值。在文本示例中对角系数学习率2e-2比稀疏系数2e-3高一个数量级分类头同样使用独立学习率。参数名匹配采用子串匹配frod_lambda_l in n注意frod_lambda_s_values不包含frod_lambda_l子串因此两组互不干扰。训练完成后将optimizers(optimizer, None)传入Trainer即完全接管优化器而不用 Transformers 默认调度器。FRoD 注入与训练流程peft_config FrodConfig( task_typeTaskType.SEQ_CLS, target_modulesfrod_args.target_modules, modules_to_save[classifier], frod_dropoutfrod_args.frod_dropout, sparse_ratefrod_args.sparse_rate, runtime_offload_base_weightfrod_args.runtime_offload_base_weight, ) model get_peft_model(model, peft_config) model.print_trainable_parameters()modules_to_save[classifier]表示分类头随机初始化、需要可训练并保存进最终 checkpointfrod_dropout0.0的设定是刻意的——在这些示例中稀疏旋转参数化本身就是主要正则化手段因此不再叠加 dropout。随后是标准的Trainer流程预处理tokenizer DataCollatorWithPadding、compute_metrics计算准确率、trainer.train()、trainer.evaluate()最后model.save_pretrained(training_args.output_dir)保存适配器。图像分类示例CLIP ViT Stanford Carsfrod_image_classification.py 在openai/clip-vit-base-patch32上微调tanganke/stanford_cars数据集的训练/测试 parquet 分片。数据加载的两种方式脚本用load_dataset(parquet, data_filesdata_files)加载数据。未指定data_dir时直接读取 Hub 上的 parquet 分片data_files { train: [ hf://datasets/tanganke/stanford_cars/data/train-00000-of-00002.parquet, hf://datasets/tanganke/stanford_cars/data/train-00001-of-00002.parquet, ], test: [ hf://datasets/tanganke/stanford_cars/data/test-00000-of-00002.parquet, hf://datasets/tanganke/stanford_cars/data/test-00001-of-00002.parquet, ], }指定本地data_dir时改用本地文件路径{data_dir}/data/train-*.parquet便于在无外网环境下使用数据集镜像。图像专用配置差异图像脚本与文本脚本的差异点target_modules覆盖注意力与 MLP 六类投影[q_proj, k_proj, v_proj, out_proj, fc1, fc2]sparse_rate0.01文本为 0.02三段学习率整体下调frod_lambda_l_lr5e-4、frod_lambda_s_lr5e-5、classifier_lr1e-4新增projection_prng_key3用于稀疏 FRoD 投影掩码COO 结构的随机种子训练参数使用lr_scheduler_typeconstant、remove_unused_columnsFalse因为with_transform需要保留原始图像列。标签信息从数据集的 label 特征中提取id2label/label2id映射并以num_labelslen(label_names)、ignore_mismatched_sizesTrue重建 CLIP 的分类头。FrodConfig无需task_type模型自带分类头但同样通过modules_to_save[classifier]保留分类头可训练。图像预处理通过dataset.with_transform(transform)完成批量转 RGB、经AutoImageProcessor得到pixel_values并辅以自定义collate_fn堆叠张量。FrodConfig 配置项全解FrodConfig定义在 tuners/frod/config.py继承自PeftConfig。除上文已述参数外其余配置项如下参数默认值说明projection_prng_key0初始化稀疏 FRoD COO 结构非对角位置采样时使用的随机种子save_projectionTrue是否把 FRoD 投影张量保存进 state dict。True增大 checkpoint 体积但保证加载不依赖投影再生细节False减小体积加载时由基础权重 projection_prng_key重建投影fan_in_fan_outFalse若被替换层以(fan_in, fan_out)存储权重如 GPT-2 的Conv1D需设为True。源码 model.py 会根据目标层类型自动纠正该设置并给出警告biasnone可选none/all/frod_only。设为非none时对应偏置会参与训练注意此时即使停用适配器模型输出也不再与基础模型完全一致init_weightsTrue是否用默认初始化初始化 FRoD 层。False时稀疏系数以std0.1的正态分布初始化、对角系数叠加0.1尺度噪声见 layer.py仅在明确知道后果时修改layers_to_transformNone只变换指定索引的层传整数则只变换该层layers_patternNone配合layers_to_transform指定模型nn.ModuleList的名称常见为layers或h。源码会校验指定了layers_pattern而未指定layers_to_transform时直接抛错regularization_alpha1e-3从基础权重构建共享基时加入的小正数用于稳定同类相关层的矩阵求逆ridge 项progressbarTrue构建 FRoD 投影时是否显示进度条。投影初始化需要对每个目标模块类别执行矩阵分解大模型上较慢可设False关闭此外sparse_rate必须位于[0, 1]区间否则__post_init__会抛出ValueError见 config.py。使用本地镜像断网环境的完整用法README 特别给出了图像模型/数据集使用本地镜像的 CLI 方式python examples/frod_finetuning/frod_image_classification.py \ --model_name_or_path /path/to/local/clip-vit-model \ --data_dir /path/to/local/stanford_cars \ --output_dir clip-vit-local-frod-stanford-cars文本脚本同样可以传--model_name_or_path指向本地模型、--dataset_name指向本地数据集路径。所有 CLI 参数均来自上述 dataclass 字段可按需覆盖任意默认值。原理深挖共享投影、稀疏旋转与 checkpoint 策略投影张量按类别共享FRoD 的V/U投影并非每个被替换层一份而是按模块类别共享同一 transformer 中承担相同角色的模块如所有 attention 的q_proj共享同一组投影缓冲。模型源码 model.py 中的_category_from_key负责从模块路径推断类别例如encoder.layer.0.attention.self.query归入self_queryvision_model.encoder.layers.0.self_attn.q_proj归入self_attn_q_proj而 BERT 的 attention 输出层attention.output.dense被归一化为attention_output以避免与 MLP 的output.dense冲突。投影构建流程_init_frod_projectionsmodel.py为收集所有目标模块权重 → 按层索引与类别分组 → 对每个类别调用_projection_from_weights做 QR/SVD 分解与特征分解得到共享基V→ 用projection_prng_key种子随机采样非对角 COO 位置生成frod_s_indices。类别的层数、维度信息会显示在 tqdm 进度条descFRoD hierarchical joint decomposition中。前向计算与内存优化FrodLayer.forward 的逻辑是FRoD 直接重建适配后的权重参与计算因此单个激活适配器且无随机 dropout 时基础层前向可以整体跳过skip_base_layer只走投影 稀疏矩阵乘路径。这也解释了runtime_offload_base_weightTrue的意义——当激活的 FRoD 路径不需要基础权重时把目标基础权重留在 CPU从而降低 GPU 显存占用。该特性是 opt-in默认False因为通常的 PEFT 约定是模型移动或前向之后所有基础参数都留在加速器上。源码 layer.py 中_offload_base_weight_to_cpu实现了显存的按需搬移且卸载unload时会确保基础权重回到适配器所在设备。save_projection 与多适配器约束当save_projectionFalse时checkpoint 只保存对角/稀疏系数投影张量在加载时根据基础权重与固定种子重新生成因此 checkpoint 体积更小但默认save_projectionTrue以换取加载过程与再生细节完全解耦。加载逻辑model.py会校验配置要求加载投影而 state dict 中没有投影时报错反之给出警告。此外多适配器场景下所有适配器的projection_prng_key必须一致、save_projection与runtime_offload_base_weight也必须统一见 model.py。可训练参数规模可训练参数只有两类对角系数frod_lambda_l长度等于输出维度与稀疏系数frod_lambda_s_values长度等于 COO 非零元数量由sparse_rate决定。model.print_trainable_parameters()会直接打印可训练参数量与占比用于确认稀疏率设定是否符合预期。测试验证与进一步探索仓库为 FRoD 提供了专门的测试文件 tests/test_frod.py覆盖了多适配器保存/加载含save_projectionFalse、共享投影缓冲、PRNG 种子一致性等关键行为tests/regression/test_state_dict.py 与 tests/test_custom_models.py 也包含 FRoD 相关回归用例。官方 API 文档见 docs/source/package_reference/frod.md其中包含更简短的 Quickstart 代码片段runtime_offload_base_weightTrue示例。FRoD 的模块映射表定义在 src/peft/utils/constants.py默认沿用 VeRA 的映射并为 ViT 补充了[query, value]可据此快速了解 FRoD 在各类 Transformers 模型上的默认目标模块。结语通过本文你已掌握 PEFT FRoD 的两套开箱即用示例文本与图像分类、FrodConfig全参数语义、三段式学习率设计动机以及共享投影/稀疏旋转的底层原理。下一步建议先跑通文本示例并观察print_trainable_parameters的输出再尝试调整sparse_rate观察精度与参数量权衡在显存受限时开启runtime_offload_base_weightTrue在部署时按需设置save_projection平衡 checkpoint 体积与加载可靠性。【免费下载链接】peft PEFT: State-of-the-art Parameter-Efficient Fine-Tuning.项目地址: https://gitcode.com/gh_mirrors/pe/peft创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考