LoRA

LoRA — один из самых популярных методов PEFT и хорошая отправная точка, если вы только начинаете работать с PEFT. Изначально он был разработан для больших языковых моделей, но стал чрезвычайно популярным методом обучения для диффузионных моделей благодаря своей эффективности и результативности.

Метод адапции низкого ранга (LoRA) — это метод PEFT, который разлагает большую матрицу на две более мелкие матрицы низкого ранга. Это значительно сокращает количество параметров, требующих дообучения.

Аннотация из статьи:

Важная парадигма обработки естественного языка заключается в крупномасштабном предобучении на данных общей предметной области и адаптации к конкретным задачам или доменам. По мере того как мы предобучаем более крупные модели, полная дообучка, при которой пересчитываются все параметры модели, становится всё менее осуществимой. Возьмём, например, GPT-3 175B: развёртывание независимых экземпляров дообученных моделей, каждая из которых содержит 175 млрд параметров, является prohibitively expensive. Мы предлагаем Low-Rank Adaptation, или LoRA, которая замораживает веса предобученной модели и внедряет обучаемые матрицы разложения с низким рангом в каждый слой архитектуры Transformer, что значительно сокращает количество обучаемых параметров для downstream-задач. По сравнению с GPT-3 175B, дообученным с помощью Adam, LoRA позволяет сократить количество обучаемых параметров в 10 000 раз, а требования к памяти GPU — в 3 раза. LoRA демонстрирует качество модели, сопоставимое с полным дообучением или превосходящее его, на RoBERTa, DeBERTa, GPT-2 и GPT-3, несмотря на меньшее количество обучаемых параметров, более высокую пропускную способность обучения и, в отличие от адаптеров, отсутствие дополнительных задержек при инференсе. Мы также проводим эмпирическое исследование ранговой недостаточности при адаптации языковых моделей, что проливает свет на эффективность LoRA. Мы выпускаем пакет, облегчающий интеграцию LoRA с моделями PyTorch, и предоставляем наши реализации и контрольные точки моделей для RoBERTa, DeBERTa и GPT-2 по этой ссылке.

LoRA представляет собой обновления весов $\Delta W$ с помощью двух матриц меньшего размера (называемых матрицами обновления) ) посредством разложения низкого ранга. Эти новые матрицы можно обучать для адаптации к новым данным, сохраняя общее количество параметров на низком уровне. Исходная матрица весов остаётся замороженной и не получает дальнейших обновлений. Для получения окончательных результатов исходные и дополнительные адаптированные веса объединяются. Также можно объединить веса адаптера с базовой моделью, чтобы устранить задержку при выводе.

Этот подход имеет ряд преимуществ:

• LoRA делает дообучение более эффективным, значительно сокращая количество обучаемых параметров.
• Исходные предобученные веса остаются замороженными, что позволяет создавать множество лёгких и переносимых моделей LoRA для различных задач, построенных на их основе.
• LoRA ортогональна другим параметрически эффективным методам и может сочетаться со многими из них.
• Производительность моделей, дообученных с использованием LoRA, сопоставима с производительностью полностью дообученных моделей.

В принципе, LoRA можно применять к любому подмножеству матриц весов в нейронной сети, чтобы сократить количество обучаемых параметров. Однако ради простоты и дальнейшей эффективности по параметрам LoRA обычно применяется только к блокам внимания в моделях Transformer — возможно, стоит также обратить внимание на другие слои. Итоговое количество обучаемых параметров в модели LoRA зависит от размера матриц обновления, который определяется в основном рангом r и формой исходной матрицы весов.

Вы можете инициализировать матрицы низкого ранга с учётом различных задач — осведомлённость о задаче (CorDA, EVA, Astra), более быстрая сходимость (PiSSA), смягчение эффектов квантования (LoftQ) — это лишь некоторые примеры. Подробнее о различных способах инициализации читайте ниже. Инициализация по умолчанию настроена так, чтобы LoRA изначально не изменяла модель (no-op), позволяя постепенно обучать новое поведение, минимально вмешиваясь в работу существующей модели.

Использование

Размер матриц низкорангового обновления определяется параметром rank или r. Чем выше ранг, тем больше параметров модели подлежит обучению, но и тем выше её способность к обучению. В следующем примере вы нацеливаетесь на матрицы query и value блоков внимания. Другие важные параметры, которые необходимо задать: lora_alpha (коэффициент масштабирования), bias (обучать ли none, all или только параметры смещения LoRA), и modules_to_save (модули, помимо слоёв LoRA, которые нужно обучить и сохранить). Все эти параметры — и другие — описаны в LoraConfig.

from peft import LoraConfig, get_peft_model

config = LoraConfig(
    r=16,
    lora_alpha=16,
    target_modules=["query", "value"],
    lora_dropout=0.1,
    bias="none",
    modules_to_save=["classifier"],
)
model = get_peft_model(model, config)
model.print_healthcheck()

Обзор бенчмарков

Инициализация

Инициализация весов LoRA управляется параметром init_lora_weights в LoraConfig. По умолчанию PEFT инициализирует веса LoRA методом Kaiming-uniform для веса A и нулями для веса B, что приводит к тождественному преобразованию (как в эталонной реализации).

Для слоёв transformers.Conv1D, таких как проекции в GPT-2, используйте fan_in_fan_out=True, поскольку их веса хранятся в формате (in_features, out_features), а не в раскладке nn.Linear. Поддерживаемые инициализаторы на основе весов используют раскладку Linear для декомпозиции и восстанавливают исходный формат хранения при обновлении базовых весов. Масштабирование "stable" в LoRA-GA также использует выходное измерение независимо от формата хранения.

Также можно передать init_lora_weights="gaussian". Как следует из названия, это инициализирует веса A с помощью гауссова распределения, а веса B — нулями (именно так Diffusers инициализирует веса LoRA).

from peft import LoraConfig

config = LoraConfig(init_lora_weights="gaussian", ...)

Также существует вариант установить init_lora_weights=False, который полезен для отладки и тестирования. Это должен быть единственный случай, когда вы используете этот параметр. При выборе этого варианта веса LoRA инициализируются таким образом, что они не приводят к тождественному преобразованию.

from peft import LoraConfig

config = LoraConfig(init_lora_weights=False, ...)

from torch import nn

from peft import LoraConfig, get_peft_model

model = nn.Sequential(
    nn.Linear(32, 32),
    nn.ReLU(),
    nn.Linear(32, 16),
)

config = LoraConfig(
    r=8,
    lora_alpha=8,
    target_modules=["0", "2"],
    init_lora_weights="nora",
    bias="none",
    lora_bias=False,
    use_rslora=False,
)
model = get_peft_model(model, config)
model.print_healthcheck()

from peft import LoraConfig
config = LoraConfig(init_lora_weights="pissa", ...)

lora_config = LoraConfig(init_lora_weights="pissa_niter_[number of iters]", ...)

from peft import LoraConfig
config = LoraConfig(init_lora_weights="mica", r=16, target_modules=["q_proj", "v_proj"], ...)

@torch.no_grad()
def run_model():
    # Assume `model` and `dataset` is in context...
    model.eval()
    for batch in dataset:
        model(**batch)


