# PEFT[[transformers.integrations.PeftAdapterMixin]]

[PeftAdapterMixin](/docs/transformers/v5.23.0/zh/main_classes/peft#transformers.integrations.PeftAdapterMixin) 提供了来自 [PEFT](https://huggingface.co/docs/peft/index) 库的函数，用于在 Transformers 中管理适配器。该 mixin 支持所有非提示学习类的 PEFT 方法（LoRA、IA3、AdaLoRA 等）。前缀调优方法（prompt tuning、prompt learning）不受支持，因为它们无法注入到 torch 模块中。

#### transformers.integrations.PeftAdapterMixin[[transformers.integrations.PeftAdapterMixin]]

```python
transformers.integrations.PeftAdapterMixin()
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/integrations/peft.py#L57)

一个包含所有用于加载和使用 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[[transformers.integrations.PeftAdapterMixin.load_adapter]]

```python
load_adapter(peft_model_id: str | None = None, adapter_name: str | None = None, peft_config: dict[str, typing.Any] | None = None, adapter_state_dict: dict[str, 'torch.Tensor'] | None = None, low_cpu_mem_usage: bool = False, is_trainable: bool = False, hotswap: typing.Union[bool, typing.Literal['auto']] = 'auto', local_files_only: bool = False, adapter_kwargs: dict[str, typing.Any] | None = None, load_config: typing.Optional[ForwardRef('LoadStateDictConfig')] = None, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/integrations/peft.py#L80)

**参数：**

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]`, *可选*) : 要加载的 adapter 的 state dict。当用户直接传入 PEFT state dict 时，会使用此参数。

low_cpu_mem_usage (`bool`，*可选*，默认为 `False`)：在加载 PEFT 适配器时减少内存占用。这同时也能加快加载过程。

is_trainable (`bool`，*可选*，默认为 `False`)：适配器是否可训练。如果为 `False`，适配器将被冻结，仅可用于推理。

hotswap : (`"auto"` 或 `bool`，*可选*，默认为 `"auto"`) 是否就地用新加载的适配器替换现有的（LoRA）适配器。这意味着，不会加载额外的适配器，而是将现有适配器的权重替换为新适配器的权重。这种方式可能更快且更节省内存。然而，热替换的主要优势在于，当模型使用 torch.compile 编译时，加载新适配器无需重新编译模型。使用热替换时，传入的 `adapter_name` 应为已加载适配器的名称。 如果新适配器和旧适配器的秩（rank）和/或 LoRA alpha（即缩放系数）不同，在加载适配器之前需要调用一个额外方法：  ```py 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=True` 才能启用。如果先调用了 `enable_peft_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[[transformers.integrations.PeftAdapterMixin.add_adapter]]

```python
add_adapter(adapter_config, adapter_name: str | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/integrations/peft.py#L390)

**参数：**

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[[transformers.integrations.PeftAdapterMixin.set_adapter]]

```python
set_adapter(adapter_name: list[str] | str)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/integrations/peft.py#L430)

**参数：**

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

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

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

#### disable_adapters[[transformers.integrations.PeftAdapterMixin.disable_adapters]]

```python
disable_adapters()
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/integrations/peft.py#L471)

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

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

#### enable_adapters[[transformers.integrations.PeftAdapterMixin.enable_adapters]]

```python
enable_adapters()
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/integrations/peft.py#L490)

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

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

#### enable_peft_hotswap[[transformers.integrations.PeftAdapterMixin.enable_peft_hotswap]]

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

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/integrations/peft.py#L353)

**参数：**

target_rank (`int`，*可选*，默认为 `128`)：所有将加载的适配器中的最高秩。

check_compiled (`str`，*可选*，默认为 `"error"`)：当模型已被编译时如何处理，通常应避免这种情况。选项如下：- "error"（默认）：引发错误 - "warn"：发出警告 - "ignore"：不执行任何操作

允许热切换具有不同秩的 PEFT 适配器，或者，如果模型已编译，则在不触发重新编译的情况下进行切换。

目前，热替换仅支持 LoRA。

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

#### active_adapters[[transformers.integrations.PeftAdapterMixin.active_adapters]]

```python
active_adapters()
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/integrations/peft.py#L508)

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

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

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

#### get_adapter_state_dict[[transformers.integrations.PeftAdapterMixin.get_adapter_state_dict]]

```python
get_adapter_state_dict(adapter_name: str | None = None, state_dict: dict | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/integrations/peft.py#L537)

**参数：**

adapter_name (`str`, *可选*) : 要获取状态字典的适配器名称。如果未传入名称，则使用当前激活的适配器。

state_dict （嵌套字典，包含 `torch.Tensor`，*可选*）：模型的 state dictionary。默认值为 `self.state_dict()`，但在恢复模型 state dictionary 时需要采取特殊预防措施的情况下（例如使用模型并行时），可以使用此参数。

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

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

#### delete_adapter[[transformers.integrations.PeftAdapterMixin.delete_adapter]]

```python
delete_adapter(adapter_names: list[str] | str)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/integrations/peft.py#L622)

**参数：**

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

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

