PEFT documentation
Tur Cepat
Tur Cepat
PEFT menawarkan metode yang efisien secara parameter untuk finetuning model pretrained berskala besar. Paradigma tradisional adalah dengan melakukan finetuning pada seluruh parameter model untuk setiap tugas downstream, namun hal ini menjadi sangat mahal dan tidak praktis karena jumlah parameter yang sangat besar pada model saat ini. Sebagai gantinya, lebih efisien untuk melatih sejumlah kecil parameter prompt atau menggunakan metode reparametrisasi seperti low-rank adaptation (LoRA) untuk mengurangi jumlah parameter yang dapat dilatih.

Quicktour ini akan menunjukkan fitur-fitur utama PEFT dan bagaimana Anda dapat melatih atau menjalankan inferensi pada model besar yang biasanya tidak dapat diakses pada perangkat konsumen.
Konfigurasi PEFT dan model
Untuk setiap metode PEFT, Anda perlu membuat konfigurasi yang berisi semua parameter yang menentukan bagaimana metode PEFT harus diterapkan, terutama lapisan mana dari model yang ada yang akan ditargetkan dengan parameter yang dapat dilatih. Setelah konfigurasi disetel, lewati ke fungsi get_peft_model() bersama dengan model dasar untuk membuat PeftModel yang dapat dilatih.
Mari kita gunakan LoRA sebagai contoh, tetapi hanya membahas parameter umum - Anda mungkin ingin menggunakan salah satu dari banyak metode PEFT lainnya. Konfigurasi biasanya melibatkan hal ini:
target_modules: modul mana dari model dasar yang akan diadaptasitask_type(default:None, lihatTaskTypeyang tersedia): sifat dari tugas yang dilatih; jika diberikan, dapat membantu menyimpan lapisan yang relevan secara otomatis bersama bobot adapter atau memberi peringatan tentang ketidakcocokaninference_mode(default:False): apakah Anda menggunakan model untuk inferensi atau tidak
Tergantung pada metode PEFT yang Anda pilih, Anda akan menambahkan parameter spesifik yang, misalnya, menentukan ukuran matriks pembaruan. Berikut adalah contoh konfigurasi yang mungkin Anda temui di dunia nyata:
from peft import LoraConfig, TaskType
peft_config = LoraConfig(target_modules=["q_proj"], task_type=TaskType.CAUSAL_LM, inference_mode=False, r=8, lora_alpha=32, lora_dropout=0.1)Lihat panduan konfigurasi untuk detail lebih lanjut tentang cara kerja konfigurasi PEFT di balik layar.
Setelah LoraConfig diatur, buat PeftModel dengan fungsi get_peft_model(). Fungsi ini menerima model dasar - yang dapat (namun tidak wajib) dimuat dari pustaka Transformers - dan LoraConfig yang berisi parameter untuk mengatur model agar dapat dilatih dengan LoRA.
Muat model dasar yang ingin Anda finetune.
from transformers import AutoModelForCausalLM
model = AutoModelForCausalLM.from_pretrained("meta-llama/Llama-3.2-1B")Sekarang bungkus model dasar dan peft_config dengan fungsi get_peft_model() untuk membuat PeftModel.
Wrapping berarti PEFT mengganti lapisan yang ditargetkan (di sini: semua lapisan q_proj) dengan lapisan spesifik adapter untuk tipe lapisan target. Karena kita berurusan dengan lapisan linear, dalam kasus ini akan menjadi lapisan lora.Linear. Perhatikan bahwa perubahan ini dilakukan secara in-place untuk menghemat memori, sehingga model dasar Anda sekarang telah dimodifikasi.
Perhatikan bahwa kami hanya menentukan q_proj, tetapi pada kenyataannya kami menargetkan semua lapisan model.layers[:].self_attn.q_proj. Hal ini karena PEFT secara default mencari sufiks yang cocok. Sertakan string dengan ekspresi reguler jika Anda ingin menargetkan pola lapisan yang lebih kompleks.


