PEFT 中的 RoAd2D 旋转适配从原理到微调、量化与混合批次推理的完整实践指南【免费下载链接】peft PEFT: State-of-the-art Parameter-Efficient Fine-Tuning.项目地址: https://gitcode.com/gh_mirrors/pe/peftRoAd2D Rotary Adaptation是 PEFT 提供的一种参数高效微调方法它通过学习一组作用于隐藏维度对的 2×2 旋转矩阵及可选缩放因子来适配大语言模型以不足 0.1% 的可训练参数取得与 LoRA 等主流方法相当甚至更优的效果。本文以 docs/source/package_reference/road.md 为骨架结合 road 调谐器源码 与 road_finetuning 示例完整讲解 RoAd 的数学原理、RoadConfig 全部配置参数、微调训练流程、bitsandbytes 量化支持以及同批次多适配器混合推理的实现细节帮助你在实际项目中直接落地 RoAd。RoAd 是什么用稀疏 2D 旋转代替低秩更新RoAd 的核心思想非常简洁把隐藏向量切分成许多 2 维向量然后用各自独立的 2×2 旋转矩阵去旋转每一个 2 维向量为了获得额外灵活性每个旋转矩阵还会乘上一个可训练的缩放因子 α。从 layer.py 的 RoadLayer 文档字符串可以看到对向量R x的变换可展开为两个逐元素公式y₀ x₀ * α * cosθ - xₙ * α * sinθyₙ x₀ * α * sinθ xₙ * α * cosθ其中缩放因子 α 与角度 θ 为每个元素对分别学习且当使用 road_2、road_4 变体时旋转矩阵中的 4 个分量还可以各不相同详见下文「变体」一节。与 LoRA 的批量低秩更新相比RoAd 的稀疏旋转可以改写为简单的逐元素element-wise运算因此在前向传播与推理时不引入昂贵的批量矩阵乘法。这一特性带来两个直接收益极低的参数开销适配器只需要存储角度 θ 与缩放 α而不是完整的矩阵 R可训练参数占比低于 0.1%更高的服务吞吐当同一批次中同时处理异构请求即同时服务多个适配器时逐元素运算的开销远小于 LoRA 的批量低秩更新显著提升混合批次推理的吞吐。此外RoAd 还能无缝融入分布式交换干预distributed interchange intervention框架把稀疏的 2D 旋转理解为在隐藏表示学习子空间中的任务特定干预。这些正交子空间可以相互组合从而在不额外微调的情况下合并多种任务行为如多语言能力、指令跟随实现模块化、可解释的 LLM 适配。需要指出的是上述「不足 0.1% 参数、更高吞吐、可组合」等表述均来自 road.md 与 examples/road_finetuning/README.md 的官方描述具体效果以你自己的基准测试为准仓库的 method_comparison/MetaMathQA 基准目录中提供了 RoAd 在 MetaMathQA 任务上的实测结果 JSON 文件可供参考。使用约束与适用前提在动手之前先明确 RoAd 的边界条件来自 road.md 与源码学习率RoAd 微调通常需要比 LoRA 等方法更高的学习率建议设为1e-3 左右目标模块当前 RoAd仅支持线性层torch.nn.Linear从 model.py 的分发逻辑可以看到不支持的模块类型会直接抛出ValueError量化支持可用于 bitsandbytes 量化的模型4-bit 或 8-bit对应实现见 bnb.py 中的Linear8bitLt与Linear4bit混合批次推理不同 RoAd 适配器在同一批次内混合推理的能力与 LoRA 相同可参考 lora.md 中「Inference with different LoRA adapters in the same batch」一节源码实现位于 model.py 的_enable_peft_forward_hooks与 layer.py 的_mixed_batch_forward。RoadConfig核心配置参数详解RoadConfig 定义在 src/peft/tuners/road/config.py继承自PeftConfig。其关键参数如下参数默认值说明variantroad_1RoAd 变体可选road_1/road_2/road_4详见下文group_size64元素分组大小决定元素如何配成 2D 向量进行旋转init_weightsTrue是否执行 RoAd 权重的默认初始化target_modulesNone要替换为目标模块名的列表或正则字符串modules_to_saveNone除 RoAd 层外需要置为可训练并保存的模块列表在__post_init__中config.py配置会做三件事将peft_type固定为PeftType.ROAD若target_modules传入列表则转换为set校验合法性variant必须是road_1、road_2、road_4之一group_size必须为正且能被 2 整除否则抛出ValueError。variant三种参数规模档位variant直接决定每个层级的可训练参数量对应 config.py 与 layer.py 中的实现road_1所有元素对共享同一组缩放与角度。每个应用 RoAd 的层只存储数量等于输出隐藏维度的参数实际为out_features // 2配对被复用参数最少road_2每个元素使用独立的缩放与角度参数量为road_1的2 倍out_features个road_4每个元素使用两个不同的缩放与角度旋转矩阵两列分别学习参数量为road_1的4 倍out_features * 2个。三种变体对应的参数准备逻辑在 layer.py 的_prepare_cols中实现road_1通过repeat_interleave复用组内group_size // 2个参数road_2每个元素独立road_4把参数 reshape 为(-1, 2, group_size)前半段用于第一列alpha_1 * cosθ后半段用于第二列alpha_2 * sinθ。group_size分组配对与推理速度group_size定义元素如何分组为 2D 向量在每个组内元素 0 与元素group_size/2配对元素 1 与元素group_size/21配对依此类推。这种「前一半与后一半配对」而非相邻配对的方式是特意设计的——它不改变模型性能因为元素是无序的但对推理速度有影响在 VLLM 等场景下尤为明显。官方建议group_size 至少取 32推荐 64默认值以获得最佳速度硬性约束模型的隐藏维度使用张量并行时为每个分区的隐藏维度必须能被group_size整除。因此对于隐藏维度很小的模型你可能需要调小该参数。若out_features % group_size ! 0layer.py 会抛出ValueError。target_modules 与 modules_to_savetarget_modules传字符串时执行正则匹配传列表时做精确匹配或以列表元素为后缀的匹配传all-linear通配符时选择所有 linear/Conv1D 模块若模型是PreTrainedModel输出层会被排除若不指定则按模型架构自动选择RoAd 的目标模块映射TRANSFORMERS_MODELS_TO_ROAD_TARGET_MODULES_MAPPING由 LoRA 的映射复制而来见 constants.py。对于未知架构会抛出错误此时需手动指定target_modules。modules_to_save例如在 Sequence Classification 或 Token Classification 任务中随机初始化的classifier/score最终层需要被设为可训练并保存就通过该参数指定。权重初始化road.md 未展开初始化细节但从 layer.py 的reset_parameters可以看到init_weightsTrue默认road_theta用nn.init.zeros_置零、road_alpha用nn.init.ones_置为 1即初始为恒等旋转保证训练开始时与基础模型行为一致init_weightsFalseroad_theta用均值 0、标准差 0.5 的正态分布初始化road_alpha用均值 1、标准差 0.5 的正态分布初始化。config 的帮助文本特别提醒除非你完全清楚自己在做什么否则不要修改init_weights默认值。快速开始用 RoadConfig 微调因果语言模型最直接的入口是 examples/road_finetuning/README.md 提供的快速开始代码from peft import RoadConfig, get_peft_model from transformers import AutoModelForCausalLM, AutoTokenizer, Trainer from datasets import load_dataset model AutoModelForCausalLM.from_pretrained(huggyllama/llama-7b, device_mapauto) tokenizer AutoTokenizer.from_pretrained(huggyllama/llama-7b) dataset load_dataset(timdettmers/openassistant-guanaco, splittrain) road_config RoadConfig(variantroad_1) peft_model get_peft_model(model, road_config) trainer Trainer( modelpeft_model, train_datasetdataset, dataset_text_fieldtext, max_length2048, tokenizertokenizer, ) trainer.train() peft_model.save_pretrained(road-llama-3-8b)注意示例 README 中RoadConfig(variant1)属于示例中的写法而配置校验config.py要求变体必须严格等于road_1/road_2/road_4因此请使用variantroad_1这类完整取值。微调时请务必把学习率调高到1e-3 附近相对 LoRA 而言这是 road.md 明确给出的建议。完整训练脚本与命令行参数仓库在 examples/road_finetuning/road_finetuning.py 提供了开箱即用的完整训练脚本支持 Hugging Face Trainer、4-bit 量化与推送 Hub。核心配置段如下road_finetuning.pyfrom peft import RoadConfig, get_peft_model, prepare_model_for_kbit_training # RoAd config for the PEFT model road_config RoadConfig( variantvariant, # road_1 / road_2 / road_4 target_modules( road_target_modules.split(,) if road_target_modules else [q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj] ), ) # get the peft model with RoAd config model get_peft_model(model, road_config)脚本内部支持量化路径road_finetuning.py通过BitsAndBytesConfig(load_in_4bitTrue, ...)加载模型后调用prepare_model_for_kbit_training(model, use_gradient_checkpointingTrue)与 RoAd 无缝配合。运行方式examples/road_finetuning/README.md# 普通微调 python examples/road_finetuning/road_finetuning.py \ --base_model meta-llama/Meta-Llama-3-8B \ --data_path timdettmers/openassistant-guanaco # 4-bit 量化微调 python examples/road_finetuning/road_finetuning.py \ --base_model meta-llama/Meta-Llama-3-8B \ --quantize完整参数示例含学习率、变体与目标模块python road_finetuning.py \ --base_model PATH_TO_MODEL \ --data_path PATH_TO_DATASET \ --output_dir PATH_TO_OUTPUT_DIR \ --batch_size 1 \ --num_epochs 3 \ --learning_rate 1e-3 \ --cutoff_len 512 \ --val_set_size 500 \ --quantize \ --eval_step 10 \ --save_step 100 \ --device cuda:0 \ --variant road_1 \ --road_target_modules q_proj,k_proj,v_proj,o_proj \ --hub_model_id YOUR_HF_REPO \ --push_to_hub训练完成后可用save_pretrained保存适配器加载时与普通 PEFT 模型一致通过AutoModel.from_pretrained即可直接使用。推理与合并逐元素运算背后的数学RoAd 前向传播的逐元素实现位于 layer.py 的_apply_roadx_grouped x.reshape(-1, 2, group_size // 2) x1 x_grouped[:, 0, :] x2 x_grouped[:, 1, :] rotate_half_x torch.stack((-x2, x1), dim1).reshape(x.shape) result x * first_col rotate_half_x * second_col即先按组把向量切成前后两半并配对构造「旋转一半」(-x2, x1)与 RoPE 的 rotate_half 思路一致再与预计算的first_col、second_colα*cosθ与α*sinθ逐元素相乘累加——整个旋转过程不出现稠密矩阵乘法这正是 RoAd 高效推理的基础。如果需要把适配器合并进基础权重layer.py 给出了合并公式R (W x b) (R W) x R b左侧是未合并状态下的使用方式用高效的逐元素实现替代矩阵乘法右侧是合并后(R W)成为新权重、R b成为新偏置。具体合并实现见Linear.mergelayer.py它通过_get_delta_weight由角度与缩放重建分块对角旋转矩阵 R 并与权重做torch.matmulsafe_mergeTrue时会在副本上检查 NaN 再写入。合并后的unmerge则利用torch.linalg.inv求逆还原由于旋转矩阵未必正交因此用逆而非转置layer.py。对 bitsandbytes 量化模型合并逻辑在 bnb.py 中8-bit 合并Linear8bitLt.merge与 4-bit 合并Linear4bit.merge都会先将量化权重反量化、与 R 相乘后重新封装为bnb.nn.Int8Params/bnb.nn.Params4bit且官方在源码中提示对量化层合并/反合并可能因舍入误差导致生成结果与未合并时略有差异。同批次混合多适配器推理RoAd 与 LoRA 一样支持在同一个批次中为不同样本使用不同适配器。调用方式与 lora.md 中的「Inference with different LoRA adapters in the same batch」一致在模型 forward 时传入adapter_names列表长度与输入批次一致其中可用__base__表示不使用任何适配器。其底层实现路径是model.py 的_enable_peft_forward_hooks校验adapter_names中不存在的适配器名防止拼写错误并注入 forward 预钩子训练模式下传adapter_names会直接抛错layer.py 的_mixed_batch_forward先跑一次基础层前向再按adapter_names把批次切分为子批次对每个子批次分别应用对应适配器的_apply_road最后写回原位置。由于 RoAd 是逐元素运算这种「按样本分派」的开销远小于逐样本执行批量矩阵乘法这正是文档所述高吞吐的来源若存在已合并的适配器同时传入adapter_names会抛出错误layer.py需先调用unmerge_adapter。该能力在测试侧同样有覆盖tests/testing_common.py的_test_mixed_adapter_batches明确将RoadConfig与LoraConfig一并列为支持混合适配器批次的配置类tests/testing_common.py。配置与测试验证配置合法性tests/test_config.py 将RoadConfig纳入全量配置测试矩阵验证其默认值、__post_init__校验非法 variant、非偶数 group_size 抛错以及保存/加载往返一致性与框架集成RoadConfig在 auto.py 与 peft_types.py 中注册为PeftType.ROAD因此AutoPeftModel、get_peft_model等统一入口均可用目标模块映射复用 LoRA 的映射表constants.py意味着主流 Transformers 架构开箱即用。小结RoAd 是 PEFT 家族中「以最简几何操作换取极致参数效率」的代表方法2×2 旋转 缩放即可完成适配逐元素前向天然适配混合批次高吞吐服务稀疏旋转还可作为可组合、可解释的子空间干预。落地时记住三个要点学习率用 1e-3 量级、只作用于线性层、group_size需整除隐藏维度。需要深入时可继续阅读 road 调谐器源码config / layer / model / bnb 四个文件与 road_finetuning 示例并结合 method_comparison/MetaMathQA 的实测数据自行评估效果。【免费下载链接】peft PEFT: State-of-the-art Parameter-Efficient Fine-Tuning.项目地址: https://gitcode.com/gh_mirrors/pe/peft创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
