PEFT 中的 IA3(Infused Adapter)完全指南:用三个学习向量实现最小 Adapter 的参数高效微调

原创2026-09-19 14:33:162,249 阅读
文章标签:人工智能大模型微调LoRA机器学习深度学习模型压缩

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 的源码阅读,你可以精确掌控可训练参数量,并借助仓库的示例与基准工程快速验证它在你的任务上的收益。

登录后查看全文
peft