企业官网建设流程全解析

• 人工智能
• 大模型
• 微调
• LoRA

Super-Tuning（论文 arXiv:2607.09287）是 PEFT 中一种稀疏微调方法：它冻结基础权重，仅依据权重幅值（magnitude）选择每个目标权重矩阵中极小一部分标量条目作为可训练"支持集"，全程数据无关、无需校准集。本文以 examples/supertuning_finetuning/README.md 为主干，结合 PEFT 中SupertuningConfig/SupertuningLayer的源码实现（config.py、layer.py、model.py）与配套脚本 supertuning_finetuning.py，完整讲解从零配置、训练、保存到加载推理的全流程，并深入解释sparsity、select_top、r、lora_alpha等关键参数在源码中的实际作用。读完你将掌握如何用纯 Super 稀疏微调（仅训练 1% 权重条目）以及 Supra 混合模式（稀疏支持 + LoRA 低秩适配器）微调 Llama 3.2 等因果语言模型，并了解其 checkpoint 结构与合并（merge）语义。

一、Super-Tuning 是什么：动机与设计要点

1.1 与 LoRA 的本质区别

LoRA 将可训练参数约束在一个低秩子空间（ΔW = B·A，秩为r）；Super-Tuning 则不做这种子空间限制——它直接在冻结的基础权重上选取一小部分单个标量条目进行训练。具体做法：

• 基础权重保持requires_grad=False完全冻结；
• 一个紧凑的(indices, values)对编码可训练支持集：indices是选中条目在权重矩阵中的扁平位置，values是对应的可训练标量；
• 前向时通过scatter_add将这些标量"散布加"回基础权重，等效于在参与矩阵乘法前先组装出有效权重（layer.py 的SupertuningLayer注释对此有明确说明）。

这带来两个直接好处：一是可训练参数不再受低秩子空间限制，理论上能覆盖基础权重中任意位置；二是训练集选择完全数据无关（data-free）——只需读取权重的绝对值，不需要任何校准集（对比 Wanda 等基于激活的方法需要校准 pass）。

1.2 Supra 混合模式

论文的 "Supra" 混合方案是：在稀疏支持集之上再叠加一个 LoRA 风格的低秩适配器。在配置中设置r为任意正整数即可启用：update_layer会额外分配 LoRA 的A（[r, in_features]）与B（[out_features, r]）参数，前向时其贡献(alpha / r) * (B @ A)与稀疏组合输出相加（layer.py）。

值得注意的初始化细节：init_weights=True（默认）时，稀疏values与 LoRAB均零初始化，LoRAA使用 Kaiming-uniform——这与 PEFT LoRA 层约定一致，即构造时刻适配器是恒等更新，不会干扰初始输出（config.py）。

1.3 支持范围与约束

从SupertuningModel._create_new_module的源码看，目前仅支持torch.nn.Linear目标层，其余类型会抛出TypeError（model.py）。这与 README 的 Additional Notes 一致。

二、快速上手：从 LoRA 到 Super-Tuning 的一行替换

2.1 最小训练示例

在标准 PEFT 训练流程中，只需把LoraConfig换成SupertuningConfig：

import torch from peft import SupertuningConfig, get_peft_model from transformers import AutoTokenizer, AutoModelForCausalLM from trl import SFTConfig, SFTTrainer from datasets import load_dataset model = AutoModelForCausalLM.from_pretrained("meta-llama/Llama-3.2-1B", dtype=torch.bfloat16, device_map="auto") tokenizer = AutoTokenizer.from_pretrained("meta-llama/Llama-3.2-1B") tokenizer.pad_token_id = tokenizer.eos_token_id supertuning_config = SupertuningConfig(sparsity=0.99, target_modules=["q_proj", "v_proj"]) peft_model = get_peft_model(model, supertuning_config) peft_model.print_trainable_parameters() dataset = load_dataset("imdb", split="train[:1%]") training_args = SFTConfig(dataset_text_field="text", max_length=128) trainer = SFTTrainer( model=peft_model, args=training_args, train_dataset=dataset, processing_class=tokenizer, ) trainer.train() peft_model.save_pretrained("supertuning-llama-3.2-1b")

关键点：

• sparsity=0.99表示每个目标权重矩阵中约1% 的条目可训练，其余冻结；
• 不传r（保持None）即为纯 Super 模式；
• 该示例将 Super-Tuning 应用于注意力的q_proj与v_proj两层。

2.2 加载与推理

微调产物可用标准的PeftModel.from_pretrained加载：

import torch from peft import PeftModel from transformers import AutoModelForCausalLM model = AutoModelForCausalLM.from_pretrained( "meta-llama/Llama-3.2-1B", dtype=torch.bfloat16, device_map="auto" ) peft_model = PeftModel.from_pretrained(model, "supertuning-llama-3.2-1b")

