Adapters

用于参数高效且模块化迁移学习的统一库

官网   •   文档   •   论文

Adapters 是 HuggingFace's Transformers 的一个附加库，它将 10 多种适配器方法 集成到 20 多种最先进的 Transformer 模型 中，同时在训练和推理过程中只需极少的代码开销。

Adapters 提供了一个统一的接口，用于高效的微调和模块化的迁移学习，支持多种功能，例如全精度或量化训练（如 Q-LoRA、Q-Bottleneck Adapters 或 Q-PrefixTuning）、通过任务算术进行 适配器合并，或者通过 组合块 组合多个适配器，从而为自然语言处理任务中的参数高效迁移学习研究提供了可能。

注意：Adapters 库已取代了 adapter-transformers 包。所有先前训练好的适配器都与新库兼容。有关迁移说明，请参阅：https://docs.adapterhub.ml/transitioning.html。

安装

adapters 目前支持 Python 3.9+ 和 PyTorch 2.0+。 在 安装 PyTorch 后，您可以从 PyPI 安装 adapters ...

pip install -U adapters

... 或者通过克隆仓库从源代码安装：

git clone https://github.com/adapter-hub/adapters.git
cd adapters
pip install .

快速入门

加载预训练适配器：

from adapters import AutoAdapterModel
from transformers import AutoTokenizer

model = AutoAdapterModel.from_pretrained("roberta-base")
tokenizer = AutoTokenizer.from_pretrained("roberta-base")

model.load_adapter("AdapterHub/roberta-base-pf-imdb", source="hf", set_active=True)

print(model(**tokenizer("This works great!", return_tensors="pt")).logits)

了解更多

适应现有模型设置：

import adapters
from transformers import AutoModelForSequenceClassification

model = AutoModelForSequenceClassification.from_pretrained("t5-base")

adapters.init(model)

model.add_adapter("my_lora_adapter", config="lora")
model.train_adapter("my_lora_adapter")

# 您的常规训练循环...

了解更多

灵活配置适配器：

from adapters import ConfigUnion, PrefixTuningConfig, ParBnConfig, AutoAdapterModel

model = AutoAdapterModel.from_pretrained("microsoft/deberta-v3-base")

adapter_config = ConfigUnion(
    PrefixTuningConfig(prefix_length=20),
    ParBnConfig(reduction_factor=4),
)
model.add_adapter("my_adapter", config=adapter_config, set_active=True)

了解更多

轻松在一个模型中组合适配器：

from adapters import AdapterSetup, AutoAdapterModel
import adapters.composition as ac

model = AutoAdapterModel.from_pretrained("roberta-base")

qc = model.load_adapter("AdapterHub/roberta-base-pf-trec")
sent = model.load_adapter("AdapterHub/roberta-base-pf-imdb")

with AdapterSetup(ac.Parallel(qc, sent)):
    print(model(**tokenizer("What is AdapterHub?", return_tensors="pt")))

了解更多

有用资源

HuggingFace 关于如何开始使用 Transformers 的优秀文档可以在这里找到：https://huggingface.co/transformers/index.html。adapters 与 Transformers 完全兼容。

要开始使用适配器，请参考以下资源：

• Colab 笔记本教程，这是一系列笔记本，介绍了 (adapter-)transformers 和 AdapterHub 的所有主要概念。
• https://docs.adapterhub.ml，我们关于使用 adapters 训练和应用适配器的文档。
• https://adapterhub.ml，用于探索可用的预训练适配器模块并分享您自己的适配器。
• 此仓库的 示例文件夹，其中包含 HuggingFace 的示例训练脚本，许多已针对适配器训练进行了改编。

已实现的方法

目前，Adapters 集成了以下所有架构和方法：

方法	论文	快速链接
瓶颈适配器	Houlsby 等 (2019) Bapna 和 Firat (2019) Steitz 和 Roth (2024)	快速入门, 笔记本
AdapterFusion	Pfeiffer 等 (2021)	文档：训练, 笔记本
MAD-X, 可逆适配器	Pfeiffer 等 (2020)	笔记本
AdapterDrop	Rücklé 等 (2021)	笔记本
MAD-X 2.0, 嵌入训练	Pfeiffer 等 (2021)	文档：嵌入, 笔记本
前缀调优	Li 和 Liang (2021)	文档
并行适配器, 混搭适配器	He 等 (2021)	文档
Compacter	Mahabadi 等 (2021)	文档
LoRA	Hu 等 (2021)	文档
MTL-LoRA	Yang 等, 2024	文档
(IA)^3	Liu 等 (2022)	文档
Vera	Kopiczko 等, 2024	文档
DoRA	Liu 等, 2024	文档
UniPELT	Mao 等 (2022)	文档
提示调优	Lester 等 (2021)	文档
QLoRA	Dettmers 等 (2023)	笔记本
ReFT	Wu 等 (2024)	文档
适配器任务算术	Chronopoulou 等 (2023) Zhang 等 (2023)	文档, 笔记本

支持的模型

我们目前支持文档中 模型概览 页面上列出的所有模型的 PyTorch 版本。

开发与贡献

如需开始自行开发 Adapters 并了解如何参与贡献，请参阅 https://docs.adapterhub.ml/contributing.html。

引用

如果您在工作中使用了 Adapters，请考虑引用我们的库论文：Adapters: 用于参数高效且模块化迁移学习的统一库

