# X-LoRA

Mixture of LoRA Experts ([X-LoRA](https://huggingface.co/papers/2402.07148)) adalah metode PEFT yang memungkinkan campuran LoRA experts secara sparse atau dense berdasarkan matriks penskalaan dengan granularitas tinggi (token, layer, sequence). Metode ini memanfaatkan adapter LoRA yang dibekukan dan model dasar yang dibekukan untuk secara drastis mengurangi jumlah parameter yang perlu dihaluskan.

Aspek unik dari X-LoRA adalah versatilitasnya: dapat diterapkan pada model dasar `transformers` mana pun dengan adapter LoRA. Artinya, meskipun menggunakan strategi mixture of experts, tidak perlu dilakukan perubahan pada kode model.

Grafik di bawah ini menunjukkan bagaimana penskalaan berubah untuk prompt yang berbeda pada setiap token. Hal ini menyoroti aktivasi adapter yang berbeda seiring kemajuan generasi dan pembentukan konteks baru oleh urutan.

![Token-by-token scalings](https://github.com/EricLBuehler/xlora/raw/master/res/token_by_token_scalings.gif)

Untuk setiap langkah, X-LoRA memerlukan model dasar untuk dijalankan dua kali: pertama, untuk mendapatkan hidden states tanpa adapter LoRA apa pun, dan kedua, hidden states tersebut digunakan untuk menghitung scalings yang diterapkan pada adapter LoRA, kemudian model dijalankan untuk kedua kalinya. Hasil dari eksekusi kedua adalah hasil dari langkah model.

Pada akhirnya, X-LoRA memungkinkan model untuk merefleksikan pengetahuannya berkat skema dual forward pass, serta secara dinamis mengonfigurasi ulang arsitekturnya.

Abstrak dari makalah tersebut adalah:

*Kami melaporkan strategi campuran pakar untuk membuat model bahasa besar yang telah disempurnakan menggunakan pendekatan token per lapisan dalam yang berbasis pada adaptasi peringkat rendah (LoRA). Dimulai dari seperangkat adapter LoRA yang telah dilatih sebelumnya, strategi gating kami menggunakan keadaan tersembunyi untuk mencampur lapisan yang telah diadaptasi secara dinamis, memungkinkan model X-LoRA yang dihasilkan untuk memanfaatkan berbagai kemampuan dan menciptakan kombinasi lapisan dalam yang belum pernah digunakan sebelumnya untuk menyelesaikan tugas. Desain ini terinspirasi oleh prinsip biologi universalitas dan keberagaman, di mana blok bangunan jaringan saraf digunakan kembali dalam manifestasi hierarkis yang berbeda. Oleh karena itu, model X-LoRA dapat dengan mudah diimplementasikan untuk model bahasa besar (LLM) yang sudah ada tanpa perlu modifikasi pada struktur dasarnya. Kami mengembangkan model X-LoRA yang disesuaikan yang menawarkan kemampuan ilmiah termasuk tugas analisis maju/balik dan kemampuan penalaran yang ditingkatkan, dengan fokus pada analisis biomaterial, mekanika dan desain protein. Dampak dari pekerjaan ini termasuk akses ke model yang mudah diperluas dan diadaptasi dengan pengetahuan domain yang kuat serta kemampuan untuk terintegrasi di berbagai bidang pengetahuan. Dengan menghadirkan pakar di bidang biologi, matematika, penalaran, material bio-terinspirasi, mekanika dan material, kimia, biofisika protein, mekanika, dan sifat molekuler berbasis mekanika kuantum, kami melakukan serangkaian studi kasus yang berfokus pada fisika. Kami memeriksa pengingatan pengetahuan, tugas maju/balik mekanika protein, desain protein, pemodelan agen adversarial termasuk konstruksi graf pengetahuan ontologis, serta desain molekuler. Model ini mampu tidak hanya membuat prediksi kuantitatif tentang sifat nanomekanik protein atau sifat molekuler mekanika kuantum, tetapi juga menalar hasil tersebut dan dengan benar memprediksi mekanisme yang mungkin menjelaskan perilaku molekuler yang berbeda.*.

Silakan sitasi X-LoRA sebagai:
```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)
```

[Sumber](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/xlora/config.py#L25)

**Parameter:**

hidden_size (`int`) : Ukuran tersembunyi dari model dasar.

adapters (`dict`) : Pemetaan nama adapter ke id adapter LoRA, sesuai dengan PeftModel.load_adapter. *Mereka akan dimuat secara otomatis*, untuk digunakan sebagai pakar LoRA. Saat menggunakan from_pretrained, lewati dict adapter baru sebagai argumen kata kunci.

enable_softmax (`bool`, *opsional*, defaultnya `True`) : Mengaktifkan penerapan softmax untuk klasifikator X-LoRA.

enable_softmax_topk (`bool`, *opsional*, defaultnya `False`) : Mengaktifkan penerapan softmax untuk adapter LoRA top-k. Saling eksklusif dengan `enable_softmax` dan hanya boleh diatur jika `top_k_lora` diatur.

softmax_temperature (`float`, *opsional*, default 1.0) : Suhu softmax, nilai yang lebih rendah menghasilkan prediksi yang lebih tajam

layerwise_scalings (`bool`, *opsional*, defaultnya `False`) : Jika True, generate scalings untuk setiap adapter LoRA (setiap layer). Jika ini False, maka scalings akan di-broadcast, sama, ke setiap layer.

top_k_lora (`int`, *opsional*, defaultnya None) : Pilih secara jarang top_k pakar LoRA alih-alih metode dense default.

xlora_depth (`int`, *opsional*, default 1) : Kedalaman klasifikator X-LoRA.

xlora_size (`int`, *opsional*, default 2048) : Ukuran tersembunyi dari klasifikator X-LoRA, tidak relevan jika `xlora_depth=1`.

xlora_dropout_p (`float`, *opsional*, default 0.2) : Probabilitas dropout dari klasifikator X-LoRA, tidak relevan jika `xlora_depth=1`.

use_trainable_adapters (`bool`, *opsional*, defaultnya False) : Membuat adapter dapat dilatih.

scaling_pass_value (`float`, *opsional*, default 0) : Nilai scaling pass.

global_scaling_weight (`float`, *opsional*, default 1) : Bobot untuk mengalikan output dari setiap adapter LoRA.

Ini adalah kelas konfigurasi untuk menyimpan konfigurasi dari `XLoraModel`. Saat konfigurasi dimuat ulang, path dari field `adapters` diabaikan demi adapter yang disimpan. Dengan demikian, hanya key yang penting saat pemuatan.

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

[Sumber](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/xlora/model.py#L156)

**Parameter:**

model (`torch.nn.Module`) : Model yang akan diadaptasi.

config ([XLoraConfig](/docs/peft/v0.22.0/id/package_reference/xlora#peft.XLoraConfig)) : Konfigurasi model Lora.

adapter_name (`str`) : Nama adapter, tidak memengaruhi nama adapter LoRA.

**Mengembalikan:** `torch.nn.Module`

Model X-LoRA.

Membuat model X-LoRA (Mixture of LoRA experts) dari model transformers yang sudah dilatih sebelumnya. Saat ini, implementasi X-LoRA ini hanya berfungsi dengan model yang memiliki arsitektur transformer.

Metode ini dijelaskan secara detail di https://huggingface.co/papers/2402.07148.

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

[Sumber](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/xlora/model.py#L518)

Hapus log skalasi.

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

```python
disable_scalings_logging()
```

[Sumber](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/xlora/model.py#L511)

Nonaktifkan pencatatan penskalaan, tanpa menghapus log.

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

```python
enable_scalings_logging()
```

[Sumber](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/xlora/model.py#L504)

Aktifkan pencatatan penskalaan.

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

```python
get_bucketed_scalings_log()
```

[Sumber](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/xlora/model.py#L525)

Mengembalikan penskalaan yang dikelompokkan, dikelompokkan berdasarkan seq_len. Setiap nilai terdiri dari posisi (yang pertama) dan tensor terkait. Posisi dipasangkan dengan tensor terkait dan memberikan posisi dalam log penskalaan.

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

```python
get_global_scaling_weight()
```

[Sumber](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/xlora/model.py#L481)

Dapatkan bobot LoRA global.

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

```python
get_latest_scalings()
```

[Sumber](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/xlora/model.py#L488)

Mengembalikan prediksi scalings terbaru, atau None jika tidak ada scalings yang diprediksi. Tensor memiliki bentuk (batch_size, seq_len, n_layers, n_classes).

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

```python
get_scalings_log()
```

[Sumber](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/xlora/model.py#L495)

Mengembalikan salinan dangkal (hanya menyalin daftar itu sendiri, bukan tensor) dari daftar yang berisi log penskalaan. Mengedit daftar tidak mengubah log yang mendasarinya. Tensor memiliki bentuk (batch_size, seq_len, n_layers, n_classes). Dimensi seq_len dapat bervariasi sesuai dengan dimensi input.

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

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

[Sumber](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/xlora/model.py#L465)

Atur bobot LoRA global, yaitu skalar untuk mengalikan keluaran dari setiap adapter LoRA. Secara default, nilainya adalah 1. Nilai ini tercermin dalam konfigurasi.

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

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

[Sumber](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/xlora/model.py#L473)

Setel nilai pass penskalaan, yaitu nilai yang akan disetel untuk penskalaan selama pass penskalaan. Jika nilainya None, nilai pass penskalaan akan menjadi 1/n di mana n adalah jumlah adapter.

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

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

[Sumber](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/xlora/model.py#L457)

Pilih secara jarang top_k pakar LoRA yang ditentukan alih-alih metode dense default. Atur ke None untuk menggunakan dense. Hal ini tercermin dalam config.

