TRL documentation

PEFT Entegrasyonu

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

PEFT Entegrasyonu

TRL, bellek verimli model eğitimi için PEFT (Parameter-Efficient Fine-Tuning) yöntemlerini destekler. PEFT, temel modeli dondurarak yalnızca küçük bir ek parametre kümesini eğitmek suretiyle büyük dil modellerinin ince ayarını mümkün kılar; bu sayede hesaplama maliyetleri ve bellek gereksinimleri önemli ölçüde azaltılır.

Bu kılavuz, LoRA, QLoRA ve prompt tuning teknikleri dahil olmak üzere PEFT'nin farklı TRL trainer'ları ile nasıl kullanılacağını ele alır.

Tamamen çalışan bir örnek için SFT with LoRA/QLoRA notebook'a bakın.

Kurulum

TRL ile PEFT kullanmak için gerekli bağımlılıkları yükleyin:

pip install trl[peft]

QLoRA desteği (4-bit ve 8-bit kuantizasyon) için ayrıca şunu da yükleyin:

pip install bitsandbytes

Hızlı Başlangıç

Tüm TRL eğitimcileri, peft_config argümanı aracılığıyla PEFT'yi destekler. PEFT'yi etkinleştirmenin en basit yolu, --use_peft bayrağını kullanarak komut satırı arayüzünü kullanmaktır:

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

Alternatif olarak, PEFT yapılandırmasını doğrudan Python kodunuzda geçebilirsiniz:

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,
)

PEFT'yi Yapılandırmak İçin Üç Yöntem

TRL, PEFT'yi yapılandırmak için farklı kullanım senaryolarına uygun üç farklı yöntem sunar:

1. CLI Bayraklarını Kullanma (En Kolay Yol)

PEFT'yi etkinleştirmenin en kolay yolu, komut satırı arayüzüyle --use_peft bayrağını kullanmaktır. Bu yöntem, hızlı deneyler ve standart yapılandırmalar için idealdir:

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

Avantajlar: Hızlı kurulum, kod gerektirmez

Dezavantajlar: LoRA ile sınırlı, daha az özelleştirme seçeneği

2. peft_config'in Trainer'a geçirilmesi (Önerilen)

Daha fazla kontrol için, bir PEFT yapılandırmasını doğrudan trainer'a iletin. Çoğu kullanım senaryosu için önerilen yaklaşım budur:

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
)

Avantajlar: Tam kontrol, tüm PEFT yöntemlerini destekler (LoRA, Prompt Tuning vb.)

Dezavantajlar: Python kodu gerektirir

3. PEFT'yi Doğrudan Modelde Uygulama (Gelişmiş)

Maksimum esneklik için, modeli eğiticinin (trainer) içine geçirmeden önce PEFT'yi uygulayabilirsiniz:

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
)

Avantajlar: Maksimum kontrol, özel model mimarileri veya karmaşık kurulumlar için faydalı

Dezavantajlar: Daha ayrıntılı, PEFT iç yapısının anlaşılmasını gerektirir

Öğrenme Hızı Düşünceleri

LoRA veya diğer PEFT yöntemlerini kullanırken, tam ince ayara kıyasla genellikle daha yüksek bir öğrenme oranı (yaklaşık 10 kat) kullanmanız gerekir. Bunun nedeni, PEFT yöntemlerinin parametrelerin yalnızca küçük bir kısmını eğitmesi ve benzer parametre güncellemelerini elde etmek için daha büyük bir öğrenme oranı gerektirmesidir.

Önerilen öğrenme oranları:

TrainerTam İnce AyarLoRA (10x) ile
SFT2.0e-52.0e-4
DPO5.0e-75.0e-6
GRPO1.0e-61.0e-5
Komut AyarlamaN/A1.0e-2 ile 3.0e-2 arasında

Neden 10x? LoRA adaptörleri, tam modele kıyasla çok daha az eğitilebilir parametreye sahiptir. Daha yüksek bir öğrenme oranı, bu azalmış parametre sayısını telafi ederek etkili bir eğitim sağlar. Ayrıntılı açıklama için bu blog yazısına bakın.

LoRA'yı etkili bir şekilde kullanmaya ilişkin ek en iyi uygulamalar için LoRA Without Regret belgesine başvurun.

Farklı Eğitimcilerle PEFT

TRL eğitimcileri, çeşitli eğitim paradigmaları için PEFT yapılandırmalarını destekler. Aşağıda, her bir ana eğitimci için ayrıntılı örnekler yer almaktadır.

sft
dpo
grpo

Gözetimli İnce Ayar (SFT)

