LoRA

LoRA adalah salah satu metode PEFT yang paling populer dan merupakan titik awal yang baik jika Anda baru mulai menggunakan PEFT. Metode ini awalnya dikembangkan untuk model bahasa besar, tetapi menjadi metode pelatihan yang sangat populer untuk model difusi karena efisiensi dan efektivitasnya.

Low-Rank Adaptation (LoRA) adalah metode PEFT yang menguraikan matriks besar menjadi dua matriks ber-rank rendah yang lebih kecil. Hal ini secara drastis mengurangi jumlah parameter yang perlu dihaluskan.

Abstrak dari makalah tersebut adalah:

Paradigma penting dalam pemrosesan bahasa alami terdiri dari pra-pelatihan berskala besar pada data domain umum dan adaptasi ke tugas atau domain tertentu. Seiring dengan pra-pelatihan model yang semakin besar, fine-tuning penuh, yang melatih ulang semua parameter model, menjadi semakin tidak layak. Menggunakan GPT-3 175B sebagai contoh — mendeploykan instance independen dari model yang telah di-fine-tune, masing-masing dengan 175B parameter, sangat mahal. Kami mengusulkan Low-Rank Adaptation, atau LoRA, yang membekukan bobot model pra-terlatih dan menyuntikkan matriks dekomposisi rank yang dapat dilatih ke setiap lapisan arsitektur Transformer, sehingga sangat mengurangi jumlah parameter yang dapat dilatih untuk tugas downstream. Dibandingkan dengan GPT-3 175B yang di-fine-tune dengan Adam, LoRA dapat mengurangi jumlah parameter yang dapat dilatih hingga 10.000 kali dan kebutuhan memori GPU hingga 3 kali. LoRA menghasilkan kualitas model yang setara atau lebih baik daripada fine-tuning pada RoBERTa, DeBERTa, GPT-2, dan GPT-3, meskipun memiliki lebih sedikit parameter yang dapat dilatih, throughput pelatihan yang lebih tinggi, dan, berbeda dengan adapters, tidak ada latensi inferensi tambahan. Kami juga menyediakan investigasi empiris mengenai rank-deficiency dalam adaptasi model bahasa, yang memberikan wawasan tentang efektivitas LoRA. Kami merilis paket yang memfasilitasi integrasi LoRA dengan model PyTorch dan menyediakan implementasi serta checkpoint model kami untuk RoBERTa, DeBERTa, dan GPT-2 di this https URL.

LoRA merepresentasikan pembaruan bobot $\Delta W$ dengan dua matriks yang lebih kecil (disebut matriks pembaruan) melalui dekomposisi rank rendah. Matriks-matriks baru ini dapat dilatih untuk beradaptasi dengan data baru sambil menjaga jumlah total parameter tetap rendah. Matriks bobot asli tetap dibekukan dan tidak menerima pembaruan lebih lanjut. Untuk menghasilkan hasil akhir, bobot asli dan bobot adaptif tambahan digabungkan. Anda juga dapat menggabungkan bobot adapter dengan model dasar untuk menghilangkan latensi inferensi.

Pendekatan ini memiliki sejumlah keuntungan:

• LoRA membuat finetuning lebih efisien dengan mengurangi secara drastis jumlah parameter yang dapat dilatih.
• Bobot pretrained asli tetap dibekukan, yang berarti Anda dapat memiliki beberapa model LoRA yang ringan dan portabel untuk berbagai tugas turunan yang dibangun di atasnya.
• LoRA bersifat ortogonal terhadap metode parameter-efisien lainnya dan dapat dikombinasikan dengan banyak di antaranya.
• Kinerja model yang ditala ulang menggunakan LoRA sebanding dengan kinerja model yang ditala ulang secara penuh.

Pada prinsipnya, LoRA dapat diterapkan pada subset matriks bobot mana pun dalam jaringan saraf untuk mengurangi jumlah parameter yang dapat dilatih. Namun, untuk kesederhanaan dan efisiensi parameter yang lebih lanjut, LoRA biasanya hanya diterapkan pada blok perhatian dalam model Transformer - mungkin juga layak menargetkan lapisan lainnya. Jumlah parameter yang dapat dilatih dalam model LoRA yang dihasilkan bergantung pada ukuran matriks pembaruan, yang terutama ditentukan oleh rank r dan bentuk matriks bobot asli.

Anda dapat menginisialisasi matriks ber-rank rendah dengan mempertimbangkan berbagai kasus penggunaan - kesadaran tugas (CorDA, EVA, Astra), konvergensi yang lebih cepat (PiSSA), mitigasi kuantisasi (LoftQ) - hanya untuk menyebut beberapa kasus penggunaan. Baca tentang inisialisasi yang berbeda di bawah. Inisialisasi default adalah agar LoRA menjadi no-op, untuk secara bertahap mempelajari perilaku baru tanpa banyak mengganggu model yang ada.

Penggunaan

Ukuran matriks pembaruan ber-rank rendah ditentukan oleh rank atau r. Rank yang lebih tinggi berarti model memiliki lebih banyak parameter untuk dilatih, tetapi juga berarti model memiliki kapasitas belajar yang lebih besar. Pada contoh berikut, Anda akan menargetkan matriks query dan value dari blok perhatian. Parameter penting lainnya yang perlu diatur adalah lora_alpha (faktor penskalaan), bias (apakah none, all atau hanya parameter bias LoRA yang harus dilatih), dan modules_to_save (modul di luar lapisan LoRA yang akan dilatih dan disimpan). Semua parameter ini - dan lainnya - dapat ditemukan di LoraConfig.

from peft import LoraConfig, get_peft_model

config = LoraConfig(
    r=16,
    lora_alpha=16,
    target_modules=["query", "value"],
    lora_dropout=0.1,
    bias="none",
    modules_to_save=["classifier"],
)
model = get_peft_model(model, config)
model.print_healthcheck()

Ikhtisar benchmark

Inisialisasi

Inisialisasi bobot LoRA dikendalikan oleh parameter init_lora_weights di LoraConfig. Secara default, PEFT menginisialisasi bobot LoRA dengan Kaiming-uniform untuk bobot A dan nol untuk bobot B, yang menghasilkan transformasi identitas (sama seperti implementasi referensi).

Untuk lapisan transformers.Conv1D, seperti proyeksi GPT-2, gunakan fan_in_fan_out=True karena bobotnya disimpan sebagai (in_features, out_features) alih-alih tata letak nn.Linear. Inisialisator berbasis bobot yang didukung menggunakan tata letak Linear untuk dekomposisi dan memulihkan tata letak penyimpanan saat memperbarui bobot dasar. Penskalaan "stable" dari LoRA-GA juga menggunakan dimensi keluaran terlepas dari tata letak penyimpanan.

Anda juga dapat meneruskan init_lora_weights="gaussian". Sesuai namanya, ini menginisialisasi bobot A dengan distribusi Gaussian dan nol untuk bobot B (inilah cara Diffusers menginisialisasi bobot LoRA).

from peft import LoraConfig

config = LoraConfig(init_lora_weights="gaussian", ...)

Tersedia juga opsi untuk mengatur init_lora_weights=False yang berguna untuk debugging dan pengujian. Ini seharusnya satu-satunya kali Anda menggunakan opsi ini. Saat memilih opsi ini, bobot LoRA diinisialisasi sedemikian rupa sehingga tidak menghasilkan transformasi identitas.

from peft import LoraConfig

config = LoraConfig(init_lora_weights=False, ...)

from torch import nn

from peft import LoraConfig, get_peft_model

model = nn.Sequential(
    nn.Linear(32, 32),
    nn.ReLU(),
    nn.Linear(32, 16),
)

config = LoraConfig(
    r=8,
    lora_alpha=8,
    target_modules=["0", "2"],
    init_lora_weights="nora",
    bias="none",
    lora_bias=False,
    use_rslora=False,
)
model = get_peft_model(model, config)
model.print_healthcheck()

from peft import LoraConfig
config = LoraConfig(init_lora_weights="pissa", ...)

lora_config = LoraConfig(init_lora_weights="pissa_niter_[number of iters]", ...)

from peft import LoraConfig
config = LoraConfig(init_lora_weights="mica", r=16, target_modules=["q_proj", "v_proj"], ...)