corda_config = CordaConfig(
    corda_method="kpm",
)
lora_config = LoraConfig(
    init_lora_weights="corda",
    corda_config=corda_config,
)
preprocess_corda(model, lora_config, run_model=run_model)
peft_model = get_peft_model(model, lora_config)

@torch.no_grad()
def run_model():
    # Assume `model` and `dataset` is in context...
    model.eval()
    for batch in dataset:
        model(**batch)


from peft.tuners.lora import AstraConfig, preprocess_astra

astra_config = AstraConfig()
lora_config = LoraConfig(
    init_lora_weights="astra",
    target_modules=["q_proj", "v_proj"],
    astra_config=astra_config,
)
preprocess_astra(model, lora_config, run_model=run_model)
peft_model = get_peft_model(model, lora_config)

from peft import LoraConfig
config = LoraConfig(init_lora_weights="olora", ...)

from peft import LoraConfig, EvaConfig
peft_config = LoraConfig(
    init_lora_weights = "eva",
    eva_config = EvaConfig(rho = 2.0),
    ...
)

peft_model = get_peft_model(model, peft_config, low_cpu_mem_usage=True)

initialize_lora_eva_weights(peft_model, dataloader)

from peft import LoraConfig

config = LoraConfig(use_rslora=True, ...)

from peft.tuners.lora import preprocess_loraga

def train_step():
    """Run forward and backward passes for gradient estimation."""
    dataloader_iter = iter(grad_dataloader)
    for _ in range(N):
        batch = next(dataloader_iter)
        batch = {k: v.to(device) for k, v in batch.items()}
        outputs = model(**batch)
        loss = outputs.loss
        loss.backward()

preprocess_loraga(model, lora_config, train_step)

Обучение

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

Обучение в стиле QLoRA

Настройки LoRA по умолчанию в PEFT добавляют обучаемые веса в слои запросов и значений каждого блока внимания. Однако QLoRA, который добавляет обучаемые веса во все линейные слои трансформерной модели, способен обеспечить производительность, сопоставимую с полностью дообученной моделью. Чтобы применить LoRA ко всем линейным слоям, как в QLoRA, установите target_modules="all-linear" (это проще, чем указывать отдельные модули по имени, которое может различаться в зависимости от архитектуры).

config = LoraConfig(target_modules="all-linear", ...)

Для получения дополнительной информации о том, как применить квантование к адаптерам PEFT, обратитесь к руководству по квантованию.

Эффективное по памяти дублирование слоёв с LoRA

Один из подходов к повышению производительности моделей заключается в расширении модели путём дублирования слоёв для построения более крупной модели на основе предобученной модели заданного размера. Например, увеличение модели 7B до 10B, как описано в статье SOLAR. PEFT LoRA поддерживает такой тип расширения с высокой эффективностью использования памяти, позволяя выполнять дальнейшую дообучение с помощью адаптеров LoRA, привязанных к слоям после их дублирования. Дублированные слои не требуют дополнительной памяти, поскольку они разделяют базовые веса, поэтому единственная дополнительная память, необходимая для этого, — это память для весов адаптеров. Для использования этой функции необходимо создать конфигурацию с аргументом layer_replication.

config = LoraConfig(layer_replication=[[0,4], [2,5]], ...)

Допустим, исходная модель содержала 5 слоёв [0, 1, 2 ,3, 4]. В этом случае будет создана модель с 7 слоями, расположенными в порядке [0, 1, 2, 3, 2, 3, 4]. Это соответствует конвенции сквозного слияния (pass through merge) в mergekit, согласно которой последовательности слоёв, заданные кортежами «начало включительно, конец исключая», складываются для построения итоговой модели. Каждый слой в итоговой модели получает собственный уникальный набор адаптеров LoRA.

Fewshot-Metamath-OrcaVicuna-Mistral-10B — это пример модели, обученной с использованием этого метода на базе Mistral-7B, расширенной до 10B. Файл adapter_config.json содержит пример конфигурации адаптера LoRA, применяющей этот метод для дообучения.

Тонкий контроль над рангами и альфа (масштабирование)

По умолчанию все слои, для которых применяется LoRA, имеют одинаковый ранг r и одинаковое значение lora_alpha (которое определяет масштабирование LoRA), в соответствии с тем, что указано в LoraConfig. Однако в некоторых случаях может потребоваться задать разные значения для разных слоёв. Это можно сделать, передав аргументы rank_pattern и alpha_pattern в LoraConfig. Эти аргументы должны быть словарями, где ключом является имя слоя, а значением — значение ранга/альфы. Ключами могут быть регулярные выражения (regex). Все слои LoRA, которые явно не указаны в rank_pattern и alpha_pattern, будут использовать значения по умолчанию r и lora_alpha.

В качестве примера предположим, что у нас есть модель со следующей структурой:

>>> print(model)
Outer(
  (foo): Linear(...)
  (module): Middle(
    (foo): Linear(...)
    (foobar): Linear(...)
    (module): Inner(
      (foo): Linear(...)
      (barfoo): Linear(...)
    )
  )
)

• rank_pattern={"foo": 42} будет соответствовать всем 3 слоям foo. Ни foobar, ни barfoo не совпадают.
• rank_pattern={"^foo": 42} будет соответствовать только слою foo модели, но не module.foo и не module.module.foo. Это связано с тем, что ^ в регулярных выражениях означает «начало строки», и только foo начинается с "foo", а у остальных имён слоёв есть префиксы.
• rank_pattern={"^module.foo": 42} совпадает только с module.foo, но не с module.module.foo, по той же причине.
• rank_pattern={"module.foo": 42} совпадает как с module.foo, так и с module.module.foo, но не с foo.
• rank_pattern={"^foo": 42, "^module.module.foo": 55} соответствует foo и module.module.foo соответственно, но не module.foo.
• Нет необходимости указывать $ для обозначения конца совпадения, так как PEFT добавляет его автоматически.

Та же логика применима к alpha_pattern. Если вы сомневаетесь, не пытайтесь усложнять с помощью регулярных выражений — просто передайте полное имя каждого модуля с другим рангом/альфой, предваряя его префиксом ^, и всё будет в порядке.

Автоматическое обнаружение подходящих целевых модулей

peft.helpers.KappaTuneSelector реализует стратегию выбора целевых слоёв на основе числа обусловленности, описанную в статье KappaTune. Она просматривает каждый модуль nn.Linear и, для моделей, в которых веса экспертов MoE хранятся как объединённые 3D-тензоры nn.Parameter (например, Llama-4, Qwen3-MoE), также эти параметры, вычисляет для каждого число обусловленности матрицы κ = σ_max / σ_min и выбирает наиболее изотропные слои (с наименьшим κ). Эти изотропные слои являются идеальными кандидатами для дообучения, поскольку их высокая энтропия позволяет им легче усваивать новую информацию, оставляя специализированные анизотропные слои нетронутыми для снижения катастрофического забывания при непрерывном обучении.

Используйте peft.helpers.find_kappa_target_modules() как однострочник, чтобы получить оптимальные target_modules для LoraConfig:

from peft import LoraConfig, get_peft_model
from peft.helpers import find_kappa_target_modules

model = AutoModelForCausalLM.from_pretrained("mistralai/Mixtral-8x7B-Instruct-v0.1")