SFTTrainer, talimat veri kümelerinde denetimli ince ayar için kullanılır.

LoRA ile

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

Python Örneği

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()

QLoRA: Kuantize Düşük-Rütbe Uyarlaması

QLoRA, 4-bit kuantizasyonu LoRA ile birleştirerek çok büyük modellerin tüketici donanımlarında ince ayar yapılmasını sağlar. Bu teknik, standart LoRA'ya kıyasla bellek gereksinimlerini 4 kata kadar azaltabilir.

QLoRA Nasıl Çalışır

  1. 4-bit Kuantizasyon: Temel model, bitsandbytes kullanılarak 4-bit hassasiyette yüklenir
  2. Dondurulmuş Ağırlıklar: Kuantize model ağırlıkları eğitim sırasında dondurulmuş kalır
  3. LoRA Adaptörleri: Yalnızca LoRA adaptör parametreleri daha yüksek hassasiyette eğitilir
  4. Bellek Verimliliği: Llama-70B gibi modellerin tek bir tüketici GPU'sunda ince ayar yapılmasını sağlar

TRL ile QLoRA Kullanımı

load_in_4bit=True parametresini PEFT yapılandırmasıyla birleştirin:

Komut Satırı

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

Python Örneği

quantization_config değerini peft_config ile birlikte doğrudan trainer'a iletin — trainer, modeli sizin için yükler ve kuantize eder. Aynı quantization_config argümanı SFTTrainer, DPOTrainer, GRPOTrainer ve RLOOTrainer sınıflarında da mevcuttur.

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()

QLoRA Yapılandırma Seçenekleri

BitsAndBytesConfig, bellek ve performansı optimize etmek için çeşitli seçenekler sunar:

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
)

Yapılandırma Parametreleri:

  • bnb_4bit_quant_type: Kuantizasyon veri türü ("nf4" veya "fp4"). NF4 önerilir.
  • bnb_4bit_compute_dtype: Hesaplama için kullanılan dtype. Daha iyi eğitim istikrarı için bfloat16 kullanın.
  • bnb_4bit_use_double_quant: Parametre başına ek olarak ~0,4 bit tasarruf etmek için iç içe geçmiş kuantizasyonu etkinleştirir.

8-bit Kuantizasyon

Daha düşük bellek tasarrufuyla biraz daha yüksek hassasiyet için 8-bit kuantizasyon kullanabilirsiniz:

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",
)

Veya komut satırı üzerinden:

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

Önceden kuantize edilmiş kontrol noktaları

Bazı kontrol noktaları, gpt-oss'in MXFP4 veya Mistral Medium 3.5'in FP8 gibi, kuantize edilmiş olarak yayınlanır. Bu ağırlıklar yerinde eğitilemediğinden, böyle bir kontrol noktasını adıyla geçirdiğinizde, eğitimci onu peft_config ile veya olmadan, dequantize edilmiş olarak yükler. Model, dequantize edilmiş ağırlıklarının belleğini kullanır; örneğin gpt-oss-20b için bfloat16'da yaklaşık 42 GB, MXFP4 kontrol noktası için ise 13 GB. bfloat16'da yüklemek için, diğer herhangi bir modelde olduğu gibi:

from trl import SFTConfig

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

FP8 checkpoint'ları, transformers 5.0.0 veya daha yeni bir sürüm gerektirir.

Prompt Ayarlama

Prompt tuning, tüm modeli dondurarak girdinin başına eklenen yumuşak istemleri (sürekli gömme vektörlerini) öğrenen başka bir PEFT tekniğidir. Bu, özellikle büyük modeller için son derece etkilidir.

Prompt Tuning Nasıl Çalışır

  1. Sanal Jetonlar: Girişe öğrenilebilir sürekli gömme (sanal jeton) ekler
  2. Dondurulmuş Model: Tüm temel model dondurulmuş olarak kalır
  3. Görev Özel İstemleri: Her görev kendi istem gömme değerlerini öğrenir
  4. Aşırı Verimlilik: Sadece istem gömlemeleri eğitilir (genellikle 8-20 jeton)

TRL ile Prompt Tuning Kullanma

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()

Prompt Tuning Yapılandırması

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",
)

Yapılandırma Parametreleri:

  • task_type: Görev türü (dil modelleme için TaskType.CAUSAL_LM)
  • prompt_tuning_init: Başlatma yöntemi (TEXT, RANDOM)
  • num_virtual_tokens: Başa eklenecek sanal jeton sayısı (genellikle 8-20)
  • prompt_tuning_init_text: Sanal token'ları başlatmak için kullanılacak metin (TEXT başlatma kullanıldığında)
  • tokenizer_name_or_path: Metinden başlatmak için Tokenizer

