Integrasi PEFT

TRL mendukung metode PEFT (Parameter-Efficient Fine-Tuning) untuk pelatihan model yang hemat memori. PEFT memungkinkan fine-tuning model bahasa besar dengan hanya melatih sejumlah kecil parameter tambahan sambil mempertahankan model dasar tetap beku, sehingga secara signifikan mengurangi biaya komputasi dan kebutuhan memori.

Panduan ini membahas cara menggunakan PEFT dengan berbagai trainer TRL, termasuk teknik LoRA, QLoRA, dan prompt tuning.

Untuk contoh lengkap yang berfungsi, lihat notebook SFT dengan LoRA/QLoRA.

Instalasi

Untuk menggunakan PEFT dengan TRL, instal dependensi yang diperlukan:

pip install trl[peft]

Untuk dukungan QLoRA (kuantisasi 4-bit dan 8-bit), juga instal:

pip install bitsandbytes

Mulai Cepat

Semua trainer TRL mendukung PEFT melalui argumen peft_config. Cara paling sederhana untuk mengaktifkan PEFT adalah dengan menggunakan antarmuka baris perintah menggunakan flag --use_peft:

python trl/scripts/sft.py \
    --model_name_or_path Qwen/Qwen2-0.5B \
    --dataset_name trl-lib/Capybara \
    --use_peft \
    --lora_r 32 \
    --lora_alpha 16 \
    --output_dir Qwen2-0.5B-SFT-LoRA

Sebagai alternatif, Anda dapat meneruskan konfigurasi PEFT secara langsung di kode Python Anda:

from peft import LoraConfig
from trl import SFTTrainer

# Configure LoRA
peft_config = LoraConfig(
    r=32,
    lora_alpha=16,
    lora_dropout=0.05,
    bias="none",
    task_type="CAUSAL_LM",
)

# Configure training - note the higher learning rate for LoRA (10x base rate)
training_args = SFTConfig(
    learning_rate=2.0e-4,  # 10x the base rate (2.0e-5) for LoRA
    ...
)

# Create trainer with PEFT
trainer = SFTTrainer(
    model=model,
    train_dataset=dataset,
    peft_config=peft_config,
)

Tiga Cara Mengonfigurasi PEFT

TRL menyediakan tiga metode berbeda untuk mengonfigurasi PEFT, masing-masing cocok untuk kasus penggunaan yang berbeda:

1. Menggunakan Flag CLI (Paling Sederhana)

Cara termudah untuk mengaktifkan PEFT adalah dengan menggunakan flag --use_peft pada antarmuka baris perintah. Metode ini ideal untuk eksperimen cepat dan konfigurasi standar:

python trl/scripts/sft.py \
    --model_name_or_path Qwen/Qwen2-0.5B \
    --dataset_name trl-lib/Capybara \
    --use_peft \
    --lora_r 32 \
    --lora_alpha 16 \
    --lora_dropout 0.05 \
    --output_dir Qwen2-0.5B-SFT-LoRA

Kelebihan: Pengaturan cepat, tidak memerlukan kode

Kekurangan: Terbatas pada LoRA, lebih sedikit opsi kustomisasi

2. Menyalurkan peft_config ke Trainer (Disarankan)

Untuk kontrol lebih lanjut, berikan konfigurasi PEFT secara langsung ke trainer. Ini adalah pendekatan yang direkomendasikan untuk sebagian besar kasus penggunaan:

from peft import LoraConfig
from trl import SFTConfig, SFTTrainer

peft_config = LoraConfig(
    r=32,
    lora_alpha=16,
    lora_dropout=0.05,
    bias="none",
    task_type="CAUSAL_LM",
    target_modules=["q_proj", "v_proj", "k_proj", "o_proj"],
)

trainer = SFTTrainer(
    model=model,
    args=training_args,
    train_dataset=dataset,
    peft_config=peft_config,  # Pass config here
)

Kelebihan: Kontrol penuh, mendukung semua metode PEFT (LoRA, Prompt Tuning, dll.)

Kekurangan: Memerlukan kode Python

3. Menerapkan PEFT Langsung ke Model (Lanjutan)

