# MonteCLoRA (Monte Carlo Low-Rank Adaptation)

> [!NOTE]
> Это вариант LoRA, поэтому всё, что возможно с LoRA, применимо и к этому методу, если на этой странице не указано иное.

MonteCLoRA дополняет стандартный адаптер LoRA небольшим вариационным модулем, который во время обучения извлекает выборки Монте-Карло стохастических возмущений поверх матрицы `A` LoRA. Конкретно, он обучает вариационные параметры (ковариацию на основе распределения Уишарта, член шума с многомерным нормальным распределением для каждой выборки и веса Дирихле по выборкам) и добавляет полученное усреднённое возмущение к `lora_A` на каждом проходе вперёд. К функции потерь обучения добавляется член KL-дивергенции + энтропии, чтобы удерживать эти вариационные параметры вблизи разумного априорного распределения. На этапе инференса сэмплер отключается, и MonteCLoRA работает точно так же, как обычный адаптер LoRA, поэтому **нет дополнительных затрат на инференс и дополнительных параметров для слияния**. Полное описание метода см. по ссылке https://huggingface.co/papers/2411.04358.

Вы можете рассмотреть вариант использования MonteCLoRA в следующих случаях:

- Вы дообучаете модель на небольшом или зашумленном наборе данных и хотите более сильную регуляризацию, чем в стандартном LoRA. Среднее по Монте-Карло и член KL вместе действуют как регуляризатор в стиле байесовского подхода.
- Вы хотите улучшить калибровку неопределённости / устойчивость вашего адаптера без дополнительных затрат на этапе инференса (вариационный механизм используется только при обучении).
- Vanilla LoRA переобучается, и уменьшение `r` или увеличение `lora_dropout` не помогает.

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

Чтобы включить MonteCLoRA, передайте `MontecloraConfig` в `LoraConfig`:

```py
from peft import LoraConfig, MontecloraConfig

monteclora_config = MontecloraConfig(
    num_samples=8,         # number of Monte Carlo samples per forward pass
    sample_scaler=1e-4,    # magnitude of the variational perturbation
    kl_loss_weight=1e-5,   # weight of the KL term added to the training loss
)
config = LoraConfig(
    r=16,
    lora_alpha=32,
    target_modules=["q_proj", "v_proj"],
    monteclora_config=monteclora_config,
)
```

Во время обучения необходимо добавлять потерю вариационной регуляризации к потере задачи. Самый простой способ — вызвать `LoraModel._get_monteclora_loss()` на базовой модели `LoraModel`:

```py
task_loss = ...  # standard loss returned by your model
monteclora_loss = model._get_monteclora_loss()  # 0.0 if MonteCLoRA is not used
total_loss = task_loss + monteclora_loss
total_loss.backward()
```

Если вы обучаете с помощью `Trainer` от HF, вы можете просто добавить `peft.helpers.MontecloraTrainerMixin`, который выполняет это за вас в `compute_loss`:

```py
from transformers import Trainer
from peft.helpers import MontecloraTrainerMixin

class MontecloraTrainer(MontecloraTrainerMixin, Trainer):
    pass
```

Полный рабочий пример доступен в [`examples/monteclora_finetuning`](https://github.com/huggingface/peft/tree/main/examples/monteclora_finetuning).

# API

## MonteCloraConfig[[peft.MontecloraConfig]]

#### peft.MontecloraConfig[[peft.MontecloraConfig]]

```python
peft.MontecloraConfig(num_samples: int = 8, use_entropy: bool = False, dirichlet_prior: float = 0.1, sample_scaler: float = 0.0001, kl_loss_weight: float = 1e-05, buffer_size: int = 150)
```

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

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

num_samples (`int`) : Количество выборок Монте-Карло, извлекаемых на каждом прямом проходе. Более высокие значения обычно обеспечивают более плавное обучение и более точные оценки неопределенности, но увеличивают вычислительные затраты и потребление памяти. Уменьшите это значение, если обучение слишком медленное или ограничено по памяти; увеличьте его, если обучение стабильно и вы хотите более сильное усреднение Монте-Карло.

use_entropy (`bool`) : Добавлять ли член регуляризации по энтропии, который предотвращает схлопывание весов Монте-Карло в единственную выборку. Включите этот параметр, если наблюдаете, что сэмплер становится слишком пиковым, или если требуется более сильная регуляризация; оставьте его выключенным, чтобы более точно имитировать стандартный LoRA.

dirichlet_prior (`float`) : Параметр концентрации для априорного распределения Дирихле над весами выборок/экспертов. Большие значения сдвигают веса в сторону более равномерного распределения (более сильная регуляризация, меньшая разреженность), тогда как малые положительные значения поощряют более разреженные, пиковые веса. Увеличьте значение, если сэмплер переобучается; уменьшите (но сохраняйте > 0), если он слишком консервативен.

sample_scaler (`float`) : Общий коэффициент масштабирования для выбранных возмущений, применяемых к весам LoRA. Увеличение этого значения усиливает шум Монте-Карло (что приводит к большей регуляризации и исследованию пространства, но также к большей нестабильности обучения); уменьшение приближает поведение к стандартному детерминированному LoRA. Установка значения, очень близкого к 0, в значительной степени отключает эффект Monteclora.

kl_loss_weight (`float`) : Вес члена KL-дивергенции между вариационным распределением и его априорным распределением. Большие значения сильнее акцентируют соответствие априорному распределению (более сильная регуляризация, потенциальная недообученность); меньшие значения больше опираются на правдоподобие данных (более слабая регуляризация, потенциальная переобученность). Настройте этот параметр, если вы обнаруживаете, что Monteclora чрезмерно или недостаточно регуляризирует адаптер.

buffer_size (`int`) : Размер внутреннего буфера, используемого сэмплером Монте-Карло (например, для хранения последних статистик). Большие значения могут стабилизировать оцениваемые вариационные параметры за счёт дополнительного потребления памяти; уменьшите это значение, если объём памяти ограничен.

Это класс подконфигурации для хранения конфигурации Monteclora (Monte Carlo Low-Rank Adaptation). Monteclora вводит вариационный вывод в LoRA, добавляя выборку Монте-Карло к весам адаптера.

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