从源码看，SupertuningConfig的peft_type被设置为PeftType.SUPERTUNING（config.py），因此 PEFT 的自动加载机制能正确识别该适配器类型，无需任何额外参数。

2.3 支持集的自动选择：target_modules

target_modules支持三种写法（config.py）：

• None：使用模型架构默认的目标模块映射；
• 列表：按后缀/精确名匹配，例如["q_proj", "v_proj"]；
• 字符串：作为正则表达式匹配，例如".*self_attn.*(q_proj|v_proj)$"。

实现层面，SupertuningModel.target_module_mapping直接复用 LoRA 的架构映射表TRANSFORMERS_MODELS_TO_SUPERTUNING_TARGET_MODULES_MAPPING = TRANSFORMERS_MODELS_TO_LORA_TARGET_MODULES_MAPPING.copy()（constants.py），因此凡 LoRA 支持自动映射的架构，Super-Tuning 默认也有对应的目标模块。

三、进阶用法：命令行脚本实操

仓库提供了完整的可运行脚本 supertuning_finetuning.py，基于 TransformersTrainer+DataCollatorForLanguageModeling实现因果语言建模微调，默认数据集为timdettmers/openassistant-guanaco。

3.1 指定目标模块（默认作用于 Q/V 层）

脚本默认把 Super-Tuning 应用到 query 与 value 层；想换目标层，传逗号分隔列表：

python examples/supertuning_finetuning/supertuning_finetuning.py --base_model meta-llama/Llama-3.2-1B --target_modules "q_proj,k_proj,v_proj,o_proj"

注意脚本内部会把该字符串split(",")后传入配置（supertuning_finetuning.py）。

3.2 训练 Supra 混合模式

传--rank即启用稀疏支持 + LoRA 的 Supra 混合；--lora_alpha省略时自动取2 * rank：

python examples/supertuning_finetuning/supertuning_finetuning.py --base_model meta-llama/Llama-3.2-1B --rank 8

lora_alpha = 2 * r这一默认逻辑在配置的__post_init__中实现（config.py）：r为非空整数时若未显式给lora_alpha，自动补为2 * r；反之若r is None却传了lora_alpha，会直接报错——Supra 模式必须显式声明秩。

3.3 完整训练参数示例

python supertuning_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-4 \ --cutoff_len 512 \ --eval_step 10 \ --save_step 100 \ --device "auto" \ --sparsity 0.99 \ --rank 8 \ --target_modules "q_proj,v_proj" \ --hub_model_id "YOUR_HF_REPO" \ --push_to_hub

各参数含义与脚本默认值（见脚本 argparse 定义）：

脚本其他值得注意的工程细节：自动选择 bf16/fp32（取决于设备 bf16 支持，supertuning_finetuning.py）、warmup 取总步数的 10%、gradient_accumulation_steps=16、save_total_limit=2。

四、核心参数深度解析（源码级）

4.1sparsity：控制可训练条目比例

• 取值范围[0.0, 1.0)，在__post_init__中强校验，越界抛ValueError（config.py）；
• 可训练条目数由int(num_params * (1 - sparsity))计算（layer.py）；
• 若稀疏率过高导致一个条目都选不中，直接抛错而不是静默不训练：update_layer中num_trainable < 1时会抛出 "leaves no trainable entries" 的ValueError（layer.py）。该行为由测试 test_supertuning.py 显式验证。

4.2select_top：幅值选择方向

• True（默认）：保留幅值最大的条目作为支持集——对应论文的 Super/Supra；
• False：保留幅值最小的条目——对应论文的-bottom变体；
• 论文报告最佳方向因模型与任务而异，README 明确提醒需要实验确定；
• 测试 test_supertuning.py 验证了 top-k 与 bottom-k 选出的支持集互不相交。

4.3r/lora_alpha/lora_dropout：Supra 混合参数

• r=None（默认）：纯 Super，只训练稀疏values，不分配任何 LoRA 参数（supertuning_rank记为 0）；
• r为正整数：分配 LoRAA/B层，lora_alpha默认2*r，lora_dropout默认0.0（即nn.Identity()，layer.py）；
• LoRA 层统一以无 bias 的nn.Linear且 fp32 精度存放（匹配 PEFT LoRA 约定，保证训练稳定性）；bf16 基础权重下，前向会把输入提升到 fp32 参与 LoRA 矩阵乘，再降回结果 dtype（layer.py），该路径由回归测试 test_supertuning.py 覆盖。

4.4init_weights：恒等初始化 vs 非平凡初始化

