# X-LoRA

Mixture of LoRA Experts ([X-LoRA](https://huggingface.co/papers/2402.07148)) — это метод 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](https://github.com/EricLBuehler/xlora/raw/master/res/token_by_token_scalings.gif)

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

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

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

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

Пожалуйста, цитируйте X-LoRA следующим образом:
```bibtex
@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]]

#### peft.XLoraConfig[[peft.XLoraConfig]]

```python
peft.XLoraConfig(task_type: Optional[Union[str, TaskType]] = None, peft_type: Optional[Union[str, PeftType]] = None, auto_mapping: Optional[dict] = None, peft_version: Optional[str] = None, base_model_name_or_path: Optional[str] = None, revision: Optional[str] = None, inference_mode: bool = False, hidden_size: int = None, adapters: dict[str, str] = None, enable_softmax: bool = True, enable_softmax_topk: bool = False, layerwise_scalings: bool = False, xlora_depth: int = 1, xlora_size: int = 2048, xlora_dropout_p: float = 0.2, use_trainable_adapters: bool = False, softmax_temperature: float = 1.0, top_k_lora: Optional[int] = None, scaling_pass_value: float = 0.0, global_scaling_weight: float = 1.0)
```

[Источник](https://github.com/huggingface/peft/blob/main/src/peft/tuners/xlora/config.py#L25)

**Параметры:**

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`, *optional*, по умолчанию 1.0) : Температура softmax; меньшее значение приводит к более резким прогнозам

layerwise_scalings (`bool`, *необязательный*, по умолчанию `False`) : Если True, генерируются масштабы для каждого адаптера LoRA (каждого слоя). Если False, масштабы будут распространяться одинаково на каждый слой.

top_k_lora (`int`, *optional*, по умолчанию None) : Разреженно выбирает top_k экспертов LoRA вместо метода dense по умолчанию.

xlora_depth (`int`, *необязательный*, по умолчанию 1) : Глубина классификатора X-LoRA.

xlora_size (`int`, *optional*, по умолчанию 2048) : Размер скрытого слоя классификатора X-LoRA, не имеет значения, если `xlora_depth=1`.

xlora_dropout_p (`float`, *optional*, по умолчанию 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]]

#### peft.XLoraModel[[peft.XLoraModel]]

```python
peft.XLoraModel(model: nn.Module, config: Union[dict[str, XLoraConfig], XLoraConfig], adapter_name: str, torch_device: Optional[str] = None, ephemeral_gpu_offload: bool = False, autocast_adapter_dtype: bool = True, **kwargs)
```

[Источник](https://github.com/huggingface/peft/blob/main/src/peft/tuners/xlora/model.py#L156)

**Параметры:**

model (`torch.nn.Module`) : модель, подлежащая адаптации.

config ([XLoraConfig](/docs/peft/main/ru/package_reference/xlora#peft.XLoraConfig)) : конфигурация модели Lora.

adapter_name (`str`) : Имя адаптера, не влияет на имена адаптеров LoRA.

**Возвращает:** `torch.nn.Module`

Модель X-LoRA.

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

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

Пример:
```py
>>> 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[[peft.XLoraModel.clear_scalings_log]]

```python
clear_scalings_log()
```

[Источник](https://github.com/huggingface/peft/blob/main/src/peft/tuners/xlora/model.py#L518)

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

#### disable_scalings_logging[[peft.XLoraModel.disable_scalings_logging]]

```python
disable_scalings_logging()
```

[Источник](https://github.com/huggingface/peft/blob/main/src/peft/tuners/xlora/model.py#L511)

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

#### enable_scalings_logging[[peft.XLoraModel.enable_scalings_logging]]

```python
enable_scalings_logging()
```

[Источник](https://github.com/huggingface/peft/blob/main/src/peft/tuners/xlora/model.py#L504)

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

#### get_bucketed_scalings_log[[peft.XLoraModel.get_bucketed_scalings_log]]

```python
get_bucketed_scalings_log()
```

[Источник](https://github.com/huggingface/peft/blob/main/src/peft/tuners/xlora/model.py#L525)

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

#### get_global_scaling_weight[[peft.XLoraModel.get_global_scaling_weight]]

```python
get_global_scaling_weight()
```

[Источник](https://github.com/huggingface/peft/blob/main/src/peft/tuners/xlora/model.py#L481)

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

#### get_latest_scalings[[peft.XLoraModel.get_latest_scalings]]

```python
get_latest_scalings()
```

[Источник](https://github.com/huggingface/peft/blob/main/src/peft/tuners/xlora/model.py#L488)

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

#### get_scalings_log[[peft.XLoraModel.get_scalings_log]]

```python
get_scalings_log()
```

[Источник](https://github.com/huggingface/peft/blob/main/src/peft/tuners/xlora/model.py#L495)

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

#### set_global_scaling_weight[[peft.XLoraModel.set_global_scaling_weight]]

```python
set_global_scaling_weight(weight: float)
```

[Источник](https://github.com/huggingface/peft/blob/main/src/peft/tuners/xlora/model.py#L465)

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

#### set_scaling_pass_value[[peft.XLoraModel.set_scaling_pass_value]]

```python
set_scaling_pass_value(value: float | None)
```

[Источник](https://github.com/huggingface/peft/blob/main/src/peft/tuners/xlora/model.py#L473)

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

#### set_topk_lora[[peft.XLoraModel.set_topk_lora]]

```python
set_topk_lora(value: Optional[int])
```

[Источник](https://github.com/huggingface/peft/blob/main/src/peft/tuners/xlora/model.py#L457)

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