Lapisan dari model dasar akan dibungkus, dipertahankan, dan tidak dilatih, sementara bobot baru yang dapat dilatih ditambahkan dan digabungkan. Struktur bobot baru ini dan cara penggabungan mereka dengan bobot model dasar merupakan bagian besar yang membedakan berbagai metode PEFT.
Sebelum memulai pelatihan, jalankan healthcheck untuk mengonfirmasi status adapter dan memeriksa jumlah parameter yang dapat dilatih.
from peft import get_peft_model, LoraConfig
peft_config = LoraConfig() # or your other PEFT method of choice
peft_model = get_peft_model(model, peft_config)
peft_model.print_healthcheck()Healthcheck mencakup fraksi parameter yang dapat dilatih bersama dengan status adapter, konfigurasi model, dan lingkungan.
Jalankan pemeriksaan kesehatan
Gunakan print_healthcheck() untuk mengidentifikasi kondisi yang mencurigakan, seperti adapter yang digabungkan atau tidak konsisten, dan untuk membuat laporan ringkas untuk laporan bug.
peft_model.print_healthcheck()
Ini seharusnya menampilkan sesuatu seperti:
PEFT healthcheck
Model:
ID: meta-llama/Llama-3.2-1B, type: LlamaForCausalLM, adapters: default (LORA)
Environment:
peft: 0.21.0, transformers: 5.18.0.dev0, torch: 2.14.0+cu130, Python: 3.13.9
Runtime:
training: True, devices: cpu, dtypes: bfloat16=1,235,814,400, float32=851,968, activation checkpointing: False
Parameters:
trainable: 851,968, total: 1,236,666,368, percent trainable: 0.0689%, adapter layers: 32
State:
adapter is enabled: True, active: default, merged: none
Layer types:
default:
lora.Linear=32Output cetak dapat berubah, jangan mencoba memarsinya. Untuk penggunaan programatik, panggil healthcheck() sebagai gantinya, yang mengembalikan informasi yang sama sebagai kamus yang dapat diserialisasi JSON.
Itu saja 🎉! Sekarang Anda dapat melatih model dengan Trainer Transformers, Accelerate, atau loop pelatihan PyTorch kustom apa pun.
Sebagai contoh, untuk melatih dengan kelas Trainer, siapkan kelas TrainingArguments dengan beberapa hiperparameter pelatihan.
training_args = TrainingArguments(
output_dir="your-name/meta-llama/my-llama3.2-adapter",
learning_rate=1e-3,
per_device_train_batch_size=32,
per_device_eval_batch_size=32,
num_train_epochs=2,
weight_decay=0.01,
eval_strategy="epoch",
save_strategy="epoch",
load_best_model_at_end=True,
)Lewatkan model, argumen pelatihan, dataset, tokenizer, dan komponen lain yang diperlukan ke Trainer, lalu panggil train untuk memulai pelatihan.
trainer = Trainer(
model=peft_model,
args=training_args,
train_dataset=tokenized_datasets["train"],
eval_dataset=tokenized_datasets["test"],
data_collator=data_collator,
compute_metrics=compute_metrics,
)
trainer.train()Simpan model
Setelah model Anda selesai dilatih, Anda dapat menyimpan model ke direktori menggunakan fungsi save_pretrained().
peft_model.save_pretrained("output_dir")Anda juga dapat menyimpan model Anda ke Hub (pastikan Anda sudah masuk ke akun Hugging Face terlebih dahulu) dengan fungsi push_to_hub.
from huggingface_hub import notebook_login
notebook_login()
peft_model.push_to_hub("your-name/my-llama3.2-adapter")Kedua metode hanya menyimpan bobot PEFT tambahan yang dilatih, sehingga sangat efisien untuk disimpan, ditransfer, dan dimuat. Sebagai contoh, model facebook/opt-350m yang dilatih dengan LoRA hanya berisi dua file: adapter_config.json dan adapter_model.safetensors. File adapter_model.safetensors hanya berukuran 6,3MB!
Inferensi
Lihat referensi API AutoPeftModel untuk daftar lengkap kelas
AutoPeftModelyang tersedia.
Muat dengan mudah model yang dilatih PEFT mana pun untuk inferensi dengan kelas AutoPeftModel dan metode from_pretrained:
from peft import AutoPeftModelForCausalLM
from transformers import AutoTokenizer
import torch
device = torch.accelerator.current_accelerator().type if hasattr(torch, "accelerator") else "cuda"
peft_model = AutoPeftModelForCausalLM.from_pretrained("ybelkada/opt-350m-lora")
tokenizer = AutoTokenizer.from_pretrained("facebook/opt-350m")
peft_model = peft_model.to(device)
peft_model.eval()
inputs = tokenizer("Preheat the oven to 350 degrees and place the cookie dough", return_tensors="pt")
outputs = peft_model.generate(input_ids=inputs["input_ids"].to(peft_model.device), max_new_tokens=50)
print(tokenizer.batch_decode(outputs.detach().cpu().numpy(), skip_special_tokens=True)[0])
"Preheat the oven to 350 degrees and place the cookie dough in the center of the oven. In a large bowl, combine the flour, baking powder, baking soda, salt, and cinnamon. In a separate bowl, combine the egg yolks, sugar, and vanilla."Untuk tugas lain yang tidak didukung secara eksplisit dengan kelas AutoPeftModelFor - seperti pengenalan ucapan otomatis - Anda tetap dapat menggunakan kelas dasar AutoPeftModel untuk memuat model untuk tugas tersebut.
from peft import AutoPeftModel
peft_model = AutoPeftModel.from_pretrained("smangrul/openai-whisper-large-v2-LORA-colab")Cara paling umum untuk memuat adapter PEFT yang telah dilatih ke dalam model adalah dengan menggunakan from_pretrained():
from transformers import AutoPeftModelForCausalLM
from peft import PeftModel
base_model = AutoModelForCausalLM.from_pretrained("meta-llama/llama3.2-1B")
peft_model = PeftModel.from_pretrained(base_model, "my-user/my-llama-adapter") # you can also pass a directory instead of a hub pathBeberapa adapter
PEFT mendukung pemasangan beberapa adapter (dari jenis yang sama, dalam dokumen ini yaitu LoRA) di atas model dasar. Saat Anda memanggil get_peft_model, hanya ada satu adapter bernama "default", tetapi Anda dapat menambahkan sebanyak mungkin adapter tambahan dengan memanggil peft_model.add_adapter(adapter_name=...).
Ini bekerja karena lapisan yang dibungkus sebenarnya memiliki kumpulan bobot yang dapat dilatih secara unik untuk setiap nama adapter. Tidak semua adapter aktif dan dapat dilatih secara default. Anda harus secara eksplisit mengaktifkan adapter berdasarkan nama sebelum mereka menjadi aktif. Hal ini memungkinkan Anda untuk dengan cepat berpindah antar adapter di mana pengetahuan spesifik tugas diperlukan atau melayani berbagai kasus penggunaan di atas satu model.

Ingatlah untuk memanggil peft_model.set_adapter(<adapter_name>) terlebih dahulu untuk mengaktifkan adapter.
Contoh cepat:
peft_model.add_adapter(adapter_name='new_adapter')
peft_model.set_adapter('new_adapter')Langkah selanjutnya
Sekarang setelah Anda melihat cara melatih model dengan salah satu metode PEFT, kami mendorong Anda untuk mencoba beberapa metode lain seperti prompt tuning. Langkah-langkahnya sangat mirip dengan yang ditunjukkan di quicktour:
- siapkan PeftConfig untuk metode PEFT, misalnya LoraConfig atau konfigurasi lain (lihat ringkasan metode)
- gunakan metode get_peft_model() untuk membuat PeftModel dari konfigurasi dan model dasar
Lalu Anda dapat melatihnya sesuai keinginan! Untuk memuat model PEFT untuk inferensi, Anda dapat menggunakan kelas AutoPeftModel.
Silakan juga melihat panduan tugas jika Anda tertarik melatih model dengan metode PEFT lain untuk tugas tertentu seperti segmentasi semantik, pengenalan ucapan otomatis multibahasa, DreamBooth, klasifikasi token, dan lainnya.
Update on GitHub