PEFT documentation

PSOFT

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

PSOFT

PSOFT — это метод параметрически эффективной дообучения (parameter-efficient fine-tuning) на основе ортогонального дообучения (OFT), который сохраняет геометрические связи между векторами столбцов предобученных весов, обеспечивая сбалансированный компромисс между качеством и многомерной эффективностью, включая количество параметров, потребление памяти и вычислительные затраты. Ограничивая ортогональные преобразования подпространством низкого ранга, выведенным из предобученных весов, PSOFT закрывает разрыв между LoRA и OFT, предоставляя как теоретические гарантии, так и практическую адаптивность. Его эффективность подтверждена обширными оценками на разнообразных бенчмарках, включая GLUE, VTAB-1K, GSM8K, MATH и бенчмарки рассуждений на основе здравого смысла.

  • Поддерживаются только слои nn.Linear.
  • Квантованные слои не поддерживаются.

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

Стремительный рост числа параметров моделей сделал параметрически эффективную дообучение (PEFT) необходимым инструментом для адаптации больших моделей к разнообразным задачам в условиях ограниченных вычислительных ресурсов. В рамках этого подхода ортогональное дообучение и его варианты сохраняют семантические представления предобученных моделей, однако сталкиваются с трудностями в одновременном обеспечении выразительности и эффективности с точки зрения количества параметров, памяти и вычислений. Чтобы преодолеть это ограничение, мы предлагаем эффективное ортогональное дообучение с адапцией в главном подпространстве (PSOFT), которое ограничивает ортогональные преобразования главным подпространством весов предобученной модели. Конкретно, PSOFT конструирует это подпространство с помощью разложения матриц для обеспечения совместимых преобразований, устанавливает теоретическое условие, строго сохраняющее геометрию данного подпространства для сохранения ключевой семантики, и вводит эффективные настраиваемые векторы, которые постепенно ослабляют ортогональность в процессе обучения, повышая адаптивность. Обширные эксперименты на 35 задачах NLP и CV с использованием четырех репрезентативных моделей показывают, что PSOFT предлагает практичное и масштабируемое решение для одновременного достижения сохранения семантики, выразительности и многомерной эффективности в PEFT.

Как работает PSOFT

PSOFT разлагает каждую матрицу весов WpreW_{pre} на WpriW_{pri} и WresW_{res} с помощью SVD: Wpre=USV⊤W_{\text{pre}} = U S V^\top

Главное подпространство Wpri=UrSrVr⊤=ABW_{\text{pri}} = U_r S_r V_r^\top = AB построено из первых $r$ сингулярных компонент:

Wpre=Wpri+Wres=AB+Wres,W_{\text{pre}} = W_{\text{pri}} + W_{\text{res}} = AB + W_{\text{res}},

