# Инъекция адаптеров

С помощью PEFT вы можете внедрять обучаемые адаптеры в любой модуль `torch`, что позволяет использовать методы адаптеров без зависимости от классов моделирования в PEFT. Это работает для всех адаптеров, кроме тех, что основаны на обучении промптов (например, prefix tuning или p-tuning), и адаптеров, сохраняющих состояние, разделяемое между несколькими целевыми слоями.

Ознакомьтесь с таблицей ниже, чтобы узнать, когда следует внедрять адаптеры.

| Преимущества | Недостатки |
|---|---|
| модель изменяется на месте, сохраняя все исходные атрибуты и методы | вручную написать утилитарные функции `from_pretrained` и `save_pretrained` из Hugging Face для сохранения и загрузки адаптеров |
| работает с любым модулем `torch` и модальностью | не работает ни с одним из вспомогательных методов, предоставляемых `PeftModel`, таких как отключение и объединение адаптеров |

> [!WARNING]
> `inject_adapter_in_model` не поддерживает методы PEFT, которые сохраняют состояние адаптера общим для нескольких целевых слоёв. В настоящее время это включает TinyLoRA, UniLoRA, VeRA, PVeRA, VBLoRA и FRoD. Для этих методов используйте вместо этого [get_peft_model()](/docs/peft/v0.22.0/ru/package_reference/peft_model#peft.get_peft_model).

## Создание новой модели PEFT

Для выполнения инъекции адаптера используйте метод [inject_adapter_in_model()](/docs/peft/v0.22.0/ru/package_reference/peft_model#peft.inject_adapter_in_model). Этот метод принимает три аргумента: конфигурацию PEFT, модель и необязательное имя адаптера. Вы также можете подключить к модели несколько адаптеров, если вызовите [inject_adapter_in_model()](/docs/peft/v0.22.0/ru/package_reference/peft_model#peft.inject_adapter_in_model) несколько раз с разными именами адаптеров.

Например, чтобы внедрить адаптеры LoRA в подмодуль `linear` модуля `DummyModel`:

```python
import torch
from peft import inject_adapter_in_model, LoraConfig

class DummyModel(torch.nn.Module):
    def __init__(self):
        super().__init__()
        self.embedding = torch.nn.Embedding(10, 10)
        self.linear = torch.nn.Linear(10, 10)
        self.lm_head = torch.nn.Linear(10, 10)

    def forward(self, input_ids):
        x = self.embedding(input_ids)
        x = self.linear(x)
        x = self.lm_head(x)
        return x

lora_config = LoraConfig(
    lora_alpha=16,
    lora_dropout=0.1,
    r=64,
    bias="none",
    target_modules=["linear"],
)

model = DummyModel()
model = inject_adapter_in_model(lora_config, model)

dummy_inputs = torch.LongTensor([[0, 1, 2, 3, 4, 5, 6, 7]])
dummy_outputs = model(dummy_inputs)
```

Выведите модель, чтобы убедиться, что адаптеры были корректно внедрены.

```bash
DummyModel(
  (embedding): Embedding(10, 10)
  (linear): Linear(
    in_features=10, out_features=10, bias=True
    (lora_dropout): ModuleDict(
      (default): Dropout(p=0.1, inplace=False)
    )
    (lora_A): ModuleDict(
      (default): Linear(in_features=10, out_features=64, bias=False)
    )
    (lora_B): ModuleDict(
      (default): Linear(in_features=64, out_features=10, bias=False)
    )
    (lora_embedding_A): ParameterDict()
    (lora_embedding_B): ParameterDict()
  )
  (lm_head): Linear(in_features=10, out_features=10, bias=True)
)
```

### Инъекция на основе `state_dict`

Иногда может оказаться, что есть контрольная точка адаптера PEFT, но соответствующая конфигурация PEFT по какой-либо причине неизвестна. Чтобы внедрить слои PEFT для этой контрольной точки, обычно приходится восстанавливать соответствующую конфигурацию PEFT, в первую очередь аргумент `target_modules`, на основе `state_dict` из контрольной точки. Это может быть затруднительно и подвержено ошибкам. Чтобы избежать этого, можно также вызвать [inject_adapter_in_model()](/docs/peft/v0.22.0/ru/package_reference/peft_model#peft.inject_adapter_in_model) и передать загруженный `state_dict` в качестве аргумента:

```python
from safetensors.torch import load_file

model = ...
state_dict = load_file(<path-to-safetensors-file>)
lora_config = LoraConfig(...)
model = inject_adapter_in_model(lora_config, model, state_dict=state_dict)
```

В этом случае PEFT будет использовать `state_dict` в качестве ориентира для определения целевых слоёв, а не конфигурацию PEFT. Вам как пользователю не нужно указывать точные `target_modules` в конфигурации PEFT, чтобы это сработало. Однако вы всё равно должны передать конфигурацию PEFT правильного типа, в данном примере `LoraConfig`, при этом `target_modules` можно оставить как `None`.

Обратите внимание, что на этом этапе создаются только неинициализированные слои PEFT, значения из `state_dict` не используются для заполнения весов модели. Чтобы заполнить веса, продолжите с вызовом [set_peft_model_state_dict()](/docs/peft/v0.22.0/ru/package_reference/functional#peft.set_peft_model_state_dict), как описано ниже.

⚠️ Обратите внимание, что при несоответствии между настройками, указанными в конфигурации PEFT, и содержимым `state_dict`, PEFT выдаст предупреждение. Вы можете проигнорировать это предупреждение, если уверены, что конфигурация PEFT указана неверно.

> [!WARNING]
> Если исходные адаптеры PEFT использовали `target_parameters` вместо `target_modules`, инъекция из `state_dict` не будет работать корректно. В этом случае обязательно используйте правильную конфигурацию PEFT для инъекции.

## Сохранение модели

Чтобы сохранить только адаптер, используйте функцию [get_peft_model_state_dict()](/docs/peft/v0.22.0/ru/package_reference/peft_model#peft.get_peft_model_state_dict):

```python
from peft import get_peft_model_state_dict

peft_state_dict = get_peft_model_state_dict(model)
print(peft_state_dict)
```

В противном случае `model.state_dict()` возвращает полный state dict модели.

## Загрузка модели

После загрузки сохранённого `state_dict` его можно применить с помощью функции [set_peft_model_state_dict()](/docs/peft/v0.22.0/ru/package_reference/functional#peft.set_peft_model_state_dict):

```python
from peft import set_peft_model_state_dict

model = DummyModel()
model = inject_adapter_in_model(lora_config, model)
outcome = set_peft_model_state_dict(model, peft_state_dict)
# check that there were no wrong keys
print(outcome.unexpected_keys)
```

Если внедрение адаптера выполняется медленно или необходимо загрузить большое количество адаптеров, можно использовать оптимизацию, позволяющую создать «пустой» адаптер на meta-устройстве и заполнить веса реальными значениями только при вызове [set_peft_model_state_dict()](/docs/peft/v0.22.0/ru/package_reference/functional#peft.set_peft_model_state_dict). Для этого передайте `low_cpu_mem_usage=True` в обе функции: [inject_adapter_in_model()](/docs/peft/v0.22.0/ru/package_reference/peft_model#peft.inject_adapter_in_model) и [set_peft_model_state_dict()](/docs/peft/v0.22.0/ru/package_reference/functional#peft.set_peft_model_state_dict).

```python
model = DummyModel()
model = inject_adapter_in_model(lora_config, model, low_cpu_mem_usage=True)

print(model.linear.lora_A["default"].weight.device.type == "meta")  # should be True
set_peft_model_state_dict(model, peft_state_dict, low_cpu_mem_usage=True)
print(model.linear.lora_A["default"].weight.device.type == "cpu")  # should be True
```

Для загрузки весов с хабa существует низкоуровневая функция `load_peft_weights()`:

```python
state_dict = load_peft_weights("my-account/my-adapter-repo")
```

## Установка и загрузка базовых весов

Функции выше работают со state dict *адаптера*. Однако существуют ситуации, когда веса *базовой модели* необходимо читать или записывать через обёртку PEFT. Это не совсем тривиальная задача, поскольку PEFT переименовывает параметры целевых модулей (например, `q_proj.weight` становится `q_proj.base_layer.weight`) и добавляет параметры адаптера, которых нет в базовой модели. Используйте `get_base_model_state_dict()` и `set_base_model_state_dict()`, чтобы переводить между двумя способами именования:

```python
from peft import LoraConfig, get_peft_model, get_base_model_state_dict, set_base_model_state_dict
from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained("facebook/opt-125m")
model = get_peft_model(model, LoraConfig(target_modules="all-linear"))

# state dict with the original (pre-PEFT) key names, adapter parameters excluded
base_state_dict = get_base_model_state_dict(model)

# load a state dict with original key names into the PEFT-wrapped model
outcome = set_base_model_state_dict(model, base_state_dict, strict=False)
# check that there were no wrong keys
print(outcome.missing_keys, outcome.unexpected_keys)
```

Основной сценарий использования — загрузка базовых весов *после* того, как модель уже была обёрнута PEFT. Например, конфигурации обучения FSDP, такие как TorchTitan, инициализируют модель на meta-устройстве, применяют PEFT и разбивают результат на шарды. Реальная память существует только после шардирования, поэтому чекпоинт, ключи которого используют исходные имена, должен быть загружен в уже обёрнутую модель. Обратите внимание, что `get_base_model_state_dict()` возвращает живые тензоры модели, а не их копии.

