PEFT 中的 IA3(Infused Adapter)完全指南:用三个学习向量实现最小 Adapter 的参数高效微调
PEFT 中的 IA3(Infused Adapter)完全指南:用三个学习向量实现最小 Adapter 的参数高效微调
IA3(Infused Adapter by Inhibiting and Amplifying Inner Activations)是 🤗 PEFT 提供的一种参数高效微调方法:它不引入低秩矩阵,而是用三个可学习的向量对 Transformer 内部激活做逐元素缩放,从而在保持与全量微调相当性能的同时,把可训练参数量压到极致。本文以 docs/source/package_reference/ia3.md 为主线,结合 PEFT 仓库中 src/peft/tuners/ia3/ 的完整实现,讲解 IA3 的工作原理、配置参数、支持层类型、合并推理与实战微调方案。读完本文,你将能够独立配置 IA3 适配器、判断它与 LoRA 的适用边界,并理解其底层前向计算与合并逻辑。
IA3 是什么:方法背景与论文动机
IA3 源自论文 Few-shot Parameter-Efficient Fine-tuning is Better and Cheaper than In-Context Learning(arXiv:2205.05638)。论文的核心动机是:少样本上下文学习(ICL)虽然能让预训练语言模型无需梯度训练即可执行新任务,但每次预测都要处理全部训练示例,带来巨大的计算、内存与存储开销。作为对比,参数高效微调(PEFT)只训练一小部分参数即可让模型掌握新任务。论文在严格对比后指出:PEFT 在精度上更优,同时计算成本大幅更低,并由此提出了 (IA)³ 方法——用学习到的向量缩放激活,以极少的参数获得更强的性能。基于 T0 模型搭配 (IA)³ 的 T-Few 配方在 RAFT 基准上首次达到超越人类的表现,比当时的最先进方法高出 6% 的绝对精度。
PEFT 仓库对该方法的实现完全遵循上述设计:在 src/peft/tuners/ia3/model.py 中,IA3Model 的 docstring 明确指出其依据论文 2205.05638,在预训练 transformers 模型上注入 (IA)³ 层;PeftType.IA3 则在 src/peft/utils/peft_types.py 中注册。
工作原理:lv、lk、lff 三个向量如何缩放内部激活
在一个典型的 Transformer 架构中,IA3 向注意力模块与前馈模块注入学习向量。官方文档对注入位置做了精确说明:在自注意力与编码器-解码器注意力的 key、value 层输出处,以及每个 Transformer 块中第二个前馈层的输入处,各引入一个学习向量进行重新缩放——即论文图例中的 lv、lk、lff 三个向量。
在 src/peft/tuners/ia3/layer.py 中,前向逻辑清晰地体现了"乘在输出还是乘在输入"的区分:
# src/peft/tuners/ia3/layer.py 中 Linear.forward 的核心逻辑(约 L172-L199)
if self.is_feedforward:
interm = (x * ia3_scaling).to(previous_dtype)
result = self.base_layer(interm, *args, **kwargs)
else:
result = self.base_layer(x, *args, **kwargs)
result = (result * ia3_scaling).to(result_dtype)
- 对非 feedforward 层(如
k_proj、v_proj):先执行基础层计算,再在输出上乘以缩放向量ia3_l; - 对feedforward 层(如
down_proj):先对输入乘以缩放向量,再送入基础层计算。
这一区别正是配置中 feedforward_modules 存在的意义:它告诉 PEFT 哪些目标模块属于前馈层,从而施加"乘输入"而非"乘输出"的正确缩放。此外,多个激活适配器会通过累乘(ia3_scaling *= ...)组合,这意味着可以叠加多个 IA3 适配器进行推理。
缩放向量的形状与初始化也值得注意(layer.py 的 update_layer / reset_ia3_parameters):
- 非 feedforward 层:向量形状为
(out_features, 1); - feedforward 层:向量形状为
(1, in_features); - 默认用
torch.randn生成后通过nn.init.constant_(..., 1.0)初始化为全 1(对应init_ia3_weights=True),即初始状态等价于"不缩放",保证微调从与基础模型一致的行为出发。
每个被替换的目标层只持有一个 nn.Parameter 向量(存于 ia3_l 的 ParameterDict 中),这正是 IA3 可训练参数极少的根源:参数数量等于被选目标层的维度之和,而不是低秩矩阵的秩积。
IA3 的核心优势
官方文档明确指出,IA3 与 LoRA 高度相似,继承了参数高效微调的几乎所有优点:
- 极少的可训练参数:以 T0 为例,IA3 模型仅有约 0.01% 的可训练参数,而 LoRA 也超过 0.1%——IA3 通常比 LoRA 还要小一个数量级,是追求最小磁盘/内存占用与最快训练速度时的强候选方案;
- 基础权重保持冻结:原始预训练权重完全冻结,可以在同一基座模型上叠加多个轻量、可移植的 IA3 适配器,分别服务于不同下游任务;
- 性能与全量微调相当:使用 IA3 微调的模型性能可与全量微调媲美;
- 不增加推理延迟:因为适配器向量可以被合并进基础模型(见下文"合并与卸载"),推理时零额外开销。
从源码结构看,由于可训练参数是逐层一个向量,训练过程中的优化器状态、梯度显存也相应极小,这对于存储受限或显存受限的部署场景尤为友好。
快速上手:为 Llama 配置 IA3 并打印可训练参数
官方文档给出了针对自回归模型(因果语言建模任务)的完整示例,并附有重要提示:对于自回归模型,作者发现 k_proj、v_proj 与 down_proj 是最有效的目标层,同时必须将 feedforward_modules=["down_proj"] 显式声明,IA3 才能对前馈层施加正确的"乘输入"缩放。
from peft import IA3Config, TaskType, get_peft_model
from transformers import AutoModelForCausalLM
model = AutoModelForCausalLM.from_pretrained("HuggingFaceTB/SmolLM-135M")
peft_config = IA3Config(
task_type=TaskType.CAUSAL_LM,
target_modules=["k_proj", "v_proj", "down_proj"],
feedforward_modules=["down_proj"],
)
model = get_peft_model(model, peft_config)
model.print_trainable_parameters()
运行后,print_trainable_parameters() 会输出类似 trainable params: xxx || all params: xxx || trainable%: xxx 的信息,可据此直接验证 IA3 的可训练占比远低于 LoRA。这一步背后的调用链是:get_peft_model 依据 IA3Config 构造 IA3Model,后者通过 _create_and_replace / _create_new_module 把命中的目标模块替换为带 IA3Layer 的实现,并冻结其余全部权重。
对于序列到序列任务,仓库的示例 examples/conditional_generation/peft_ia3_seq2seq.ipynb 展示了另一种常见配置:IA3Config(task_type=TaskType.SEQ_2_SEQ_LM, inference_mode=False, feedforward_modules=[]),配合 bigscience/mt0-large 与学习率 8e-3(文档中建议性参数,训练 3 个 epoch、batch size 8)。当 feedforward_modules=[] 且未指定 target_modules 时,目标模块会从仓库内置的模型映射表中自动选取(见下文),例如 mt5 默认取 k、v、wi_1。
IA3Config 参数详解
IA3Config 定义于 src/peft/tuners/ia3/config.py,继承自 PeftConfig。官方 API 文档(autodoc 生成)对应的全部字段及源码注释如下:
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
task_type |
TaskType |
依任务而定 | 任务类型(如 CAUSAL_LM、SEQ_2_SEQ_LM),决定默认注入策略; |
target_modules |
Optional[Union[List[str], str]] |
None |
要注入 (IA)³ 的模块名。传字符串时按正则匹配;传列表时做精确匹配或以任一字符串结尾匹配。'all-linear' 表示匹配除输出层外的全部 linear/Conv1D 层;不指定时按模型架构自动选择,架构未知则报错并要求手动指定; |
exclude_modules |
Optional[Union[List[str], str]] |
None |
不注入适配器的模块名,规则同上,用于从目标中排除特定层; |
feedforward_modules |
Optional[Union[List[str], str]] |
None |
按原论文语义被视作前馈层的模块名,这些模块的 (IA)³ 向量乘在输入而非输出上。必须与 target_modules 中的名称一致,且必须是 target_modules 的子集(源码在 __post_init__ 中会校验并抛出 ValueError); |
fan_in_fan_out |
bool |
False |
被替换层是否以 (fan_in, fan_out) 方式存储权重。GPT-2 的 Conv1D 层即为此存储方式,应设为 True; |
modules_to_save |
Optional[List[str]] |
None |
除 (IA)³ 层之外需要保持可训练并随 checkpoint 保存的模块,例如序列分类/词元分类任务中随机初始化的 classifier/score 头; |
init_ia3_weights |
bool |
True |
是否将 (IA)³ 向量初始化为全 1。关闭(False)不被推荐; |
inference_mode |
bool |
— | 是否在推理模式下使用适配器,继承自 PeftConfig。 |
几点源码级补充:
__post_init__会把target_modules、exclude_modules、feedforward_modules统一转成set,并执行"feedforward 是 target 子集"的合法性检查(config.py 的__post_init__);feedforward_modules的匹配在 model.py 的_check_target_module_feedforward中完成:字符串按re.fullmatch全匹配,列表则按key.endswith判定;- 若
target_modules与feedforward_modules均未指定,_prepare_adapter_config会从TRANSFORMERS_MODELS_TO_IA3_TARGET_MODULES_MAPPING与TRANSFORMERS_MODELS_TO_IA3_FEEDFORWARD_MODULES_MAPPING中按model_type自动填充,架构不在映射表中则抛出ValueError,提示手动指定。
内置的模型目标模块映射
在 src/peft/utils/constants.py 中,PEFT 为常见架构预置了 IA3 的目标模块与前馈模块映射(节选):
t5:["k", "v", "wo"],feedforward 为["wo"];mt5:["k", "v", "wi_1"];llama/mistral/gemma/qwen2/qwen3:["k_proj", "v_proj", "down_proj"],feedforward 为["down_proj"];llama4为["q_proj", "v_proj", "down_proj"];mixtral为["k_proj", "v_proj", "w2"];gpt2/gpt_bigcode:["c_attn", "mlp.c_proj"];bloom/falcon/RefinedWeb:["query_key_value", "dense_4h_to_h"](feedforward 为["mlp.dense_4h_to_h"]等);bert/roberta:["key", "value", "output.dense"];deberta-v2:["key_proj", "value_proj", "output.dense"];opt/bart/phi:["q_proj", "v_proj", "fc2"];gptj:["q_proj", "v_proj", "fc_out"];gpt_neox:["query_key_value", "dense_4h_to_h"];gpt_neo:["q_proj", "v_proj", "c_proj"]。
可以看到,绝大多数架构的默认目标都遵循"key、value + 第二个前馈层"的论文设定。当你的模型不在映射表中时,参考上表手动指定 target_modules 与 feedforward_modules 即可,tests/test_tuners_utils.py 中亦有使用正则(如 ".*lin.*")与列表两种方式配置的用例可参考。
支持的层类型与量化适配
从 model.py 的 _create_new_module 分支可以看出,IA3 在当前仓库中支持以下目标层类型:
torch.nn.Linear:标准全连接层,对应 layer.py 中的Linear;torch.nn.Conv2d/torch.nn.Conv3d:卷积层,对应Conv2d/Conv3d(缩放向量形状扩展为(1, num_features, 1, ...),并处理了分组卷积的通道展开逻辑,见_get_ia3_scaling_for_weight),因此 IA3 也适用于视觉模型;transformers.pytorch_utils.Conv1D(GPT-2 风格):会自动强制fan_in_fan_out=True并记录is_target_conv_1d_layer以便卸载还原;- bitsandbytes 量化层:在 bnb.py 中实现了
Linear8bitLt与Linear4bit,分别用于 8-bit 与 4-bit 量化模型(对应is_loaded_in_8bit/is_loaded_in_4bit)。注意量化场景下基础层权重被冻结且不支持合并,且量化 IA3 的前向会做必要的浮点转换以保持数值稳定性。
若目标模块类型不在上述范围内,_create_new_module 会抛出 ValueError(提示当前仅支持 Linear、Conv2d、Conv1D)。此外,tests/test_custom_models.py 中还有 target_modules=["conv"]、feedforward_modules=["conv"] 的自定义卷积模型用例,可作为视觉任务的配置参考。
合并与卸载:零开销推理
IA3 的缩放向量可以直接乘入基础权重,从而实现无额外延迟的推理。Linear.merge 的实现(layer.py)就是:
base_layer.weight.data = torch.mul(base_layer.weight.data, ia3_l).to(orig_dtype)
- 对非 feedforward 层,bias 也会按缩放向量做逐元素缩放;
safe_merge=True时先在拷贝上执行合并并检查 NaN,避免破坏原始权重;unmerge通过除法逆向还原权重,但源码明确给出警告"Unmerge result can be inaccurate for (IA)^3."(由于是逐元素乘法而非低秩相加,逆向除法可能无法完全还原)——这决定了在需要反复切换合并状态的场景要谨慎使用;- 对应的高层 API 是
IA3Model的_unload_and_optionally_merge(即merge_and_unload的底层实现),且当模型以 8-bit / 4-bit 量化方式加载时会抛出ValueError,明确禁止合并量化权重(model.py 的_unload_and_optionally_merge)。
此外,IA3Model 还实现了 add_weighted_adapter,支持对多个已有 IA3 适配器按权重线性合成新适配器(_check_add_weighted_adapter 会校验目标/前馈模块类型一致性,合成时向量按 target_ia3_l.data += current_adapter_ia3_l.data * weight 累加),可用于多适配器加权推理实验。
何时用 IA3,何时用 LoRA
官方文档给出的选型建议是:
- 选 IA3:当你需要尽可能小的适配器(存储受限部署)、希望用更少的可训练参数快速收敛时;
- 选 LoRA:当你需要 LoRA 庞大的变体生态(DoRA、QLoRA 等)、或希望使用被社区广泛验证、工具链最成熟的方案时。
两者并非互斥:PEFT 支持在同一基座模型上注入多种类型的适配器,tests/test_low_level_api.py、tests/test_custom_models.py 中都有 IA3 与其他方法共存的用例,可按任务灵活组合。
效果验证:仓库内置的 IA3 基准
docs/source/package_reference/ia3.md 中嵌入了 IA3 的方法对比基准(Benchmark overview)面板,用于对比各 PEFT 方法在统一实验设置下的表现。仓库内也提供了对应的完整复现工程:
- method_comparison/MetaMathQA:数学推理基准,其
results/目录下包含ia3--llama-3.2-3B-default.json等实验产物(配置信息可见:模型meta-llama/Llama-3.2-3B、bfloat16、max_steps 5000、AdamW lr 1e-4、cosine 调度等),配合 method_comparison/MetaMathQA/run.py 可复现同一套训练/评估流程; - method_comparison/image-gen:图像生成基准,同样包含
ia3--flux2-klein-default.json结果文件,用于观察 IA3 在扩散类视觉任务上的表现。
这些工程使用统一的 default_training_params.json 与 Makefile 管理实验,可以直接作为横向对比 IA3 与 LoRA、全量微调等方法的实验脚手架。
总结
IA3 在 PEFT 中代表了一条"以最小参数代价换取接近全量微调性能"的路线:三个学习向量 lv、lk、lff 分别缩放 key、value 与第二个前馈层的激活,全 1 初始化保证训练起点与基础模型一致,向量可与权重合并实现零开销推理。配置时只需把握两个关键点——在 target_modules 中选定注入层,并在 feedforward_modules 中如实声明其中的前馈层。结合 IA3Config、IA3Model 与 layer.py 的源码阅读,你可以精确掌控可训练参数量,并借助仓库的示例与基准工程快速验证它在你的任务上的收益。