Wps-tuned=ARB+Wres.W_{\text{ps-tuned}} = ARB + W_{\text{res}}. (PSOFT-SO: PSOFT с строгой ортогональностью

Wps-tuned=A diag(α) R diag(β) B+Wres.W_{\text{ps-tuned}} = A \, \mathrm{diag}(\alpha) \, R \, \mathrm{diag}(\beta) \, B + W_{\text{res}}. (PSOFT-RO: PSOFT с ослабленным условием ортогональности

Во время обучения $A$, $B$ и WresW_{\text{res}} заморожены, а обучаемым является только RR (или RR с α\alpha и $\beta$).

Для совместимости с фреймворком PEFT (который ожидает аддитивные обновления весов) PSOFT реализован в следующей аддитивной форме: Wps-tuned=Wpre+A(R−Ir)BW_{\text{ps-tuned}} = W_{\text{pre}} + A (R - I_r) B

Обучаемые параметры

После применения PSOFT:

  • Исходные веса модели ($A$, $B$ и $W_{\text{res}}$) заморожены.
  • Только ортогональная матрица RR (и, при необходимости, $\alpha$, $\beta$) обучаемы.
  • Не вводятся дополнительные параметры смещения.

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

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer
from peft import PsoftConfig, get_peft_model

# Load base model
model_id = "facebook/opt-125m"
model = AutoModelForCausalLM.from_pretrained(model_id)

# Configure PSOFT
config = PsoftConfig(
    r=32,                                   # the dimension of trainable matrix R,
    psoft_alpha=32,                         # scaling factor (typically set to r in PSOFT),
    target_modules=["q_proj", "v_proj"],    # target attention projection layers
    ab_svd_init="psoft_init",        # principal subspace initialization
    psoft_svd="full",                       # SVD method
    psoft_orth=True,                        # enable orthogonal R (Cayley parameterization)
    psoft_mag_a=True,                       # enable tunable vector alpha
    psoft_mag_b=True,                       # enable tunable vector beta
    use_cayley_neumann=False,               # disable Cayley–Neumann approximation
    num_cayley_neumann_terms=5,             # number of Neumann series terms
    cayley_neumann_eps=None,                # improve numerical stability
)

# Apply PSOFT
model = get_peft_model(model, config)
model.train()

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

# Train
inputs = tokenizer("Hello world", return_tensors="pt", padding=True)
loss = model(**inputs, labels=inputs["input_ids"]).loss
loss.backward()

trainable = [p for p in model.parameters() if p.requires_grad]
optimizer = torch.optim.AdamW(trainable, lr=5e-4)
optimizer.step()
optimizer.zero_grad(set_to_none=True)

Варианты конфигурации

Разный режим

(PSOFT-SO: PSOFT с строгой ортогональностью)

config = PsoftConfig(psoft_orth=True,psoft_mag_a=False,psoft_mag_b=False)

(PSOFT-RO: PSOFT с ослабленным условием ортогональности)

config = PsoftConfig(psoft_orth=True,psoft_mag_a=True,psoft_mag_b=True)

Лучшие практики

  1. Выбор ранга: Меньшие ранги (например, 32–128) подходят для более простых задач, тогда как большие ранги (например, 64–256) обеспечивают большую выразительность для более сложных задач ценой увеличения количества параметров и вычислений.
  2. Scaling Factor: Масштабирующий коэффициент обычно устанавливается в rr в PSOFT.
  3. Коэффициент обучения: используйте стандартные значения коэффициента обучения (например, 1e-4–5e-3) для стабильного обучения.
  4. Инициализация SVD: вариант lowrank требует меньше памяти и вычислений, чем full, что делает его более подходящим для больших моделей.
  5. Приближение Кэли–Неймана: при большом ранге включение приближения Кэли–Неймана может значительно повысить вычислительную эффективность, тогда как при малых рангах выигрыш менее заметен. На практике небольшое количество членов ряда Неймана (обычно 5) обеспечивает хороший баланс между точностью и эффективностью.

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

API

PsoftConfig

класс peft.PsoftConfig

< >

( task_type: Optional[Union[str, TaskType]] = Nonepeft_type: Optional[Union[str, PeftType]] = Noneauto_mapping: Optional[dict] = Nonepeft_version: Optional[str] = Nonebase_model_name_or_path: Optional[str] = Nonerevision: Optional[str] = Noneinference_mode: bool = Falser: int = 32target_modules: Optional[Union[list[str], str]] = Noneexclude_modules: Optional[Union[list[str], str]] = Nonepsoft_alpha: int = 32psoft_dropout: float = 0.0fan_in_fan_out: bool = Falseab_svd_init: Literal['psoft_init', 'pissa_init'] = 'psoft_init'psoft_svd: Literal['full', 'lowrank'] = 'full'psoft_svd_lowrank_niter: int = 10random_seed: int = 0psoft_orth: bool = Truepsoft_mag_b: bool = Truepsoft_mag_a: bool = Trueuse_cayley_neumann: bool = Falsenum_cayley_neumann_terms: int = 5cayley_neumann_eps: Optional[float] = Nonemodules_to_save: Optional[list[str]] = Noneinit_weights: bool = Truelayers_to_transform: Optional[Union[list[int], int]] = Nonelayers_pattern: Optional[Union[list[str], str]] = None )

Параметры

  • r (int) — По умолчанию 32. PSOFT-ранг (r) управляет ёмкостью адаптера через преобразование r*r R. Для простых задач обычно достаточно малых рангов 32–128. Более сложные задачи могут выиграть от значений 64–256, что повышает выразительность за счёт дополнительных параметров и вычислений. См. статью с эмпирически проверенными настройками: https://openreview.net/forum?id=FSHrinMArK.
  • target_modules (Optional[Union[List[str], str]]) — Имена модулей, к которым следует применить адаптер. Если это значение указано, будут заменены только модули с указанными именами. При передаче строки выполняется сопоставление по регулярному выражению. При передаче списка строк выполняется точное совпадение или проверяется, заканчивается ли имя модуля каким-либо из переданных строк. Если это значение указано как ‘all-linear’, выбираются все линейные/Conv1D модули (если модель является PreTrainedModel, выходной слой исключается). Если это значение не указано, модули выбираются в соответствии с архитектурой модели. Если архитектура неизвестна, будет выброшена ошибка — в этом случае следует указать целевые модули вручную.
  • exclude_modules (Optional[Union[List[str], str]]) — Имена модулей, к которым не следует применять адаптер. При передаче строки выполняется сопоставление по регулярному выражению. При передаче списка строк выполняется точное совпадение или проверяется, заканчивается ли имя модуля каким-либо из переданных строк.
  • psoft_alpha (int) — По умолчанию 32. Управляет коэффициентом масштабирования PSOFT. Семантика такая же, как у LoRA alpha.
  • psoft_dropout (float) — По умолчанию 0.0. Dropout для пути PSOFT. Семантика такая же, как у dropout в LoRA.
  • fan_in_fan_out (bool) — Установите это значение в True, если заменяемый слой хранит веса в формате (fan_in, fan_out). Например, gpt-2 использует Conv1D, который хранит веса в формате (fan_in, fan_out), поэтому это значение должно быть установлено в True.
  • ab_svd_init (Literal["psoft_init", "pissa_init"]) — По умолчанию ‘psoft_init’. Стратегия инициализации A и B, используемая для построения главного подпространства в PSOFT. ‘psoft_init’: инициализация на основе SVD с A, ортогональным по строкам, что обеспечивает строгую ортогональность (PSOFT). ‘pissa_init’: инициализация на основе SVD с симметричными A и B (стандартный PiSSA).
  • psoft_svd (Literal["full", "lowrank"]) — По умолчанию ‘full’. Бэкенд SVD для инициализации: ‘full’ использует torch.linalg.svd; ‘lowrank’ использует torch.svd_lowrank.
  • psoft_svd_lowrank_niter (int) — Используется только при psoft_svd=‘lowrank’. По умолчанию равно 10. Количество итераций метода степеней, используемых в torch.svd_lowrank при psoft_svd=‘lowrank’.
  • psoft_orth (bool) — По умолчанию ‘True’. Если True, матрица R ограничивается ортогональностью с помощью параметризации Кэли, что сохраняет геометрические соотношения между столбцами векторов предобученных весов. Если False, R является свободной матрицей без ограничений ортогональности.
  • psoft_mag_b (bool) — По умолчанию ‘True’. Если True, обучает вектор диагонального масштабирования на стороне ‘output’ матрицы R. Часто используется в паре с psoft_mag_a для повышения адаптивности к задаче, с незначительным искажением предобученной геометрии.
  • psoft_mag_a (bool) — По умолчанию ‘True’. Если True, обучает вектор диагонального масштабирования на стороне ‘input’ матрицы R. Часто используется в паре с psoft_mag_b для повышения адаптивности к задаче, с незначительным искажением предобученной геометрии.
  • use_cayley_neumann (bool) — По умолчанию ‘False’. Использовать ли формулировку Кэли–Ноймана для PSOFT. Установите True для повышения вычислительной эффективности, но это приведёт к увеличению ошибки аппроксимации ортогональности.
  • num_cayley_neumann_terms (int) — По умолчанию равно 5. Используется только при use_cayley_neumann=True. Количество членов Кэли-Ноймана, которые следует использовать. Чем больше значение, тем меньше ошибка аппроксимации ортогональности.
  • cayley_neumann_eps (optional[float]) — По умолчанию ‘None’. Используется только при use_cayley_neumann=True. Необязательное ограничение нормы Фробениуса для матрицы генератора Q в приближении Кэли-Ниманна. Если значение равно None (по умолчанию), перемасштабирование не применяется. Если установлено значение из интервала (0, 1) (например, 0.9), Q перемасштабируется всякий раз, когда ||Q||_F превышает порог, для улучшения численной устойчивости. Подробности см. по адресу https://spherelab.ai/oftv2/.
  • init_weights (bool) — По умолчанию ‘True’. Определяет, следует ли инициализировать веса слоёв PSOFT с использованием их стандартной инициализации. Не изменяйте этот параметр, если вы точно не знаете, что делаете.
  • modules_to_save (List[str]) — Список модулей, помимо адаптерных слоёв, которые нужно сделать обучаемыми и сохранить в итоговой контрольной точке.
  • layers_to_transform (Union[List[int], int]) — Индексы слоёв, подлежащих трансформации. Если передан список целых чисел, адаптер будет применён к слоям с индексами, указанными в этом списке. Если передано одно целое число, трансформации будут применены к слою с этим индексом.
  • layers_pattern (Optional[Union[List[str], str]]) — Имя шаблона слоя, используется только в том случае, если layers_to_transform отличается от None. Этот параметр должен указывать на nn.ModuleList модели, который часто называется 'layers' или 'h'.

Конфигурация для PSOFT (Эффективное ортогональное дообучение с адапцией главного подпространства).

PSOFT вставляет ортогональное преобразование R размера r*r между матрицами низкого ранга A и B, так что обновление низкого ранга имеет вид ΔW = B @ (R-I) @ A. Обучается только R (а также необязательные настраиваемые векторы); A и B инициализируются с помощью psoft_init (на основе SVD, с ортогональными по строкам A) и затем замораживаются.

PsoftModel

класс peft.PsoftModel

< >

( modelpeft_config: Union[PeftConfig, dict[str, PeftConfig]]adapter_name: strlow_cpu_mem_usage: bool = Falsestate_dict: Optional[dict[str, torch.Tensor]] = None )

Параметры

  • model — Модель, которую нужно адаптировать.
  • config — PsoftConfig.
  • adapter_name — Имя адаптера, по умолчанию “default”.
  • low_cpu_mem_usage — Создаёт пустые веса адаптера на мета-устройстве.

Модель PSOFT (Efficient Orthogonal Fine-Tuning with Principal Subspace Adaptation).

Вставляет ортогональное (или масштабированное) преобразование R размера r*r между матрицами низкого ранга A и B: ΔW = B @ (R-I) @ A. Используйте ab_svd_init="psoft_init", чтобы инициализировать A/B с помощью SVD и заморозить их, обучая только R (и необязательные векторы амплитуды).

Update on GitHub