@inproceedings{poth-etal-2023-adapters,
    title = "Adapters: A Unified Library for Parameter-Efficient and Modular Transfer Learning",
    author = {Poth, Clifton  and
      Sterz, Hannah  and
      Paul, Indraneil  and
      Purkayastha, Sukannya  and
      Engl{\"a}nder, Leon  and
      Imhof, Timo  and
      Vuli{\'c}, Ivan  and
      Ruder, Sebastian  and
      Gurevych, Iryna  and
      Pfeiffer, Jonas},
    booktitle = "Proceedings of the 2023 Conference on Empirical Methods in Natural Language Processing: System Demonstrations",
    month = dec,
    year = "2023",
    address = "Singapore",
    publisher = "Association for Computational Linguistics",
    url = "https://aclanthology.org/2023.emnlp-demo.13",
    pages = "149--160",
}

或者，对于其前身 adapter-transformers、Hub 基础设施以及由 AdapterHub 团队上传的适配器，请考虑引用我们的初始论文：AdapterHub: 用于调整 Transformer 的框架

@inproceedings{pfeiffer2020AdapterHub,
    title={AdapterHub: A Framework for Adapting Transformers},
    author={Pfeiffer, Jonas and
            R{\"u}ckl{\'e}, Andreas and
            Poth, Clifton and
            Kamath, Aishwarya and
            Vuli{\'c}, Ivan and
            Ruder, Sebastian and
            Cho, Kyunghyun and
            Gurevych, Iryna},
    booktitle={Proceedings of the 2020 Conference on Empirical Methods in Natural Language Processing: System Demonstrations},
    pages={46--54},
    year={2020}
}

Adapters 快速上手指南

Adapters 是一个基于 Hugging Face Transformers 的扩展库，旨在为自然语言处理任务提供统一、高效且模块化的参数微调（Parameter-Efficient Transfer Learning）解决方案。它支持 LoRA、Prefix Tuning、AdapterFusion 等 10+ 种主流微调方法，并兼容 20+ 种最先进的 Transformer 模型。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux, macOS 或 Windows
• Python 版本: 3.9 或更高
• PyTorch 版本: 2.0 或更高
• 前置依赖: 需先安装 PyTorch。

国内开发者提示：建议配置国内镜像源以加速依赖下载。

• PyTorch 安装参考：https://pytorch.org/get-started/locally/ (可选择国内镜像)
• pip 临时使用清华源：pip install -i https://pypi.tuna.tsinghua.edu.cn/simple ...

安装步骤

您可以选择通过 PyPI 直接安装，或从源代码安装。

方式一：通过 PyPI 安装（推荐）

pip install -U adapters

国内加速版：

pip install -U adapters -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：从源代码安装

git clone https://github.com/adapter-hub/adapters.git
cd adapters
pip install .

基本使用

Adapters 的设计初衷是极简集成。以下是两种最常用的场景：加载预训练 Adapter 和对现有模型添加 Adapter。

场景 1：加载并使用预训练 Adapter

直接加载 Hugging Face Hub 上已有的适配器模型进行推理。

from adapters import AutoAdapterModel
from transformers import AutoTokenizer

# 加载基础模型和分词器
model = AutoAdapterModel.from_pretrained("roberta-base")
tokenizer = AutoTokenizer.from_pretrained("roberta-base")

# 加载预训练适配器 (例如：IMDB 情感分析)
# source="hf" 表示从 Hugging Face Hub 加载
model.load_adapter("AdapterHub/roberta-base-pf-imdb", source="hf", set_active=True)

# 执行推理
inputs = tokenizer("This works great!", return_tensors="pt")
outputs = model(**inputs)
print(outputs.logits)

场景 2：为现有模型添加并训练 Adapter

将任意支持的 Transformers 模型转换为可训练 Adapter 的模式，并以 LoRA 为例进行配置。

import adapters
from transformers import AutoModelForSequenceClassification

# 加载标准 Transformers 模型
model = AutoModelForSequenceClassification.from_pretrained("t5-base")

# 初始化 adapters 支持
adapters.init(model)

# 添加一个新的 adapter，指定方法为 "lora"
model.add_adapter("my_lora_adapter", config="lora")

# 设置该 adapter 为训练状态（冻结其他参数，仅训练 adapter 部分）
model.train_adapter("my_lora_adapter")

# 接下来即可使用您常规的训练循环进行训练
# for batch in dataloader:
#     outputs = model(**batch)
#     loss = outputs.loss
#     loss.backward()
#     ...

进阶：灵活组合多个 Adapter

Adapters 支持通过简单的上下文管理器组合多个适配器（例如并行执行不同任务的适配器）。

from adapters import AdapterSetup, AutoAdapterModel
import adapters.composition as ac
from transformers import AutoTokenizer

model = AutoAdapterModel.from_pretrained("roberta-base")
tokenizer = AutoTokenizer.from_pretrained("roberta-base")

# 加载两个不同的适配器
qc_adapter = model.load_adapter("AdapterHub/roberta-base-pf-trec")
sent_adapter = model.load_adapter("AdapterHub/roberta-base-pf-imdb")

# 使用 Parallel 块并行运行这两个适配器
with AdapterSetup(ac.Parallel(qc_adapter, sent_adapter)):
    inputs = tokenizer("What is AdapterHub?", return_tensors="pt")
    outputs = model(**inputs)
    print(outputs)

更多详细文档、Colab 教程及支持的模型列表，请访问 官方文档。