# MonteCLoRA (Adaptation de rang faible Monte Carlo)

> [!NOTE]
> Il s’agit d’une variante de LoRA et, par conséquent, tout ce qui est possible avec LoRA s’applique à cette méthode, sauf indication contraire sur cette page.

MonteCLoRA enveloppe un adaptateur LoRA standard avec un petit module variationnel qui tire des échantillons Monte Carlo de perturbations stochastiques sur la matrice `A` de LoRA pendant l’entraînement. Concrètement, il apprend des paramètres variationnels (une covariance basée sur Wishart, un terme de bruit multivarié normal par échantillon, et un pondération Dirichlet sur les échantillons) et ajoute la perturbation moyenne résultante à `lora_A` à chaque passe avant. Un terme de divergence KL + entropie est ajouté à la perte d’entraînement pour ancrer ces paramètres variationnels à une a priori raisonnable. Au moment de l’inférence, l’échantillonneur est désactivé et MonteCLoRA se comporte exactement comme un adaptateur LoRA classique, il n’y a donc **aucun coût d’inférence supplémentaire ni de paramètres supplémentaires à fusionner**. Pour la méthode complète, voir https://huggingface.co/papers/2411.04358.

Vous pouvez envisager d'utiliser MonteCLoRA lorsque :

- Vous effectuez un fine-tuning sur un petit jeu de données ou un jeu de données bruité et souhaitez une régularisation plus forte que celle de LoRA standard. La moyenne de Monte Carlo et le terme KL agissent ensemble comme un régularisateur de type bayésien.
- Vous souhaitez une meilleure calibration de l'incertitude / une meilleure robustesse de votre adaptateur sans coût supplémentaire au moment de l'inférence (le mécanisme variationnel n'est utilisé que lors de l'entraînement).
- LoRA standard est en surapprentissage et diminuer `r` ou augmenter `lora_dropout` ne suffit pas.

Vous n'avez probablement *pas* besoin de MonteCLoRA si vous disposez d'un jeu de données volumineux et propre et que LoRA standard s'entraîne déjà de manière stable — dans ce régime, les paramètres variationnels supplémentaires ajoutent principalement une surcharge d'entraînement sans grand bénéfice.

Pour activer MonteCLoRA, passez un `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,
)
```

Lors de l’entraînement, vous devez ajouter la perte de régularisation variationnelle à la perte de la tâche. La méthode la plus simple consiste à appeler `LoraModel._get_monteclora_loss()` sur le `LoraModel` sous-jacent :

```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()
```

Si vous entraînez avec le `Trainer` de HF, vous pouvez simplement intégrer `peft.helpers.MontecloraTrainerMixin`, qui le fait pour vous dans `compute_loss` :

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

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

Un exemple complet et fonctionnel est disponible dans [`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)
```

[Source](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/lora/config.py#L1283)

**Paramètres :**

num_samples (`int`) : Nombre d'échantillons de Monte Carlo à tirer par passe avant. Des valeurs plus élevées donnent généralement un entraînement plus lisse et de meilleures estimations d'incertitude, mais augmentent l'utilisation du calcul et de la mémoire. Diminuez cette valeur si l'entraînement est trop lent ou si la mémoire est limitée ; augmentez-la si l'entraînement est stable et que vous souhaitez un lissage de Monte Carlo plus robuste.

use_entropy (`bool`) : Indique s'il faut ajouter un terme de régularisation par entropie pour empêcher les poids de Monte Carlo de se concentrer sur un seul échantillon. Activez cette option si vous observez que l'échantillonneur devient très pointu ou si vous souhaitez une régularisation plus forte ; laissez-la désactivée pour imiter plus fidèlement le LoRA standard.

dirichlet_prior (`float`) : Paramètre de concentration pour l'antécédent de Dirichlet sur les poids des échantillons/experts. Des valeurs plus élevées poussent les poids à être plus uniformes (régularisation plus forte, moins de parcimonie), tandis que des valeurs positives plus faibles encouragent des poids plus parcimonieux et plus pointus. Augmentez si l'échantillonneur sur-apprend ; diminuez (mais gardez > 0) s'il est trop conservateur.

sample_scaler (`float`) : Facteur d'échelle global pour les perturbations échantillonnées appliquées aux poids LoRA. L'augmenter renforce le bruit de Monte Carlo (plus de régularisation et d'exploration, mais aussi plus d'instabilité d'entraînement) ; le diminuer rapproche le comportement du LoRA déterministe standard. Le régler très proche de 0 désactive largement l'effet de Monteclora.

kl_loss_weight (`float`) : Poids du terme de divergence de KL entre la distribution variationnelle et son a priori. Des valeurs plus élevées accordent plus d'importance à l'ajustement à l'a priori (régularisation plus forte, risque de sous-apprentissage) ; des valeurs plus faibles s'appuient davantage sur la vraisemblance des données (régularisation plus faible, risque de sur-apprentissage). Ajustez ce paramètre si vous constatez que Monteclora régularise excessivement ou insuffisamment l'adaptateur.

buffer_size (`int`) : Taille du tampon interne utilisé par l'échantillonneur Monte Carlo (par exemple pour stocker les statistiques récentes). Des valeurs plus élevées peuvent stabiliser les paramètres variationnels estimés au prix d'une mémoire supplémentaire ; réduisez cette valeur si vous êtes limité en mémoire.

Il s’agit de la classe de sous-configuration destinée à stocker la configuration de Monteclora (Monte Carlo Low-Rank Adaptation). Monteclora introduit l’inférence variationnelle dans LoRA en ajoutant un échantillonnage de Monte Carlo aux poids de l’adaptateur.

En pratique, vous pouvez considérer Monteclora comme l'ajout de perturbations stochastiques et apprises sur les poids LoRA afin d'obtenir un adaptateur mieux calibré et mieux régularisé. Les arguments ci-dessous vous permettent de trouver un équilibre entre la stabilité, l'intensité de la régularisation et le coût de calcul.

