PEFT documentation

X-LoRA

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.21.0).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

X-LoRA

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

A unique aspect of X-LoRA is its versatility: it can be applied to any transformers base model with LoRA adapters. This means that, despite the mixture of experts strategy, no changes to the model code must be made.

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

Token-by-token scalings

На каждом шаге X-LoRA требует, чтобы базовая модель запускалась дважды: сначала для получения скрытых состояний без каких-либо адаптеров LoRA, а затем эти скрытые состояния используются для вычисления масштабирующих коэффициентов, которые применяются к адаптерам LoRA, после чего модель запускается второй раз. Результатом шага модели является выход второго запуска.

В конечном итоге X-LoRA позволяет модели рефлексировать над своими знаниями благодаря схеме двойного прямого прохода и динамически перенастраивать архитектуру.

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

Мы описываем стратегию смешения экспертов для создания дообученных больших языковых моделей с использованием глубокого послойного подхода на уровне токенов, основанного на адаптации низкого ранга (LoRA). Начиная с набора предварительно обученных адаптеров LoRA, наша стратегия гейтинга использует скрытые состояния для динамического смешивания адаптированных слоев, что позволяет итоговой модели X-LoRA опираться на различные возможности и создавать ранее не использовавшиеся глубокие послойные комбинации для решения задач. Дизайн вдохновлен биологическими принципами универсальности и разнообразия, при которых строительные блоки нейронных сетей переиспользуются в различных иерархических проявлениях. Таким образом, модель X-LoRA легко реализуется для любой существующей большой языковой модели (LLM) без необходимости модификации базовой структуры. Мы разработали специализированную модель X-LoRA, которая предлагает научные возможности, включая задачи прямого/обратного анализа и улучшенную способность к рассуждениям, с фокусом на анализе биоматериалов, механике и дизайне белков. Влияние этой работы включает доступ к легко расширяемым и адаптируемым моделям с сильными знаниями в предметной области и способностью к интеграции между областями знаний. Имея экспертов в области биологии, математики, рассуждений, биоинспирированных материалов, механики и материаловедения, химии, биофизики белков, механики и квантово-механических молекулярных свойств, мы проводим серию исследований, ориентированных на физику. Мы изучаем воспроизведение знаний, прямые/обратные задачи механики белков, дизайн белков, адверсариальное агентное моделирование, включая построение онтологических графов знаний, а также молекулярный дизайн. Модель способна не только делать количественные прогнозы наномеханических свойств белков или квантово-механических молекулярных свойств, но и рассуждать над результатами и правильно предсказывать вероятные механизмы, объясняющие различные молекулярные поведения..

Пожалуйста, цитируйте X-LoRA следующим образом:

