PEFT

PeftAdapterMixin 提供了来自 PEFT 库的函数，用于在 Transformers 中管理适配器。该 mixin 支持所有非提示学习类的 PEFT 方法（LoRA、IA3、AdaLoRA 等）。前缀调优方法（prompt tuning、prompt learning）不受支持，因为它们无法注入到 torch 模块中。

class transformers.integrations.PeftAdapterMixin

< source >

( )

一个包含所有用于加载和使用 PEFT 库支持的适配器权重的函数的类。有关适配器及其在基于 Transformer 的模型上注入的更多详细信息，请参阅 PEFT 库的文档：https://huggingface.co/docs/peft/index

目前支持的 PEFT 方法均为非提示学习方法（如 LoRA、IA³ 等）。其他 PEFT 模型（如 prompt tuning、prompt learning）不在讨论范围内，因为这些适配器无法“注入”到 torch 模块中。如需使用这些方法，请参阅 PEFT 库的使用指南。

使用此混入类，如果安装了正确版本的 PEFT（>= 0.20.0），则可以：

从本地路径或远程 Hub 仓库加载适配器，并将其注入到模型中
在模型中附加新的适配器，并使用 Trainer 或自行编写代码进行训练。
附加多个适配器并迭代地激活/停用它们
激活/停用模型中的所有适配器。
获取当前激活适配器的 state_dict。

load_adapter

< source >

( peft_model_id: str | None = Noneadapter_name: str | None = Nonepeft_config: dict[str, typing.Any] | None = Noneadapter_state_dict: dict[str, 'torch.Tensor'] | None = Nonelow_cpu_mem_usage: bool = Falseis_trainable: bool = Falsehotswap: typing.Union[bool, typing.Literal['auto']] = 'auto'local_files_only: bool = Falseadapter_kwargs: dict[str, typing.Any] | None = Noneload_config: typing.Optional[ForwardRef('LoadStateDictConfig')] = None**kwargs )

参数

peft_model_id (str, 可选) — 用于在 Hub 上查找模型的标识符，或指向已保存的适配器配置文件和适配器权重的本地路径。
adapter_name (str, 可选) — 要使用的适配器名称。如果未设置，将使用名称 “default”。
load_config (LoadStateDictConfig，可选) — 用于在拉取适配器权重时复用的加载配置，通常来自 from_pretrained。
kwargs (dict[str, Any]，可选) — 作为关键字参数传递的额外 LoadStateDictConfig 字段。
peft_config (dict[str, Any], 可选) — 要添加的适配器的配置，支持的适配器包括所有非提示学习配置（LoRA、IA³ 等）。当用户直接传入 PEFT 状态字典时，会使用此参数。
adapter_state_dict (dict[str, torch.Tensor], 可选) — 要加载的适配器的状态字典。当用户直接传入 PEFT 状态字典时，会使用此参数。
low_cpu_mem_usage（bool，可选，默认为 False）— 在加载 PEFT 适配器时降低内存占用。这同时也能加快加载过程。
is_trainable (bool，可选，默认为 False) — 适配器是否可训练。如果为 False，适配器将被冻结，仅可用于推理。
hotswap — ("auto" or bool, optional, defaults to "auto") Whether to substitute an existing (LoRA) adapter with the newly loaded adapter in-place. This means that, instead of loading an additional adapter, this will take the existing adapter weights and replace them with the weights of the new adapter. This can be faster and more memory efficient. However, the main advantage of hotswapping is that when the model is compiled with torch.compile, loading the new adapter does not require recompilation of the model. When using hotswapping, the passed adapter_name should be the name of an already loaded adapter.
如果新适配器和旧适配器的秩和/或 LoRA alpha（即缩放）不同，则在加载适配器之前需要调用一个额外的方法：
```
model = AutoModel.from_pretrained(...)
max_rank = ...  # the highest rank among all LoRAs that you want to load
# call *before* compiling and loading the LoRA adapter
model.enable_peft_hotswap(target_rank=max_rank)
model.load_adapter(file_name_1, adapter_name="default")
# optionally compile the model now
model = torch.compile(model, ...)
output_1 = model(...)
# now you can hotswap the 2nd adapter, use the same name as for the 1st
# hotswap is activated by default since enable_peft_hotswap was called
model.load_adapter(file_name_2, adapter_name="default")
output_2 = model(...)
```
默认情况下，hotswap 处于禁用状态，需要传入 hotswap=True 才能启用。如果您先调用了 enable_peft_hotswap，则 hotswap 已启用。在这种情况下，您仍可通过传入 hotswap=False 手动将其禁用。