Untuk fleksibilitas maksimal, Anda dapat menerapkan PEFT ke model Anda sebelum melewatkan model tersebut ke trainer:

from peft import LoraConfig, get_peft_model
from transformers import AutoModelForCausalLM
from trl import SFTConfig, SFTTrainer

# Load base model
model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2-0.5B")

# Apply PEFT configuration
peft_config = LoraConfig(
    r=32,
    lora_alpha=16,
    lora_dropout=0.05,
    bias="none",
    task_type="CAUSAL_LM",
)
model = get_peft_model(model, peft_config)

# Pass PEFT-wrapped model to trainer
trainer = SFTTrainer(
    model=model,  # Already has PEFT applied
    args=training_args,
    train_dataset=dataset,
    # Note: no peft_config needed here
)

Kelebihan: Kontrol maksimal, berguna untuk arsitektur model kustom atau konfigurasi yang kompleks

Kekurangan: Lebih banyak kata, membutuhkan pemahaman tentang bagian internal PEFT

Pertimbangan Laju Pembelajaran

Saat menggunakan LoRA atau metode PEFT lainnya, Anda biasanya perlu menggunakan learning rate yang lebih tinggi (sekitar 10x) dibandingkan fine-tuning penuh. Hal ini karena metode PEFT hanya melatih sebagian kecil parameter, sehingga memerlukan learning rate yang lebih besar untuk mencapai pembaruan parameter yang serupa.

Laju pembelajaran yang direkomendasikan:

Mengapa 10x? Adapter LoRA memiliki jumlah parameter yang dapat dilatih jauh lebih sedikit dibandingkan model penuh. Laju pembelajaran yang lebih tinggi mengompensasi pengurangan jumlah parameter ini, sehingga memastikan pelatihan yang efektif. Untuk penjelasan terperinci, lihat artikel blog ini.

Untuk praktik terbaik tambahan dalam menggunakan LoRA secara efektif, lihat dokumentasi LoRA Without Regret.

PEFT dengan Trainer yang Berbeda

Trainer dari TRL mendukung konfigurasi PEFT untuk berbagai paradigma pelatihan. Di bawah ini adalah contoh terperinci untuk setiap trainer utama.

python trl/scripts/sft.py \
    --model_name_or_path Qwen/Qwen2-0.5B \
    --dataset_name trl-lib/Capybara \
    --learning_rate 2.0e-4 \
    --num_train_epochs 1 \
    --per_device_train_batch_size 2 \
    --gradient_accumulation_steps 8 \
    --use_peft \
    --lora_r 32 \
    --lora_alpha 16 \
    --output_dir Qwen2-0.5B-SFT-LoRA

from peft import LoraConfig
from trl import SFTConfig, SFTTrainer

# Configure LoRA
peft_config = LoraConfig(
    r=32,
    lora_alpha=16,
    lora_dropout=0.05,
    bias="none",
    task_type="CAUSAL_LM",
    target_modules=["q_proj", "v_proj"],  # optional: specify target modules
)

# Configure training with higher learning rate for LoRA
training_args = SFTConfig(
    learning_rate=2.0e-4,  # 10x the base rate for LoRA
    ...
)

# Create trainer with PEFT config
trainer = SFTTrainer(
    model="Qwen/Qwen2-0.5B",  # can pass model name or loaded model
    args=training_args,
    train_dataset=dataset,
    peft_config=peft_config,  # pass PEFT config here
)
trainer.train()

python trl/scripts/dpo.py \
    --model_name_or_path Qwen/Qwen2-0.5B-Instruct \
    --dataset_name trl-lib/ultrafeedback_binarized \
    --learning_rate 5.0e-6 \
    --per_device_train_batch_size 2 \
    --gradient_accumulation_steps 8 \
    --use_peft \
    --lora_r 32 \
    --lora_alpha 16 \
    --output_dir Qwen2-0.5B-DPO-LoRA

from peft import LoraConfig
from trl import DPOConfig, DPOTrainer

# Configure LoRA
peft_config = LoraConfig(
    r=32,
    lora_alpha=16,
    lora_dropout=0.05,
    bias="none",
    task_type="CAUSAL_LM",
)

