# MiSS

[MiSS (Matrix Shard Sharing)](https://arxiv.org/abs/2409.15371) adalah metode PEFT yang mencapai keseimbangan yang baik antara kinerja model dan efisiensi komputasi. Metode ini hanya memerlukan satu matriks yang dapat dilatih dan memperkenalkan mekanisme berbagi shard yang berbeda dari LoRA.

Abstrak dari makalah tersebut adalah:

*Metode Fine-Tuning yang Efisien Parameter (PEFT), khususnya Low-Rank Adaptation (LoRA), secara efektif mengurangi jumlah parameter yang dapat dilatih pada Large Language Models (LLM). Namun, seiring terus membesarnya skala model, kebutuhan akan sumber daya komputasi tetap menjadi tantangan signifikan. Varian LoRA yang ada sering kali kesulitan mencapai keseimbangan optimal antara kemampuan adaptasi (kinerja model dan kecepatan konvergensi) dan efisiensi (beban komputasi, penggunaan memori, dan waktu inisialisasi). Kertas kerja ini memperkenalkan MiSS (Matrix Shard Sharing), pendekatan PEFT baru yang mengatasi trade-off ini melalui mekanisme berbagi shard yang sederhana. MiSS memanfaatkan wawasan bahwa adaptasi low-rank dapat dicapai dengan mendekomposisi matriks bobot menjadi beberapa matriks fragmen dan memanfaatkan fragmen bersama yang dapat dilatih. Metode ini membangun matriks pembaruan low-rank melalui replikasi shard-partisi bersama ini. Kami juga mengusulkan implementasi yang efisien secara hardware dan luas penerapannya untuk MiSS. Eksperimen ekstensif yang dilakukan pada berbagai tugas, bersama dengan analisis sistematis kinerja komputasi, menunjukkan keunggulan MiSS. Hasilnya menunjukkan bahwa MiSS secara signifikan melampaui LoRA standar dan variannya yang menonjol dalam metrik kinerja model maupun efisiensi komputasi, termasuk kecepatan inisialisasi dan throughput pelatihan. Dengan menyeimbangkan kekuatan ekspresif dan pemanfaatan sumber daya secara efektif, MiSS menawarkan solusi yang menarik untuk mengadaptasi model berskala besar secara efisien.*

## Ikhtisar benchmark

<iframe src="https://peft-internal-testing-peft-method-comparison-embed.hf.space/?highlight[type]=MISS" frameborder="0" width="850" height="1000"
>

## Kapan menggunakan MiSS

MiSS adalah pilihan yang tepat ketika:

- Anda menginginkan inisialisasi yang lebih cepat dan throughput pelatihan yang lebih tinggi daripada skema inisialisasi LoRA lanjutan yang menggunakan setup mahal (seperti PiSSA, LoRA-GA, atau OLoRA).
- Anda menginginkan alternatif drop-in untuk LoRA dengan perubahan konfigurasi yang minimal.

Jika Anda membutuhkan ekspresivitas yang lebih kuat dengan mengorbankan sedikit efisiensi, pertimbangkan varian inisialisasi `bat` (lihat di bawah).

## mode init_weights

MiSS mendukung tiga mode inisialisasi melalui parameter `init_weights`:

- `True` (default): Inisialisasi MiSS standar. Titik awal terbaik untuk sebagian besar kasus penggunaan.
- `"bat"`: Mengaktifkan pembaruan nonlinier di antara shard yang berbeda. Menghasilkan hasil yang lebih baik daripada MiSS standar, tetapi menggunakan lebih banyak memori dan sekitar dua kali lebih lambat. Gunakan ini ketika performa menjadi prioritas di atas efisiensi.
- `"mini"`: Menggunakan rank yang lebih kecil di sepanjang dimensi `out_features`, dikendalikan oleh `mini_r`. Hal ini mengurangi jumlah parameter yang dapat dilatih lebih lanjut. Saat menggunakan mode ini, `mini_r` harus diatur dan `out_features` harus dapat dibagi habis oleh `mini_r`.

## Mulai cepat

```python
import torch
from peft import MissConfig, get_peft_model
from transformers import AutoModelForCausalLM, AutoTokenizer

model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-2-7b-hf",
    torch_dtype=torch.bfloat16,
    device_map="auto"
)
tokenizer = AutoTokenizer.from_pretrained("meta-llama/Llama-2-7b-hf")
tokenizer.pad_token_id = tokenizer.eos_token_id

# Standard MiSS
config = MissConfig(
    r=64,
    miss_dropout=0.01,
    task_type="CAUSAL_LM"
)

# BAT variant — better performance, more memory
# config = MissConfig(
#     r=64,
#     init_weights="bat",
#     task_type="CAUSAL_LM"
# )

# Mini variant — fewer trainable parameters
# config = MissConfig(
#     r=64,
#     init_weights="mini",
#     mini_r=8,
#     task_type="CAUSAL_LM"
# )

model = get_peft_model(model, config)
model.print_healthcheck()
```

Untuk contoh fine-tuning lengkap yang mencakup pelatihan dan inferensi, lihat [contoh fine-tuning MiSS](https://github.com/huggingface/peft/tree/main/examples/miss_finetuning).

# API

## MissConfig[[peft.MissConfig]]

#### peft.MissConfig[[peft.MissConfig]]

```python
peft.MissConfig(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, r: int = 64, miss_dropout: float = 0.0, mini_r: int = 1, target_modules: Optional[Union[list[str], str]] = None, exclude_modules: Optional[Union[list[str], str]] = None, init_weights: bool | Literal['bat', 'mini'] = True, layers_to_transform: Optional[Union[list[int], int]] = None, layers_pattern: Optional[str] = None, bias: str = 'none', modules_to_save: Optional[list[str]] = None)
```

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

**Parameter:**

r (`int`) : Rank dari MiSS di berbagai lapisan. Disarankan untuk mengatur 'r' ke angka genap; jika tidak, metode inisialisasi default tidak akan berfungsi. Rank dari MiSS sesuai dengan dekomposisi low-rank di sepanjang dimensi in_features.

miss_dropout (`float`) : Probabilitas dropout untuk lapisan MiSS.

mini_r (`int`) : Rank dari MiSS sesuai dengan dekomposisi low-rank sepanjang dimensi out_features. Ketika Anda mengatur `init_weights=mini`, Anda perlu mengatur `mini_r`. Pastikan bahwa `out_features` dapat dibagi habis oleh `mini_r`.

target_modules (`Optional[Union[List[str], str]]`) : Nama-nama modul yang akan diterapkan adapter-nya. Jika ini ditentukan, hanya modul dengan nama yang ditentukan yang akan diganti. Saat meneruskan string, pencocokan regex akan dilakukan. Saat meneruskan daftar string, pencocokan persis akan dilakukan atau diperiksa apakah nama modul diakhiri dengan salah satu string yang diteruskan. Jika ini ditentukan sebagai 'all-linear', maka semua modul linear dipilih, kecuali lapisan output. Jika ini tidak ditentukan, modul akan dipilih sesuai dengan arsitektur model. Jika arsitekturnya tidak diketahui, error akan dilempar -- dalam kasus ini, Anda harus menentukan modul target secara manual.

exclude_modules (`Optional[Union[List[str], str]]`) : Nama-nama modul yang tidak akan diterapkan adapter. Saat melewatkan string, pencocokan regex akan dilakukan. Saat melewatkan daftar string, pencocokan persis akan dilakukan atau diperiksa apakah nama modul diakhiri dengan salah satu string yang dilewatkan.

init_weights (bool | Literal["bat", "mini"]) : Inisialisasi yang berbeda sesuai dengan varian MiSS yang berbeda. Secara default (balance), metode yang paling efisien dan umum dalam MiSS akan digunakan. 'bat': Dalam mode ini, Anda dapat mengaktifkan pembaruan nonlinier di antara shard yang berbeda. 'mini': Dalam mode ini, Anda dapat mengatur rank yang lebih kecil untuk menggunakan parameter yang dapat dilatih lebih sedikit, tetapi disarankan untuk menjaga `out_features % mini_r == 0`.

layers_to_transform (`Union[List[int], int]`) : Indeks lapisan yang akan ditransformasi. Jika daftar int diberikan, adapter akan diterapkan pada indeks lapisan yang ditentukan dalam daftar ini. Jika satu integer diberikan, transformasi akan diterapkan pada lapisan di indeks tersebut.

layers_pattern (`str`) : Nama pola layer, hanya digunakan jika `layers_to_transform` berbeda dari `None`.

bias (`str`) : Jenis bias untuk MiSS. Bisa berupa `'none'`, `'all'` atau `'MiSS_only'`.

modules_to_save (`List[str]`) : Daftar modul selain lapisan adapter yang akan diatur sebagai dapat dilatih dan disimpan dalam checkpoint akhir.

Ini adalah kelas konfigurasi untuk menyimpan konfigurasi dari [MissModel](/docs/peft/main/id/package_reference/miss#peft.MissModel).

## MissModel[[peft.MissModel]]

#### peft.MissModel[[peft.MissModel]]

```python
peft.MissModel(model, peft_config: Union[PeftConfig, dict[str, PeftConfig]], adapter_name: str, low_cpu_mem_usage: bool = False, state_dict: Optional[dict[str, torch.Tensor]] = None)
```

[Sumber](https://github.com/huggingface/peft/blob/main/src/peft/tuners/miss/model.py#L38)

**Parameter:**

model (`torch.nn.Module`) : Model tempat lapisan adapter tuner akan dilampirkan.

config ([MissConfig](/docs/peft/main/id/package_reference/miss#peft.MissConfig)) : Konfigurasi dari model MiSS.

adapter_name (`str`) : Nama adapter, secara default `"default"`.

low_cpu_mem_usage (`bool`, `optional`, defaultnya `False`) : Membuat bobot adapter kosong pada perangkat meta. Berguna untuk mempercepat proses pemuatan.

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

Model MiSS.

Membuat model adaptasi refleksi Householder (MiSS) dari model pretrained. Metode ini dijelaskan di https://huggingface.co/papers/2409.15371

Contoh:
```py
>>> from diffusers import StableDiffusionPipeline
>>> from peft import MissModel, MissConfig

>>> config_te = MissConfig(
...     r=8,
...     target_modules=["k_proj", "q_proj", "v_proj", "out_proj", "fc1", "fc2"],
...     init_weights=True,
... )
>>> config_unet = MissConfig(
...     r=8,
...     target_modules=[
...         "proj_in",
...         "proj_out",
...         "to_k",
...         "to_q",
...         "to_v",
...         "to_out.0",
...         "ff.net.0.proj",
...         "ff.net.2",
...     ],
...     init_weights=True,
... )

>>> model = StableDiffusionPipeline.from_pretrained("runwayml/stable-diffusion-v1-5")
>>> model.text_encoder = MissModel(model.text_encoder, config_te, "default")
>>> model.unet = MissModel(model.unet, config_unet, "default")
```

**Atribut**:
- **model** (`~torch.nn.Module`) -- Model yang akan diadaptasi.
- **peft_config** ([MissConfig](/docs/peft/main/id/package_reference/miss#peft.MissConfig)): Konfigurasi model MiSS.