@torch.no_grad()
def run_model():
    # Assume `model` and `dataset` is in context...
    model.eval()
    for batch in dataset:
        model(**batch)


corda_config = CordaConfig(
    corda_method="kpm",
)
lora_config = LoraConfig(
    init_lora_weights="corda",
    corda_config=corda_config,
)
preprocess_corda(model, lora_config, run_model=run_model)
peft_model = get_peft_model(model, lora_config)

@torch.no_grad()
def run_model():
    # Assume `model` and `dataset` is in context...
    model.eval()
    for batch in dataset:
        model(**batch)


from peft.tuners.lora import AstraConfig, preprocess_astra

astra_config = AstraConfig()
lora_config = LoraConfig(
    init_lora_weights="astra",
    target_modules=["q_proj", "v_proj"],
    astra_config=astra_config,
)
preprocess_astra(model, lora_config, run_model=run_model)
peft_model = get_peft_model(model, lora_config)

from peft import LoraConfig
config = LoraConfig(init_lora_weights="olora", ...)

from peft import LoraConfig, EvaConfig
peft_config = LoraConfig(
    init_lora_weights = "eva",
    eva_config = EvaConfig(rho = 2.0),
    ...
)

peft_model = get_peft_model(model, peft_config, low_cpu_mem_usage=True)

initialize_lora_eva_weights(peft_model, dataloader)

from peft import LoraConfig

config = LoraConfig(use_rslora=True, ...)

from peft.tuners.lora import preprocess_loraga

def train_step():
    """Run forward and backward passes for gradient estimation."""
    dataloader_iter = iter(grad_dataloader)
    for _ in range(N):
        batch = next(dataloader_iter)
        batch = {k: v.to(device) for k, v in batch.items()}
        outputs = model(**batch)
        loss = outputs.loss
        loss.backward()

preprocess_loraga(model, lora_config, train_step)

Pelatihan

Bagian ini menunjukkan cara menangani skenario pelatihan yang lebih kompleks, bukan sekadar menerapkan adapter ber-rank rendah pada model dan memberi umpan data.

Pelatihan bergaya QLoRA

Pengaturan LoRA bawaan di PEFT menambahkan bobot yang dapat dilatih ke lapisan query dan value dari setiap blok perhatian. Namun, QLoRA, yang menambahkan bobot yang dapat dilatih ke semua lapisan linear dari model transformer, dapat memberikan performa yang setara dengan model yang sepenuhnya ditala ulang. Untuk menerapkan LoRA ke semua lapisan linear, seperti pada QLoRA, atur target_modules="all-linear" (lebih mudah daripada menentukan modul individual berdasarkan nama yang dapat bervariasi tergantung pada arsitektur).

config = LoraConfig(target_modules="all-linear", ...)

Untuk informasi lebih lanjut tentang cara menerapkan kuantisasi ke adapter PEFT, lihat panduan kuantisasi.

Replikasi Layer yang Efisien Memori dengan LoRA

Pendekatan yang digunakan untuk meningkatkan kinerja model adalah memperluas model dengan menduplikasi lapisan dalam model untuk membangun model yang lebih besar dari model pralatih berukuran tertentu. Misalnya, meningkatkan model 7B menjadi model 10B seperti yang dijelaskan dalam makalah SOLAR. PEFT LoRA mendukung jenis ekspansi ini dengan cara yang hemat memori, yang memungkinkan penyesuaian lanjutan menggunakan adapter LoRA yang dipasang pada lapisan setelah replikasi lapisan. Lapisan yang direplikasi tidak memerlukan memori tambahan karena mereka berbagi bobot dasar, sehingga satu-satunya memori tambahan yang diperlukan adalah memori untuk bobot adapter. Untuk menggunakan fitur ini, Anda akan membuat konfigurasi dengan argumen layer_replication.

config = LoraConfig(layer_replication=[[0,4], [2,5]], ...)

Dengan asumsi model asli memiliki 5 lapisan [0, 1, 2 ,3, 4], ini akan membuat model dengan 7 lapisan yang disusun sebagai [0, 1, 2, 3, 2, 3, 4]. Hal ini mengikuti konvensi merge pass through mergekit di mana urutan lapisan yang ditentukan sebagai tuple mulai inklusif dan akhir eksklusif ditumpuk untuk membangun model akhir. Setiap lapisan dalam model akhir mendapatkan set adapter LoRA yang berbeda.

Fewshot-Metamath-OrcaVicuna-Mistral-10B adalah contoh model yang dilatih menggunakan metode ini pada Mistral-7B yang diperluas menjadi 10B. adapter_config.json menunjukkan contoh konfigurasi adapter LoRA yang menerapkan metode ini untuk fine-tuning.

Kontrol terperinci atas rank dan alpha (penyeskalan)

Secara default, semua lapisan yang ditargetkan dengan LoRA akan memiliki rank r yang sama dan lora_alpha yang sama (yang menentukan penskalaan LoRA), tergantung pada apa yang ditentukan dalam LoraConfig. Namun, dalam beberapa kasus, Anda mungkin ingin menunjukkan nilai yang berbeda untuk lapisan yang berbeda. Hal ini dimungkinkan dengan meneruskan argumen rank_pattern dan alpha_pattern ke LoraConfig. Argumen ini harus berupa kamus dengan kunci berupa nama lapisan dan nilai berupa nilai rank/alpha. Kunci dapat berupa regular expressions (regex). Semua lapisan LoRA yang tidak disebutkan secara eksplisit dalam rank_pattern dan alpha_pattern akan mengambil nilai default r dan lora_alpha.

Sebagai contoh, misalkan kita memiliki model dengan struktur berikut:

>>> print(model)
Outer(
  (foo): Linear(...)
  (module): Middle(
    (foo): Linear(...)
    (foobar): Linear(...)
    (module): Inner(
      (foo): Linear(...)
      (barfoo): Linear(...)
    )
  )
)

• rank_pattern={"foo": 42} akan mencocokkan semua 3 lapisan foo. Baik foobar maupun barfoo tidak dicocokkan.
• rank_pattern={"^foo": 42} hanya akan mencocokkan lapisan foo dari model, tetapi tidak mencocokkan module.foo maupun module.module.foo. Hal ini karena ^ berarti “awal string” saat menggunakan ekspresi reguler, dan hanya foo yang diawali dengan "foo"; nama lapisan lainnya memiliki prefiks.
• rank_pattern={"^module.foo": 42} hanya cocok dengan module.foo, tetapi tidak dengan module.module.foo, karena alasan yang sama.
• rank_pattern={"module.foo": 42} cocok dengan module.foo dan module.module.foo, tetapi tidak dengan foo.
• rank_pattern={"^foo": 42, "^module.module.foo": 55} cocok dengan foo dan module.module.foo, masing-masing, tetapi tidak dengan module.foo.
• Tidak perlu menandai $ untuk menandai akhir dari pencocokan, karena ini ditambahkan secara otomatis oleh PEFT.

Logika yang sama berlaku untuk alpha_pattern. Jika Anda ragu, jangan mencoba menggunakan ekspresi reguler yang rumit — cukup berikan nama lengkap untuk setiap modul dengan rank/alpha yang berbeda, didahului oleh prefiks ^, dan Anda seharusnya tidak akan mengalami masalah.

Deteksi modul target yang layak secara otomatis

peft.helpers.KappaTuneSelector mengimplementasikan strategi pemilihan target berbasis bilangan kondisi dari makalah KappaTune. Modul ini memindai setiap modul nn.Linear dan, untuk model di mana bobot ahli MoE disimpan sebagai tensor nn.Parameter 3D yang digabungkan (misalnya Llama-4, Qwen3-MoE), juga parameter-parameter tersebut, menghitung bilangan kondisi matriks κ = σ_max / σ_min untuk masing-masing, lalu memilih lapisan yang paling isotropik (κ terendah). Lapisan isotropik ini berfungsi sebagai kandidat ideal untuk fine-tuning, karena sifat entropi tingginya memungkinkan mereka menyerap informasi baru dengan lebih mudah, sementara lapisan yang terspesialisasi dan anisotropik dibiarkan utuh untuk memitigasi pelupaan katastrofik selama pembelajaran berkelanjutan.

Gunakan peft.helpers.find_kappa_target_modules() sebagai satu baris untuk mendapatkan target_modules optimal untuk LoraConfig:

from peft import LoraConfig, get_peft_model
from peft.helpers import find_kappa_target_modules

model = AutoModelForCausalLM.from_pretrained("mistralai/Mixtral-8x7B-Instruct-v0.1")

targets = find_kappa_target_modules(model, top_p=0.2)
config = LoraConfig(
    target_modules=targets["target_modules"],
    target_parameters=targets["target_parameters"] if stable_modules_dic["target_parameters"] else None,
    r=64,
    lora_alpha=32,
    task_type="CAUSAL_LM",
)
peft_model = get_peft_model(model, config)

Lihat contoh lengkap di sini.

Menargetkan nn.Parameter secara langsung

Secara umum, Anda sebaiknya menggunakan target_modules untuk menargetkan modul (misalnya nn.Linear). Namun, dalam beberapa situasi, hal ini tidak memungkinkan. Misalnya, pada banyak lapisan mixture of expert (MoE) di HF Transformers, nn.Parameter digunakan alih-alih nn.Linear. PEFT biasanya menimpa metode forward untuk LoRA, tetapi untuk nn.Parameter, tidak ada metode tersebut. Oleh karena itu, untuk menerapkan LoRA pada parameter tersebut, parameter itu perlu ditargetkan dengan target_parameters. Sebagai contoh, untuk Llama4, Anda dapat meneruskan: target_parameters=['feed_forward.experts.gate_up_proj', 'feed_forward.experts.down_proj].

Perlu diperhatikan bahwa saat menargetkan parameter ahli, PEFT dapat menambah overhead waktu eksekusi yang signifikan. Alasannya adalah PEFT selalu mematerialisasi kontribusi LoRA untuk setiap ahli meskipun hanya sejumlah kecil ahli yang diperlukan. Selama pelatihan, hal ini kurang relevan karena, sepanjang sekuens, biasanya sebagian besar ahli diaktifkan setidaknya sekali. Namun, selama inferensi, biasanya cache KV digunakan sehingga kita hanya perlu menghitung token terakhir, yang berarti hanya sejumlah kecil ahli yang diaktifkan. Oleh karena itu, penggunaan LoRA pada lapisan MoE dapat menyebabkan perlambatan yang signifikan pada waktu inferensi. Rekomendasinya adalah menggabungkan bobot (model.merge_adapter() atau model = model.merge_and_unload()). Hal ini menghilangkan overhead PEFT.

Investigasi yang lebih rinci mengenai masalah ini dapat ditemukan pada pull request tentang optimasi MoE ini.

Catatan

• Saat ini, argumen ini memungkinkan penargetan nn.Parameter 2-dimensi atau 3-dimensi. Diasumsikan bahwa untuk parameter 3-dimensi, dimensi ke-0 adalah dimensi ahli (expert).
• Beberapa adapter LoRA (ditambahkan melalui model.add_adapter atau model.load_adapter) yang menggunakan target_parameters didukung, tetapi semuanya harus menargetkan set parameter yang sama.

Parameter pakar MoE dan vLLM

Beberapa model MoE di Transformers menyimpan bobot pakar sebagai tensor nn.Parameter (sering kali 3D), bukan modul nn.Linear. Untuk menerapkan LoRA ke pakar-pakar tersebut, gunakan target_parameters dan atur rank per lapisan dengan rank_pattern:

num_experts = getattr(model.config, "num_local_experts", None) or model.config.num_experts
effective_r = max(1, r // num_experts)
config = LoraConfig(
    r=r,
    lora_alpha=32,
    target_modules=["q_proj", "v_proj"],
    target_parameters=[
        # Mixtral / Qwen3-MoE / GPT-OSS
        "mlp.experts.gate_up_proj",
        "mlp.experts.down_proj",
        # Llama4
        # "feed_forward.experts.gate_up_proj",
        # "feed_forward.experts.down_proj",
    ],
    rank_pattern={
        "experts.gate_up_proj": effective_r,
        "experts.down_proj": effective_r,
    },
)

Hal ini menjaga total anggaran parameter LoRA tetap serupa dengan lapisan padat (lihat LoRA Without Regret oleh Schulman dkk.). Modul non-ahli menggunakan rank default r.

Inferensi yang dipercepat dengan model yang telah dihaluskan dimungkinkan, misalnya, dengan vLLM yang mendukung lapisan ahli MoE yang digabungkan sejak v0.11.2.

Latih token secara efisien bersama LoRA

Adaptor PEFT LoRA mendukung penambahan token baru dengan parameter trainable_token_indices. Hal ini memungkinkan penyesuaian token lain bersamaan dengan fine-tuning lapisan tertentu. Hanya token yang ditentukan yang dilatih, sementara semua token lainnya tidak diubah. Metode ini menghemat memori dan tidak membuang konteks yang telah dipelajari dari embedding token yang ada, berbeda dengan melatih seluruh matriks embedding. Di balik layar, metode ini menggunakan lapisan dari TrainableTokensModel.

# for layer 'embed_tokens'
config = LoraConfig(trainable_token_indices=[idx_1, idx_2, ...], ...)

# specific embedding layer
config = LoraConfig(trainable_token_indices={'emb_tokens': [idx_1, idx_2, ...]}, ...)

Pada potongan kode di bawah ini, kami menunjukkan cara menambahkan token baru ke model dan cara melatihnya bersama lapisan lain dalam model.

from transformers import AutoTokenizer, AutoModelForCausalLM
from peft import get_peft_model, LoraConfig

base_model = AutoModelForCausalLM.from_pretrained("mistralai/Mistral-7B-v0.1")
tokenizer = AutoTokenizer.from_pretrained("mistralai/Mistral-7B-v0.1")

# we define our new tokens and add them to the tokenizer as special tokens
special_tokens = ['<|start_think|>', '<|stop_think|>']
tokenizer.add_special_tokens({'additional_special_tokens': special_tokens})

# make room for new tokens in the embedding matrix if it isn't big enough already
base_model.resize_token_embeddings(max(len(tokenizer), base_model.model.embed_tokens.num_embeddings))

# typical LoRA config with `trainable_token_indices` targeting embedding layer `embed_tokens`
# and specifically our new tokens we just added
lora_config = LoraConfig(
    target_modules='all-linear',
    trainable_token_indices={'embed_tokens': tokenizer.convert_tokens_to_ids(special_tokens)},
)
peft_model = get_peft_model(base_model, lora_config)

# proceed to train the model like normal
[...]

Bobot token disimpan sebagai bagian dari state dict adapter bersama dengan bobot LoRA. Fine-tuning penuh dan penyimpanan matriks embedding akan menyimpan file yang jauh lebih besar.

Untuk memberikan gambaran seberapa banyak VRAM yang dapat dihemat, perbandingan sederhana dari contoh di atas dilakukan antara melatih matriks embedding secara penuh (modules_to_save=["embed_tokens"]), menggunakan LoRA untuk matriks embedding (target_modules=[..., "embed_tokens"], rank 32) dan token yang dapat dilatih (trainable_token_indices=[...], 6 token):

Pengikatan bobot

Banyak LM kausal menggunakan weight tying, di mana dua atau lebih bobot berbagi parameter dasar yang sama. Dalam kasus yang paling umum, bobot embedding input (embed_tokens) dan bobot proyeksi output (lm_head) berbagi tensor yang sama. Hal ini karena mengurangi jumlah parameter dan biasanya mempertahankan kualitas model.

Tidak selalu jelas bagaimana PEFT menangani bobot terikat ini ketika ditargetkan untuk fine-tuning. Untuk LoRA, ensure_weight_tying pada LoraConfig mengontrol apakah PEFT harus secara eksplisit menjaga pembaruan sisi adapter tetap terikat untuk lapisan-lapisan tersebut. Dalam praktiknya, hal ini dapat memengaruhi modules_to_save, target_modules, dan trainable_token_indices. Perhatikan bahwa logika ini sebagian bergantung pada konvensi dalam penamaan lapisan ("embed_tokens", "lm_head") dan kerja yang tepat tidak dapat dijamin jika konvensi tersebut tidak digunakan.

Tabel di bawah ini merangkum perilaku yang diharapkan.

modules_to_save

target_modules

trainable_token_indices

Untuk token yang dapat dilatih, terdapat komplikasi tambahan bahwa meskipun LM head dan embeddings diikat, sebagai pengguna saya mungkin ingin melakukan fine-tuning pada token yang berbeda di atasnya. Oleh karena itu, pada tabel contoh di bawah, kami membedakan antara fine-tuning token yang sama dan fine-tuning token yang berbeda.

Bagi pengguna, ini berarti:

• Secara umum, jika Anda ingin melakukan fine-tuning pada bobot yang terikat dan ingin tetap mengikatnya, berikan ensure_weight_tying=True.
• Jika bobot model dasar Anda tidak terikat, ensure_weight_tying=True tidak dapat memaksa pengikatan dan hanya memberikan peringatan.
• Untuk trainable_token_indices, lapisan yang terikat harus menggunakan indeks token yang sama ketika ensure_weight_tying=True.

Optimizer

Pelatihan LoRA dapat secara opsional mencakup optimizer khusus. Saat ini, PEFT mendukung LoRA-FA, LoRA+, dan Riemannian-preconditioned LoRA.

Optimizer LoRA-FA

Pelatihan LoRA dapat menjadi lebih efektif dan efisien dengan menggunakan LoRA-FA, seperti yang dijelaskan dalam LoRA-FA. LoRA-FA mengurangi konsumsi memori aktivasi dengan mengunci matriks A dan hanya menyetel matriks B. Selama pelatihan, gradien dari B dioptimalkan untuk mengaproksimasi gradien penyetelan parameter penuh. Selain itu, konsumsi memori LoRA-FA tidak sensitif terhadap rank (karena menghapus aktivasi dari $A$), sehingga dapat meningkatkan kinerja dengan memperbesar lora rank tanpa meningkatkan konsumsi memori.

from peft import LoraConfig, get_peft_model
from peft.optimizers import create_lorafa_optimizer
from transformers import Trainer, get_cosine_schedule_with_warmup

base_model = AutoModelForCausalLM.from_pretrained("meta-llama/Meta-Llama-3-8B-Instruct")

config = LoraConfig(...)
model = get_peft_model(base_model, config)

optimizer = create_lorafa_optimizer(
    model=model,
    r=128,
    lora_alpha=32,
    lr=7e-5,
)

scheduler = get_cosine_schedule_with_warmup(
    optimizer,
    num_warmup_steps=100,
    num_training_steps=1000,
)

trainer = Trainer(
    ...,
    optimizers=(optimizer, scheduler),
)

LoRA+ mengoptimalkan LoRA

Pelatihan LoRA dapat dioptimalkan menggunakan LoRA+, yang menggunakan tingkat pembelajaran berbeda untuk matriks adapter A dan B, yang terbukti meningkatkan kecepatan finetuning hingga 2x dan performa sebesar 1-2%.

from peft import LoraConfig, get_peft_model
from peft.optimizers import create_loraplus_optimizer
from transformers import Trainer
import bitsandbytes as bnb

base_model = ...
config = LoraConfig(...)
model = get_peft_model(base_model, config)

optimizer = create_loraplus_optimizer(
    model=model,
    optimizer_cls=bnb.optim.Adam8bit,
    lr=5e-5,
    loraplus_lr_ratio=16,
)
scheduler = None

...
trainer = Trainer(
    ...,
    optimizers=(optimizer, scheduler),
)

LoRA dengan preconditioning Riemannian

Pelatihan LoRA dapat ditingkatkan dengan preconditioner Riemannian, seperti yang dijelaskan dalam Riemannian Preconditioned LoRA. Pada setiap langkah optimizer, gradien dari matriks LoRA $A$ dan $B$ dikalikan dengan $r \times r$ preconditioner yang menskalakan ulang gradien Euclidean menuju arah Riemannian (scaled-gradient) pada manifold matriks low-rank, yang memberikan kondisi yang lebih baik untuk pembaruan dan dapat meningkatkan konvergensi. Karena preconditioner berukuran $r \times r$, overhead memori dan waktu eksekusinya kecil relatif terhadap rank LoRA. create_riemannian_optimizer membungkus kelas optimizer dasar mana pun (misalnya torch.optim.AdamW atau torch.optim.SGD): parameter non-LoRA diperbarui oleh optimizer dasar tanpa perubahan, dan hanya nn.Linear-lapisan LoRA berbentuklora_A / lora_B) dipreconditioner.

from peft import LoraConfig, get_peft_model
from peft.optimizers import create_riemannian_optimizer
from transformers import Trainer, get_cosine_schedule_with_warmup
import torch

base_model = AutoModelForCausalLM.from_pretrained("meta-llama/Meta-Llama-3-8B-Instruct")

config = LoraConfig(...)
model = get_peft_model(base_model, config)

optimizer = create_riemannian_optimizer(
    model=model,
    optimizer_cls=torch.optim.AdamW,
    lr=5e-5,
    reg=1e-2,
)

scheduler = get_cosine_schedule_with_warmup(
    optimizer,
    num_warmup_steps=100,
    num_training_steps=1000,
)

trainer = Trainer(
    ...,
    optimizers=(optimizer, scheduler),
)

reg adalah suku redaman yang ditambahkan ke $r \times r$ diagonal matriks sebelum inversi; ia menstabilkan preconditioner ketika faktor LoRA (hampir) rank-deficient.

Pelatihan Pasca

Bagian ini menunjukkan metode pasca-pemrosesan potensial untuk adapter yang telah dilatih.

Menggabungkan bobot LoRA ke dalam model dasar

Meskipun LoRA jauh lebih kecil dan lebih cepat untuk dilatih, Anda mungkin mengalami masalah latensi selama inferensi karena model dasar dan adapter LoRA dimuat secara terpisah. Untuk menghilangkan latensi, gunakan fungsi merge_and_unload() untuk menggabungkan bobot adapter dengan model dasar. Hal ini memungkinkan Anda menggunakan model gabungan baru tersebut sebagai model mandiri. Fungsi merge_and_unload() tidak menyimpan bobot adapter di memori.

Berikut adalah diagram yang menjelaskan intuisi penggabungan adapter LoRA:

Kami menunjukkan di cuplikan di bawah cara menjalankannya menggunakan PEFT.

from transformers import AutoModelForCausalLM
from peft import PeftModel

base_model = AutoModelForCausalLM.from_pretrained("mistralai/Mistral-7B-v0.1")
peft_model_id = "alignment-handbook/zephyr-7b-sft-lora"
model = PeftModel.from_pretrained(base_model, peft_model_id)
model = model.merge_and_unload()

Penting untuk menugaskan model yang dikembalikan ke sebuah variabel dan menggunakannya, karena merge_and_unload() bukan operasi in-place. Jika Anda perlu menyimpan salinan bobot agar dapat membatalkan penggabungan adapter nanti atau menghapus dan memuat yang berbeda, Anda sebaiknya menggunakan fungsi merge_adapter() sebagai gantinya. Sekarang Anda memiliki opsi untuk menggunakan unmerge_adapter() untuk mengembalikan model dasar.

from transformers import AutoModelForCausalLM
from peft import PeftModel

base_model = AutoModelForCausalLM.from_pretrained("mistralai/Mistral-7B-v0.1")
peft_model_id = "alignment-handbook/zephyr-7b-sft-lora"
model = PeftModel.from_pretrained(base_model, peft_model_id)
model.merge_adapter()

# unmerge the LoRA layers from the base model
model.unmerge_adapter()

Pada model terkuantisasi, proses unmerging tidak bersifat eksak: merging akan mengkuantisasi ulang bobot dasar, dan siklus merge dan unmerge yang berulang dapat mengakumulasi error pembulatan. Lihat Merging adapters into quantized weights.

Jika beberapa adapter aktif dan hanya sebagian yang digabungkan, adapter yang tidak digabungkan akan secara diam-diam tidak diterapkan. Perilaku ini akan berubah di PEFT v1.0. Lihat Menggabungkan hanya sebagian dari adapter yang aktif.

Fungsi add_weighted_adapter() berguna untuk menggabungkan beberapa LoRA menjadi adapter baru berdasarkan skema pembobotan yang diberikan pengguna pada parameter weights. Di bawah ini adalah contoh end-to-end.

Pertama, muat model dasar:

from transformers import AutoModelForCausalLM
from peft import PeftModel
import torch

base_model = AutoModelForCausalLM.from_pretrained(
    "mistralai/Mistral-7B-v0.1", dtype=torch.float16, device_map="auto"
)

Lalu kami memuat adapter pertama:

peft_model_id = "alignment-handbook/zephyr-7b-sft-lora"
model = PeftModel.from_pretrained(base_model, peft_model_id, adapter_name="sft")

Lalu muat adapter yang berbeda dan gabungkan dengan yang pertama:

weighted_adapter_name = "sft-dpo"
model.load_adapter("alignment-handbook/zephyr-7b-dpo-lora", adapter_name="dpo")
model.add_weighted_adapter(
    adapters=["sft", "dpo"],
    weights=[0.7, 0.3],
    adapter_name=weighted_adapter_name,
    combination_type="linear"
)
model.set_adapter(weighted_adapter_name)

Terdapat beberapa metode yang didukung untuk combination_type. Lihat dokumentasi untuk detail lebih lanjut. Perhatikan bahwa “svd” sebagai combination_type tidak didukung saat menggunakan torch.float16 atau torch.bfloat16 sebagai tipe data.

Sekarang, lakukan inferensi:

device = torch.accelerator.current_accelerator().type if hasattr(torch, "accelerator") else "cuda"

tokenizer = AutoTokenizer.from_pretrained("mistralai/Mistral-7B-v0.1")

prompt = "Hey, are you conscious? Can you talk to me?"
inputs = tokenizer(prompt, return_tensors="pt")
inputs = {k: v.to(device) for k, v in inputs.items()}

with torch.no_grad():
    generate_ids = model.generate(**inputs, max_length=30)
outputs = tokenizer.batch_decode(generate_ids, skip_special_tokens=True, clean_up_tokenization_spaces=False)[0]
print(outputs)

Memulihkan kinerja model dasar melalui reduksi dimensi intruder

Paper LoRA vs Full Fine-tuning: An Illusion of Equivalence berargumen bahwa pelatihan LoRA memperkenalkan dimensi tambahan ke dalam bobot yang sangat sedikit kesamaannya dengan bobot yang sudah dipelajari dan menyebabkan lupa terhadap informasi yang sudah dipelajari. PEFT menerapkan mitigasi yang disarankan di peft.tuners.lora.intruders.reduce_intruder_dimension().

Mekanisme mitigasi ini akan mengambil model PEFT dengan LoRA yang dimuat dan membuat adapter baru yang dimodifikasi, yang dimuat berdampingan dengan adapter yang sudah ada dan kini menjadi adapter aktif.

Contoh penggunaan:

from peft.tuners.lora.intruders import reduce_intruder_dimension

peft_model = AutoPeftModelForCausalLM.from_pretrained('hubnemo/llama-3.2b-metamathqa-lora64')

reduce_intruder_dimension(
    peft_model,
    mitigation_lambda=0.75,
)

peft_model.generate(...)

Ada beberapa hiperparameter yang dapat digunakan untuk menyetel efektivitas mitigasi, namun, seperti yang ditunjukkan pada Gambar 8 dari makalah tersebut, akan selalu ada trade-off antara akurasi tugas yang dipelajari oleh adapter dan hilangnya pengetahuan model dasar. Mitigasi akan menghapus informasi dari adapter untuk mengurangi dampak terhadap hilangnya pengetahuan sebelumnya, tetapi ini juga berarti bahwa beberapa informasi tentang tugas yang dipelajari oleh adapter juga hilang.

Meskipun nilai default diatur untuk memberikan keseimbangan yang baik antara kedua faktor tersebut, tidak dijamin bahwa nilai default tersebut akan berlaku untuk adapter, model, dan data Anda. Oleh karena itu, disarankan untuk menyiapkan benchmark guna mengukur efeknya.

Muat adapter

Adapters dapat dimuat ke model pretrained dengan load_adapter(), yang berguna untuk mencoba berbagai adapter yang bobotnya tidak digabungkan. Atur bobot adapter yang aktif dengan fungsi set_adapter().

from transformers import AutoModelForCausalLM
from peft import PeftModel

base_model = AutoModelForCausalLM.from_pretrained("mistralai/Mistral-7B-v0.1")
peft_model_id = "alignment-handbook/zephyr-7b-sft-lora"
model = PeftModel.from_pretrained(base_model, peft_model_id)

# load different adapter
model.load_adapter("alignment-handbook/zephyr-7b-dpo-lora", adapter_name="dpo")

# set adapter as active
model.set_adapter("dpo")

Untuk mengembalikan model dasar, Anda dapat menggunakan unload() untuk memuat ulang semua modul LoRA atau delete_adapter() untuk menghapus adapter sepenuhnya. unload() bukan operasi in-place, ingatlah untuk menugaskan model yang dikembalikan ke variabel dan menggunakannya.

# unload adapter
model = model.unload()

# delete adapter
model.delete_adapter("dpo")

Paralelisme Tensor

LoRA mendukung Tensor Parallelism (TP) yang disediakan oleh Transformers. Ketika model dasar dimuat dengan tp_plan, PEFT secara otomatis mendeteksi konfigurasi TP dari setiap modul target dan menambahkan hook yang sesuai ke bobot adapter LoRA agar mereka berpartisipasi dengan benar dalam komputasi tensor-parallel.

Dukungan Tensor Parallelism untuk LoRA memerlukan transformers >= 5.4.0. API Tensor Parallelism berbasis DTensor memerlukan peft >= 0.21.1 dan transformers >= 5.17.0.

Penggunaannya identik dengan alur kerja LoRA standar — cukup muat model dasar dengan tp_plan sebelum membungkusnya dengan PEFT:

from transformers import AutoModelForCausalLM
from peft import get_peft_model, LoraConfig

model = AutoModelForCausalLM.from_pretrained("meta-llama/Llama-3.1-8B", tp_plan="auto")
lora_config = LoraConfig(r=16, target_modules=["q_proj", "v_proj"])
model = get_peft_model(model, lora_config)

Menyimpan dan memuat bekerja seperti biasa melalui save_pretrained / from_pretrained. PEFT mengumpulkan bobot adapter yang terpecah kembali menjadi tensor penuh sebelum menyimpan, sehingga checkpoint bersifat portabel dan independen dari jumlah perangkat yang digunakan selama pelatihan.

Jika Anda menerapkan tensor parallelism tanpa rencana TP, misalnya dengan parallelize_module dari PyTorch, PEFT akan menentukan ukuran bobot LoRA dari nn.Linear yang di-shard sesuai dengan shard lokalnya jika device mesh bobot tersebut memiliki dimensi bernama "tp", dan sesuai dengan bentuk layer penuh jika tidak (seperti pada FSDP2). PEFT tidak menambahkan hook TP ke bobot LoRA ini atau mengumpulkannya saat menyimpan. Jika dimensi mesh TP Anda memiliki nama yang berbeda, tambahkan sebelum membuat model PEFT:

from peft.utils.integrations import TpMeshDimRegistry

TpMeshDimRegistry.register("tp_dim")

Inferensi

Bagian ini menampilkan apa yang dapat Anda lakukan saat inferensi dengan LoRA, seperti memisahkan adapter.

LoRA yang Diaktifkan (aLoRA)

Activated LoRA (aLoRA) adalah arsitektur low rank adapter untuk LM kausal yang menggunakan ulang KV cache dari model dasar yang ada untuk inferensi yang lebih efisien. Pendekatan ini paling cocok untuk pipeline inferensi yang mengandalkan model dasar untuk sebagian besar tugas/generasi, tetapi menggunakan adapter aLoRA untuk melakukan tugas khusus dalam rantai tersebut. Misalnya, memeriksa atau mengoreksi output yang dihasilkan oleh model dasar. Dalam pengaturan ini, waktu inferensi dapat dipercepat hingga satu orde magnitudo atau lebih. Untuk informasi lebih lanjut tentang aLoRA dan banyak contoh kasus penggunaan, lihat paper aLoRA.

Teknik ini memindai kemunculan terakhir dari urutan pemanggilan (alora_invocation_tokens) pada setiap input (ini bisa sesingkat 1 token). Bobot adapter diaktifkan pada token yang dimulai dari awal urutan pemanggilan. Input apa pun setelah urutan pemanggilan juga diadaptasi, dan semua token yang dihasilkan akan menggunakan bobot yang telah diadaptasi. Bobot pada token sebelumnya dibiarkan tidak diadaptasi, sehingga cache untuk token-token tersebut dapat dipertukarkan dengan cache model dasar karena adanya causal attention mask pada LM kausal. Pemakaiannya sangat mirip dengan LoRA standar. Perbedaan utamanya adalah bahwa urutan pemanggilan harus ditentukan saat adapter dibuat:

from peft import LoraConfig

config = LoraConfig(alora_invocation_tokens=alora_invocation_tokens, task_type="CAUSAL_LM", ...)

`alora_invocation_tokens` adalah daftar id token integer. Diberikan string invocation yang diinginkan, ini dapat diperoleh sebagai:

invocation_string = "placeholder"
alora_invocation_tokens = tokenizer.encode(invocation_string, add_special_tokens=False).

Tokenizer adalah tokenizer dari model dasar. Gunakan add_special_tokens=False untuk menghindari penambahan token SOS/EOS dalam string pencarian kita (yang kemungkinan besar akan menyebabkan pencarian gagal).

Catatan

• aLoRA hanya didukung untuk tugas task_type=CAUSAL_LM karena fokusnya pada penggunaan ulang cache.
• Karena bobot disesuaikan pada lebih sedikit token, aLoRA sering kali (tidak selalu) membutuhkan rank (r) yang lebih tinggi daripada LoRA. r=32 bisa menjadi titik awal yang baik.
• Bobot aLoRA tidak dapat digabungkan ke dalam model dasar berdasarkan definisinya, karena bobot adapter diterapkan secara selektif ke subset token. Upaya untuk menggabungkannya akan menghasilkan error.
• Beam search belum didukung.
• Secara umum, tidak disarankan untuk menambahkan token baru ke tokenizer yang tidak ada di model dasar. Hal ini dapat mempersulit kasus penggunaan di mana model dasar dan model adapter beroperasi pada konteks yang tumpang tindih. Anda dapat menghindari masalah ini dengan menambahkan token yang dapat dilatih ke model dasar sebelum melatih adapter.

Pilihan urutan pemanggilan dan desain SFT

Anda harus menambahkan sekuens alora_invocation_tokens karena tidak ditambahkan secara otomatis. Kami merekomendasikan untuk mengaktifkan bobot adapter lebih awal (di awal prompting yang spesifik untuk adapter), tetapi setelah input panjang apa pun, untuk memaksimalkan kinerja model tanpa mengorbankan penggunaan ulang cache. Seperti pada model apa pun, format harus konsisten antara pelatihan dan pengujian.

Pertimbangkan contoh berikut, di mana model dasar memiliki template chat, dan tujuannya adalah melatih adapter untuk menghasilkan output yang diinginkan.

• Opsi 1: Jika tidak ada prompt khusus tugas, yaitu inputnya adalah riwayat chat dengan prompt assistant, maka prompt assistant dari template chat (misalnya <|start_of_role|>assistant<|end_of_role|>) adalah pilihan yang alami untuk string pemanggilan. Lihat template chat model untuk menemukan prompt untuk model tersebut.
• Opsi 2: Jika ada prompt khusus tugas untuk adapter yang menjelaskan tugas yang dipelajari adapter, dan prompt tersebut ditempatkan sebagai giliran user tepat sebelum generasi, maka prompt user dari template chat (misalnya <|start_of_role|>user<|end_of_role|>) adalah pilihan yang alami untuk string pemanggilan.

Setelah menentukan string pemanggilan, dapatkan tokenizer model dan peroleh alora_invocation_tokens sebagai

alora_invocation_tokens = tokenizer.encode(invocation_string, add_special_tokens=False).

Contoh setup inferensi ada di alora finetuning.

Jika menggunakan string kustom untuk string pemanggilan, pastikan bahwa awal dan akhir string adalah token khusus untuk menghindari masalah dengan tokenisasi di batas-batasnya.

Untuk memahami alasannya, bayangkan ‘a’, ‘b’, ‘c’, dan ‘ab’ adalah token dalam tokenizer Anda (nomor 1, 2, 3, 4 masing-masing). Misalkan alora_invocation_tokens = [2, 3]. Sekarang bayangkan string input Anda adalah “abc”. Karena “ab” adalah sebuah token, string ini akan ditokenisasi menjadi [4,3]. Akibatnya, alora_invocation_tokens akan gagal ditemukan, meskipun string “bc” ada di dalamnya. Namun, jika awal dan akhir string invokasi adalah token khusus, kasus kegagalan ini tidak akan pernah terjadi karena token khusus tidak pernah ditokenisasi menjadi token yang sama dengan karakter lain.

Menggunakan (dan menggunakan ulang) cache untuk generasi

Tujuan utama aLoRA adalah membuat KV cache dapat dipertukarkan antara model dasar dan model adapter aLoRA sebelum urutan pemanggilan karena nilai KV dasar dan yang diadaptasi tidak kompatibel. Secara spesifik, kunci dan nilai yang disimpan selama satu generasi model dapat digunakan dalam generasi berikutnya untuk menghindari operasi prefill yang mahal untuk token konteks. Saat berbagi cache antara model dasar dan adapter aLoRA, terdapat 2 pola utama:

1. Model dasar telah menghasilkan sesuatu, dan kemudian adapter aLoRA dipanggil untuk melakukan generasi lanjutan. Misalnya, model dasar menjawab sebuah pertanyaan, dan aLoRA yang dilatih untuk mendeteksi halusinasi memeriksa respons dari model dasar.
2. Sebuah adapter aLoRA telah menghasilkan sesuatu, dan model dasar atau adapter aLoRA lain dipanggil untuk melakukan generasi lanjutan yang memiliki tumpang tindih konteks parsial dengan aLoRA asli. Misalnya, pengguna memberikan kueri, dan aLoRA menulis ulang kueri tersebut agar lebih mandiri dan meningkatkan pengambilan dalam sistem RAG. Kemudian, dokumen diambil dan dimuat ke dalam konteks, aLoRA memeriksa apakah dokumen-dokumen ini relevan dengan pertanyaan, dan kemudian model dasar menghasilkan jawaban.

Untuk mendemonstrasikan perilaku di atas saat menggunakan caching, kami menggunakan DynamicCache dari transformers. Pastikan nilai cache yang diadaptasi tidak dicampur dengan nilai cache dasar. Secara khusus, diperlukan langkah tambahan untuk berbagi cache ketika ada tumpang tindih konteks parsial (pola 2).

Polakan 1: Model dasar diikuti oleh aLoRA Di sini, seluruh input dan hasil generasi dari model dasar dimasukkan ke dalam adapter aLoRA, bersama dengan urutan pemanggilan:

from transformers import DynamicCache
...
cache = DynamicCache()
inputs_base = tokenizer(prompt_base, return_tensors="pt")
# Generate from base model and save cache
with model_alora.disable_adapter():
    output = model_alora.generate(inputs_base["input_ids"].to(device),attention_mask=inputs_base["attention_mask"].to(device),past_key_values = cache,return_dict_in_generate=True)
output_text_base = tokenizer.decode(output.sequences[0])
cache = output.past_key_values

# Generate with aLoRA adapter from cache
prompt_alora = output_text + INVOCATION_STRING
inputs_alora = tokenizer(prompt_alora, return_tensors="pt").to(device)
output = model_alora.generate(**inputs_alora, past_key_values=cache)
output_text_alora = tokenizer.decode(output[0])

# Note: cache is now tainted with adapter values and cannot be used in base model from here on!

Polakan 2: generasi aLoRA diikuti oleh model dasar (atau aLoRA lain) dengan tumpang tindih konteks parsial Di sini, kami melakukan prefill konteks bersama menggunakan model dasar, lalu melakukan generasi.

from transformers import DynamicCache
import copy
...
cache = DynamicCache()
inputs_shared = tokenizer(prompt_shared, return_tensors="pt").to(device)

# Prefill from base model and save cache
with model_alora.disable_adapter():
    with torch.no_grad():
        model_alora(**inputs_shared, past_key_values=cache)
cache_copy = copy.deepcopy(cache)

# Generate from aLoRA using prefilled cache
prompt_alora = prompt_shared + INVOCATION_STRING
inputs_alora = tokenizer(prompt_alora, return_tensors="pt").to(device)
output = model_alora.generate(**inputs_alora, past_key_values=cache)
output_text_alora = tokenizer.decode(output[0])

# Generate from base model using saved cache not tainted by aLoRA KV values
prompt_base = prompt_shared
inputs_base = tokenizer(prompt_base, return_tensors="pt").to(device)
with model_alora.disable_adapter():
    output = model_alora.generate(**inputs_base, past_key_values=cache_copy)
output_text_base = tokenizer.decode(output[0])

Inferensi dengan adapter LoRA yang berbeda dalam batch yang sama

Biasanya, setiap batch inferensi harus menggunakan adapter yang sama dalam PEFT. Hal ini terkadang merepotkan, karena kita mungkin memiliki batch yang berisi sampel yang ditujukan untuk digunakan dengan adapter LoRA yang berbeda. Misalnya, kita bisa memiliki model dasar yang bekerja dengan baik dalam bahasa Inggris dan dua adapter LoRA lainnya, satu untuk bahasa Prancis dan satu untuk bahasa Jerman. Biasanya, kita harus memecah batch kita sehingga setiap batch hanya berisi sampel dari salah satu bahasa; kita tidak dapat menggabungkan bahasa yang berbeda dalam batch yang sama.

Untungnya, Anda dapat mencampur berbagai adapter LoRA dalam batch yang sama menggunakan argumen adapter_name. Di bawah ini, kami menunjukkan contoh bagaimana hal ini bekerja dalam praktiknya. Pertama, mari muat model dasar, English, dan dua adapter, French dan German, seperti ini:

from transformers import AutoTokenizer, AutoModelForCausalLM
from peft import PeftModel

model_id = ...
tokenizer = AutoTokenizer.from_pretrained(model_id)

model = AutoModelForCausalLM.from_pretrained(model_id)
# load the LoRA adapter for French
peft_model = PeftModel.from_pretrained(model, <path>, adapter_name="adapter_fr")
# next, load the LoRA adapter for German
peft_model.load_adapter(<path>, adapter_name="adapter_de")

Sekarang, kita ingin menghasilkan teks pada sampel yang berisi ketiga bahasa: tiga sampel pertama dalam bahasa Inggris, tiga sampel berikutnya dalam bahasa Prancis, dan tiga sampel terakhir dalam bahasa Jerman. Kita dapat menggunakan argumen adapter_names untuk menentukan adapter mana yang akan digunakan untuk setiap sampel. Karena model dasar kita digunakan untuk bahasa Inggris, kita menggunakan string khusus "__base__" untuk sampel-sampel ini. Untuk tiga sampel berikutnya, kita menunjukkan nama adapter dari fine-tune LoRA Prancis, dalam hal ini "adapter_fr". Untuk tiga sampel terakhir, kita menunjukkan nama adapter dari fine-tune LoRA Jerman, dalam hal ini "adapter_de". Dengan cara ini, kita dapat menggunakan model dasar dan dua adapter dalam satu batch.

inputs = tokenizer(
    [
        "Hello, my dog is cute",
        "Hello, my cat is awesome",
        "Hello, my fish is great",
        "Salut, mon chien est mignon",
        "Salut, mon chat est génial",
        "Salut, mon poisson est super",
        "Hallo, mein Hund ist süß",
        "Hallo, meine Katze ist toll",
        "Hallo, mein Fisch ist großartig",
    ],
    return_tensors="pt",
    padding=True,
)

adapter_names = [
    "__base__", "__base__", "__base__",
    "adapter_fr", "adapter_fr", "adapter_fr",
    "adapter_de", "adapter_de", "adapter_de",
]
output = peft_model.generate(**inputs, adapter_names=adapter_names, max_new_tokens=20)

Perhatikan bahwa urutan tidak menjadi masalah di sini, yaitu sampel dalam batch tidak perlu dikelompokkan berdasarkan adapter seperti pada contoh di atas. Kami hanya perlu memastikan bahwa argumen adapter_names selaras dengan sampel.

Selain itu, pendekatan yang sama juga berfungsi dengan fitur modules_to_save, yang memungkinkan penyimpanan dan penggunaan ulang lapisan jaringan saraf tertentu, seperti kepala kustom untuk tugas klasifikasi, di antara berbagai adapter LoRA.

Catatan

Menggunakan fitur ini memiliki beberapa kekurangan, yaitu:

• Itu hanya berfungsi untuk inferensi, bukan untuk pelatihan.
• Menonaktifkan adapter menggunakan konteks with model.disable_adapter() memiliki prioritas lebih tinggi daripada adapter_names.
• Anda tidak dapat meneruskan adapter_names ketika beberapa bobot adapter telah digabungkan dengan bobot dasar menggunakan metode merge_adapter. Silakan batalkan penggabungan semua adapter terlebih dahulu dengan memanggil model.unmerge_adapter(). Perhatikan bahwa penggabungan hanya sebagian dari adapter yang aktif memiliki catatan serupa di luar adapter_names.
• Karena alasan yang jelas, ini tidak dapat digunakan setelah memanggil merge_and_unload(), karena dalam kasus ini semua adapter LoRA akan digabungkan ke dalam bobot dasar.
• Fitur ini saat ini tidak berfungsi dengan DoRA, jadi atur use_dora=False di LoraConfig Anda jika Anda ingin menggunakannya.
• Fitur modules_to_save saat ini hanya didukung untuk lapisan bertipe Linear, Embedding, Conv2d, dan Conv1d.
• Terdapat overhead yang diharapkan untuk inferensi dengan adapter_names, terutama jika jumlah adapter yang berbeda dalam batch sangat tinggi. Hal ini terjadi karena ukuran batch secara efektif berkurang menjadi jumlah sampel per adapter. Jika kinerja runtime adalah prioritas utama Anda, coba lakukan hal berikut:
  • Tingkatkan ukuran batch.
  • Usahakan untuk menghindari adanya sejumlah besar adapter yang berbeda dalam batch yang sama, lebih baik gunakan batch yang homogen. Hal ini dapat dicapai dengan menampung sampel yang memiliki adapter yang sama dan hanya melakukan inferensi dengan sedikit adapter yang berbeda.
  • Lihatlah implementasi alternatif seperti LoRAX, punica, atau S-LoRA, yang dirancang khusus untuk bekerja dengan sejumlah besar adapter yang berbeda.

Menggabungkan dan Menggunakan Ulang Adapter LoRA

Arrow

Arrow adalah algoritma routing modular yang dirancang untuk menggabungkan beberapa adapter LoRA spesifik tugas yang telah dilatih sebelumnya guna menyelesaikan tugas tertentu, serupa dengan Polytropon tetapi tanpa memerlukan fine-tuning. Alih-alih menggabungkan semua adapter secara naif, Arrow memperkenalkan mekanisme routing mixture-of-experts (MoE) berbasis token yang bebas gradien. Pada saat inferensi, algoritma ini pertama-tama menghitung prototipe untuk setiap LoRA dengan mengekstrak vektor singular kanan teratas dari dekomposisi SVD-nya. Setiap representasi token kemudian dibandingkan dengan prototipe tersebut melalui kemiripan kosinus untuk memperoleh koefisien routing. Token dialokasikan ke k adapter LoRA yang paling relevan, dengan koefisiennya dinormalisasi melalui softmax, dan outputnya digabungkan secara linear. Hal ini memungkinkan pemanfaatan ulang modul LoRA yang ada untuk tugas baru dan menghasilkan generalisasi zero-shot yang lebih kuat.

Di PEFT, Arrow diaktifkan melalui [`ArrowConfig]andcreate_arrow_model. You can also configure parameters such astop_k(the number of LoRA adapters combined per token),router_temperature(the softmax temperature applied to the routing coefficients), andrng_seed` (for reproducibility).

from peft import create_arrow_model, ArrowConfig
from transformers import AutoModelForCausalLM

# Loading the model
base_model = AutoModelForCausalLM.from_pretrained("microsoft/Phi-3-mini-4k-instruct")

# Creating the Arrow config
arrow_config = ArrowConfig(
    top_k=3,
    router_temperature=1.0,
    rng_seed=42,
)

# The LoRA adapters below were trained on a clustered FLAN dataset.
# Task clustering was performed using the Model-Based Clustering (MBC) method,
# as described in the Arrow paper.
# While one could train a separate LoRA for each task and let Arrow route tokens among them,
# training LoRAs on clusters of tasks instead provides an indirect optimization for
# transfer across the multi-task dataset.
task_specific_adapter_paths = [
        f"TahaBa/phi3-mini-clustered-flan/ts_expert_{i}" for i in range(10)
    ]

# Creating the Arrow model
model = create_arrow_model(
        base_model=base_model,
        task_specific_adapter_paths=task_specific_adapter_paths,
        arrow_config=arrow_config,
    )

# Now the forward path could be called on this model, like a normal PeftModel.

Selain itu, Anda dapat menambahkan atau menghapus adapter setelah memanggil create_arrow_model—misalnya, untuk melakukan fine-tuning pada adapter baru atau membuang yang tidak diperlukan. Setelah adapter ditempatkan, Anda dapat mengaktifkan "arrow_router" untuk inferensi guna menggunakan Arrow. Perhatikan bahwa jika Anda menambahkan adapter LoRA baru setelah create_arrow_model dan ingin melakukan fine-tuning padanya, Anda harus secara eksplisit mengatur adapter baru tersebut sebagai aktif, karena "arrow_router" diaktifkan secara default di create_arrow_model.

from trl import SFTTrainer, SFTConfig

# Adding a new adapter and activating it
model.add_adapter(adapter_name='new_adapter')
model.set_adapter('new_adapter')

# Now the model could be trained along the `new_adapter`.
trainer = SFTTrainer(
        model=model,
        args=SFTConfig(...),
        ...
    )

# Once the training is done, you can activate `arrow_router` and use it in inference
model.set_adapter('arrow_router')    # Model is ready to be used at inference time now

GenKnowSub

GenKnowSub meningkatkan Arrow dengan memurnikan adapter LoRA yang spesifik tugas sebelum routing. Ide utamanya adalah mengurangi pengetahuan umum yang terenkodasi dalam ruang LoRA—berdasarkan prinsip pelupaan-via-negasi—sehingga adapter tugas menjadi lebih terisolasi dan berfokus pada sinyal yang relevan dengan tugas. Secara konkret, GenKnowSub memperkirakan subruang “umum” berdimensi rendah dari seperangkat adapter LoRA umum (bukan spesifik tugas) dan menghapus komponen ini dari pembaruan LoRA setiap adapter tugas sebelum routing per-token Arrow. Hal ini biasanya meningkatkan komposabilitas dan mengurangi interferensi saat menggabungkan banyak adapter tugas.

Di PEFT, aktifkan GenKnowSub dengan mengatur use_gks=True di ArrowConfig, dan menyediakan general_adapter_paths di create_arrow_model:

from peft import create_arrow_model, ArrowConfig
from transformers import AutoModelForCausalLM

# Loading the model
base_model = AutoModelForCausalLM.from_pretrained("microsoft/Phi-3-mini-4k-instruct")

# Creating the Arrow config
arrow_config = ArrowConfig(
    top_k=3,
    router_temperature=1.0,
    use_gks=True,
    rng_seed=42,
)

# Path to task-specific, trained on flan clustered dataset (as we explained before.)
task_specific_adapter_paths = [
        f"TahaBa/phi3-mini-clustered-flan/ts_expert_{i}" for i in range(10)
    ]
# These general adapters are trained on English, German, and French Wikipedia dataset,
# with causal language modelling objective, each pair like: (507 token tsentence, 5 token completion), and the loss computed on the completion
general_adapter_paths = [
        "TahaBa/phi3-mini-general-adapters/cluster0_batch16_prop1.0_langen/checkpoint-17",
        "TahaBa/phi3-mini-general-adapters/cluster0_batch16_prop1.0_langfr/checkpoint-35",
        "TahaBa/phi3-mini-general-adapters/cluster0_batch16_prop1.0_langger/checkpoint-17"
    ]

# Creating the Arrow model
model = create_arrow_model(
        base_model=base_model,
        task_specific_adapter_paths=task_specific_adapter_paths,
        general_adapter_paths=general_adapter_paths,
        arrow_config=arrow_config,
    )

# Now the forward path could be called on this model, like a normal PeftModel.

Untuk mengkodekan pengetahuan umum, GenKnowSub mengurangi rata-rata dari adapter umum yang diberikan dari setiap adapter khusus tugas sekali, sebelum routing dimulai. Selain itu, kemampuan untuk menambahkan atau menghapus adapter setelah memanggil create_arrow_model (seperti yang dijelaskan di bagian Arrow) masih didukung dalam kasus ini.

Hal-hal yang perlu diperhatikan saat menggunakan Arrow + GenKnowSub:

• Semua adapter LoRA (khusus tugas dan umum) harus berbagi rank dan target_modules yang sama.

• Setiap inkonsistensi dalam pengaturan ini akan memicu error di create_arrow_model.

• Mendukung faktor penskalaan (lora_alpha) yang berbeda di antara adapter tugas — Arrow menanganinya secara otomatis.

• Menggabungkan "arrow_router" tidak didukung, karena perilaku routing dinamisnya.

• Pada create_arrow_model, task adapter dimuat sebagai task_i dan general adapter sebagai gks_j (di mana i dan j adalah indeks). Fungsi ini memastikan konsistensi target_modules, rank, dan apakah adapter diterapkan pada lapisan Linear atau Linear4bit. Kemudian, modul "arrow_router" ditambahkan dan diaktifkan. Setiap kustomisasi proses ini memerlukan penggantian (override) pada create_arrow_model.

• Implementasi ini kompatibel dengan kuantisasi 4-bit (melalui bitsandbytes):

  Disalin

  from transformers import AutoModelForCausalLM, BitsAndBytesConfig
  import torch
  
  # Quantisation config
  bnb_config = BitsAndBytesConfig(
          load_in_4bit=True,
          bnb_4bit_quant_type="nf4",
          bnb_4bit_compute_dtype=torch.bfloat16,
          bnb_4bit_use_double_quant=False,
      )
  
  # Loading the model
  base_model = AutoModelForCausalLM.from_pretrained(
      "microsoft/Phi-3-mini-4k-instruct",
      dtype=torch.bfloat16,
      device_map="auto",
      quantization_config=bnb_config,
  )
  
  # Now call create_arrow_model() as we explained before.

API

LoraConfig

LoraModel

>>> from transformers import AutoModelForSeq2SeqLM
>>> from peft import LoraConfig, get_peft_model

>>> config = LoraConfig(
...     task_type="SEQ_2_SEQ_LM",
...     r=8,
...     lora_alpha=32,
...     target_modules=["q", "v"],
...     lora_dropout=0.01,
... )

>>> model = AutoModelForSeq2SeqLM.from_pretrained("t5-base")
>>> lora_model = get_peft_model(model, config)

>>> import torch
>>> import transformers
>>> from peft import LoraConfig, get_peft_model, prepare_model_for_kbit_training

>>> rank = ...
>>> target_modules = ["q_proj", "k_proj", "v_proj", "out_proj", "fc_in", "fc_out", "wte"]
>>> config = LoraConfig(
...     r=4, lora_alpha=16, target_modules=target_modules, lora_dropout=0.1, bias="none", task_type="CAUSAL_LM"
... )
>>> quantization_config = transformers.BitsAndBytesConfig(load_in_8bit=True)

>>> tokenizer = transformers.AutoTokenizer.from_pretrained(
...     "kakaobrain/kogpt",
...     revision="KoGPT6B-ryan1.5b-float16",  # or float32 version: revision=KoGPT6B-ryan1.5b
...     bos_token="[BOS]",
...     eos_token="[EOS]",
...     unk_token="[UNK]",
...     pad_token="[PAD]",
...     mask_token="[MASK]",
... )
>>> model = transformers.GPTJForCausalLM.from_pretrained(
...     "kakaobrain/kogpt",
...     revision="KoGPT6B-ryan1.5b-float16",  # or float32 version: revision=KoGPT6B-ryan1.5b
...     pad_token_id=tokenizer.eos_token_id,
...     use_cache=False,
...     device_map={"": rank},
...     torch_dtype=torch.float16,
...     quantization_config=quantization_config,
... )
>>> model = prepare_model_for_kbit_training(model)
>>> lora_model = get_peft_model(model, config)

Utilitas

ArrowConfig

LoftQ

replace_lora_weights_loftq

LoftQConfig

Eva

EvaConfig

initialize_lora_eva_weights

get_eva_state_dict

LoraGAConfig

Utilitas

Reduksi Dimensi Intruder