# Configure training with higher learning rate for LoRA
training_args = DPOConfig(
    learning_rate=5.0e-6,  # 10x the base rate for DPO with LoRA
    ...
)

# Create trainer with PEFT config
trainer = DPOTrainer(
    model="Qwen/Qwen2-0.5B",  # can pass model name or loaded model
    args=training_args,
    train_dataset=dataset,
    peft_config=peft_config,  # pass PEFT config here
)
trainer.train()

python trl/scripts/grpo.py \
    --model_name_or_path Qwen/Qwen2-0.5B \
    --dataset_name trl-lib/math-reasoning \
    --learning_rate 1.0e-5 \
    --per_device_train_batch_size 2 \
    --use_peft \
    --lora_r 32 \
    --lora_alpha 16 \
    --output_dir Qwen2-0.5B-GRPO-LoRA

from peft import LoraConfig
from trl import GRPOConfig, GRPOTrainer

# Configure LoRA
peft_config = LoraConfig(
    r=32,
    lora_alpha=16,
    lora_dropout=0.05,
    bias="none",
    task_type="CAUSAL_LM",
)

# Configure training with higher learning rate for LoRA
training_args = GRPOConfig(
    learning_rate=1.0e-5,  # 10x the base rate for GRPO with LoRA
    ...
)

# Create trainer with PEFT config
trainer = GRPOTrainer(
    model="Qwen/Qwen2-0.5B",  # can pass model name or loaded model
    args=training_args,
    train_dataset=dataset,
    peft_config=peft_config,  # pass PEFT config here
)
trainer.train()

QLoRA: Adaptasi Rank Rendah Terkuantisasi

QLoRA menggabungkan kuantisasi 4-bit dengan LoRA untuk memungkinkan penyesuaian halus (fine-tuning) model yang sangat besar pada perangkat konsumen. Teknik ini dapat mengurangi kebutuhan memori hingga 4x dibandingkan dengan LoRA standar.

Cara Kerja QLoRA

1. Kuantisasi 4-bit: Model dasar dimuat dalam presisi 4-bit menggunakan bitsandbytes
2. Bobot Beku: Bobot model terkuantisasi tetap beku selama pelatihan
3. Adaptasi LoRA: Hanya parameter adaptasi LoRA yang dilatih dalam presisi yang lebih tinggi
4. Efisiensi Memori: Memungkinkan fine-tuning model seperti Llama-70B pada satu GPU konsumen

Menggunakan QLoRA dengan TRL

Cukup gabungkan load_in_4bit=True dengan konfigurasi PEFT:

Baris Perintah

python trl/scripts/sft.py \
    --model_name_or_path meta-llama/Llama-2-7b-hf \
    --dataset_name trl-lib/Capybara \
    --load_in_4bit \
    --use_peft \
    --lora_r 32 \
    --lora_alpha 16 \
    --per_device_train_batch_size 1 \
    --gradient_accumulation_steps 16 \
    --output_dir Llama-2-7b-QLoRA

Contoh Python

Lewatkan quantization_config langsung ke trainer bersama peft_config — trainer akan memuat dan mengkuantisasi model untuk Anda. Argumen quantization_config yang sama tersedia di SFTTrainer, DPOTrainer, GRPOTrainer, dan RLOOTrainer.

import torch

from peft import LoraConfig
from transformers import BitsAndBytesConfig
from trl import SFTConfig, SFTTrainer

# Configure 4-bit quantization
bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_compute_dtype=torch.bfloat16,
    bnb_4bit_use_double_quant=True,
)

# Configure LoRA
peft_config = LoraConfig(
    r=32,
    lora_alpha=16,
    lora_dropout=0.05,
    bias="none",
    task_type="CAUSAL_LM",
)

# Configure training with higher learning rate for LoRA
training_args = SFTConfig(
    learning_rate=2.0e-4,  # 10x the base rate for QLoRA
    ...
)

# Create trainer with quantization and PEFT config
trainer = SFTTrainer(
    model="meta-llama/Llama-2-7b-hf",
    args=training_args,
    train_dataset=dataset,
    quantization_config=bnb_config,
    peft_config=peft_config,
)