@article{10.1063/5.0203126,
    author = {Buehler, Eric L. and Buehler, Markus J.},
    title = "{X-LoRA: Mixture of low-rank adapter experts, a flexible framework for large language models with applications in protein mechanics and molecular design}",
    journal = {APL Machine Learning},
    volume = {2},
    number = {2},
    pages = {026119},
    year = {2024},
    month = {05},
    abstract = "{We report a mixture of expert strategy to create fine-tuned large language models using a deep layer-wise token-level approach based on low-rank adaptation (LoRA). Starting with a set of pre-trained LoRA adapters, our gating strategy uses the hidden states to dynamically mix adapted layers, allowing the resulting X-LoRA model to draw upon different capabilities and create never-before-used deep layer-wise combinations to solve tasks. The design is inspired by the biological principles of universality and diversity, where neural network building blocks are reused in different hierarchical manifestations. Hence, the X-LoRA model can be easily implemented for any existing large language model without a need for modifications of the underlying structure. We develop a tailored X-LoRA model that offers scientific capabilities, including forward/inverse analysis tasks and enhanced reasoning capability, focused on biomaterial analysis, protein mechanics, and design. The impact of this work includes access to readily expandable and adaptable models with strong domain knowledge and the capability to integrate across areas of knowledge. Featuring experts in biology, mathematics, reasoning, bio-inspired materials, mechanics and materials, chemistry, protein biophysics, mechanics, and quantum-mechanics based molecular properties, we conduct a series of physics-focused case studies. We examine knowledge recall, protein mechanics forward/inverse tasks, protein design, adversarial agentic modeling including ontological knowledge graph construction, and molecular design. The model is capable not only of making quantitative predictions of nanomechanical properties of proteins or quantum mechanical molecular properties but also reasoning over the results and correctly predicting likely mechanisms that explain distinct molecular behaviors.}",
    issn = {2770-9019},
    doi = {10.1063/5.0203126},
    url = {https://doi.org/10.1063/5.0203126},
    eprint = {https://pubs.aip.org/aip/aml/article-pdf/doi/10.1063/5.0203126/19964043/026119\_1\_5.0203126.pdf},
}

API

XLoraConfig

класс peft.XLoraConfig

< >

( 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 = Falsehidden_size: int = Noneadapters: dict[str, str] = Noneenable_softmax: bool = Trueenable_softmax_topk: bool = Falselayerwise_scalings: bool = Falsexlora_depth: int = 1xlora_size: int = 2048xlora_dropout_p: float = 0.2use_trainable_adapters: bool = Falsesoftmax_temperature: float = 1.0top_k_lora: Optional[int] = Nonescaling_pass_value: float = 0.0global_scaling_weight: float = 1.0 )

Параметры

  • hidden_size (int) — Размер скрытого слоя базовой модели.
  • adapters (dict) — Сопоставление имён адаптеров с идентификаторами адаптеров LoRA, согласно PeftModel.load_adapter. Они будут автоматически загружены для использования в качестве экспертов LoRA. При использовании from_pretrained передайте новый словарь адаптеров как именованный аргумент.
  • enable_softmax (bool, необязательный, по умолчанию True) — Включает применение softmax для классификатора X-LoRA.
  • enable_softmax_topk (bool, необязательный, по умолчанию False) — Включает применение softmax для топ-k адаптеров LoRA. Взаимоисключающий с enable_softmax и должен устанавливаться только в том случае, если задан top_k_lora.
  • softmax_temperature (float, необязательный, по умолчанию 1.0) — Температура softmax; меньшее значение приводит к более чётким предсказаниям
  • layerwise_scalings (bool, необязательный, по умолчанию False) — Если True, генерирует масштабы для каждого адаптера LoRA (каждого слоя). Если False, масштабы будут распространяться одинаково на каждый слой.
  • top_k_lora (int, необязательный, по умолчанию None) — Спарсифицированно выбирает top_k LoRA-экспертов вместо метода по умолчанию (dense).
  • xlora_depth (int, необязательный, по умолчанию 1) — Глубина классификатора X-LoRA.
  • xlora_size (int, необязательный, по умолчанию 2048) — Размер скрытого слоя классификатора X-LoRA, не имеет значения, если xlora_depth=1.
  • xlora_dropout_p (float, необязательный, по умолчанию 0.2) — Вероятность dropout для классификатора X-LoRA, не имеет значения, если xlora_depth=1.
  • use_trainable_adapters (bool, необязательный, по умолчанию False) — Сделать адаптеры обучаемыми.
  • scaling_pass_value (float, необязательный, по умолчанию 0) — Значение масштабируемого прохода.
  • global_scaling_weight (float, необязательный, по умолчанию 1) — Множитель, на который умножается выход каждого адаптера LoRA.

Это класс конфигурации для хранения настроек модели XLoraModel. При повторной загрузке конфигурации пути из поля adapters игнорируются в пользу сохранённых адаптеров. Таким образом, при загрузке важны только ключи.

XLoraModel

класс peft.XLoraModel

< >

( model: nn.Moduleconfig: Union[dict[str, XLoraConfig], XLoraConfig]adapter_name: strtorch_device: Optional[str] = Noneephemeral_gpu_offload: bool = Falseautocast_adapter_dtype: bool = True**kwargs ) → torch.nn.Module

Параметры

  • model (torch.nn.Module) — Модель, подлежащая адаптации.
  • config (XLoraConfig) — конфигурация модели Lora.
  • adapter_name (str) — Имя адаптера, не влияет на имена адаптеров LoRA.

Возвращает

torch.nn.Module

Модель X-LoRA.

Создаёт модель X-LoRA (смесь экспертов LoRA) на основе предобученной модели transformers. В настоящее время эта реализация X-LoRA работает только с моделями, имеющими архитектуру трансформера.

Метод подробно описан в https://huggingface.co/papers/2402.07148.

Пример:

>>> import torch
>>> from transformers import AutoModelForCausalLM, AutoConfig, BitsAndBytesConfig
>>> from peft import XLoraConfig, get_peft_model, prepare_model_for_kbit_training

>>> model_config = AutoConfig.from_pretrained("mistralai/Mistral-7B-Instruct-v0.1")
>>> config = XLoraConfig(
...     task_type="CAUSAL_LM",
...     hidden_size=model_config.hidden_size,
...     xlora_depth=4,
...     adapters={
...         "adapter_1": "./path/to/the/checkpoint/",
...         "adapter_2": "./path/to/the/checkpoint/",
...         "adapter_n": "./path/to/the/checkpoint/",
...     },
... )
>>> int8_config = BitsAndBytesConfig(load_in_8bit=True)
>>> model = AutoModelForCausalLM.from_pretrained(
...     "mistralai/Mistral-7B-Instruct-v0.1",
...     trust_remote_code=True,
...     attn_implementation="flash_attention_2",
...     device_map="cuda:0",
...     torch_dtype=torch.bfloat16,
...     quantization_config=int8_config,
... )
>>> model = prepare_model_for_kbit_training(model)
>>> xlora_model = get_peft_model(model, config)

clear_scalings_log

< >

( )

Очистите журнал масштабирования.

disable_scalings_logging

< >

( )

Отключить ведение журнала масштабирования, не очищая журнал.

enable_scalings_logging

< >

( )

Включить ведение журнала масштабирования.

get_bucketed_scalings_log

< >

( )

Возвращает масштабирования, сгруппированные по seq_len. Каждое значение состоит из позиций (первое) и связанных тензоров. Позиции сопоставляются с соответствующими тензорами и указывают позицию в журнале масштабирования.

get_global_scaling_weight

< >

( )

Получите глобальный вес LoRA.

get_latest_scalings

< >

( )

Возвращает последнее предсказание масштабирования или None, если масштабирования не предсказывались. Форма тензора — (batch_size, seq_len, n_layers, n_classes).

get_scalings_log

< >

( )

Возвращает поверхностную (копирует только сам список, но не тензоры) копию списка, содержащего журнал масштабирования. Изменение списка не изменяет исходный журнал. Тензоры имеют форму (batch_size, seq_len, n_layers, n_classes). Размерность seq_len может варьироваться в зависимости от входного размера.

set_global_scaling_weight

< >

( weight: float )

Установите глобальный вес LoRA — скаляр, на который умножается выход каждого адаптера LoRA. По умолчанию он равен 1. Это отражается в конфигурации.

set_scaling_pass_value

< >

( value: float | None )

Установите значение для прохода масштабирования, то есть значение, которое будет присвоено масштабированиям во время прохода масштабирования. Если значение равно None, значение прохода масштабирования будет равно 1/n, где n — количество адаптеров.

set_topk_lora

< >

( value: Optional[int] )

Разреженно выбирайте указанные top_k эксперты LoRA вместо метода dense по умолчанию. Установите None, чтобы использовать dense. Это отражается в конфигурации.

Update on GitHub