targets = find_kappa_target_modules(model, top_p=0.2)
config = LoraConfig(
    target_modules=targets["target_modules"],
    target_parameters=targets["target_parameters"] if stable_modules_dic["target_parameters"] else None,
    r=64,
    lora_alpha=32,
    task_type="CAUSAL_LM",
)
peft_model = get_peft_model(model, config)

Полный пример доступен здесь.

Целевое указание nn.Parameter напрямую

Как правило, для указания модуля (например, nn.Linear) следует использовать target_modules. Однако в некоторых случаях это невозможно. Например, во многих слоях mixture of expert (MoE) в HF Transformers вместо nn.Linear используется nn.Parameter. PEFT обычно переопределяет метод forward для LoRA, но для nn.Parameter такого метода нет. Поэтому, чтобы применить LoRA к этому параметру, его необходимо указать с помощью target_parameters. В качестве примера, для Llama4 можно передать: target_parameters=['feed_forward.experts.gate_up_proj', 'feed_forward.experts.down_proj].

Обратите внимание, что при работе с параметрами экспертов PEFT может добавлять значительные накладные расходы во время выполнения. Причина в том, что PEFT всегда материализует вклад LoRA для каждого эксперта, даже если требуется лишь небольшое количество экспертов. Во время обучения это менее критично, поскольку в течение последовательности, как правило, активируется значительная доля экспертов хотя бы один раз. Однако во время инференса обычно используется KV-кэш, и нам нужно вычислять только последний токен, что означает активацию лишь небольшого числа экспертов. Следовательно, использование LoRA на слоях MoE может привести к существенному замедлению во время инференса. Поэтому рекомендуется объединить веса (model.merge_adapter() или model = model.merge_and_unload()). Это устраняет накладные расходы PEFT.

Более подробное исследование этой проблемы можно найти в этом pull request по оптимизации MoE.

Ограничения

• На данный момент этот аргумент позволяет указывать nn.Parameter с 2 или 3 измерениями. Предполагается, что в случае параметра с 3 измерениями нулевое измерение является измерением экспертов.
• Поддерживается несколько адаптеров LoRA (добавленных через model.add_adapter или model.load_adapter), использующих target_parameters, но все они должны нацеливаться на один и тот же набор параметров.

Параметры экспертов MoE и vLLM

Некоторые MoE-модели в Transformers хранят веса экспертов как тензоры nn.Parameter (часто 3D), а не как модули nn.Linear. Чтобы применить LoRA к таким экспертам, используйте target_parameters и задайте ранг для каждого слоя с помощью rank_pattern:

num_experts = getattr(model.config, "num_local_experts", None) or model.config.num_experts
effective_r = max(1, r // num_experts)
config = LoraConfig(
    r=r,
    lora_alpha=32,
    target_modules=["q_proj", "v_proj"],
    target_parameters=[
        # Mixtral / Qwen3-MoE / GPT-OSS
        "mlp.experts.gate_up_proj",
        "mlp.experts.down_proj",
        # Llama4
        # "feed_forward.experts.gate_up_proj",
        # "feed_forward.experts.down_proj",
    ],
    rank_pattern={
        "experts.gate_up_proj": effective_r,
        "experts.down_proj": effective_r,
    },
)

Это позволяет сохранить общий бюджет параметров LoRA на уровне, сопоставимом с плотными слоями (см. LoRA Without Regret от Schulman и др.). Модули, не являющиеся экспертами, используют ранг по умолчанию r.

Ускоренный вывод с помощью дообученной модели возможен, например, с использованием vLLM, который поддерживает объединённые слои экспертов MoE начиная с версии v0.11.2.

Эффективное обучение токенов вместе с LoRA

Адаптеры PEFT LoRA поддерживают добавление новых токенов с помощью параметра trainable_token_indices. Это позволяет настраивать другие токены одновременно с дообучением конкретных слоёв. Обучаются только указанные токены, а все остальные остаются неизменными. Это экономит память и не приводит к потере контекста, накопленного в существующих эмбеддингах токенов, в отличие от обучения всей матрицы эмбеддингов. Внутренне этот метод использует слой TrainableTokensModel.

# for layer 'embed_tokens'
config = LoraConfig(trainable_token_indices=[idx_1, idx_2, ...], ...)

# specific embedding layer
config = LoraConfig(trainable_token_indices={'emb_tokens': [idx_1, idx_2, ...]}, ...)

В приведённом ниже фрагменте кода показано, как добавить новые токены в модель и как обучать их вместе с другими слоями модели.

from transformers import AutoTokenizer, AutoModelForCausalLM
from peft import get_peft_model, LoraConfig

base_model = AutoModelForCausalLM.from_pretrained("mistralai/Mistral-7B-v0.1")
tokenizer = AutoTokenizer.from_pretrained("mistralai/Mistral-7B-v0.1")

# we define our new tokens and add them to the tokenizer as special tokens
special_tokens = ['<|start_think|>', '<|stop_think|>']
tokenizer.add_special_tokens({'additional_special_tokens': special_tokens})

# make room for new tokens in the embedding matrix if it isn't big enough already
base_model.resize_token_embeddings(max(len(tokenizer), base_model.model.embed_tokens.num_embeddings))

# typical LoRA config with `trainable_token_indices` targeting embedding layer `embed_tokens`
# and specifically our new tokens we just added
lora_config = LoraConfig(
    target_modules='all-linear',
    trainable_token_indices={'embed_tokens': tokenizer.convert_tokens_to_ids(special_tokens)},
)
peft_model = get_peft_model(base_model, lora_config)

# proceed to train the model like normal
[...]

Веса токенов сохраняются как часть состояния адаптера (adapter state dict) наряду с весами LoRA. При полной дообучении и сохранении матрицы эмбеддингов файл был бы значительно больше.

Чтобы дать представление о том, сколько VRAM можно сэкономить, было проведено примитивное сравнение приведённого выше примера: обучение матрицы эмбеддингов полностью (modules_to_save=["embed_tokens"]), использование LoRA для матрицы эмбеддингов (target_modules=[..., "embed_tokens"], ранг 32) и обучаемых токенов (trainable_token_indices=[...], 6 токенов):

Связывание весов

Многие каузальные LM используют weight tying, при котором две или более весовые матрицы разделяют одни и те же базовые параметры. В наиболее распространённом случае веса входных эмбеддингов (embed_tokens) и веса выходной проекции (lm_head) используют один и тот же тензор. Это позволяет сократить количество параметров и, как правило, сохраняет качество модели.

Не всегда очевидно, как PEFT обрабатывает эти связанные веса, когда они являются целью дообучения. Для LoRA параметр ensure_weight_tying в LoraConfig определяет, должен ли PEFT явно сохранять связь обновлений на стороне адаптера для этих слоёв. На практике это может влиять на modules_to_save, target_modules и trainable_token_indices. Обратите внимание, что эта логика частично опирается на соглашения о наименовании слоёв ("embed_tokens", "lm_head"), и корректная работа не гарантируется, если эти соглашения не соблюдаются.

Таблицы ниже обобщают ожидаемое поведение.

modules_to_save

target_modules

trainable_token_indices

Для обучаемых токенов возникает дополнительная сложность: даже если LM head и эмбеддинги связаны, как пользователь я могу захотеть дообучить разные токены на них. Поэтому в таблице ниже мы различаем дообучение одних и тех же токенов и дообучение разных токенов.

Для пользователей это означает:

• В общем, если вы хотите дообучить связанные веса и сохранить их связанными, передайте ensure_weight_tying=True.
• Если веса базовой модели не связаны, ensure_weight_tying=True не может принудительно установить связь и лишь выводит предупреждение.
• Для trainable_token_indices связанные слои должны использовать одни и те же индексы токенов, если ensure_weight_tying=True.

Оптимизаторы

Обучение LoRA может опционально включать специализированные оптимизаторы. В настоящее время PEFT поддерживает LoRA-FA, LoRA+ и Riemannian-preconditioned LoRA.

Оптимизатор LoRA-FA

Обучение с использованием LoRA может быть более эффективным и производительным с применением LoRA-FA, как описано в LoRA-FA. LoRA-FA снижает потребление памяти для активаций, фиксируя матрицу A и настраивая только матрицу B. Во время обучения градиент B оптимизируется так, чтобы приближать градиент полной параметрической донастройки. Кроме того, потребление памяти в LoRA-FA не зависит от ранга (поскольку активация $A$ стирается), поэтому производительность можно повысить, увеличивая lora rank, без роста потребления памяти.

from peft import LoraConfig, get_peft_model
from peft.optimizers import create_lorafa_optimizer
from transformers import Trainer, get_cosine_schedule_with_warmup

base_model = AutoModelForCausalLM.from_pretrained("meta-llama/Meta-Llama-3-8B-Instruct")

config = LoraConfig(...)
model = get_peft_model(base_model, config)

optimizer = create_lorafa_optimizer(
    model=model,
    r=128,
    lora_alpha=32,
    lr=7e-5,
)

scheduler = get_cosine_schedule_with_warmup(
    optimizer,
    num_warmup_steps=100,
    num_training_steps=1000,
)

trainer = Trainer(
    ...,
    optimizers=(optimizer, scheduler),
)

LoRA+ оптимизированный LoRA

Обучение LoRA можно оптимизировать с помощью LoRA+, который использует различные скорости обучения для матриц адаптеров A и B, что позволяет ускорить дообучение до 2 раз и повысить качество на 1–2%.

from peft import LoraConfig, get_peft_model
from peft.optimizers import create_loraplus_optimizer
from transformers import Trainer
import bitsandbytes as bnb

base_model = ...
config = LoraConfig(...)
model = get_peft_model(base_model, config)

optimizer = create_loraplus_optimizer(
    model=model,
    optimizer_cls=bnb.optim.Adam8bit,
    lr=5e-5,
    loraplus_lr_ratio=16,
)
scheduler = None

...
trainer = Trainer(
    ...,
    optimizers=(optimizer, scheduler),
)

LoRA с римановым предусловием

Обучение LoRA можно улучшить с помощью римановского преобразователя, как описано в Riemannian Preconditioned LoRA. На каждом шаге оптимизатора градиенты матриц LoRA $A$ и $B$ умножаются на $r \times r$ преобразователь, который масштабирует евклидов градиент в направлении риманова (масштабированного градиента) на многообразии матриц низкого ранга, что улучшает обусловленность обновления и может повысить сходимость. Поскольку преобразователь имеет размер $r \times r$, его накладные расходы на память и время выполнения невелики при ранге LoRA. create_riemannian_optimizer оборачивает любой базовый класс оптимизатора (например, torch.optim.AdamW или torch.optim.SGD): параметры, не относящиеся к LoRA, обновляются базовым оптимизатором без изменений, а только nn.Linear-слои LoRA формыlora_A / lora_B) преобразуются с использованием преобразователя.

from peft import LoraConfig, get_peft_model
from peft.optimizers import create_riemannian_optimizer
from transformers import Trainer, get_cosine_schedule_with_warmup
import torch

base_model = AutoModelForCausalLM.from_pretrained("meta-llama/Meta-Llama-3-8B-Instruct")

config = LoraConfig(...)
model = get_peft_model(base_model, config)

optimizer = create_riemannian_optimizer(
    model=model,
    optimizer_cls=torch.optim.AdamW,
    lr=5e-5,
    reg=1e-2,
)

scheduler = get_cosine_schedule_with_warmup(
    optimizer,
    num_warmup_steps=100,
    num_training_steps=1000,
)

trainer = Trainer(
    ...,
    optimizers=(optimizer, scheduler),
)

reg — это коэффициент затухания, добавляемый к диагонали матрицы $r \times r$ перед инверсией; он стабилизирует предобусловитель, когда фактор LoRA имеет (почти) вырожденный ранг.

Постобучение

В этом разделе представлены возможные методы постобработки для обученных адаптеров.

Слияние весов LoRA с базовой моделью

While LoRA is significantly smaller and faster to train, you may encounter latency issues during inference due to separately loading the base model and the LoRA adapter. To eliminate latency, use the merge_and_unload() function to merge the adapter weights with the base model. This allows you to use the newly merged model as a standalone model. The merge_and_unload() function doesn’t keep the adapter weights in memory.

Ниже представлена схема, объясняющая интуицию слияния адаптеров LoRA:

Ниже в примерах показано, как выполнить это с помощью PEFT.

from transformers import AutoModelForCausalLM
from peft import PeftModel

base_model = AutoModelForCausalLM.from_pretrained("mistralai/Mistral-7B-v0.1")
peft_model_id = "alignment-handbook/zephyr-7b-sft-lora"
model = PeftModel.from_pretrained(base_model, peft_model_id)
model = model.merge_and_unload()

Важно присвоить возвращенную модель переменной и использовать её, так как merge_and_unload() не является операцией in-place. Если вам нужно сохранить копию весов, чтобы позже отменить слияние адаптера или удалить его и загрузить другой, следует использовать функцию merge_adapter(). Теперь у вас есть возможность использовать unmerge_adapter(), чтобы вернуть базовую модель.

from transformers import AutoModelForCausalLM
from peft import PeftModel

base_model = AutoModelForCausalLM.from_pretrained("mistralai/Mistral-7B-v0.1")
peft_model_id = "alignment-handbook/zephyr-7b-sft-lora"
model = PeftModel.from_pretrained(base_model, peft_model_id)
model.merge_adapter()

# unmerge the LoRA layers from the base model
model.unmerge_adapter()

В квантованной модели операция unmerge не является точной: при merge происходит повторная квантизация базовых весов, а многократные циклы merge и unmerge могут накапливать ошибку округления. См. Merging adapters into quantized weights.

Если активно несколько адаптеров, а объединены только некоторые из них, необъединённые адаптеры молча не применяются. Это поведение изменится в PEFT v1.0. См. Объединение только части активных адаптеров.

Функция add_weighted_adapter() полезна для объединения нескольких LoRA в новый адаптер на основе схемы весов, заданной пользователем в параметре weights. Ниже приведён пример «от и до».

Сначала загрузите базовую модель:

from transformers import AutoModelForCausalLM
from peft import PeftModel
import torch

base_model = AutoModelForCausalLM.from_pretrained(
    "mistralai/Mistral-7B-v0.1", dtype=torch.float16, device_map="auto"
)

Затем мы загружаем первый адаптер:

peft_model_id = "alignment-handbook/zephyr-7b-sft-lora"
model = PeftModel.from_pretrained(base_model, peft_model_id, adapter_name="sft")

Затем загрузите другой адаптер и объедините его с первым:

weighted_adapter_name = "sft-dpo"
model.load_adapter("alignment-handbook/zephyr-7b-dpo-lora", adapter_name="dpo")
model.add_weighted_adapter(
    adapters=["sft", "dpo"],
    weights=[0.7, 0.3],
    adapter_name=weighted_adapter_name,
    combination_type="linear"
)
model.set_adapter(weighted_adapter_name)

Существует несколько поддерживаемых методов для combination_type. Подробности см. в документации. Обратите внимание, что значение “svd” для combination_type не поддерживается при использовании torch.float16 или torch.bfloat16 в качестве типа данных.

Теперь выполните инференс:

device = torch.accelerator.current_accelerator().type if hasattr(torch, "accelerator") else "cuda"

tokenizer = AutoTokenizer.from_pretrained("mistralai/Mistral-7B-v0.1")

prompt = "Hey, are you conscious? Can you talk to me?"
inputs = tokenizer(prompt, return_tensors="pt")
inputs = {k: v.to(device) for k, v in inputs.items()}

with torch.no_grad():
    generate_ids = model.generate(**inputs, max_length=30)
outputs = tokenizer.batch_decode(generate_ids, skip_special_tokens=True, clean_up_tokenization_spaces=False)[0]
print(outputs)

Восстановление производительности базовой модели с помощью снижения размерности интрузивного пространства

Статья LoRA vs Full Fine-tuning: An Illusion of Equivalence утверждает, что обучение с использованием LoRA вводит в веса дополнительные измерения, которые имеют мало общего с уже выученными весами и приводят к забыванию ранее полученной информации. PEFT реализует предложенное средство смягчения в peft.tuners.lora.intruders.reduce_intruder_dimension().

Для смягчения проблемы будет взята модель PEFT с загруженным LoRA и создан новый изменённый адаптер, который загружается вместе с существующим адаптером и становится активным.

Пример использования:

from peft.tuners.lora.intruders import reduce_intruder_dimension

peft_model = AutoPeftModelForCausalLM.from_pretrained('hubnemo/llama-3.2b-metamathqa-lora64')

reduce_intruder_dimension(
    peft_model,
    mitigation_lambda=0.75,
)

peft_model.generate(...)

Существует несколько гиперпараметров, которые можно использовать для настройки эффективности митигации, однако, как показано на рисунке 8 в статье, всегда будет существовать компромисс между точностью задачи, которую изучает адаптер, и забыванием знаний базовой модели. Митигация удаляет информацию из адаптера, чтобы снизить влияние на забывание предыдущих знаний, но это также означает, что часть информации о задаче, изученной адаптером, также теряется.

По умолчанию параметры настроены так, чтобы обеспечить хороший баланс между двумя факторами, однако не гарантируется, что эти значения будут оптимальными для вашего адаптера, модели и данных, поэтому разумно заранее подготовить бенчмарк для измерения эффекта.

Загрузка адаптеров

Адаптеры можно загрузить в предобученную модель с помощью load_adapter(), что полезно для проверки различных адаптеров, веса которых не объединены. Активные веса адаптера задаются функцией set_adapter().

from transformers import AutoModelForCausalLM
from peft import PeftModel

base_model = AutoModelForCausalLM.from_pretrained("mistralai/Mistral-7B-v0.1")
peft_model_id = "alignment-handbook/zephyr-7b-sft-lora"
model = PeftModel.from_pretrained(base_model, peft_model_id)

# load different adapter
model.load_adapter("alignment-handbook/zephyr-7b-dpo-lora", adapter_name="dpo")

# set adapter as active
model.set_adapter("dpo")

Чтобы вернуть базовую модель, вы можете использовать unload() для выгрузки всех модулей LoRA или delete_adapter() для полного удаления адаптера. unload() не является операцией in-place, не забудьте присвоить возвращаемую модель переменной и использовать её.

# unload adapter
model = model.unload()

# delete adapter
model.delete_adapter("dpo")

Параллелизм тензоров

LoRA поддерживает Tensor Parallelism (TP), предоставляемый Transformers. Когда базовая модель загружается с tp_plan, PEFT автоматически определяет конфигурацию TP для каждого целевого модуля и добавляет соответствующие хуки к весам адаптера LoRA, чтобы они корректно участвовали в тензорно-параллельных вычислениях.

Поддержка Tensor Parallelism для LoRA требует transformers >= 5.4.0. API Tensor Parallelism на основе DTensor требует peft >= 0.21.1 и transformers >= 5.17.0.

Использование идентично стандартному рабочему процессу LoRA — просто загрузите базовую модель с tp_plan перед её обёртыванием с помощью PEFT:

from transformers import AutoModelForCausalLM
from peft import get_peft_model, LoraConfig

model = AutoModelForCausalLM.from_pretrained("meta-llama/Llama-3.1-8B", tp_plan="auto")
lora_config = LoraConfig(r=16, target_modules=["q_proj", "v_proj"])
model = get_peft_model(model, lora_config)

Сохранение и загрузка работают как обычно через save_pretrained / from_pretrained. PEFT собирает разбитые веса адаптера обратно в полные тензоры перед сохранением, поэтому контрольные точки переносимы и не зависят от количества устройств, использованных во время обучения.

Если вы применяете тензорное параллелизм без TP-плана, например, с помощью parallelize_module из PyTorch, PEFT задаёт размеры весов LoRA для шардированного nn.Linear в соответствии с его локальным шардом, если размерность device mesh веса называется "tp", а в противном случае — в соответствии с полной формой слоя (как в случае с FSDP2). PEFT не добавляет TP-хуки к этим весам LoRA и не собирает их при сохранении. Если имя размерности вашей TP-сетки отличается, добавьте его перед созданием модели PEFT:

from peft.utils.integrations import TpMeshDimRegistry

TpMeshDimRegistry.register("tp_dim")

Вывод

В этом разделе показано, что можно сделать на этапе инференса с LoRA, например, отсоединить адаптер.

Активированный LoRA (aLoRA)

Активированный LoRA (aLoRA) — это архитектура адаптеров низкого ранга для каузальных языковых моделей, которая повторно использует существующий кэш KV базовой модели для более эффективного вывода. Этот подход лучше всего подходит для конвейеров вывода, которые полагаются на базовую модель для большинства задач/генераций, но используют адаптер(ы) aLoRA для выполнения специализированных задач в цепочке. Например, для проверки или исправления сгенерированных выходов базовой модели. В таких сценариях время вывода может быть сокращено на порядок или более. Для получения дополнительной информации об aLoRA и множества примеров использования см. статью об aLoRA.

Этот метод находит последнее вхождение последовательности вызова (alora_invocation_tokens) в каждом входном сообщении (она может состоять всего из 1 токена). Веса адаптера активируются на токенах, начиная с начала последовательности вызова. Все входные данные после последовательности вызова также адаптируются, и все сгенерированные токены будут использовать адаптированные веса. Веса на предыдущих токенах остаются без адаптации, что делает кэш для этих токенов взаимозаменяемым с кэшем базовой модели благодаря маске причинного внимания в причинных языковых моделях. Использование очень похоже на стандартный LoRA. Главное отличие состоит в том, что последовательность вызова должна быть указана при создании адаптера:

from peft import LoraConfig

config = LoraConfig(alora_invocation_tokens=alora_invocation_tokens, task_type="CAUSAL_LM", ...)

alora_invocation_tokens` — это список целочисленных идентификаторов токенов. Для заданной строки вызова это можно получить следующим образом:

invocation_string = "placeholder"
alora_invocation_tokens = tokenizer.encode(invocation_string, add_special_tokens=False).

Токенизатор — это токенизатор базовой модели. Используйте add_special_tokens=False, чтобы избежать добавления токенов SOS/EOS в строку поиска (что с высокой вероятностью приведёт к неудаче поиска).

Примечания

• aLoRA поддерживается только для задач task_type=CAUSAL_LM в связи с акцентом на повторное использование кэша.
• Поскольку веса адаптируются на меньшем количестве токенов, aLoRA часто (но не всегда) требует более высокий ранг (r), чем LoRA. r=32 может быть хорошей отправной точкой.
• Веса aLoRA по определению не могут быть объединены с базовой моделью, поскольку веса адаптера применяются выборочно к подмножеству токенов. Попытки выполнить объединение приведут к ошибкам.
• Поиск по лучам пока не поддерживается.
• Как правило, не рекомендуется добавлять в токенизатор новые токены, отсутствующие в базовой модели. Это может усложнить целевой сценарий использования, в котором базовая модель и адаптерная модель работают с пересекающимся контекстом. Чтобы обойти эту проблему, можно добавить обучаемые токены в базовую модель до обучения адаптера.

Выбор последовательности вызовов и проектирование SFT

Необходимо добавить последовательность alora_invocation_tokens, поскольку она не добавляется автоматически. Мы рекомендуем активировать веса адаптера на раннем этапе (в начале любого промптинга, специфичного для адаптера), но после любых длинных входных данных, чтобы максимизировать производительность модели, не ухудшая повторное использование кэша. Как и в случае с любой моделью, форматирование должно быть согласовано между этапами обучения и тестирования.

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

• Вариант 1: если нет промпта, специфичного для задачи, то есть вход представляет собой историю чата с промптом assistant, то промпт assistant из шаблона чата (например, <|start_of_role|>assistant<|end_of_role|>) является естественным выбором для строки вызова. Чтобы найти промпт для модели, обратитесь к шаблону чата модели.
• Вариант 2: если для адаптера существует промпт, специфичный для задачи, который описывает задачу, на которой обучается адаптер, и этот промпт помещается в качестве хода user непосредственно перед генерацией, то промпт user из шаблона чата (например, <|start_of_role|>user<|end_of_role|>) является естественным выбором для строки вызова.

После выбора строки вызова получите токенизатор модели и получите alora_invocation_tokens как

alora_invocation_tokens = tokenizer.encode(invocation_string, add_special_tokens=False).

Пример конфигурации для инференса находится в alora finetuning.

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

Чтобы понять, почему это важно, представьте, что ‘a’, ‘b’, ‘c’ и ‘ab’ — это токены вашего токенизатора (с номерами 1, 2, 3 и 4 соответственно). Допустим, ваш alora_invocation_tokens = [2, 3]. Теперь представьте, что входная строка — это “abc”. Поскольку “ab” является токеном, эта строка будет токенизирована как [4,3]. В результате alora_invocation_tokens не будут найдены, несмотря на то, что строка “bc” в ней присутствует. Однако, если начало и конец строки вызова — это специальные токены, такой сбой никогда не произойдет, поскольку специальные токены никогда не объединяются с другими символами в один и тот же токен.

Использование (и повторное использование) кэша для генерации

Основная цель aLoRA — сделать кэш KV взаимозаменяемым между базовой моделью и моделями с адаптерами aLoRA до начала последовательности вызовов, поскольку значения KV базовой модели и адаптированной модели несовместимы. В частности, ключи и значения, сохранённые во время одной генерации модели, могут использоваться в последующих генерациях, чтобы избежать дорогостоящих операций prefill для токенов контекста. При обмене кэшем между базовой моделью и адаптерами aLoRA существуют два основных паттерна:

1. Базовая модель сгенерировала некоторый результат, после чего вызывается адаптер aLoRA для выполнения последующей генерации. Например, базовая модель отвечает на вопрос, а aLoRA, обученный обнаруживать галлюцинации, проверяет ответ базовой модели.
2. Адаптер aLoRA сгенерировал некоторый результат, и базовая модель или другой адаптер aLoRA вызываются для последующей генерации, где контекст частично пересекается с контекстом исходного aLoRA. Например, пользователь предоставляет запрос, а aLoRA переписывает его, чтобы сделать более самодостаточным и улучшить извлечение в RAG-системе. Затем документы извлекаются и загружаются в контекст, aLoRA проверяет, являются ли эти документы релевантными для вопроса, и после этого базовая модель генерирует ответ.

Для демонстрации описанного выше поведения при использовании кэширования мы применяем DynamicCache из transformers. Следите за тем, чтобы адаптированные значения кэша не смешивались с базовыми значениями кэша. В частности, при частичном пересечении контекста (паттерн 2) для общего использования кэша требуется дополнительный шаг.

Вариант 1: базовая модель, за которой следует aLoRA Здесь весь вход и результат генерации базовой модели передаются в адаптер aLoRA вместе с последовательностью вызова:

from transformers import DynamicCache
...
cache = DynamicCache()
inputs_base = tokenizer(prompt_base, return_tensors="pt")
# Generate from base model and save cache
with model_alora.disable_adapter():
    output = model_alora.generate(inputs_base["input_ids"].to(device),attention_mask=inputs_base["attention_mask"].to(device),past_key_values = cache,return_dict_in_generate=True)
output_text_base = tokenizer.decode(output.sequences[0])
cache = output.past_key_values

# Generate with aLoRA adapter from cache
prompt_alora = output_text + INVOCATION_STRING
inputs_alora = tokenizer(prompt_alora, return_tensors="pt").to(device)
output = model_alora.generate(**inputs_alora, past_key_values=cache)
output_text_alora = tokenizer.decode(output[0])

# Note: cache is now tainted with adapter values and cannot be used in base model from here on!

Паттерн 2: генерация с aLoRA, за которой следует базовая модель (или другой aLoRA) с частичным перекрытием контекста Здесь мы предварительно заполняем общий контекст с помощью базовой модели, а затем выполняем генерацию.

from transformers import DynamicCache
import copy
...
cache = DynamicCache()
inputs_shared = tokenizer(prompt_shared, return_tensors="pt").to(device)

# Prefill from base model and save cache
with model_alora.disable_adapter():
    with torch.no_grad():
        model_alora(**inputs_shared, past_key_values=cache)
cache_copy = copy.deepcopy(cache)

# Generate from aLoRA using prefilled cache
prompt_alora = prompt_shared + INVOCATION_STRING
inputs_alora = tokenizer(prompt_alora, return_tensors="pt").to(device)
output = model_alora.generate(**inputs_alora, past_key_values=cache)
output_text_alora = tokenizer.decode(output[0])

# Generate from base model using saved cache not tainted by aLoRA KV values
prompt_base = prompt_shared
inputs_base = tokenizer(prompt_base, return_tensors="pt").to(device)
with model_alora.disable_adapter():
    output = model_alora.generate(**inputs_base, past_key_values=cache_copy)
output_text_base = tokenizer.decode(output[0])

Вывод с разными адаптерами LoRA в одном батче

Обычно каждая партия (батч) при инференсе должна использовать один и тот же адаптер (или набор адаптеров) в PEFT. Это может быть неудобно, так как в партиях могут содержаться примеры, предназначенные для разных адаптеров LoRA. Например, у нас может быть базовая модель, хорошо работающая с английским, и два дополнительных адаптера LoRA — один для французского, другой для немецкого. Как правило, нам приходится разделять партии так, чтобы каждая из них содержала примеры только одного языка; объединять разные языки в одной партии нельзя.

К счастью, можно использовать разные адаптеры LoRA в одном батче, передавая аргумент adapter_name. Ниже мы показываем пример того, как это работает на практике. Сначала загрузим базовую модель, английский адаптер, а также адаптеры для французского и немецкого языков:

from transformers import AutoTokenizer, AutoModelForCausalLM
from peft import PeftModel

model_id = ...
tokenizer = AutoTokenizer.from_pretrained(model_id)

model = AutoModelForCausalLM.from_pretrained(model_id)
# load the LoRA adapter for French
peft_model = PeftModel.from_pretrained(model, <path>, adapter_name="adapter_fr")
# next, load the LoRA adapter for German
peft_model.load_adapter(<path>, adapter_name="adapter_de")

Теперь мы хотим сгенерировать текст на выборке, содержащей все три языка: первые три примера на английском, следующие три — на французском, а последние три — на немецком. Мы можем использовать аргумент adapter_names, чтобы указать, какой адаптер использовать для каждого примера. Поскольку базовая модель используется для английского, для этих примеров мы применяем специальную строку "__base__". Для следующих трёх примеров мы указываем имя адаптера французской LoRA-дообученной модели, в данном случае "adapter_fr". Для последних трёх примеров мы указываем имя адаптера немецкой LoRA-дообученной модели, в данном случае "adapter_de". Таким образом, мы можем использовать базовую модель и два адаптера в одном батче.

inputs = tokenizer(
    [
        "Hello, my dog is cute",
        "Hello, my cat is awesome",
        "Hello, my fish is great",
        "Salut, mon chien est mignon",
        "Salut, mon chat est génial",
        "Salut, mon poisson est super",
        "Hallo, mein Hund ist süß",
        "Hallo, meine Katze ist toll",
        "Hallo, mein Fisch ist großartig",
    ],
    return_tensors="pt",
    padding=True,
)

adapter_names = [
    "__base__", "__base__", "__base__",
    "adapter_fr", "adapter_fr", "adapter_fr",
    "adapter_de", "adapter_de", "adapter_de",
]
output = peft_model.generate(**inputs, adapter_names=adapter_names, max_new_tokens=20)

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

Кроме того, тот же подход также работает с функцией modules_to_save, которая позволяет сохранять и повторно использовать определённые слои нейронной сети, например, пользовательские головы для задач классификации, между различными адаптерами LoRA.

Ограничения

Использование этой функции имеет некоторые недостатки, а именно:

• Это работает только для инференса, а не для обучения.
• Отключение адаптеров с помощью контекста with model.disable_adapter() имеет приоритет над adapter_names.
• Нельзя передавать adapter_names, если веса некоторых адаптеров были объединены с базовыми весами с помощью метода merge_adapter. Сначала отмените объединение всех адаптеров, вызвав model.unmerge_adapter(). Обратите внимание, что объединение только части активных адаптеров имеет аналогичное ограничение вне контекста adapter_names.
• По очевидным причинам это нельзя использовать после вызова merge_and_unload(), поскольку в этом случае все адаптеры LoRA будут объединены с базовыми весами.
• В настоящее время эта функция не работает с DoRA, поэтому установите use_dora=False в вашем LoraConfig, если вы хотите её использовать.
• Возможность modules_to_save в настоящее время поддерживается только для слоёв типов Linear, Embedding, Conv2d и Conv1d.
• При выводе с использованием adapter_names, ожидается дополнительное время выполнения, особенно если в батче много разных адаптеров. Это происходит потому, что размер батча фактически уменьшается до количества образцов на адаптер. Если производительность во время выполнения для вас в приоритете, попробуйте следующее:
  • Увеличьте размер пакета.
  • Старайтесь избегать наличия большого количества различных адаптеров в одном батче, предпочитая однородные батчи. Этого можно достичь, буферизуя примеры с одним и тем же адаптером и выполняя инференс только с небольшим набором различных адаптеров.
  • Ознакомьтесь с альтернативными реализациями, такими как LoRAX, punica или S-LoRA, которые оптимизированы для работы с большим количеством различных адаптеров.

Составление и повторное использование адаптеров LoRA

Arrow

Arrow — это модульный алгоритм маршрутизации, разработанный для объединения нескольких предварительно обученных адаптеров LoRA, специализированных на конкретных задачах, с целью решения поставленной задачи. Он похож на Polytropon, но не требует дообучения. Вместо наивного слияния всех адаптеров Arrow вводит механизм маршрутизации mixture-of-experts (MoE) на уровне токенов, не требующий градиентов. На этапе инференса для каждого адаптера LoRA сначала вычисляется прототип путём извлечения главного правого сингулярного вектора из его SVD-разложения. Затем представления каждого токена сравниваются с этими прототипами с помощью косинусного сходства для получения коэффициентов маршрутизации. Токены назначаются k наиболее релевантным адаптерам LoRA, коэффициенты нормализуются с помощью softmax, а их выходные значения линейно комбинируются. Это позволяет эффективно переиспользовать существующие модули LoRA для новых задач и обеспечивает более сильную обобщающую способность в режиме zero-shot.

В PEFT Arrow включается с помощью [`ArrowConfig]andcreate_arrow_model. You can also configure parameters such astop_k(the number of LoRA adapters combined per token),router_temperature(the softmax temperature applied to the routing coefficients), andrng_seed` (for reproducibility).

from peft import create_arrow_model, ArrowConfig
from transformers import AutoModelForCausalLM

# Loading the model
base_model = AutoModelForCausalLM.from_pretrained("microsoft/Phi-3-mini-4k-instruct")

# Creating the Arrow config
arrow_config = ArrowConfig(
    top_k=3,
    router_temperature=1.0,
    rng_seed=42,
)

# The LoRA adapters below were trained on a clustered FLAN dataset.
# Task clustering was performed using the Model-Based Clustering (MBC) method,
# as described in the Arrow paper.
# While one could train a separate LoRA for each task and let Arrow route tokens among them,
# training LoRAs on clusters of tasks instead provides an indirect optimization for
# transfer across the multi-task dataset.
task_specific_adapter_paths = [
        f"TahaBa/phi3-mini-clustered-flan/ts_expert_{i}" for i in range(10)
    ]

# Creating the Arrow model
model = create_arrow_model(
        base_model=base_model,
        task_specific_adapter_paths=task_specific_adapter_paths,
        arrow_config=arrow_config,
    )

# Now the forward path could be called on this model, like a normal PeftModel.

Кроме того, вы можете добавлять или удалять адаптеры после вызова create_arrow_model — например, чтобы дообучить новый адаптер или удалить ненужный. Когда адаптеры на месте, вы можете активировать "arrow_router" для вывода, чтобы использовать Arrow. Обратите внимание, что если вы добавите новый адаптер LoRA после create_arrow_model и хотите его дообучить, вам нужно явно установить новый адаптер как активный, поскольку "arrow_router" активируется по умолчанию в create_arrow_model.

from trl import SFTTrainer, SFTConfig

# Adding a new adapter and activating it
model.add_adapter(adapter_name='new_adapter')
model.set_adapter('new_adapter')

# Now the model could be trained along the `new_adapter`.
trainer = SFTTrainer(
        model=model,
        args=SFTConfig(...),
        ...
    )

# Once the training is done, you can activate `arrow_router` and use it in inference
model.set_adapter('arrow_router')    # Model is ready to be used at inference time now

GenKnowSub

GenKnowSub расширяет Arrow, очищая специфичные для задачи адаптеры LoRA перед маршрутизацией. Ключевая идея заключается в вычитании общих знаний, закодированных в пространстве LoRA, на основе принципа забывания через отрицание, чтобы адаптеры задач стали более изолированными и сфокусированными на сигналах, релевантных задаче. Конкретно, GenKnowSub оценивает низкоразмерное «общее» подпространство на основе набора общих (не специфичных для задачи) адаптеров LoRA и удаляет эту компоненту из обновления LoRA каждого адаптера задачи перед посимвольной маршрутизацией Arrow. Как правило, это улучшает композиционность и снижает интерференцию при объединении множества адаптеров задач.

В PEFT включите GenKnowSub, установив use_gks=True в ArrowConfig и передав general_adapter_paths в create_arrow_model:

from peft import create_arrow_model, ArrowConfig
from transformers import AutoModelForCausalLM

# Loading the model
base_model = AutoModelForCausalLM.from_pretrained("microsoft/Phi-3-mini-4k-instruct")

# Creating the Arrow config
arrow_config = ArrowConfig(
    top_k=3,
    router_temperature=1.0,
    use_gks=True,
    rng_seed=42,
)

# Path to task-specific, trained on flan clustered dataset (as we explained before.)
task_specific_adapter_paths = [
        f"TahaBa/phi3-mini-clustered-flan/ts_expert_{i}" for i in range(10)
    ]
# These general adapters are trained on English, German, and French Wikipedia dataset,
# with causal language modelling objective, each pair like: (507 token tsentence, 5 token completion), and the loss computed on the completion
general_adapter_paths = [
        "TahaBa/phi3-mini-general-adapters/cluster0_batch16_prop1.0_langen/checkpoint-17",
        "TahaBa/phi3-mini-general-adapters/cluster0_batch16_prop1.0_langfr/checkpoint-35",
        "TahaBa/phi3-mini-general-adapters/cluster0_batch16_prop1.0_langger/checkpoint-17"
    ]

# Creating the Arrow model
model = create_arrow_model(
        base_model=base_model,
        task_specific_adapter_paths=task_specific_adapter_paths,
        general_adapter_paths=general_adapter_paths,
        arrow_config=arrow_config,
    )

# Now the forward path could be called on this model, like a normal PeftModel.

Для кодирования общих знаний GenKnowSub один раз вычитает среднее значение предоставленных общих адаптеров из каждого адаптера, специфичного для задачи, до начала маршрутизации. Кроме того, в этом случае по-прежнему поддерживается возможность добавления или удаления адаптеров после вызова create_arrow_model (как описано в разделе Arrow).

Что следует учитывать при использовании Arrow + GenKnowSub:

• Все адаптеры LoRA (специфичные для задачи и общие) должны иметь одинаковые значения rank и target_modules.

• Любое несоответствие в этих настройках приведёт к ошибке в create_arrow_model.

• Поддерживаются различные коэффициенты масштабирования (lora_alpha) для адаптеров разных задач — Arrow обрабатывает их автоматически.

• Слияние "arrow_router" не поддерживается из-за его динамического поведения маршрутизации.

• В create_arrow_model адаптеры задач загружаются как task_i, а общие адаптеры — как gks_j (где i и j — индексы). Функция обеспечивает согласованность target_modules, rank и того, применяются ли адаптеры к слоям Linear или Linear4bit. Затем добавляется модуль "arrow_router" и активируется. Любая кастомизация этого процесса требует переопределения create_arrow_model.

• Эта реализация совместима с 4-битным квантованием (через bitsandbytes):

  Скопировано

  from transformers import AutoModelForCausalLM, BitsAndBytesConfig
  import torch
  
  # Quantisation config
  bnb_config = BitsAndBytesConfig(
          load_in_4bit=True,
          bnb_4bit_quant_type="nf4",
          bnb_4bit_compute_dtype=torch.bfloat16,
          bnb_4bit_use_double_quant=False,
      )
  
  # Loading the model
  base_model = AutoModelForCausalLM.from_pretrained(
      "microsoft/Phi-3-mini-4k-instruct",
      dtype=torch.bfloat16,
      device_map="auto",
      quantization_config=bnb_config,
  )
  
  # Now call create_arrow_model() as we explained before.

API

LoraConfig

LoraModel

>>> from transformers import AutoModelForSeq2SeqLM
>>> from peft import LoraConfig, get_peft_model

>>> config = LoraConfig(
...     task_type="SEQ_2_SEQ_LM",
...     r=8,
...     lora_alpha=32,
...     target_modules=["q", "v"],
...     lora_dropout=0.01,
... )

>>> model = AutoModelForSeq2SeqLM.from_pretrained("t5-base")
>>> lora_model = get_peft_model(model, config)

>>> import torch
>>> import transformers
>>> from peft import LoraConfig, get_peft_model, prepare_model_for_kbit_training

>>> rank = ...
>>> target_modules = ["q_proj", "k_proj", "v_proj", "out_proj", "fc_in", "fc_out", "wte"]
>>> config = LoraConfig(
...     r=4, lora_alpha=16, target_modules=target_modules, lora_dropout=0.1, bias="none", task_type="CAUSAL_LM"
... )
>>> quantization_config = transformers.BitsAndBytesConfig(load_in_8bit=True)

>>> tokenizer = transformers.AutoTokenizer.from_pretrained(
...     "kakaobrain/kogpt",
...     revision="KoGPT6B-ryan1.5b-float16",  # or float32 version: revision=KoGPT6B-ryan1.5b
...     bos_token="[BOS]",
...     eos_token="[EOS]",
...     unk_token="[UNK]",
...     pad_token="[PAD]",
...     mask_token="[MASK]",
... )
>>> model = transformers.GPTJForCausalLM.from_pretrained(
...     "kakaobrain/kogpt",
...     revision="KoGPT6B-ryan1.5b-float16",  # or float32 version: revision=KoGPT6B-ryan1.5b
...     pad_token_id=tokenizer.eos_token_id,
...     use_cache=False,
...     device_map={"": rank},
...     torch_dtype=torch.float16,
...     quantization_config=quantization_config,
... )
>>> model = prepare_model_for_kbit_training(model)
>>> lora_model = get_peft_model(model, config)

Утилиты

ArrowConfig

LoftQ

replace_lora_weights_loftq

LoftQConfig

Eva

EvaConfig

initialize_lora_eva_weights

get_eva_state_dict

LoraGAConfig

Утилиты

Сокращение размерности Intruder