请注意，热替换存在一些限制，详见此处： https://huggingface.co/docs/peft/main/en/package_reference/hotswap
adapter_kwargs (dict[str, Any], 可选) — 传递给适配器配置的 from_pretrained 方法和 find_adapter_config_file 方法的额外关键字参数。

从文件或远程 Hub 文件夹加载适配器权重。如果您对适配器和 PEFT 方法不熟悉，我们邀请您阅读 PEFT 官方文档以了解更多： https://huggingface.co/docs/peft

需要安装 PEFT 作为后端以加载适配器权重。

add_adapter

< source >

( adapter_configadapter_name: str | None = None )

参数

adapter_config (~peft.PeftConfig) — 要添加的适配器的配置，支持的适配器为非提示学习方法（LoRA、IA³ 等）。
adapter_name (str，可选，默认为 "default") — 要添加的适配器名称。如果未传入名称，则会为适配器分配一个默认名称。

如果您对适配器和 PEFT 方法不熟悉，我们邀请您阅读 PEFT 官方文档以了解更多： https://huggingface.co/docs/peft

为当前模型添加一个新的适配器，用于训练目的。如果未传入适配器名称，则会为该适配器分配一个默认名称，以遵循 PEFT 库的约定（在 PEFT 中，我们使用“default”作为默认适配器名称）。

请注意，新添加的适配器不会自动激活。要激活它，请使用 model.set_adapter。

set_adapter

< source >

( adapter_name: list[str] | str )

参数

adapter_name (Union[list[str], str]) — 要设置的适配器名称。也可以是一个字符串列表，用于设置多个适配器。

如果您对适配器和 PEFT 方法不熟悉，我们邀请您阅读 PEFT 官方文档以了解更多： https://huggingface.co/docs/peft

通过强制模型使用该适配器并禁用其他适配器，来设置特定的适配器。

disable_adapters

< source >

( )

如果您对适配器和 PEFT 方法不熟悉，我们邀请您阅读 PEFT 官方文档以了解更多： https://huggingface.co/docs/peft

禁用所有附加到模型上的适配器。这将导致仅使用基础模型进行推理。

enable_adapters

< source >

( )

如果您对适配器和 PEFT 方法不熟悉，我们邀请您阅读 PEFT 官方文档以了解更多： https://huggingface.co/docs/peft

启用附加到模型的适配器。

enable_peft_hotswap

< source >

( target_rank: int = 128check_compiled: typing.Literal['error', 'warn', 'ignore'] = 'error' )

参数

target_rank (int，可选，默认为 128) — 所有将加载的适配器中的最高秩。
check_compiled (str, 可选, 默认为 "error") — 当模型已被编译时如何处理，通常应避免这种情况。可选值：
- “error”（默认值）：引发错误
- “warn”：发出警告
- “ignore”：不执行任何操作

允许热切换具有不同秩的 PEFT 适配器，或者，如果模型已编译，则无需触发重新编译。

目前，热替换仅支持 LoRA。

仅在热切换适配器且模型已编译，或所加载适配器的秩不同时，才需要调用此方法。如果所有适配器的秩均相同且模型未编译，则无需先调用此方法即可直接进行热切换。

active_adapters

< source >

( )

如果您对适配器和 PEFT 方法不熟悉，我们邀请您阅读 PEFT 官方文档以了解更多： https://huggingface.co/docs/peft

获取模型当前激活的适配器。在适配器多路推理（组合多个适配器进行推理）的情况下，返回所有激活适配器的列表，以便用户相应地处理它们。

对于不支持多适配器推理的早期 PEFT 版本，module.active_adapter 将返回一个字符串。

get_adapter_state_dict

< source >

( adapter_name: str | None = Nonestate_dict: dict | None = None )

参数

adapter_name (str, 可选) — 要从中获取 state dict 的适配器名称。如果未传入名称，则使用当前激活的适配器。
state_dict（torch.Tensor 的嵌套字典，可选）— 模型的 state dictionary。默认使用 self.state_dict()，但在恢复模型 state dictionary 时需要采取特殊预防措施（例如使用模型并行时）的情况下，可以使用此参数。

如果您对适配器和 PEFT 方法不熟悉，我们邀请您阅读 PEFT 官方文档以了解更多： https://huggingface.co/docs/peft

获取适配器状态字典，该字典应仅包含指定 adapter_name 适配器的权重张量。如果未传入 adapter_name，则使用当前激活的适配器。

delete_adapter

< source >

( adapter_names: list[str] | str )

参数

adapter_names (Union[list[str], str]) — 要删除的适配器名称。

从基础模型中删除 PEFT 适配器。

Update on GitHub