LoRA/QLoRA 微调超参数实践指南rank、alpha、学习率与完整 Unsloth 配置解析GitHub Trending agents24 项目【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents导读本文以 plugins/llm-finetuning 插件中lora-qlora-recipes技能的参考文档 hyperparameters.md 为核心骨架系统讲解 LoRA/QLoRA 有监督微调SFT的超参数设计原则rank 与 alpha 的推导关系、按方法区分的学习率、rsLoRA 启用阈值、有效 batch 与 packing 的交互以及一份可直接复用的 UnslothFastLanguageModel TRLSFTConfig完整配置。读完本文你将掌握一套内部自洽、有明确默认值和取值边界的最佳实践超参数表并能在当前仓库的llm-finetuning-training-engineer工作流中直接落地为可运行训练脚本。本文内容属于该仓库llm-finetuning插件技能体系的一部分finetuning-method-selection负责路由决策数据形态决定方法lora-qlora-recipes负责适配器adapter本身的配置dataset-curation负责数据侧llm-finetuning-training-engineer是配置的下游消费者。1. 核心原则alpha 从 rank 推导不要独立调参超参数表中贯穿始终的第一条规则是lora_alpha 2 * r每一行都成立——alpha 由 rank 推导绝不单独设置。这条约定在 SKILL.md 中被描述为 settled convention既定惯例其理论依据是 2025 年 NeurIPS 的 intruder dimensions入侵维度研究结论在 LoRA 适配器中存在一部分入侵维度会主导梯度更新按2r设置 alpha 能控制其对更新的影响。因此调参时只需要决定 rankalpha 自动等于2 * r。1.1 Rank 与 Alpha 按任务类型取值超参数表按任务类型给出了三档 rank 区间注意它不是单一全局默认值任务类型Rank (r)lora_alpha说明RL 适配器GRPO/RLVR1–322–64低端1–8常见于叠加在已具备能力的基础模型之上的适配器通用 SFT 默认16–3232–64在无特殊理由需要更高/更低时的起点大规模 SFT大而多样的指令集最高 ~256最高 ~512仅当数据集足够大且多样、能利用额外容量时才合理——在默认使用前先看下文 rsLoRA 说明三点补充解释RL 适配器用低 rankGRPO/RLVR 是在 SFT 之后的策略优化基础模型已具备任务能力适配器只需做行为微调。这与 grpo-rlvr-training/SKILL.md 中RL 是锐化已有能力、而非从零安装能力的原则一致——rank 低是因为要改的东西少。大规模 SFT是条件性选择rank 升到 ~256 只有在数据集规模与多样性足以支撑额外容量时才成立。更高 rank 并不自动更好——它提升记忆容量的速度和提升泛化容量的速度一样快。正确做法是从任务匹配的行出发只有当较低 rank 在留出集held-out eval上可测量地欠拟合时才向上移动一档而不是默认取最大。rank 与数据量错配是最常见的过拟合来源在 SKILL.md 的 Failure Modes 中明确指出为大规模 SFT最高 ~256选的 rank 用在没有规模支撑的小数据集上结果是记忆化而非泛化。rank 必须匹配数据规模而不是匹配最大可用数字。1.2 适配器参数量与 rank 的关系来自 memory-math 的旁证为什么 rank 在 1–256 范围内对显存几乎无感memory-math.md 给出了公式rank 为r的适配器在线性层上增加r × (in out)个参数A 矩阵是r×inB 矩阵是out×r。在常规 rank 下这只占基础模型参数量的零点几个百分点内存估算中可近似视为零——这解释了为什么 LoRA 的显存大头是冻结权重本身而不是适配器。2. 学习率按方法取值LoRA 约为全参微调的 10 倍第二个核心结论LoRA/QLoRA 学习率约为等价全参微调full-FT学习率的 10 倍。这是把全参微调配置移植到 LoRA 时最常见的一个错误配置——保留原学习率不变会导致适配器欠训练under-train。学习率按方法分为三档方法LR 范围适用场景QLoRA标准2e-4QLoRA SFT 的默认起点LoRA保守1e-4更大的基础模型、更高的 rank或 2e-4 下已出现不稳定性的运行LoRA非常保守5e-5续训continuing a run、细粒度行为调整或基础模型已接近目标行为官方文档的明确态度是这些是用于围绕其扫描sweep的起点不是固定常数——但务必从这里出发而不是原封不动移植全参微调的学习率。值得注意的是LoRA 保守档1e-4反而比 QLoRA 标准档2e-4更低原因是LoRA 适配器没有量化引入的噪声在更大模型或更高 rank 下直接用 2e-4 可能不稳定因此下调一档更稳妥。在 SKILL.md 中学习率与 alpha 一起被归纳为参考配方reference recipeLoRA Without RegretThinking Machines / Schulman2025-09的一部分该配方现在是 LoRA/QLoRA SFT 的既定惯例。3. rsLoRA可选且只在 r ≥ 32 时值得开启Rank-stabilized LoRArsLoRA把适配器更新缩放从alpha / r改为alpha / sqrt(r)。参考文档给出了明确的启用边界r ≥ 32 时开启才有意义低于该 rank标准缩放alpha / r已经足够稳定rsLoRA 不会带来有意义的改变。如果启用了上文大规模 SFT行rank 最高 ~256应开启 rsLoRA对于通用默认档16–32或 RL 档1–32保持关闭除非出现了特定的不稳定性。注意与 1.1 节的衔接通用默认档的 rank 是 32恰好落在阈值上。参考配置中use_rsloraFalse的注释明确写着 r32 threshold — leave disabled here unless instability is observedr32 处于阈值——除非观察到不稳定否则保持关闭。也就是说阈值本身不是达到即开而是达到后值得考虑仅在出现不稳定时开启。4. 有效 Batch 与 Packing 的交互这是参考文档中隐藏最深的一节包含三条相互独立的规则4.1 有效 batch 保持在 32 以下参考配方在 effective batch 32 的规模下完成验证超过 32 属于未测试的外推untested extrapolation不是免费的吞吐提升。计算公式effective_batch per_device_batch_size × gradient_accumulation_steps × num_devices关键陷阱多 GPU 或高梯度累积设置下即使单设备 batch 看起来很小乘积也可能轻松越过 32。必须计算乘积而不能只看单设备数值。这也是为什么下文工作配置中per_device_train_batch_size4×gradient_accumulation_steps4 16单设备——明确标注stays under 32。4.2 Packing 改变的是 batch 的 token 组成不只是样本数把多个短样本打包进一个序列改变的是有效 batch 的 token 组成而不仅仅是样本计数——一个 8 序列的打包 batch 并不等价于 8 个短样本的非打包 batch。因此先应用 chat template再进行打包apply the chat template before packing, not after。这条与 dataset-curation/SKILL.md 的规则完全一致打包后再模板化会把角色标记role markers放错位置、破坏轮次边界。在信任管线之前先抽查解码若干条打包序列spot-check a handful of decoded packed sequences。dataset-curation/SKILL.md 将这一要求升级为强制项正式跑全量前必须解码并人工检查 5–10 条打包序列确认样本边界、模板标记、loss mask 均正确——因为打包 bug 是静默的loss 曲线看起来正常几小时后才在 eval 质量上暴露。llm-finetuning-training-engineeragent 的方法章节同样要求把解码样本附到验证报告中。4.3 梯度检查点与 packing 是独立的两条杠杆梯度检查点use_gradient_checkpointingunsloth与 packing 各自独立地在计算与内存之间做权衡梯度检查点用重计算换内存相对无检查点约节省30% VRAM来自 SKILL.md 的 Unsloth 默认值说明Packing用更紧凑的序列利用减少 padding 浪费进而改变激活内存。两者同时开启是内存受限运行的常态而非冗余。在 memory-math.md 中梯度检查点的 ~30% 节省正是激活项activations估算时唯一直接应用的修正因子且 packing/序列长度对该项是比 batch 更直接的杠杆。5. 目标模块全线性层MLP 优先适配器挂载哪些模块属于超参数配置的一部分且与 rank/alpha/LR 同等重要。参考配方的结论是瞄准全部线性层all-linear而不只是注意力层target_modules [ q_proj, k_proj, v_proj, o_proj, # attention gate_proj, up_proj, down_proj, # MLP — matters most ]MLP 层gate_proj/up_proj/down_proj最重要——只挂注意力层是旧式且更弱的约定删减模块以省显存是被明确列为 Failure Mode 的伪优化MLP 上的适配器参数只占模型总参数的一小部分砍掉它们几乎不省显存却可测量地损害质量。显存紧张时正确顺序是切换到 QLoRA、降低 rank/batch/打包长度而不是裁剪目标模块。6. 完整工作配置UnslothFastLanguageModelSFTConfig以下是参考文档给出的完整、内部自洽的配置通用默认 rankr32、QLoRA、标准学习率。配置块的默认风格是 Unsloth 快速路径这是该插件默认假定的参考实现但每个 kwarg 都有对应的原生 TRL/PEFT 写法见第 7 节映射表。from unsloth import FastLanguageModel from trl import SFTConfig, SFTTrainer BASE_MODEL from model catalog # size class task decide this, not this file model, tokenizer FastLanguageModel.from_pretrained( model_nameBASE_MODEL, max_seq_length2048, dtypeNone, # auto-detect bf16/fp16 by hardware load_in_4bitTrue, # QLoRA path — set False for bf16 LoRA ) target_modules [ q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj, ] model FastLanguageModel.get_peft_model( model, r32, target_modulestarget_modules, lora_alpha64, # 2 * r lora_dropout0, biasnone, use_gradient_checkpointingunsloth, random_state3407, use_rsloraFalse, # r32 threshold — leave disabled here unless instability is observed ) import torch # Check hardware BF16 support before forcing it — see SKILL.md # Failure Modes. Training in fp16 on hardware without solid BF16 # support is a known source of loss spikes and silent divergence, # so this is a hard prerequisite, not a config style choice. if not torch.cuda.is_bf16_supported(): raise RuntimeError( This GPU does not support BF16 — do not fall back to fp16True as if it were equivalent; pick hardware with BF16 support instead (see SKILL.md Failure Modes). ) training_args SFTConfig( output_dir./outputs, max_length2048, dataset_text_fieldtext, per_device_train_batch_size4, gradient_accumulation_steps4, # effective batch 16 (single device) — stays under 32 learning_rate2e-4, # QLoRA standard bf16True, # gated above — never fp16, see SKILL.md Failure Modes optimadamw_8bit, num_train_epochs3, logging_steps10, seed3407, ) trainer SFTTrainer( modelmodel, processing_classtokenizer, # current TRL — not tokenizer train_datasettrain_dataset, argstraining_args, ) trainer.train()6.1 配置内部自洽性检查参考文档原话逻辑这份配置的每一处取值都不是孤立的它们互相印证取值依据出处r32→lora_alpha642x 规则alpha 2 * r第 1 节表load_in_4bitTrue→learning_rate2e-4QLoRA 标准学习率第 2 节表bf16True绝不 fp16硬件 BF16 支持是硬性前置条件下方 6.3有效 batch4 × 4 16低于 32 上限第 4.1 节修改其中任何一项——rank、量化方式或 batch 形状——都应触发对照上表重新检查其他项而不是孤立地编辑该值。6.2 Unsloth 默认值及其设计原因get_peft_model调用中的几个默认值在 SKILL.md 中有明确的设计理由lora_dropout0Unsloth 优化内核路径假设零 dropout设为非零值会失去融合内核的加速。注意这是内核路径的硬性假设不是传统意义上小 dropout 有益的调参项。biasnone偏置项在此 rank 区间只增加适配器参数质量收益可忽略。use_gradient_checkpointingunslothUnsloth 的检查点变体非 HF 原生检查点相对无检查点节省约 30% VRAM。optimadamw_8bit8-bit AdamW 在 LoRA/QLoRA 适配器规模下显著削减优化器状态内存质量影响可忽略。random_state3407固定固定 LoRA 初始化以保证跨运行可复现把它当作普通 seed 对待不是可调参数。同时SFTConfig(seed3407)负责训练器侧的 RNG——两者都要设置见第 7 节映射表。6.3 BF16 硬前置检查为什么不能降级到 fp16配置中torch.cuda.is_bf16_supported()检查是硬性前置条件而非配置风格选择在不具备可靠 BF16 支持的硬件上用 fp16 训练是 loss 尖峰loss spikes与静默发散silent divergence的已知来源。文档明确禁止把fp16True当作等价回退——正确做法是选择支持 BF16 的硬件而不是换 dtype 硬跑。SKILL.md 提供了对应的命令行检查python -c import torch; print(torch.cuda.is_bf16_supported())这条规则与llm-finetuning-training-engineeragent 的失败分类Failure Triage直接对应其发散Divergence排查清单的第一位就是fp16 vs. bf16——确认bf16True且硬件支持 BF16。7. 与原生 TRL/PEFT 的映射翻译而非重写Unsloth 是 PEFT 与 TRL 之上的快速内核封装不是替代 API——每个 Unsloth kwarg 都有原生 TRL/PEFT 等价物。完整的 unsloth-trl-mapping.md 是逃生舱escape hatch机制的基础当需要回退到原生 TRL 时用映射表做机械翻译即可超参数本身不变。Unsloth kwargTRL/PEFT 等价物说明FastLanguageModel.from_pretrained(model_name...)AutoModelForCausalLM.from_pretrained(...)AutoTokenizer.from_pretrained(...)Unsloth 把模型分词器加载与内核修补融合为一次调用load_in_4bitTrueBitsAndBytesConfig(load_in_4bitTrue, bnb_4bit_quant_typenf4, bnb_4bit_compute_dtypetorch.bfloat16)传入from_pretrained两侧都是 QLoRA 路径get_peft_model(r..., target_modules..., lora_alpha..., lora_dropout..., bias..., random_state...)peft.LoraConfig(...)peft.get_peft_model(model, config)random_state→ 调用前设置 seedUnsloth 是生成同一份LoraConfig的薄封装use_gradient_checkpointingunslothSFTConfig(gradient_checkpointingTrue)Unsloth 变体更快/更低内存原生gradient_checkpointingTrue是正确回退节省收益约少 30%optimadamw_8bitSFTConfig(optimadamw_8bit)完全相同的字符串无需翻译use_rsloraTrue/FalseLoraConfig(use_rsloraTrue/False)PEFT 中同名标志max_seq_length传from_pretrainedSFTConfig(max_length...)当前 TRL字段已从max_seq_length更名为max_lengthdataset_text_fieldSFTConfig(dataset_text_field...)与max_length一样位于SFTConfigrandom_state3407SFTConfig(seed3407)两者都设Unsloth 的random_state专管 LoRA 初始化SFTConfig.seed管训练器 RNG7.1 当前 TRL API 的两个易错点unsloth-trl-mapping.md 特别警告两个近期变更过的 API 面连一些 Unsloth cookbook 片段都还在用旧写法processing_class不是tokenizerSFTTrainer(tokenizertokenizer, ...)是已移除或弃用的旧形式当前 TRL 使用SFTTrainer(processing_classtokenizer, ...)。把旧配方向前移植时这是最常见的过时 API 错误——运行前必须更新。max_length与dataset_text_field都住在SFTConfig上不要把它们分散在 trainer 调用或模型加载器里在SFTConfig实例上一次性设置不在管线其他位置重复。8. 场景决策LoRA vs QLoRA vs 全参微调超参数取值正确的前提是方法选对。参考文档连同 SKILL.md给出的默认决策表场景默认选择在演示数据上适配行为LoRA基础模型在目标 rank 下放不进 bf16QLoRA注入密集的新领域知识全参微调见 finetuning-method-selection/SKILL.md不确定选哪个LoRA——仅当内存迫使时才升级到 QLoRAQLoRA NF4 量化冻结基础权重 BF16 适配器。它的内存优势来自量化的基础权重本身而不是适配器——这正是65B 级模型在 48GB 上可训的原因。全参微调不是默认只在需要从权重层面改变模型知识密集知识注入时使用本技能范围内的其余场景LoRA 或 QLoRA 是起点假设。DGX Spark 上的反直觉陷阱QLoRA 可能在等价 bf16 LoRA 运行之前就 OOM——因为 bitsandbytes 反量化缓冲是加载期间瞬时尖峰的 CUDA 侧分配。QLoRA OOM 不代表模型放不下下一步应尝试 bf16 LoRA而不是进一步压缩 QLoRA。这与dgx-spark-ops插件的spark-memory-thermal-ops技能中的 OOM 阶梯一致先刷新再减 batch/打包长度最后降级方法——bf16 LoRA 先于 QLoRA。方法选择还受数据形态约束finetuning-method-selection的路由树明确数据形态决定方法lora-qlora-recipes假设路由已经完成数据是演示数据/示范对不处理偏好对那是preference-optimization或可验证奖励信号那是grpo-rlvr-training。9. 与模型目录和内存预估的衔接hyperparameters.md特意声明本文件不指名任何基础模型——所有示例只按规模等级size class标注。选择具体模型请查 model-catalog.md该文件是整个插件含 dgx-spark-ops中唯一指名基础模型家族的地方并带有 last verified 日期与季度刷新清单。配置BASE_MODEL前的显存可行性评估则使用 memory-math.md 的四项工作表权重 优化器状态 梯度 激活。关键数据点bf16 权重 2 字节/参数int4 NF4QLoRA0.5 字节/参数——同一参数量的 4 倍差距LoRA/QLoRA 的优化器状态与梯度只针对可训练适配器参数计算因此这两项可忽略与基础模型规模无关8B 级 bf16 LoRA 权重约 16GB8B 级 QLoRA 约 4GB70B 级 QLoRA 真实世界锚点约40GB含 NF4 双重量化元数据与运行时开销而 bf16 单权重就约 140GB——这是70B 级只能走 QLoRA 而非 bf16的数学依据。10. 三大失败模式先查配置再调训练循环SKILL.md 将三种失败模式归纳为一个共同规律它们看起来像训练循环 bugloss 尖峰、平台期、记忆化实际却是违反参考配方的配置选择。遇到这类症状应先对照本技能检查配置再调试训练循环本身。非 BF16 GPU 上的 fp16 发散在不具备可靠 BF16 支持的硬件上用 fp16 训练是 loss 尖峰与静默发散不报错地变差的已知来源。对策硬件支持处强制bf16True不支持处更换硬件而非回退 fp16见 6.3 的运行时检查。小数据集上 rank 过高导致过拟合为大规模 SFT选的 rank最高 ~256用在没有规模支撑的数据上会记忆化。对策严格对照Rank 与 Alpha 按任务类型表匹配数据规模。为省显存删除目标模块代价是质量节省可忽略。适配器参数在 MLP 上只占模型总量的一小部分删掉几乎不省显存却可测量地伤质量。对策显存紧张时先降 rank/batch/打包长度或换 QLoRA。11. 在插件工作流中的位置从源码结构看hyperparameters.md处于一条明确的消费链上finetuning-method-selection完成路由 →lora-qlora-recipes产出验证过的适配器配置即 kwarg 值而非自由形式建议 → llm-finetuning-training-engineer.md 将其直接消费生成可运行的train/train.py与train/config.yaml。该 agent 的 Phase 4 要求两个文件在启动前先提交保证失败时仍可复现并在发散时按固定顺序排查先 bf16 vs fp16再学习率 vs 方法最后打包损坏。需要特别说明的例外组合对 messages 形状的对话式 SFT 且启用assistant_only_lossTrue时Unsloth 2026.7.x 的编译训练器没有 messages 形状路径原生 TRL PEFT 逃生舱是该组合的默认路径而非罕见回归回退。此时用第 7 节映射表翻译即可——超参数不变只是设置它们的库不同。结语LoRA/QLoRA 微调的超参数不是一堆孤立可调旋钮而是一套内部自洽的系统alpha 2r的推导规则、约 10 倍于全参微调的学习率、按任务类型的 rank 区间、32 以下的有效 batch、r ≥ 32 才启用的 rsLoRA以及 bf16 硬前置检查——任一取值变动都应触发对其他项的系统性复核。以 hyperparameters.md 为参考、SKILL.md 为原则、unsloth-trl-mapping.md 为翻译桥你可以直接产出可运行、可复现、可排查的 LoRA/QLoRA SFT 配置。【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 LoRA/QLoRA 微调超参数实践指南：rank、alpha、学习率与完整 Unsloth 配置解析（GitHub Trending agents24 项目）
LoRA/QLoRA 微调超参数实践指南rank、alpha、学习率与完整 Unsloth 配置解析GitHub Trending agents24 项目【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents导读本文以 plugins/llm-finetuning 插件中lora-qlora-recipes技能的参考文档 hyperparameters.md 为核心骨架系统讲解 LoRA/QLoRA 有监督微调SFT的超参数设计原则rank 与 alpha 的推导关系、按方法区分的学习率、rsLoRA 启用阈值、有效 batch 与 packing 的交互以及一份可直接复用的 UnslothFastLanguageModel TRLSFTConfig完整配置。读完本文你将掌握一套内部自洽、有明确默认值和取值边界的最佳实践超参数表并能在当前仓库的llm-finetuning-training-engineer工作流中直接落地为可运行训练脚本。本文内容属于该仓库llm-finetuning插件技能体系的一部分finetuning-method-selection负责路由决策数据形态决定方法lora-qlora-recipes负责适配器adapter本身的配置dataset-curation负责数据侧llm-finetuning-training-engineer是配置的下游消费者。1. 核心原则alpha 从 rank 推导不要独立调参超参数表中贯穿始终的第一条规则是lora_alpha 2 * r每一行都成立——alpha 由 rank 推导绝不单独设置。这条约定在 SKILL.md 中被描述为 settled convention既定惯例其理论依据是 2025 年 NeurIPS 的 intruder dimensions入侵维度研究结论在 LoRA 适配器中存在一部分入侵维度会主导梯度更新按2r设置 alpha 能控制其对更新的影响。因此调参时只需要决定 rankalpha 自动等于2 * r。1.1 Rank 与 Alpha 按任务类型取值超参数表按任务类型给出了三档 rank 区间注意它不是单一全局默认值任务类型Rank (r)lora_alpha说明RL 适配器GRPO/RLVR1–322–64低端1–8常见于叠加在已具备能力的基础模型之上的适配器通用 SFT 默认16–3232–64在无特殊理由需要更高/更低时的起点大规模 SFT大而多样的指令集最高 ~256最高 ~512仅当数据集足够大且多样、能利用额外容量时才合理——在默认使用前先看下文 rsLoRA 说明三点补充解释RL 适配器用低 rankGRPO/RLVR 是在 SFT 之后的策略优化基础模型已具备任务能力适配器只需做行为微调。这与 grpo-rlvr-training/SKILL.md 中RL 是锐化已有能力、而非从零安装能力的原则一致——rank 低是因为要改的东西少。大规模 SFT是条件性选择rank 升到 ~256 只有在数据集规模与多样性足以支撑额外容量时才成立。更高 rank 并不自动更好——它提升记忆容量的速度和提升泛化容量的速度一样快。正确做法是从任务匹配的行出发只有当较低 rank 在留出集held-out eval上可测量地欠拟合时才向上移动一档而不是默认取最大。rank 与数据量错配是最常见的过拟合来源在 SKILL.md 的 Failure Modes 中明确指出为大规模 SFT最高 ~256选的 rank 用在没有规模支撑的小数据集上结果是记忆化而非泛化。rank 必须匹配数据规模而不是匹配最大可用数字。1.2 适配器参数量与 rank 的关系来自 memory-math 的旁证为什么 rank 在 1–256 范围内对显存几乎无感memory-math.md 给出了公式rank 为r的适配器在线性层上增加r × (in out)个参数A 矩阵是r×inB 矩阵是out×r。在常规 rank 下这只占基础模型参数量的零点几个百分点内存估算中可近似视为零——这解释了为什么 LoRA 的显存大头是冻结权重本身而不是适配器。2. 学习率按方法取值LoRA 约为全参微调的 10 倍第二个核心结论LoRA/QLoRA 学习率约为等价全参微调full-FT学习率的 10 倍。这是把全参微调配置移植到 LoRA 时最常见的一个错误配置——保留原学习率不变会导致适配器欠训练under-train。学习率按方法分为三档方法LR 范围适用场景QLoRA标准2e-4QLoRA SFT 的默认起点LoRA保守1e-4更大的基础模型、更高的 rank或 2e-4 下已出现不稳定性的运行LoRA非常保守5e-5续训continuing a run、细粒度行为调整或基础模型已接近目标行为官方文档的明确态度是这些是用于围绕其扫描sweep的起点不是固定常数——但务必从这里出发而不是原封不动移植全参微调的学习率。值得注意的是LoRA 保守档1e-4反而比 QLoRA 标准档2e-4更低原因是LoRA 适配器没有量化引入的噪声在更大模型或更高 rank 下直接用 2e-4 可能不稳定因此下调一档更稳妥。在 SKILL.md 中学习率与 alpha 一起被归纳为参考配方reference recipeLoRA Without RegretThinking Machines / Schulman2025-09的一部分该配方现在是 LoRA/QLoRA SFT 的既定惯例。3. rsLoRA可选且只在 r ≥ 32 时值得开启Rank-stabilized LoRArsLoRA把适配器更新缩放从alpha / r改为alpha / sqrt(r)。参考文档给出了明确的启用边界r ≥ 32 时开启才有意义低于该 rank标准缩放alpha / r已经足够稳定rsLoRA 不会带来有意义的改变。如果启用了上文大规模 SFT行rank 最高 ~256应开启 rsLoRA对于通用默认档16–32或 RL 档1–32保持关闭除非出现了特定的不稳定性。注意与 1.1 节的衔接通用默认档的 rank 是 32恰好落在阈值上。参考配置中use_rsloraFalse的注释明确写着 r32 threshold — leave disabled here unless instability is observedr32 处于阈值——除非观察到不稳定否则保持关闭。也就是说阈值本身不是达到即开而是达到后值得考虑仅在出现不稳定时开启。4. 有效 Batch 与 Packing 的交互这是参考文档中隐藏最深的一节包含三条相互独立的规则4.1 有效 batch 保持在 32 以下参考配方在 effective batch 32 的规模下完成验证超过 32 属于未测试的外推untested extrapolation不是免费的吞吐提升。计算公式effective_batch per_device_batch_size × gradient_accumulation_steps × num_devices关键陷阱多 GPU 或高梯度累积设置下即使单设备 batch 看起来很小乘积也可能轻松越过 32。必须计算乘积而不能只看单设备数值。这也是为什么下文工作配置中per_device_train_batch_size4×gradient_accumulation_steps4 16单设备——明确标注stays under 32。4.2 Packing 改变的是 batch 的 token 组成不只是样本数把多个短样本打包进一个序列改变的是有效 batch 的 token 组成而不仅仅是样本计数——一个 8 序列的打包 batch 并不等价于 8 个短样本的非打包 batch。因此先应用 chat template再进行打包apply the chat template before packing, not after。这条与 dataset-curation/SKILL.md 的规则完全一致打包后再模板化会把角色标记role markers放错位置、破坏轮次边界。在信任管线之前先抽查解码若干条打包序列spot-check a handful of decoded packed sequences。dataset-curation/SKILL.md 将这一要求升级为强制项正式跑全量前必须解码并人工检查 5–10 条打包序列确认样本边界、模板标记、loss mask 均正确——因为打包 bug 是静默的loss 曲线看起来正常几小时后才在 eval 质量上暴露。llm-finetuning-training-engineeragent 的方法章节同样要求把解码样本附到验证报告中。4.3 梯度检查点与 packing 是独立的两条杠杆梯度检查点use_gradient_checkpointingunsloth与 packing 各自独立地在计算与内存之间做权衡梯度检查点用重计算换内存相对无检查点约节省30% VRAM来自 SKILL.md 的 Unsloth 默认值说明Packing用更紧凑的序列利用减少 padding 浪费进而改变激活内存。两者同时开启是内存受限运行的常态而非冗余。在 memory-math.md 中梯度检查点的 ~30% 节省正是激活项activations估算时唯一直接应用的修正因子且 packing/序列长度对该项是比 batch 更直接的杠杆。5. 目标模块全线性层MLP 优先适配器挂载哪些模块属于超参数配置的一部分且与 rank/alpha/LR 同等重要。参考配方的结论是瞄准全部线性层all-linear而不只是注意力层target_modules [ q_proj, k_proj, v_proj, o_proj, # attention gate_proj, up_proj, down_proj, # MLP — matters most ]MLP 层gate_proj/up_proj/down_proj最重要——只挂注意力层是旧式且更弱的约定删减模块以省显存是被明确列为 Failure Mode 的伪优化MLP 上的适配器参数只占模型总参数的一小部分砍掉它们几乎不省显存却可测量地损害质量。显存紧张时正确顺序是切换到 QLoRA、降低 rank/batch/打包长度而不是裁剪目标模块。6. 完整工作配置UnslothFastLanguageModelSFTConfig以下是参考文档给出的完整、内部自洽的配置通用默认 rankr32、QLoRA、标准学习率。配置块的默认风格是 Unsloth 快速路径这是该插件默认假定的参考实现但每个 kwarg 都有对应的原生 TRL/PEFT 写法见第 7 节映射表。from unsloth import FastLanguageModel from trl import SFTConfig, SFTTrainer BASE_MODEL from model catalog # size class task decide this, not this file model, tokenizer FastLanguageModel.from_pretrained( model_nameBASE_MODEL, max_seq_length2048, dtypeNone, # auto-detect bf16/fp16 by hardware load_in_4bitTrue, # QLoRA path — set False for bf16 LoRA ) target_modules [ q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj, ] model FastLanguageModel.get_peft_model( model, r32, target_modulestarget_modules, lora_alpha64, # 2 * r lora_dropout0, biasnone, use_gradient_checkpointingunsloth, random_state3407, use_rsloraFalse, # r32 threshold — leave disabled here unless instability is observed ) import torch # Check hardware BF16 support before forcing it — see SKILL.md # Failure Modes. Training in fp16 on hardware without solid BF16 # support is a known source of loss spikes and silent divergence, # so this is a hard prerequisite, not a config style choice. if not torch.cuda.is_bf16_supported(): raise RuntimeError( This GPU does not support BF16 — do not fall back to fp16True as if it were equivalent; pick hardware with BF16 support instead (see SKILL.md Failure Modes). ) training_args SFTConfig( output_dir./outputs, max_length2048, dataset_text_fieldtext, per_device_train_batch_size4, gradient_accumulation_steps4, # effective batch 16 (single device) — stays under 32 learning_rate2e-4, # QLoRA standard bf16True, # gated above — never fp16, see SKILL.md Failure Modes optimadamw_8bit, num_train_epochs3, logging_steps10, seed3407, ) trainer SFTTrainer( modelmodel, processing_classtokenizer, # current TRL — not tokenizer train_datasettrain_dataset, argstraining_args, ) trainer.train()6.1 配置内部自洽性检查参考文档原话逻辑这份配置的每一处取值都不是孤立的它们互相印证取值依据出处r32→lora_alpha642x 规则alpha 2 * r第 1 节表load_in_4bitTrue→learning_rate2e-4QLoRA 标准学习率第 2 节表bf16True绝不 fp16硬件 BF16 支持是硬性前置条件下方 6.3有效 batch4 × 4 16低于 32 上限第 4.1 节修改其中任何一项——rank、量化方式或 batch 形状——都应触发对照上表重新检查其他项而不是孤立地编辑该值。6.2 Unsloth 默认值及其设计原因get_peft_model调用中的几个默认值在 SKILL.md 中有明确的设计理由lora_dropout0Unsloth 优化内核路径假设零 dropout设为非零值会失去融合内核的加速。注意这是内核路径的硬性假设不是传统意义上小 dropout 有益的调参项。biasnone偏置项在此 rank 区间只增加适配器参数质量收益可忽略。use_gradient_checkpointingunslothUnsloth 的检查点变体非 HF 原生检查点相对无检查点节省约 30% VRAM。optimadamw_8bit8-bit AdamW 在 LoRA/QLoRA 适配器规模下显著削减优化器状态内存质量影响可忽略。random_state3407固定固定 LoRA 初始化以保证跨运行可复现把它当作普通 seed 对待不是可调参数。同时SFTConfig(seed3407)负责训练器侧的 RNG——两者都要设置见第 7 节映射表。6.3 BF16 硬前置检查为什么不能降级到 fp16配置中torch.cuda.is_bf16_supported()检查是硬性前置条件而非配置风格选择在不具备可靠 BF16 支持的硬件上用 fp16 训练是 loss 尖峰loss spikes与静默发散silent divergence的已知来源。文档明确禁止把fp16True当作等价回退——正确做法是选择支持 BF16 的硬件而不是换 dtype 硬跑。SKILL.md 提供了对应的命令行检查python -c import torch; print(torch.cuda.is_bf16_supported())这条规则与llm-finetuning-training-engineeragent 的失败分类Failure Triage直接对应其发散Divergence排查清单的第一位就是fp16 vs. bf16——确认bf16True且硬件支持 BF16。7. 与原生 TRL/PEFT 的映射翻译而非重写Unsloth 是 PEFT 与 TRL 之上的快速内核封装不是替代 API——每个 Unsloth kwarg 都有原生 TRL/PEFT 等价物。完整的 unsloth-trl-mapping.md 是逃生舱escape hatch机制的基础当需要回退到原生 TRL 时用映射表做机械翻译即可超参数本身不变。Unsloth kwargTRL/PEFT 等价物说明FastLanguageModel.from_pretrained(model_name...)AutoModelForCausalLM.from_pretrained(...)AutoTokenizer.from_pretrained(...)Unsloth 把模型分词器加载与内核修补融合为一次调用load_in_4bitTrueBitsAndBytesConfig(load_in_4bitTrue, bnb_4bit_quant_typenf4, bnb_4bit_compute_dtypetorch.bfloat16)传入from_pretrained两侧都是 QLoRA 路径get_peft_model(r..., target_modules..., lora_alpha..., lora_dropout..., bias..., random_state...)peft.LoraConfig(...)peft.get_peft_model(model, config)random_state→ 调用前设置 seedUnsloth 是生成同一份LoraConfig的薄封装use_gradient_checkpointingunslothSFTConfig(gradient_checkpointingTrue)Unsloth 变体更快/更低内存原生gradient_checkpointingTrue是正确回退节省收益约少 30%optimadamw_8bitSFTConfig(optimadamw_8bit)完全相同的字符串无需翻译use_rsloraTrue/FalseLoraConfig(use_rsloraTrue/False)PEFT 中同名标志max_seq_length传from_pretrainedSFTConfig(max_length...)当前 TRL字段已从max_seq_length更名为max_lengthdataset_text_fieldSFTConfig(dataset_text_field...)与max_length一样位于SFTConfigrandom_state3407SFTConfig(seed3407)两者都设Unsloth 的random_state专管 LoRA 初始化SFTConfig.seed管训练器 RNG7.1 当前 TRL API 的两个易错点unsloth-trl-mapping.md 特别警告两个近期变更过的 API 面连一些 Unsloth cookbook 片段都还在用旧写法processing_class不是tokenizerSFTTrainer(tokenizertokenizer, ...)是已移除或弃用的旧形式当前 TRL 使用SFTTrainer(processing_classtokenizer, ...)。把旧配方向前移植时这是最常见的过时 API 错误——运行前必须更新。max_length与dataset_text_field都住在SFTConfig上不要把它们分散在 trainer 调用或模型加载器里在SFTConfig实例上一次性设置不在管线其他位置重复。8. 场景决策LoRA vs QLoRA vs 全参微调超参数取值正确的前提是方法选对。参考文档连同 SKILL.md给出的默认决策表场景默认选择在演示数据上适配行为LoRA基础模型在目标 rank 下放不进 bf16QLoRA注入密集的新领域知识全参微调见 finetuning-method-selection/SKILL.md不确定选哪个LoRA——仅当内存迫使时才升级到 QLoRAQLoRA NF4 量化冻结基础权重 BF16 适配器。它的内存优势来自量化的基础权重本身而不是适配器——这正是65B 级模型在 48GB 上可训的原因。全参微调不是默认只在需要从权重层面改变模型知识密集知识注入时使用本技能范围内的其余场景LoRA 或 QLoRA 是起点假设。DGX Spark 上的反直觉陷阱QLoRA 可能在等价 bf16 LoRA 运行之前就 OOM——因为 bitsandbytes 反量化缓冲是加载期间瞬时尖峰的 CUDA 侧分配。QLoRA OOM 不代表模型放不下下一步应尝试 bf16 LoRA而不是进一步压缩 QLoRA。这与dgx-spark-ops插件的spark-memory-thermal-ops技能中的 OOM 阶梯一致先刷新再减 batch/打包长度最后降级方法——bf16 LoRA 先于 QLoRA。方法选择还受数据形态约束finetuning-method-selection的路由树明确数据形态决定方法lora-qlora-recipes假设路由已经完成数据是演示数据/示范对不处理偏好对那是preference-optimization或可验证奖励信号那是grpo-rlvr-training。9. 与模型目录和内存预估的衔接hyperparameters.md特意声明本文件不指名任何基础模型——所有示例只按规模等级size class标注。选择具体模型请查 model-catalog.md该文件是整个插件含 dgx-spark-ops中唯一指名基础模型家族的地方并带有 last verified 日期与季度刷新清单。配置BASE_MODEL前的显存可行性评估则使用 memory-math.md 的四项工作表权重 优化器状态 梯度 激活。关键数据点bf16 权重 2 字节/参数int4 NF4QLoRA0.5 字节/参数——同一参数量的 4 倍差距LoRA/QLoRA 的优化器状态与梯度只针对可训练适配器参数计算因此这两项可忽略与基础模型规模无关8B 级 bf16 LoRA 权重约 16GB8B 级 QLoRA 约 4GB70B 级 QLoRA 真实世界锚点约40GB含 NF4 双重量化元数据与运行时开销而 bf16 单权重就约 140GB——这是70B 级只能走 QLoRA 而非 bf16的数学依据。10. 三大失败模式先查配置再调训练循环SKILL.md 将三种失败模式归纳为一个共同规律它们看起来像训练循环 bugloss 尖峰、平台期、记忆化实际却是违反参考配方的配置选择。遇到这类症状应先对照本技能检查配置再调试训练循环本身。非 BF16 GPU 上的 fp16 发散在不具备可靠 BF16 支持的硬件上用 fp16 训练是 loss 尖峰与静默发散不报错地变差的已知来源。对策硬件支持处强制bf16True不支持处更换硬件而非回退 fp16见 6.3 的运行时检查。小数据集上 rank 过高导致过拟合为大规模 SFT选的 rank最高 ~256用在没有规模支撑的数据上会记忆化。对策严格对照Rank 与 Alpha 按任务类型表匹配数据规模。为省显存删除目标模块代价是质量节省可忽略。适配器参数在 MLP 上只占模型总量的一小部分删掉几乎不省显存却可测量地伤质量。对策显存紧张时先降 rank/batch/打包长度或换 QLoRA。11. 在插件工作流中的位置从源码结构看hyperparameters.md处于一条明确的消费链上finetuning-method-selection完成路由 →lora-qlora-recipes产出验证过的适配器配置即 kwarg 值而非自由形式建议 → llm-finetuning-training-engineer.md 将其直接消费生成可运行的train/train.py与train/config.yaml。该 agent 的 Phase 4 要求两个文件在启动前先提交保证失败时仍可复现并在发散时按固定顺序排查先 bf16 vs fp16再学习率 vs 方法最后打包损坏。需要特别说明的例外组合对 messages 形状的对话式 SFT 且启用assistant_only_lossTrue时Unsloth 2026.7.x 的编译训练器没有 messages 形状路径原生 TRL PEFT 逃生舱是该组合的默认路径而非罕见回归回退。此时用第 7 节映射表翻译即可——超参数不变只是设置它们的库不同。结语LoRA/QLoRA 微调的超参数不是一堆孤立可调旋钮而是一套内部自洽的系统alpha 2r的推导规则、约 10 倍于全参微调的学习率、按任务类型的 rank 区间、32 以下的有效 batch、r ≥ 32 才启用的 rsLoRA以及 bf16 硬前置检查——任一取值变动都应触发对其他项的系统性复核。以 hyperparameters.md 为参考、SKILL.md 为原则、unsloth-trl-mapping.md 为翻译桥你可以直接产出可运行、可复现、可排查的 LoRA/QLoRA SFT 配置。【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考