PEFT documentation

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

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

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

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

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

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

inject_adapter_in_model не поддерживает методы PEFT, которые сохраняют состояние адаптера общим для нескольких целевых слоёв. В настоящее время это включает TinyLoRA, UniLoRA, VeRA, PVeRA, VBLoRA и FRoD. Для этих методов используйте вместо этого get_peft_model().

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

Для выполнения инъекции адаптера используйте метод inject_adapter_in_model(). Этот метод принимает три аргумента: конфигурацию PEFT, модель и необязательное имя адаптера. Вы также можете подключить к модели несколько адаптеров, если вызовите inject_adapter_in_model() несколько раз с разными именами адаптеров.

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

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)

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

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() и передать загруженный state_dict в качестве аргумента:

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(), как описано ниже.

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

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

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

Чтобы сохранить только адаптер, используйте функцию get_peft_model_state_dict():

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():

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(). Для этого передайте low_cpu_mem_usage=True в обе функции: inject_adapter_in_model() и set_peft_model_state_dict().

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():

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(), чтобы переводить между двумя схемами именования:

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() возвращает живые тензоры модели, а не их копии.

Update on GitHub