人工智能大模型微调LoRA【免费下载链接】peft PEFT: State-of-the-art Parameter-Efficient Fine-Tuning.项目地址https://gitcode.com/gh_mirrors/pe/peft点击查看免费下载X-LoRAMixture of LoRA Experts是 PEFT 库中一类多个 LoRA 专家混合的参数高效微调方法它以冻结的基础模型和一组冻结的 LoRA adapter 为专家池通过一个轻量分类器基于模型隐藏状态动态生成 token 级/层级的 scalings 权重矩阵来混合各专家输出。本指南以仓库中的 examples/xlora/README.md 为骨架先完整讲解使用 mistral.rs 推理引擎对 X-LoRA 模型做高性能推理的示例脚本再从 PEFT 源码层深入其配置参数、双重前向传播机制与运行时调控 API帮助读者既能直接跑通推理示例又能理解 X-LoRA 在 PEFT 内部的完整实现脉络。一、X-LoRA 方法速览混合 LoRA 专家X-LoRA 对应的论文为《X-LoRA: Mixture of low-rank adapter experts, a flexible framework for large language models with applications in protein mechanics and molecular design》官方方法文档 中概述如下其核心思想是采用基于深度、逐层、token 级deep layer-wise token-level的低秩适配LoRA混合专家策略。从一个预训练的 LoRA adapter 集合出发门控策略gating strategy利用模型隐藏状态动态混合各适配层使最终的 X-LoRA 模型能够调用不同专家能力、形成从未出现过的深层逐层组合来求解任务。从 PEFT 的视角看X-LoRA 有两个关键特性无需改动模型结构X-LoRA 可以应用到任何带有 LoRA adapter 的transformers基础模型上即使采用混合专家策略也不需要修改任何模型代码。双前向传播dual forward pass每一步推理需要基础模型运行两次——第一次在不带任何 LoRA 适配效果的情况下获取隐藏状态scaling pass随后隐藏状态被用来计算 scalingsscalings 被注入到各 LoRA adapter 上模型运行第二次第二次的输出才是本步模型结果。正因为这种先观察、再决策的机制X-LoRA 模型能够反思自身的知识并动态重构架构。在 PEFT 仓库中X-LoRA 的实现分布于 src/peft/tuners/xlora/config.py、model.py、classifier.py、layer.py由XLoraConfig与XLoraModel两个公开类组成详见 src/peft/tuners/xlora/init.py 中的导出与注册。二、核心示例用 mistral.rs 引擎对 X-LoRA 模型做推理仓库 examples/xlora/README.md 的核心内容是演示如何使用推理引擎 mistral.rs 对 X-LoRA 模型执行推理。与训练侧不同推理引擎需要在加载模型时就理解 X-LoRA 的结构基础模型 多个 LoRA 专家 ordering 文件并利用引擎级优化获得高吞吐。2.1 示例脚本位置与前置知识示例脚本位于 examples/xlora/xlora_inference_mistralrs.py。在阅读该脚本前需要了解两点mistral.rs 支持的基础模型远不止 Mistral 系列它可以从保存好的 LoRA checkpoint 直接加载模型具体支持范围可参考其文档中的 adapter model docs 与 models support matrix。ordering 文件order file是 X-LoRA 与 PEFT 兼容的关键PEFT 保存的 X-LoRA 模型带有一个 ordering 文件它记录了 LoRA 专家的排列顺序mistral.rs 加载时依据该文件把多个专家 adapter 与基础模型正确组装保证与 PEFT 训练的权重完全兼容Ordering file to ensure compatibility with PEFT。关于如何生成该文件同样参考 mistral.rs 的 adapter model docs。2.2 Runner 与 Which.XLora推理引擎的初始化脚本第一步是构建 mistral.rs 的Runner其which参数指定要加载的模型类型from mistralrs import ChatCompletionRequest, Runner, Which runner Runner( whichWhich.XLora( tok_model_idNone, # Automatically determine from ordering file model_id..., # Model ID of the base model (local path of HF model ID) xlora_model_id..., # X-LoRA Model ID of the base model (local path of HF model ID) order..., # Ordering file to ensure compatibility with PEFT tgt_non_granular_index3, # Only generate scalings for the first 3 decoding tokens, and then use the last generated one ) )各参数的含义如下参数必填说明tok_model_id否分词器tokenizer的模型 ID。传None时从 ordering 文件中自动确定。model_id是基础模型base model的 ID可以是本地路径也可以是 Hugging Face 模型 ID。xlora_model_id是X-LoRA 模型 ID即保存 X-LoRA 权重含 LoRA 专家与分类器的本地路径或 HF 模型 ID。order是ordering 文件路径用于保证与 PEFT 的兼容性见 2.1。tgt_non_granular_index否非粒度non-granularscalings 相关的优化参数设置为 3 表示只为解码的前 3 个 token 生成 scalings之后复用最后一个生成的 scalings从而显著减少计算量。原文档特别指出mistral.rs 的 X-LoRA 支持融合了多项引擎级技术dual-KV cache双 KV 缓存、continuous batching连续批处理、Paged Attention分页注意力以及可选的 non granular scalings非粒度缩放这些技术结合可实现大幅提升的吞吐量vastly improved throughput。tgt_non_granular_index参数正是非粒度 scalings这一优化在 API 层面的体现。2.3 发送推理请求初始化 runner 之后通过send_chat_completion_request发送聊天补全请求res runner.send_chat_completion_request( ChatCompletionRequest( modelmistral, messages[{role: user, content: Tell me a story about 2 low rank matrices.}], max_tokens256, presence_penalty1.0, top_p0.1, temperature0.5, ) ) print(res.choices[0].message.content) print(res.usage)请求参数说明model指定对话使用的模型名示例中为mistralmessages为 OpenAI 风格的消息列表max_tokens256限制生成的最大 token 数presence_penalty1.0提高话题多样性、抑制重复top_p0.1采用核采样且核很小使输出更聚焦于高概率 tokentemperature0.5降低采样随机性。返回结果中res.choices[0].message.content是生成的文本res.usage给出本次请求的 token 用量统计。2.4 安装与可运行示例原文档给出的配套资源包括安装按照 mistral.rs 的 Python 绑定mistralrs-pyo3README 进行安装即安装mistralrsPython 包及其依赖。可运行示例mistral.rs 仓库提供了xlora_zephyr.py这一可直接运行的 Python 示例使用 X-LoRA 版的 Zephyr 模型与本仓库脚本的用法一致可作为完整可复现的最小示例参考。Adapter 模型文档与 ordering 文件制作详细的 adapter 模型说明以及如何制作 ordering 文件参见 mistral.rs 的 adapter model docs即 2.1 节所述内容。三、PEFT 侧实现纵深XLoraConfig 与 XLoraModel 源码解读示例中的xlora_model_id指向的权重正是 PEFT 训练与保存的 X-LoRA 模型。为了让读者理解这份权重的结构与训练侧配置本节约从源码层面剖析 PEFT 的 X-LoRA 实现。3.1 XLoraConfigX-LoRA 的全部配置参数XLoraConfigsrc/peft/tuners/xlora/config.py继承自PeftConfig其字段与默认值、含义如下依据源码 docstring 与__post_init__逻辑字段类型 / 默认值说明hidden_sizeint必填基础模型的隐藏层大小。未提供时源码会打印警告并默认设为 4096使用前务必核对是否正确。adaptersdict必填映射{adapter 名称: LoRA adapter 的 model_id}与PeftModel.load_adapter的用法一致。这些 LoRA adapter 会被自动加载作为 LoRA 专家from_pretrained加载时需以关键字参数传入新的 adapters 字典。未提供时默认为空字典并打印警告。enable_softmaxbool默认True是否对 X-LoRA 分类器的输出应用 softmax。enable_softmax_topkbool默认False是否仅对 top-k 个 LoRA adapter 应用 softmax。与enable_softmax互斥同时开启会得到较差性能且仅当设置了top_k_lora时才应开启。softmax_temperaturefloat默认1.0softmax 温度越低则预测越尖锐对某些专家权重更集中。layerwise_scalingsbool默认False为True时为每个LoRA adapter 层生成独立的 scalings为False时 scalings 被广播为各层相同。top_k_loraint默认None稀疏地只选择 top-k 个 LoRA 专家替代默认的稠密dense混合方式。源码中若该值 1会打印警告。xlora_depthint默认1X-LoRA 分类器门控网络的深度层数必须严格为正。xlora_sizeint默认2048X-LoRA 分类器的隐藏层大小xlora_depth1时无关。xlora_dropout_pfloat默认0.2X-LoRA 分类器的 dropout 概率xlora_depth1时无关。use_trainable_adaptersbool默认False是否将 LoRA 专家设为可训练。默认False时专家全部冻结只有 X-LoRA 分类器是可训练部分_maybe_freeze_all_adapters会按参数名中是否含.lora_来冻结专家见 src/peft/tuners/xlora/model.py。scaling_pass_valuefloat默认0.0第一次前向scaling pass时注入的占位 scalings 值。global_scaling_weightfloat默认1.0乘以每个 LoRA adapter 输出的全局缩放系数。此外__post_init__中还会把peft_type设为PeftType.XLORA并执行若干参数合法性检查与警告例如enable_softmax_topk开启但top_k_lora未设置、两个 softmax 同时开启等。3.2 构建 X-LoRA 模型自动加载专家并替换 LoRA 层XLoraModelsrc/peft/tuners/xlora/model.py是 X-LoRA 的核心入口类。其构造流程可以概括为创建空的 LoRA 模型容器用一个target_modules为DUMMY_TARGET_MODULES的占位LoraConfig创建LoraModel作为专家容器base_lora_config还会强制biasnone、layer_replicationNone。逐个自动加载 LoRA 专家遍历config.adapters中的每一项通过_load_adapter_into_lora_model仿照PeftModel.from_pretrained的行为加载每个 LoRA checkpointadapter 内部编号为0,1, ...随后set_adapter激活全部专家并默认冻结全部专家参数除非use_trainable_adaptersTrue。层替换layer swappingconvert_layers_to_xlora遍历基础模型的所有模块凡是lora.Linear、lora.Embedding、lora.Conv2d类型用isinstance精确匹配避免把继承自nn.Embedding的其他类误判都会分别被包装为XLoraLinearLayer、XLoraEmbeddingLayer、XLoraConv2dLayer并把模块的forward替换为包装层的forward这些包装层定义在 src/peft/tuners/xlora/layer.py。该函数返回被替换的层总数与设备信息。构建分类器类别数n_classes len(adapters)以被替换层数为n_layers创建XLoraClassifier。状态初始化初始化internal_xlora_scalings None、disabled False并将整个模型置于eval()模式。值得注意的硬性约束基础模型的use_cache必须为False否则构造时直接抛出ValueError——这是因为双前向传播机制需要完整地拿到每步隐藏状态缓存会导致机制失效。3.3 双重前向传播scalings 的计算与注入X-LoRA 每次前向的关键逻辑位于_enable_peft_forward_hooks上下文管理器src/peft/tuners/xlora/model.py其执行顺序为注册前向预钩子在基础模型上注册一个_pre_forward预钩子同时为每一个LoraLayer模块注册scalings_injection_hook用于把 scalings 以scalings关键字注入 LoRA 层。Scaling pass第一次前向生成形状为(batch_size, seq_len, n_layers, n_classes)的占位 scalingsmake_dummy_scalings填充值为scaling_pass_value默认 0在torch.no_grad()下先disable_adapter_layers()然后以output_hidden_statesTrue、return_dictTrue运行基础模型得到不带 LoRA 贡献的隐藏状态结束后清理钩子并enable_adapter_layers()再根据配置重新冻结专家。计算真实 scalings把隐藏状态交给XLoraClassifier见 3.4预测出真正的 scalings并缓存到internal_xlora_scalings这就是get_latest_scalings()的数据来源。真实前向第二次前向重新为所有LoraLayer注册注入真实 scalings 的钩子执行基础模型前向得到本步最终输出。同时源码对钩子管理做了防泄漏处理由于generate会在钩子上下文中多次调用前向若钩子已存在则跳过注册避免钩子累积对应测试test_forward_hooks_are_cleaned_up该问题曾记录在 issue 1472。3.4 XLoraClassifier 与 scalings 的应用分类器src/peft/tuners/xlora/classifier.py接收模型的最后一层隐藏状态result.hidden_states[-1]经一个 MLP 输出 scalings logits当xlora_depth 1时直接是一个nn.Linear(hidden_size, n_classes * n_layers)layerwise_scalingsTrue或nn.Linear(hidden_size, n_classes)否则当深度大于 1 时堆叠Linear - ReLU - Dropout隐藏块再接最后的输出层当layerwise_scalingsFalse时logits 通过unsqueezeexpand广播到n_layers维最终reshape为(batch_size, seq_len, n_layers, n_classes)若enable_softmaxTrue则经TemperatureScaledSoftmaxlogits / temperature后 softmax得到最终 scalings。专家混合src/peft/tuners/xlora/layer.py在XLoraLinearLayer/XLoraEmbeddingLayer/XLoraConv2dLayer的forward中完成若 X-LoRA adapter 被禁用adapters_disabled直接返回基础层输出不加任何 LoRA 贡献否则先经get_maybe_topk_scalings取出本层layer_number的 scalings若设置了top_k_lora则用torch.topk掩码掉非 top-k 专家若设置enable_softmax_topk则对非零项做 softmax 归一化保证每个 token 的权重和约等于 1随后对每个活跃 adapter先对输入x按该 adapter 的 scalings 逐 token 缩放apply_scalings_to_x再走lora_B(lora_A(dropout(x_mod))) * scaling * global_scaling_weight累加到基础层输出上Embedding 层还会处理embed_scale如 Gemma3 的词嵌入缩放以保证 LoRA 贡献与基础层缩放一致对应测试test_xlora_embed_scale_is_applied。源码中还明确标注了限制X-LoRA 目前不支持 LoRADoRA 层遇到use_doraTrue的层会抛出ValueError。3.5 运行时调控 API 一览XLoraModel提供了一套运行时调控接口方便推理/训练时动态调整混合策略方法作用set_topk_lora(value)切换为稀疏 top-k 专家模式传None恢复稠密模式同步反映到 config。set_global_scaling_weight(weight)/get_global_scaling_weight()设置/读取全局 LoRA 输出缩放系数。set_scaling_pass_value(value)设置 scaling pass 的占位值传None时自动取1/nn 为专家数。get_latest_scalings()返回最近一次预测的 scalings形状(batch_size, seq_len, n_layers, n_classes)无预测时返回None。enable_scalings_logging()/disable_scalings_logging()/clear_scalings_log()开关/清空 scalings 日志记录。get_scalings_log()返回 scalings 日志的浅拷贝列表。get_bucketed_scalings_log()按seq_len分桶返回 scalings 日志含位置索引便于分析不同输入长度下的门控行为。enable_adapter_layers()/disable_adapter_layers()启用/禁用 X-LoRA 适配disable_adapter上下文内部使用。3.6 一个完整的训练侧构建示例从 src/peft/tuners/xlora/model.py 的 docstring 可以直接复用一个完整的 X-LoRA 构建流程含 int8 量化加载import 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)要点hidden_size应取自model_config.hidden_sizeadapters中每个值指向一个已经微调好的 LoRA checkpoint 目录模型加载后记得确认use_cache为False源码会强制校验。四、测试佐证X-LoRA 行为验证examples/xlora/README.md 关注推理而 PEFT 的测试套件tests/test_xlora.py系统性地验证了 X-LoRA 的正确性可作为实现事实的佐证功能测试test_functional/test_functional_layerwise/test_functional_embedding验证默认、layerwise_scalingsTrue、embedding 专家三种配置下generate输出均为有限值钩子清理test_forward_hooks_are_cleaned_up验证多次generate后 LoRA 层上的前向预钩子不会累积禁用语义test_disable_adapter_matches_base_model/test_disable_adapter_matches_base_model_embedding验证disable_adapter上下文内输出与纯基础模型逐元素一致atol/rtol1e-5从而保证禁用 X-LoRA 后完全退化为基础模型保存与加载test_save_load_functional/test_save_load_functional_pt验证 safetensors 与 pickle 两种序列化下 save/load 前后generate输出完全一致门控行为test_per_token_normalization_with_softmax_topk验证 top-k softmax 后每个 token 的 scalings 在专家维求和为 1test_scalings_storage与test_scalings_logging_methods验证get_latest_scalings、scalings 日志及按 seq_len 分桶的正确性训练态保持test_generate_preserves_training_mode、test_classifier_stays_trainable_after_generate、test_experts_stay_frozen_after_forward验证generate/前向不会破坏训练/冻结状态专家加载正确性test_xlora_loading_valid直接从 Hugging Face 加载两个 LoRA adapter比对lora_A权重与 checkpoint 中权重逐元素一致印证adapters 自动加载机制的可靠性。五、总结与实践建议围绕 examples/xlora/README.md 这篇示例文档本指南打通了 X-LoRA 的推理与原理两端推理端使用 mistral.rs 的Runner(whichWhich.XLora(...))即可加载 PEFT 训练好的 X-LoRA 模型关键参数包括model_id基础模型、xlora_model_idX-LoRA 权重、order与 PEFT 兼容的 ordering 文件并可借助tgt_non_granular_index与引擎自带的 dual-KV cache、continuous batching、Paged Attention 获得高吞吐完整可复现示例可参考脚本 examples/xlora/xlora_inference_mistralrs.py。训练与原理端PEFT 侧通过XLoraConfig专家表、门控网络结构、softmax/topk 策略等全部可配置与XLoraModel自动加载专家 → 层替换 → 双前向传播 → 分类器生成 scalings 并注入各 LoRA 层实现完整的 X-LoRA 生命周期官方 API 文档见 docs/source/package_reference/xlora.md。实践中有三点务必注意其一基础模型use_cache必须为False其二LoRADoRA 层目前不被 X-LoRA 支持其三enable_softmax与enable_softmax_topk不应同时开启。在这些前提下X-LoRA 允许以一套完全冻结的专家池 一个轻量可训练门控实现对任意 transformers 模型的动态、自适应混合推理。赞分享人工智能大模型微调LoRA【免费下载链接】peft PEFT: State-of-the-art Parameter-Efficient Fine-Tuning.项目地址https://gitcode.com/gh_mirrors/pe/peft点击查看免费下载相关推荐mistral.rs 服务器 Anthropic Messages API 实战指南从 anthropic_chat.py 示例到源码级原理mistral.rs 服务器 Anthropic Messages API 实战指南从 anthropic_chat.py 示例到源码级原理 本篇技术指南以推理引擎模型推理服务AI Agent多模态3步实现LLM推理加速trl中的PEFT与LoRA实践指南3步实现LLM推理加速trl中的PEFT与LoRA实践指南 在大型语言模型LLM应用中推理速度和内存占用是开发者面临的核心挑战。trl作为Hugging人工智能大模型强化学习RLHF预训练微调LoRA3 条命令用上开源 PDF 翻译工具 pdf2zh公式与双栏排版完整保留3 条命令用上开源 PDF 翻译工具 pdf2zh公式与双栏排版完整保留 开篇速览这是一个什么工具 PDFMathTranslate命令行工具名为AI 应用人工智能NLPOCR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考