PEFT 中的 X-LoRA基于 LoRA 专家混合的动态门控微调完整指南【免费下载链接】peft PEFT: State-of-the-art Parameter-Efficient Fine-Tuning.项目地址: https://gitcode.com/gh_mirrors/pe/peftX-LoRAMixture of LoRA Experts是一种基于低秩适配LoRA的专家混合MoE式参数高效微调方法它通过一个高粒度token、layer、sequence 级别的 scalings 矩阵对一组冻结的 LoRA 适配器进行稀疏或稠密混合。本指南以 PEFT 仓库的 xlora.md 文档为核心结合 xlora 源码目录 与 test_xlora.py系统讲解 X-LoRA 的原理、双层前向机制、XLoraConfig 全部参数、构建与推理流程帮助你直接用get_peft_model为任意 transformers 模型挂载一组 LoRA 专家并动态调配它们的贡献。X-LoRA 是什么冻结 LoRA 专家 动态门控X-LoRA论文Mixture of LoRA ExpertsBuehler Buehler, APL Machine Learning, 2024是 PEFT 中的一种方法它基于一个高粒度token、layer、sequence的 scalings 矩阵实现对 LoRA 专家的稀疏或稠密混合。由于专家是冻结的 LoRA 适配器、底座模型也是冻结的需要微调的参数量被大幅压缩——实际只有 X-LoRA 门控分类器本身是可训练的。X-LoRA 的一个独特优势是通用性只要某个transformers底座模型上挂着 LoRA 适配器X-LoRA 就可以直接套用。尽管采用了专家混合策略完全不需要修改模型代码——PEFT 通过替换 LoRA 层的forward方法见下文源码分析在运行时注入 scalings模型架构代码保持原样。从源码结构看X-LoRA 在 PEFT 中作为一等公民注册src/peft/tuners/xlora/__init__.py通过register_peft_method(namexlora, config_clsXLoraConfig, model_clsXLoraModel)完成注册PeftType.XLORA定义于 peft_types.py并从包顶层导出XLoraConfig、XLoraModel见 src/peft/init.py。论文摘要的核心表述是从一组预训练的 LoRA 适配器出发门控策略利用 hidden states 动态混合各适配层使 X-LoRA 模型能够从未用过地组合深层逐层deep layer-wise能力来解决任务这种设计受生物学中通用性与多样性原则启发神经网络构建块在不同层级结构中被复用因此 X-LoRA 可以轻松应用于任何现有 LLM 而无需修改底层结构。原论文的应用聚焦于生物材料分析、蛋白质力学与设计、分子设计等科学场景但方法本身与领域无关。核心机制双层前向传播dual forward passX-LoRA 每个推理步骤都需要将底座模型运行两次这是理解其原理与算力成本的关键第一次前向scaling pass在不挂载任何 LoRA 适配器的情况下运行底座模型得到各 token 的 hidden states同时注入一组占位 scalings默认全为scaling_pass_value使后续替换过的 LoRA 层能正常执行。计算 scalings将第一步得到的 hidden states 喂给 X-LoRA 分类器分类器输出形状为(batch_size, seq_len, n_layers, n_classes)的 scalings 矩阵其中n_layers是LoRA 适配层的数量不是模型层数n_classes是专家LoRA 适配器数量。第二次前向real forward pass把计算出的 scalings 注入到各 LoRA 层重新运行模型。第二次运行的输出即为该步的最终结果。由于这套双层前向机制X-LoRA 能让模型反思自己的知识——每次生成都依据当前上下文动态重配架构不同 prompt 下每个 token 激活的适配器组合都会变化。源码中这一流程由 model.py 的_enable_peft_forward_hooks上下文管理器实现它注册一个模型的 pre-forward hookhook 内部先调用internal_xlora_classifier.make_dummy_scalings生成占位 scalings通过register_forward_pre_hook挂到每个LoraLayer上然后在torch.no_grad()与disable_adapter_layers()环境下执行 base model 前向拿到output_hidden_states接着调用self.internal_xlora_classifier(...)计算真实 scalings 并保存到internal_xlora_scalings最后再挂载一次真实 scalings 的 hook 并执行第二次前向。测试test_forward_hooks_are_cleaned_up专门验证了 generate 多次调用 forward 时 hook 不会累积泄漏详见 test_xlora.py。源码架构分类器、替换层与组装流程src/peft/tuners/xlora/目录包含 5 个文件职责划分清晰文件职责config.py定义XLoraConfig配置类model.py定义XLoraModel负责组装、加载专家、双层前向classifier.py定义XLoraClassifier与TemperatureScaledSoftmax门控网络layer.py定义XLoraLayer及线性/嵌入/卷积三种替换层init.py注册 PEFT 方法并导出公开 API门控网络 XLoraClassifierXLoraClassifierclassifier.py是一个小型 MLP输入为最后一层 hidden states输出每个 token 对每个 (层, 专家) 的 scalingsxlora_depth1默认时只有一个nn.Linear(config.hidden_size, n_classes)若layerwise_scalingsTrue则为hidden_size → n_classes * n_layers是一个线性门控xlora_depth 1时结构为Linear(hidden_size, xlora_size) → ReLU → Dropout → 若干Linear(xlora_size, xlora_size)隐藏层 → 最终 Linear若layerwise_scalingsFalse默认分类器只输出非逐层的 logits源码通过logits.unsqueeze(2)expand(-1, -1, n_layers, -1)将其广播复制到每一层enable_softmaxTrue时使用TemperatureScaledSoftmaxlogits / temperature后 softmax归一化 scalings。替换层 XLoraLayer 族convert_layers_to_xloramodel.py遍历 base model 的所有模块按精确类型匹配lora.Linear、lora.Embedding、lora.Conv2d分别包装为XLoraLinearLayer、XLoraEmbeddingLayer、XLoraConv2dLayer并直接替换module.forward为包装层的前向方法。包装层的核心逻辑layer.py若适配器被禁用adapters_disabled直接返回 base layer 结果用get_maybe_topk_scalings取出本层 scalingsscalings[:, :, layer_number, :]并按需执行 top-k 掩码与 top-k softmax对每个激活的适配器将输入x乘以对应专家维度上的 scalingsapply_scalings_to_x再走标准的 LoRA 路径lora_B(lora_A(dropout(x_mod))) * scaling * scaling_weight累加到 base 输出上。其中global_scaling_weight作为乘子统一放大/缩小每个 LoRA 专家的输出XLoraEmbeddingLayer还会额外处理带缩放因子的嵌入层如 Gemma3 的embed_scale有测试test_xlora_embed_scale_is_applied验证。组装流程 XLoraModelXLoraModel.__init__model.py依次完成用DUMMY_TARGET_MODULES创建一个空的LoraModel骨架检查use_cache必须为False否则抛ValueError遍历config.adapters字典调用_load_adapter_into_lora_model逐个自动加载LoRA 专家等价于PeftModel.from_pretrained的行为支持 hub 模型 id 或本地 checkpoint 路径set_adapter激活全部专家随后_maybe_freeze_all_adapters当use_trainable_adaptersFalse时把名字含.lora_的参数requires_gradFalse保证只有分类器可训练执行convert_layers_to_xlora替换 LoRA 层并构建XLoraClassifiern_classes len(adapters)。XLoraModel还实现了_mark_only_adapters_as_trainable空操作因为 X-LoRA 要求专家冻结、enable_adapter_layers/disable_adapter_layers切换disabled标志以及_get_adapter_state_dict只保存internal_xlora_classifier相关键即只序列化分类器权重。XLoraConfig 参数详解XLoraConfig继承自PeftConfigconfig.py全部参数如下表参数类型默认值说明hidden_sizeintNone缺失时警告并置为 4096底座模型的 hidden size必须与实际模型匹配adaptersdict[str, str]None缺失时置为空 dict适配器名字到 LoRA 模型 idhub id 或本地目录的映射构造时会自动加载这些 LoRA 作为专家from_pretrained加载时需通过关键字参数传入新的 adapters dictenable_softmaxboolTrue是否对 X-LoRA 分类器输出施加 softmaxenable_softmax_topkboolFalse是否对 top-k 选中的 LoRA 专家施加 softmax与enable_softmax互斥且必须同时设置top_k_lorasoftmax_temperaturefloat1.0softmax 温度越小预测越尖锐layerwise_scalingsboolFalse为 True 时为每个 LoRA 层每个专家分别生成 scalings为 False 时 scalings 广播复制到每一层top_k_loraintNone稀疏选择 top-k 个 LoRA 专家代替默认的稠密方法None表示稠密xlora_depthint1X-LoRA 分类器的深度xlora_sizeint2048X-LoRA 分类器的隐藏层大小xlora_depth1时无关xlora_dropout_pfloat0.2X-LoRA 分类器的 dropout 概率xlora_depth1时无关use_trainable_adaptersboolFalse是否让 LoRA 专家可训练默认冻结专家只训分类器scaling_pass_valuefloat0.0第一次前向scaling pass中占位 scalings 的填充值global_scaling_weightfloat1.0乘以每个 LoRA 专家输出的全局缩放权重__post_init__中还会做几项校验与告警hidden_size/adapters缺失时给出 warning 并填充默认值enable_softmax_topkTrue但未设置top_k_lora时告警enable_softmax_topk与enable_softmax同时开启时告警会导致更差的表现top_k_lora 1时告警。另外加载配置时adapters字段中的路径会被忽略只使用字典的 key配置重载后优先使用已保存的适配器这点在XLoraConfig的 docstring 中已明确说明。实战用 get_peft_model 构建 X-LoRA 模型以下是 model.py 文档字符串中的官方示例展示了最典型的用法——基于 Mistral-7B-Instruct 与 int8 量化底座构建 X-LoRAimport torch from transformers import AutoModelForCausalLM, AutoConfig, BitsAndBytesConfig from peft import XLoraConfig, get_peft_model, prepare_model_for_kbit_training model_config AutoConfig.from_pretrained(mistralai/Mistral-7B-Instruct-v0.1) config XLoraConfig( task_typeCAUSAL_LM, hidden_sizemodel_config.hidden_size, xlora_depth4, adapters{ adapter_1: ./path/to/the/checkpoint/, adapter_2: ./path/to/the/checkpoint/, adapter_n: ./path/to/the/checkpoint/, }, ) int8_config BitsAndBytesConfig(load_in_8bitTrue) model AutoModelForCausalLM.from_pretrained( mistralai/Mistral-7B-Instruct-v0.1, trust_remote_codeTrue, attn_implementationflash_attention_2, device_mapcuda:0, torch_dtypetorch.bfloat16, quantization_configint8_config, ) model prepare_model_for_kbit_training(model) xlora_model get_peft_model(model, config)要点解读专家来源adapters的值可以是 Hub 上的 LoRA 模型 id也可以是本地保存的 LoRA checkpoint 目录每个专家的LoraConfig如target_modules可以互不相同_load_adapter_into_lora_model会为每个专家独立读取并注入配置use_cache 必须关闭构造器会强制校验model.config.use_cache为False因此记得设置model.config.use_cache False测试 fixtures 中正是这样做的专家默认冻结use_trainable_adaptersFalse时只有internal_xlora_classifier.*参数可训练训练时用常规 Trainer 即可所有 LoRA 专家不更新。参考测试 test_xlora.py 的 fixture最小可用配置也可以简化为peft_config XLoraConfig( task_typeTaskType.CAUSAL_LM, peft_typePeftType.XLORA, hidden_sizebase_model.config.hidden_size, xlora_depth8, adaptersadapters, # {0: path/to/lora-0, 1: path/to/lora-1, ...} ) model get_peft_model(base_model, peft_config).to(device)推理与生成generate 与运行时注意事项XLoraModel.generatemodel.py在调用self.lora_model.generate前强制kwargs[use_cache] False因为门控需要每步重新计算 hidden states缓存与双层前向不兼容生成结束后会再次_maybe_freeze_all_adapters确保专家保持冻结。其它运行时行为均有测试覆盖见 test_xlora.pydisable_adapter上下文with model.disable_adapter():内禁用 X-LoRA 后模型输出应与纯底座模型完全一致test_disable_adapter_matches_base_model用torch.allclose(atol1e-5)验证包括嵌入层变体训练模式保持generate不会把模型悄悄切到 eval调用前后model.training不变test_generate_preserves_training_mode生成后仍可训练generate之后分类器参数仍保持requires_gradTrue、专家仍冻结test_classifier_stays_trainable_after_generateDoRA 限制X-LoRA 目前不支持 LoRADoRA 层遇到use_dora的专家会直接抛ValueError见 layer.py 的 TODO 注释。运行时调参与 scalings 调试 APIXLoraModel暴露了一组方法可在构造后动态调整门控行为或观察 scalings方法作用set_topk_lora(value)动态切换为 top-k 稀疏选专家传None恢复稠密set_global_scaling_weight(weight)设置全局专家输出缩放权重默认 1.0set_scaling_pass_value(value)设置 scaling pass 的占位值传None时自动用1/n_classesget_global_scaling_weight()读取当前全局缩放权重get_latest_scalings()返回最近一次预测的 scalings 张量形状(batch_size, seq_len, n_layers, n_classes)未预测时返回Noneenable_scalings_logging()/disable_scalings_logging()开启/关闭 scalings 日志关闭不清空已有日志clear_scalings_log()清空日志get_scalings_log()返回 scalings 日志列表的浅拷贝get_bucketed_scalings_log()按seq_len分桶返回日志值为位置列表 张量列表示例用法对应测试test_scalings_logging_methodsmodel.enable_scalings_logging() outputs model.generate(input_idsinputs.to(device), max_new_tokens32) latest model.get_latest_scalings() # (batch, seq, n_layers, n_classes) log model.get_scalings_log() # 每个生成步的 scalings 列表 bucketed model.get_bucketed_scalings_log() # 按 seq_len 分桶 model.disable_scalings_logging() model.clear_scalings_log()set_topk_lora与set_global_scaling_weight的修改会同步写回分类器的config即internal_xlora_classifier.config下次前向立即生效get_maybe_topk_scalings中 top-k 通过对该层 scalings 做torch.topk后掩码实现若同时开启enable_softmax_topk还会对非零部分做 per-token 归一化测试test_per_token_normalization_with_softmax_topk验证每 token 权重和恒为 1。需要注意enable_softmax_topk与enable_softmax不要同时开启否则会得到更差的门控结果。保存、加载与仓库内的进一步参考保存与加载XLoraModel的状态字典只包含internal_xlora_classifier相关键见_get_adapter_state_dict因此save_pretrained只保存门控分类器重新加载时通过PeftModel.from_pretrained(modelbase_model, model_idtmp_path)即可且加载时adapters字段的路径会被忽略、以已保存适配器为准。测试test_save_load_functional验证了保存-加载前后生成 logits 完全一致torch.equalsafe_serializationFalse的 PyTorch 权重路径也覆盖在test_save_load_functional_pt中测试tests/test_xlora.py 提供了完整的参考实现——用 4 个不同target_modules组合的 LoRA checkpoint 构造 X-LoRA 模型覆盖功能、逐层 scalingslayerwise_scalingsTrue、嵌入层专家、top-k、softmax-topk、scaling pass 值、禁用适配器、日志与分桶等全部行为推理示例examples/xlora/README.md 介绍了xlora_inference_mistralrs.py演示如何把保存的 X-LoRA/LoRA checkpoint 交给 mistral.rs 推理引擎该引擎原生支持 X-LoRA并采用 dual-KV cache、连续批处理、Paged Attention 等优化提升吞吐。引用若在你的工作或研究中使用了 X-LoRA请按仓库文档给出的 BibTeX 引用article{10.1063/5.0203126, author {Buehler, Eric L. and Buehler, Markus J.}, title {X-LoRA: Mixture of low-rank adapter experts, a flexible framework for large language models with applications in protein mechanics and molecular design}, journal {APL Machine Learning}, volume {2}, number {2}, pages {026119}, year {2024}, month {05}, doi {10.1063/5.0203126}, }小结X-LoRA 在 PEFT 中的实现遵循冻结专家 可训门控 双层前向的简洁范式XLoraConfig用一段字典声明专家集合与门控结构get_peft_model一行完成自动加载、层替换与分类器构建。理解其 scalings 矩阵的(batch, seq, n_layers, n_classes)语义、layerwise_scalings与top_k_lora等关键开关以及use_cacheFalse、DoRA 不支持等运行约束即可在任意 transformers 底座上组合现有 LoRA 资产获得随输入动态重配架构的专家混合模型。【免费下载链接】peft PEFT: State-of-the-art Parameter-Efficient Fine-Tuning.项目地址: https://gitcode.com/gh_mirrors/pe/peft创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 PEFT 中的 X-LoRA：基于 LoRA 专家混合的动态门控微调完整指南
PEFT 中的 X-LoRA基于 LoRA 专家混合的动态门控微调完整指南【免费下载链接】peft PEFT: State-of-the-art Parameter-Efficient Fine-Tuning.项目地址: https://gitcode.com/gh_mirrors/pe/peftX-LoRAMixture of LoRA Experts是一种基于低秩适配LoRA的专家混合MoE式参数高效微调方法它通过一个高粒度token、layer、sequence 级别的 scalings 矩阵对一组冻结的 LoRA 适配器进行稀疏或稠密混合。本指南以 PEFT 仓库的 xlora.md 文档为核心结合 xlora 源码目录 与 test_xlora.py系统讲解 X-LoRA 的原理、双层前向机制、XLoraConfig 全部参数、构建与推理流程帮助你直接用get_peft_model为任意 transformers 模型挂载一组 LoRA 专家并动态调配它们的贡献。X-LoRA 是什么冻结 LoRA 专家 动态门控X-LoRA论文Mixture of LoRA ExpertsBuehler Buehler, APL Machine Learning, 2024是 PEFT 中的一种方法它基于一个高粒度token、layer、sequence的 scalings 矩阵实现对 LoRA 专家的稀疏或稠密混合。由于专家是冻结的 LoRA 适配器、底座模型也是冻结的需要微调的参数量被大幅压缩——实际只有 X-LoRA 门控分类器本身是可训练的。X-LoRA 的一个独特优势是通用性只要某个transformers底座模型上挂着 LoRA 适配器X-LoRA 就可以直接套用。尽管采用了专家混合策略完全不需要修改模型代码——PEFT 通过替换 LoRA 层的forward方法见下文源码分析在运行时注入 scalings模型架构代码保持原样。从源码结构看X-LoRA 在 PEFT 中作为一等公民注册src/peft/tuners/xlora/__init__.py通过register_peft_method(namexlora, config_clsXLoraConfig, model_clsXLoraModel)完成注册PeftType.XLORA定义于 peft_types.py并从包顶层导出XLoraConfig、XLoraModel见 src/peft/init.py。论文摘要的核心表述是从一组预训练的 LoRA 适配器出发门控策略利用 hidden states 动态混合各适配层使 X-LoRA 模型能够从未用过地组合深层逐层deep layer-wise能力来解决任务这种设计受生物学中通用性与多样性原则启发神经网络构建块在不同层级结构中被复用因此 X-LoRA 可以轻松应用于任何现有 LLM 而无需修改底层结构。原论文的应用聚焦于生物材料分析、蛋白质力学与设计、分子设计等科学场景但方法本身与领域无关。核心机制双层前向传播dual forward passX-LoRA 每个推理步骤都需要将底座模型运行两次这是理解其原理与算力成本的关键第一次前向scaling pass在不挂载任何 LoRA 适配器的情况下运行底座模型得到各 token 的 hidden states同时注入一组占位 scalings默认全为scaling_pass_value使后续替换过的 LoRA 层能正常执行。计算 scalings将第一步得到的 hidden states 喂给 X-LoRA 分类器分类器输出形状为(batch_size, seq_len, n_layers, n_classes)的 scalings 矩阵其中n_layers是LoRA 适配层的数量不是模型层数n_classes是专家LoRA 适配器数量。第二次前向real forward pass把计算出的 scalings 注入到各 LoRA 层重新运行模型。第二次运行的输出即为该步的最终结果。由于这套双层前向机制X-LoRA 能让模型反思自己的知识——每次生成都依据当前上下文动态重配架构不同 prompt 下每个 token 激活的适配器组合都会变化。源码中这一流程由 model.py 的_enable_peft_forward_hooks上下文管理器实现它注册一个模型的 pre-forward hookhook 内部先调用internal_xlora_classifier.make_dummy_scalings生成占位 scalings通过register_forward_pre_hook挂到每个LoraLayer上然后在torch.no_grad()与disable_adapter_layers()环境下执行 base model 前向拿到output_hidden_states接着调用self.internal_xlora_classifier(...)计算真实 scalings 并保存到internal_xlora_scalings最后再挂载一次真实 scalings 的 hook 并执行第二次前向。测试test_forward_hooks_are_cleaned_up专门验证了 generate 多次调用 forward 时 hook 不会累积泄漏详见 test_xlora.py。源码架构分类器、替换层与组装流程src/peft/tuners/xlora/目录包含 5 个文件职责划分清晰文件职责config.py定义XLoraConfig配置类model.py定义XLoraModel负责组装、加载专家、双层前向classifier.py定义XLoraClassifier与TemperatureScaledSoftmax门控网络layer.py定义XLoraLayer及线性/嵌入/卷积三种替换层init.py注册 PEFT 方法并导出公开 API门控网络 XLoraClassifierXLoraClassifierclassifier.py是一个小型 MLP输入为最后一层 hidden states输出每个 token 对每个 (层, 专家) 的 scalingsxlora_depth1默认时只有一个nn.Linear(config.hidden_size, n_classes)若layerwise_scalingsTrue则为hidden_size → n_classes * n_layers是一个线性门控xlora_depth 1时结构为Linear(hidden_size, xlora_size) → ReLU → Dropout → 若干Linear(xlora_size, xlora_size)隐藏层 → 最终 Linear若layerwise_scalingsFalse默认分类器只输出非逐层的 logits源码通过logits.unsqueeze(2)expand(-1, -1, n_layers, -1)将其广播复制到每一层enable_softmaxTrue时使用TemperatureScaledSoftmaxlogits / temperature后 softmax归一化 scalings。替换层 XLoraLayer 族convert_layers_to_xloramodel.py遍历 base model 的所有模块按精确类型匹配lora.Linear、lora.Embedding、lora.Conv2d分别包装为XLoraLinearLayer、XLoraEmbeddingLayer、XLoraConv2dLayer并直接替换module.forward为包装层的前向方法。包装层的核心逻辑layer.py若适配器被禁用adapters_disabled直接返回 base layer 结果用get_maybe_topk_scalings取出本层 scalingsscalings[:, :, layer_number, :]并按需执行 top-k 掩码与 top-k softmax对每个激活的适配器将输入x乘以对应专家维度上的 scalingsapply_scalings_to_x再走标准的 LoRA 路径lora_B(lora_A(dropout(x_mod))) * scaling * scaling_weight累加到 base 输出上。其中global_scaling_weight作为乘子统一放大/缩小每个 LoRA 专家的输出XLoraEmbeddingLayer还会额外处理带缩放因子的嵌入层如 Gemma3 的embed_scale有测试test_xlora_embed_scale_is_applied验证。组装流程 XLoraModelXLoraModel.__init__model.py依次完成用DUMMY_TARGET_MODULES创建一个空的LoraModel骨架检查use_cache必须为False否则抛ValueError遍历config.adapters字典调用_load_adapter_into_lora_model逐个自动加载LoRA 专家等价于PeftModel.from_pretrained的行为支持 hub 模型 id 或本地 checkpoint 路径set_adapter激活全部专家随后_maybe_freeze_all_adapters当use_trainable_adaptersFalse时把名字含.lora_的参数requires_gradFalse保证只有分类器可训练执行convert_layers_to_xlora替换 LoRA 层并构建XLoraClassifiern_classes len(adapters)。XLoraModel还实现了_mark_only_adapters_as_trainable空操作因为 X-LoRA 要求专家冻结、enable_adapter_layers/disable_adapter_layers切换disabled标志以及_get_adapter_state_dict只保存internal_xlora_classifier相关键即只序列化分类器权重。XLoraConfig 参数详解XLoraConfig继承自PeftConfigconfig.py全部参数如下表参数类型默认值说明hidden_sizeintNone缺失时警告并置为 4096底座模型的 hidden size必须与实际模型匹配adaptersdict[str, str]None缺失时置为空 dict适配器名字到 LoRA 模型 idhub id 或本地目录的映射构造时会自动加载这些 LoRA 作为专家from_pretrained加载时需通过关键字参数传入新的 adapters dictenable_softmaxboolTrue是否对 X-LoRA 分类器输出施加 softmaxenable_softmax_topkboolFalse是否对 top-k 选中的 LoRA 专家施加 softmax与enable_softmax互斥且必须同时设置top_k_lorasoftmax_temperaturefloat1.0softmax 温度越小预测越尖锐layerwise_scalingsboolFalse为 True 时为每个 LoRA 层每个专家分别生成 scalings为 False 时 scalings 广播复制到每一层top_k_loraintNone稀疏选择 top-k 个 LoRA 专家代替默认的稠密方法None表示稠密xlora_depthint1X-LoRA 分类器的深度xlora_sizeint2048X-LoRA 分类器的隐藏层大小xlora_depth1时无关xlora_dropout_pfloat0.2X-LoRA 分类器的 dropout 概率xlora_depth1时无关use_trainable_adaptersboolFalse是否让 LoRA 专家可训练默认冻结专家只训分类器scaling_pass_valuefloat0.0第一次前向scaling pass中占位 scalings 的填充值global_scaling_weightfloat1.0乘以每个 LoRA 专家输出的全局缩放权重__post_init__中还会做几项校验与告警hidden_size/adapters缺失时给出 warning 并填充默认值enable_softmax_topkTrue但未设置top_k_lora时告警enable_softmax_topk与enable_softmax同时开启时告警会导致更差的表现top_k_lora 1时告警。另外加载配置时adapters字段中的路径会被忽略只使用字典的 key配置重载后优先使用已保存的适配器这点在XLoraConfig的 docstring 中已明确说明。实战用 get_peft_model 构建 X-LoRA 模型以下是 model.py 文档字符串中的官方示例展示了最典型的用法——基于 Mistral-7B-Instruct 与 int8 量化底座构建 X-LoRAimport torch from transformers import AutoModelForCausalLM, AutoConfig, BitsAndBytesConfig from peft import XLoraConfig, get_peft_model, prepare_model_for_kbit_training model_config AutoConfig.from_pretrained(mistralai/Mistral-7B-Instruct-v0.1) config XLoraConfig( task_typeCAUSAL_LM, hidden_sizemodel_config.hidden_size, xlora_depth4, adapters{ adapter_1: ./path/to/the/checkpoint/, adapter_2: ./path/to/the/checkpoint/, adapter_n: ./path/to/the/checkpoint/, }, ) int8_config BitsAndBytesConfig(load_in_8bitTrue) model AutoModelForCausalLM.from_pretrained( mistralai/Mistral-7B-Instruct-v0.1, trust_remote_codeTrue, attn_implementationflash_attention_2, device_mapcuda:0, torch_dtypetorch.bfloat16, quantization_configint8_config, ) model prepare_model_for_kbit_training(model) xlora_model get_peft_model(model, config)要点解读专家来源adapters的值可以是 Hub 上的 LoRA 模型 id也可以是本地保存的 LoRA checkpoint 目录每个专家的LoraConfig如target_modules可以互不相同_load_adapter_into_lora_model会为每个专家独立读取并注入配置use_cache 必须关闭构造器会强制校验model.config.use_cache为False因此记得设置model.config.use_cache False测试 fixtures 中正是这样做的专家默认冻结use_trainable_adaptersFalse时只有internal_xlora_classifier.*参数可训练训练时用常规 Trainer 即可所有 LoRA 专家不更新。参考测试 test_xlora.py 的 fixture最小可用配置也可以简化为peft_config XLoraConfig( task_typeTaskType.CAUSAL_LM, peft_typePeftType.XLORA, hidden_sizebase_model.config.hidden_size, xlora_depth8, adaptersadapters, # {0: path/to/lora-0, 1: path/to/lora-1, ...} ) model get_peft_model(base_model, peft_config).to(device)推理与生成generate 与运行时注意事项XLoraModel.generatemodel.py在调用self.lora_model.generate前强制kwargs[use_cache] False因为门控需要每步重新计算 hidden states缓存与双层前向不兼容生成结束后会再次_maybe_freeze_all_adapters确保专家保持冻结。其它运行时行为均有测试覆盖见 test_xlora.pydisable_adapter上下文with model.disable_adapter():内禁用 X-LoRA 后模型输出应与纯底座模型完全一致test_disable_adapter_matches_base_model用torch.allclose(atol1e-5)验证包括嵌入层变体训练模式保持generate不会把模型悄悄切到 eval调用前后model.training不变test_generate_preserves_training_mode生成后仍可训练generate之后分类器参数仍保持requires_gradTrue、专家仍冻结test_classifier_stays_trainable_after_generateDoRA 限制X-LoRA 目前不支持 LoRADoRA 层遇到use_dora的专家会直接抛ValueError见 layer.py 的 TODO 注释。运行时调参与 scalings 调试 APIXLoraModel暴露了一组方法可在构造后动态调整门控行为或观察 scalings方法作用set_topk_lora(value)动态切换为 top-k 稀疏选专家传None恢复稠密set_global_scaling_weight(weight)设置全局专家输出缩放权重默认 1.0set_scaling_pass_value(value)设置 scaling pass 的占位值传None时自动用1/n_classesget_global_scaling_weight()读取当前全局缩放权重get_latest_scalings()返回最近一次预测的 scalings 张量形状(batch_size, seq_len, n_layers, n_classes)未预测时返回Noneenable_scalings_logging()/disable_scalings_logging()开启/关闭 scalings 日志关闭不清空已有日志clear_scalings_log()清空日志get_scalings_log()返回 scalings 日志列表的浅拷贝get_bucketed_scalings_log()按seq_len分桶返回日志值为位置列表 张量列表示例用法对应测试test_scalings_logging_methodsmodel.enable_scalings_logging() outputs model.generate(input_idsinputs.to(device), max_new_tokens32) latest model.get_latest_scalings() # (batch, seq, n_layers, n_classes) log model.get_scalings_log() # 每个生成步的 scalings 列表 bucketed model.get_bucketed_scalings_log() # 按 seq_len 分桶 model.disable_scalings_logging() model.clear_scalings_log()set_topk_lora与set_global_scaling_weight的修改会同步写回分类器的config即internal_xlora_classifier.config下次前向立即生效get_maybe_topk_scalings中 top-k 通过对该层 scalings 做torch.topk后掩码实现若同时开启enable_softmax_topk还会对非零部分做 per-token 归一化测试test_per_token_normalization_with_softmax_topk验证每 token 权重和恒为 1。需要注意enable_softmax_topk与enable_softmax不要同时开启否则会得到更差的门控结果。保存、加载与仓库内的进一步参考保存与加载XLoraModel的状态字典只包含internal_xlora_classifier相关键见_get_adapter_state_dict因此save_pretrained只保存门控分类器重新加载时通过PeftModel.from_pretrained(modelbase_model, model_idtmp_path)即可且加载时adapters字段的路径会被忽略、以已保存适配器为准。测试test_save_load_functional验证了保存-加载前后生成 logits 完全一致torch.equalsafe_serializationFalse的 PyTorch 权重路径也覆盖在test_save_load_functional_pt中测试tests/test_xlora.py 提供了完整的参考实现——用 4 个不同target_modules组合的 LoRA checkpoint 构造 X-LoRA 模型覆盖功能、逐层 scalingslayerwise_scalingsTrue、嵌入层专家、top-k、softmax-topk、scaling pass 值、禁用适配器、日志与分桶等全部行为推理示例examples/xlora/README.md 介绍了xlora_inference_mistralrs.py演示如何把保存的 X-LoRA/LoRA checkpoint 交给 mistral.rs 推理引擎该引擎原生支持 X-LoRA并采用 dual-KV cache、连续批处理、Paged Attention 等优化提升吞吐。引用若在你的工作或研究中使用了 X-LoRA请按仓库文档给出的 BibTeX 引用article{10.1063/5.0203126, author {Buehler, Eric L. and Buehler, Markus J.}, title {X-LoRA: Mixture of low-rank adapter experts, a flexible framework for large language models with applications in protein mechanics and molecular design}, journal {APL Machine Learning}, volume {2}, number {2}, pages {026119}, year {2024}, month {05}, doi {10.1063/5.0203126}, }小结X-LoRA 在 PEFT 中的实现遵循冻结专家 可训门控 双层前向的简洁范式XLoraConfig用一段字典声明专家集合与门控结构get_peft_model一行完成自动加载、层替换与分类器构建。理解其 scalings 矩阵的(batch, seq, n_layers, n_classes)语义、layerwise_scalings与top_k_lora等关键开关以及use_cacheFalse、DoRA 不支持等运行约束即可在任意 transformers 底座上组合现有 LoRA 资产获得随输入动态重配架构的专家混合模型。【免费下载链接】peft PEFT: State-of-the-art Parameter-Efficient Fine-Tuning.项目地址: https://gitcode.com/gh_mirrors/pe/peft创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考