• True（默认）：稀疏values零初始化、LoRAB零初始化，构造时适配器是恒等更新；
• False：两者改为 Kaiming-uniform（LoRAA无论何种情况都是 Kaiming-uniform），主要用于测试中构造非平凡适配器（config.py）。

4.5save_precomputed_indices：checkpoint 体积优化开关

• True（默认）：把稀疏支持集索引直接写入 state dict；
• False：裁剪 checkpoint 体积——索引在加载时根据基础权重幅值确定性重建。前提是基础模型权重与训练时完全一致，否则数值漂移可能导致 topk 平局裁决不同（config.py）；
• 设置False时会触发警告，且同一模型的所有适配器必须保持一致，否则SupertuningModel._check_new_adapter_config抛错（model.py）。

4.6 继承自PeftConfig的通用参数

modules_to_save（如随机初始化的分类头，需一并训练并保存）、inference_mode等与 PEFT 其他 tuner 语义一致，详见 config.py。

五、源码级原理：前向、合并与 checkpoint

5.1 前向：稀疏组合 + LoRA 叠加

SupertuningLayer.forward的核心路径（layer.py）：

1. 若适配器被禁用或已合并，直接走基础层前向；
2. 否则把基础权重flatten，对每个活跃适配器用scatter_add把values写回indices位置，得到"稠密 + 稀疏"的有效权重；
3. 用F.linear一次性完成矩阵乘法；
4. Supra 模式下，再对每个rank > 0的适配器计算lora_B(lora_A(x))，缩放alpha / r后加到结果上。

由于基础权重冻结（requires_grad=False），autograd 不会在其上累积梯度，稀疏组合仅用scatter_add完成。一个值得注意的细节：该路径绕过了基础层自身的 forward hooks，因此如果用户在基础层上注册了 hook，_warn_once_about_module_hooks会通过 LRU 缓存只警告一次，提示改在 PEFT 适配层上注册（layer.py）。

5.2 合并与解合并

merge将每个活跃适配器的（稀疏 + LoRA）贡献原位折入基础权重：safe_merge=True时先组装合并结果并检查isfinite（发现 NaN 即抛错），False时直接scatter_add_原地修改；unmerge逆向执行（先减 LoRA delta，再scatter_add负值）（layer.py）。get_delta_weight则返回稠密的[out_features, in_features]更新量，语义与 PEFT LoRA 的get_delta_weight一致（layer.py）。

5.3 Checkpoint：紧凑的 (indices, values) 对

适配器 checkpoint 中存储的是一维的supertuning_values与supertuning_indices对，而非稠密掩码（sparse_mask），这是 Super-Tuning 独有的存储设计。索引以int32保存以减半 checkpoint 体积（位置不会超出 int32 范围），前向/合并时再转回int64（scatter_add索引内核要求 int64）。测试 test_supertuning.py 验证了：

• checkpoint 只含supertuning_values/supertuning_indices，且二者形状一致；
• 索引绝不能是浮点类型——防止_move_adapter_to_device_of_base_layer把 int 索引缓冲误转 float 导致 GPU 上越界。

5.4 多适配器语义

SupertuningLayer的adapter_layer_names与other_param_names按适配器名（ParameterDict/BufferDict/ModuleDict）组织，可通过set_adapter/add_adapter管理多个适配器。注意新增适配器默认不可训练（_create_and_replace中requires_grad_(False)，model.py）。

六、附加说明与注意事项

• 稀疏率上限：sparsity必须在[0.0, 1.0)；极高稀疏率会留下极少数可训练条目，若完全选不出条目则直接报错；
• 方向选择：select_top=True（幅值最大）与False（幅值最小）的优劣因模型、任务而异，建议做消融实验；
• 层类型限制：目前仅支持nn.Linear，nn.Conv2d、nn.Embedding等目标会报TypeError；
• 混合兼容性：该 tuner 注册时声明is_mixed_compatible=False（init.py），即 Super-Tuning 不参与 PEFT 的混合 tuner 组合；
• 架构默认目标模块：默认目标模块映射继承自 LoRA 的映射表（constants.py），因此主流 Transformers 架构都能开箱即用地获得合理的默认target_modules。

七、引用

若你的工作使用了 Super-Tuning，可引用论文：

@article{ilin2026supertuning, title={Super-Tuning: From Activation-Aware Pruning to Sparse Fine-Tuning}, author={Ivan Ilin and Philip Zmushko and Peter Richt\'arik}, year={2026}, eprint={2607.09287}, archivePrefix={arXiv}, primaryClass={cs.LG}, }

相关实现与测试可进一步参考：SupertuningConfig、SupertuningLayer / Linear、SupertuningModel、Supertuning 官方文档 以及 test_supertuning.py。

• 人工智能
• 大模型
• 微调
• LoRA