Prompt Tuning ve LoRA

ÖzellikPrompt AyarlamaLoRA
Eğitilen Parametreler~0.001%~0.1-1%
Bellek KullanımıMinimalDüşük
Eğitim HızıEn HızlıHızlı
Model DeğişikliğiNoneUyarlama katmanları
En Uygun Olduğu AlanBüyük modeller, birçok görevGenel ince ayar
Öğrenme HızıDaha yüksek (1e-2 ile 3e-2)Standart (1e-4 ile 3e-4)

Gelişmiş PEFT Yapılandırmaları

LoRA Yapılandırma Parametreleri

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
)

Önemli Parametreler:

  • r: LoRA rütbesi (tipik değerler: 8, 16, 32, 64). Daha yüksek rütbe = daha fazla parametre, ancak potansiyel olarak daha iyi performans.
  • lora_alpha: Ölçekleme faktörü (genellikle rank'in 2 katı). LoRA güncellemelerinin büyüklüğünü kontrol eder.
  • lora_dropout: LoRA katmanları için dropout olasılığı (tipik: 0.05-0.1).
  • target_modules: LoRA'nın uygulanacağı modüller. Yaygın seçimler:
    • ["q_proj", "v_proj"]: Dikkat sorgusu ve değer (bellek verimli)
    • ["q_proj", "k_proj", "v_proj", "o_proj"]: Tüm dikkat projeksiyonları
    • ["q_proj", "k_proj", "v_proj", "o_proj", "gate_proj", "up_proj", "down_proj"]: Tüm doğrusal katmanlar
  • modules_to_save: Tam olarak eğitilecek ek modüller (ör. ["embed_tokens", "lm_head"])

Hedef Modül Seçimi

LoRA'nın uygulanacağı modülleri belirleyebilirsiniz. Yaygın kalıplar:

# 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"]

Komut Satırı Argümanlarını Kullanma

TRL betikleri PEFT parametrelerini komut satırı üzerinden kabul eder:

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

Kullanılabilir bayraklar:

  • --use_peft: PEFT'yi etkinleştir
  • --lora_r: LoRA sırası (varsayılan: 16)
  • --lora_alpha: LoRA alfa (varsayılan: 32)
  • --lora_dropout: LoRA dropout (varsayılan: 0.05)
  • --lora_target_modules: Hedef modüller (boşlukla ayrılmış)
  • --lora_modules_to_save: Eğitilecek ek modüller
  • --use_rslora: Rank-Stabilized LoRA'yı etkinleştir
  • --use_dora: Weight-Decomposed LoRA (DoRA) etkinleştir
  • --load_in_4bit: 4-bit kuantizasyonu etkinleştirir (QLoRA)
  • --load_in_8bit: 8-bit kuantizasyonu etkinleştir

PEFT Modellerini Kaydetme ve Yükleme

Kaydetme

Eğitimden sonra PEFT adaptörlerinizi kaydedin:

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

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

Bu, tam modelin (~birkaç GB) yerine yalnızca adaptör ağırlıklarını (~birkaç MB) kaydeder.

Yükleniyor

Çıkarım için bir PEFT modeli yükleyin:

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()

Hub'a İtme

PEFT adaptörlerinizi Hugging Face Hub üzerinde kolayca paylaşabilirsiniz:

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

Çoklu GPU Eğitimi

PEFT, TRL’nin çoklu GPU desteğiyle kusursuz bir şekilde çalışır:

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

Birden fazla GPU ile QLoRA için temel model otomatik olarak bölünür:

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

Büyük Modeller için Naif Pipeline Parallelism (NPP)

Çok büyük modeller için (>60B parametre), TRL, modeli ve adaptörleri birden çok GPU arasında dağıtan Naive Pipeline Parallelism (NPP) özelliğini destekler. Aktivasyonlar ve gradyanlar GPU'lar arasında iletilir; hem int8 hem de diğer veri türleri desteklenir.

NPP

NPP Kullanımı

Modelinizi birden fazla cihaz arasında bölmek için özel bir device_map ile yükleyin:

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,
)
  • Hatalardan kaçınmak için lm_head modülünü ilk GPU'da (cihaz 0) tutun
  • Doğru yapılandırma için bu cihaz haritaları üzerine öğreticiye bakın
  • Eğitim betiklerini doğrudan çalıştırın (torchrun ile değil): python script.py
  • Data Parallelism, NPP ile henüz desteklenmemektedir

Kaynaklar

TRL Örnekleri ve Defterleri

Belgeler

Araştırma Makaleleri

Update on GitHub