trainer.train()

Opsi Konfigurasi QLoRA

BitsAndBytesConfig menyediakan beberapa opsi untuk mengoptimalkan memori dan kinerja:

import torch

from transformers import BitsAndBytesConfig

bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",  # or "fp4"
    bnb_4bit_compute_dtype=torch.bfloat16,  # Compute dtype for 4-bit base models
    bnb_4bit_use_double_quant=True,  # Nested quantization for additional memory savings
)

Parameter Konfigurasi:

• bnb_4bit_quant_type: Tipe data kuantisasi ("nf4" atau "fp4"). NF4 direkomendasikan.
• bnb_4bit_compute_dtype: dtype yang digunakan untuk komputasi. Gunakan bfloat16 untuk stabilitas pelatihan yang lebih baik.
• bnb_4bit_use_double_quant: Aktifkan kuantisasi bersarang untuk menghemat sekitar 0,4 bit tambahan per parameter.

Kuantisasi 8-bit

Untuk presisi yang sedikit lebih tinggi dengan penghematan memori yang berkurang, Anda dapat menggunakan kuantisasi 8-bit:

from transformers import BitsAndBytesConfig, AutoModelForCausalLM

bnb_config = BitsAndBytesConfig(load_in_8bit=True)

model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-2-7b-hf",
    quantization_config=bnb_config,
    device_map="auto",
)

Atau melalui baris perintah:

python trl/scripts/sft.py \
    --model_name_or_path meta-llama/Llama-2-7b-hf \
    --load_in_8bit \
    --use_peft \
    --lora_r 32 \
    --lora_alpha 16

Checkpoint yang sudah dikuantisasi

Beberapa checkpoint dirilis dalam bentuk terkuantisasi, seperti gpt-oss dalam MXFP4 atau Mistral Medium 3.5 dalam FP8. Bobot ini tidak dapat dilatih secara langsung, sehingga ketika Anda meneruskan checkpoint semacam itu berdasarkan nama, trainer memuatnya dalam bentuk terdekuantisasi, dengan atau tanpa peft_config. Model kemudian menggunakan memori sebesar bobot terdekuantisasinya, misalnya sekitar 42 GB dalam bfloat16 untuk gpt-oss-20b, dibandingkan 13 GB untuk checkpoint MXFP4-nya. Untuk memuatnya dalam bfloat16, seperti model lainnya:

from trl import SFTConfig

training_args = SFTConfig(model_init_kwargs={"dtype": "bfloat16"})

Checkpoint FP8 memerlukan transformers 5.0.0 atau lebih baru.

Penyesuaian Prompt

Prompt tuning adalah teknik PEFT lain yang mempelajari soft prompt (embedding kontinu) yang ditambahkan di depan input, sambil mempertahankan seluruh model tetap beku. Teknik ini sangat efektif untuk model besar.

Cara Kerja Prompt Tuning

1. Token Virtual: Menambahkan embedding kontinu yang dapat dipelajari (token virtual) ke input
2. Model Beku: Seluruh model dasar tetap beku
3. Prompt Spesifik Tugas: Setiap tugas mempelajari embedding prompt-nya sendiri
4. Keefektifan Ekstrem: Hanya embedding prompt yang dilatih (biasanya 8-20 token)

Menggunakan Prompt Tuning dengan TRL

from peft import PromptTuningConfig, PromptTuningInit, TaskType
from trl import SFTConfig, SFTTrainer

# Configure Prompt Tuning
peft_config = PromptTuningConfig(
    task_type=TaskType.CAUSAL_LM,
    prompt_tuning_init=PromptTuningInit.TEXT,
    num_virtual_tokens=8,
    prompt_tuning_init_text="Classify if the tweet is a complaint or not:",
    tokenizer_name_or_path="Qwen/Qwen2-0.5B",
)

# Configure training with higher learning rate for Prompt Tuning
training_args = SFTConfig(
    learning_rate=2.0e-2,  # Prompt Tuning typically uses 1e-2 to 3e-2
    ...
)

# Create trainer with PEFT config
trainer = SFTTrainer(
    model=model,
    args=training_args,
    train_dataset=dataset,
    peft_config=peft_config,  # pass PEFT config here
)

trainer.train()

Konfigurasi Prompt Tuning

from peft import PromptTuningConfig, PromptTuningInit, TaskType

peft_config = PromptTuningConfig(
    task_type=TaskType.CAUSAL_LM,  # Task type
    prompt_tuning_init=PromptTuningInit.TEXT,  # Initialize from text
    num_virtual_tokens=8,  # Number of virtual tokens
    prompt_tuning_init_text="Your initialization text here",
    tokenizer_name_or_path="model_name",
)

Parameter Konfigurasi:

• task_type: Jenis tugas (TaskType.CAUSAL_LM untuk pemodelan bahasa)
• prompt_tuning_init: Metode inisialisasi (TEXT, RANDOM)
• num_virtual_tokens: Jumlah token virtual yang ditambahkan di awal (biasanya 8-20)
• prompt_tuning_init_text: Teks untuk menginisialisasi token virtual (ketika menggunakan inisialisasi TEXT)
• tokenizer_name_or_path: Tokenizer untuk inisialisasi dari teks

Prompt Tuning vs LoRA

Konfigurasi PEFT Lanjutan

Parameter Konfigurasi LoRA

from peft import LoraConfig

peft_config = LoraConfig(
    r=16,  # LoRA rank
    lora_alpha=32,  # LoRA scaling factor
    lora_dropout=0.05,  # Dropout probability
    bias="none",  # Bias training strategy
    task_type="CAUSAL_LM",  # Task type
    target_modules=["q_proj", "v_proj"],  # Modules to apply LoRA
    modules_to_save=None,  # Additional modules to train
)

Parameter Utama:

• r: rank LoRA (nilai tipikal: 8, 16, 32, 64). Rank yang lebih tinggi = lebih banyak parameter tetapi berpotensi memberikan performa yang lebih baik.
• lora_alpha: Faktor penskalaan (biasanya 2x rank). Mengontrol magnitudo pembaruan LoRA.
• lora_dropout: Probabilitas dropout untuk lapisan LoRA (tipikal: 0.05-0.1).
• target_modules: Modul mana yang akan diterapkan LoRA. Pilihan umum:
  • ["q_proj", "v_proj"]: Query dan value (efisien memori) untuk Attention
  • ["q_proj", "k_proj", "v_proj", "o_proj"]: Semua proyeksi perhatian
  • ["q_proj", "k_proj", "v_proj", "o_proj", "gate_proj", "up_proj", "down_proj"]: Semua lapisan linear
• modules_to_save: Modul tambahan untuk dilatih sepenuhnya (misalnya, ["embed_tokens", "lm_head"])

Pemilihan Modul Target

Anda dapat menentukan modul mana yang akan diterapkan LoRA. Pola umum:

# Minimal (most memory efficient)
target_modules=["q_proj", "v_proj"]

# Attention only
target_modules=["q_proj", "k_proj", "v_proj", "o_proj"]

# All linear layers (best performance, more memory)
target_modules=["q_proj", "k_proj", "v_proj", "o_proj", "gate_proj", "up_proj", "down_proj"]

Menggunakan Argumen Baris Perintah

Skrip TRL menerima parameter PEFT melalui baris perintah:

python trl/scripts/sft.py \
    --model_name_or_path Qwen/Qwen2-0.5B \
    --dataset_name trl-lib/Capybara \
    --use_peft \
    --lora_r 32 \
    --lora_alpha 16 \
    --lora_dropout 0.05 \
    --lora_target_modules q_proj v_proj \
    --output_dir output

Flag yang tersedia:

• --use_peft: Aktifkan PEFT
• --lora_r: rank LoRA (default: 16)
• --lora_alpha: LoRA alpha (default: 32)
• --lora_dropout: dropout LoRA (default: 0.05)
• --lora_target_modules: Modul target (dipisahkan spasi)
• --lora_modules_to_save: Modul tambahan untuk dilatih
• --use_rslora: Aktifkan Rank-Stabilized LoRA
• --use_dora: Aktifkan Weight-Decomposed LoRA (DoRA)
• --load_in_4bit: Aktifkan kuantisasi 4-bit (QLoRA)
• --load_in_8bit: Aktifkan kuantisasi 8-bit

Menyimpan dan Memuat Model PEFT

Menyimpan

Setelah pelatihan, simpan adapter PEFT Anda:

# Save the adapters
trainer.save_model("path/to/adapters")

# Or manually
model.save_pretrained("path/to/adapters")

Ini hanya menyimpan bobot adapter (~beberapa MB) alih-alih model lengkap (~beberapa GB).

Memuat

Muat model PEFT untuk inferensi:

from transformers import AutoModelForCausalLM
from peft import PeftModel

# Load base model
base_model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2-0.5B")

# Load PEFT adapters
model = PeftModel.from_pretrained(base_model, "path/to/adapters")

# Optionally merge adapters into base model for faster inference
model = model.merge_and_unload()

Mendorong ke Hub

Anda dapat dengan mudah membagikan adapter PEFT Anda di Hugging Face Hub:

# Push adapters to Hub
model.push_to_hub("username/model-name-lora")

# Load from Hub
from peft import PeftModel
model = PeftModel.from_pretrained(base_model, "username/model-name-lora")

Pelatihan Multi-GPU

PEFT bekerja dengan mulus bersama dukungan multi-GPU dari TRL:

torchrun --nproc_per_node 8 trl/scripts/sft.py \
    --model_name_or_path Qwen/Qwen2-0.5B \
    --dataset_name trl-lib/Capybara \
    --use_peft \
    --lora_r 32 \
    --lora_alpha 16

Untuk QLoRA dengan beberapa GPU, model dasar di-shard secara otomatis:

torchrun --nproc_per_node 8 trl/scripts/sft.py \
    --model_name_or_path meta-llama/Llama-2-70b-hf \
    --load_in_4bit \
    --use_peft \
    --lora_r 32

Paralelisme Pipeline Naif (NPP) untuk Model Besar

Untuk model yang sangat besar (>60B parameter), TRL mendukung Naive Pipeline Parallelism (NPP), yang mendistribusikan model dan adapter ke beberapa GPU. Aktivasi dan gradien dikomunikasikan antar GPU, mendukung int8 dan tipe data lainnya.

Cara Menggunakan NPP

Muat model Anda dengan device_map kustom untuk membaginya ke beberapa perangkat:

from transformers import AutoModelForCausalLM
from peft import LoraConfig

# Create custom device map (see accelerate documentation)
device_map = {
    "model.embed_tokens": 0,
    "model.layers.0": 0,
    # ... distribute layers across GPUs
    "lm_head": 0,  # Must be on GPU 0
}

model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-2-70b-hf",
    device_map=device_map,
    peft_config=lora_config,
)

• Jaga modul lm_head tetap di GPU pertama (perangkat 0) untuk menghindari kesalahan
• Lihat tutorial tentang peta perangkat untuk konfigurasi yang tepat
• Jalankan skrip pelatihan secara langsung (bukan dengan torchrun): python script.py
• Data Parallelism belum didukung dengan NPP

Sumber daya

Contoh dan Notebook TRL

• Notebook SFT dengan LoRA/QLoRA - Contoh kerja lengkap yang menunjukkan implementasi LoRA dan QLoRA
• Direktori Contoh TRL - Kumpulan skrip pelatihan yang mendemonstrasikan PEFT dengan berbagai trainer
• Resep-Resep TRL Cookbook - Panduan langkah demi langkah untuk skenario pelatihan PEFT yang umum

Dokumentasi

• Dokumentasi PEFT - Dokumentasi resmi pustaka PEFT
• Dokumentasi TRL - Dokumentasi TRL lengkap dengan panduan trainer
• LoRA Tanpa Penyesalan - Praktik terbaik untuk menggunakan LoRA secara efektif

Makalah Penelitian

• Makalah LoRA - Metodologi dan hasil LoRA asli
• Makalah QLoRA - Penyesuaian halus yang efisien dengan kuantisasi 4-bit
• Makalah Prompt Tuning - Kekuatan Skala untuk Prompt Tuning yang Efisien Parameter