TRL documentation

تكامل PEFT

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v1.17.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

تكامل PEFT

يدعم TRL طرق PEFT (التدريب الدقيق الفعال من حيث المعاملات) لتدريب النماذج بكفاءة في استخدام الذاكرة. تتيح PEFT إجراء التدريب الدقيق على نماذج اللغة الكبيرة من خلال تدريب عدد صغير فقط من المعاملات الإضافية مع إبقاء النموذج الأساسي مجمّداً، مما يقلل بشكل كبير من التكاليف الحسابية ومتطلبات الذاكرة.

يتناول هذا الدليل كيفية استخدام PEFT مع مدرّبي TRL المختلفين، بما في ذلك تقنيات LoRA وQLoRA وضبط الموجهات (prompt tuning).

لمثال عملي كامل، راجع دفتر ملاحظات SFT باستخدام LoRA/QLoRA.

التثبيت

للاستخدام PEFT مع TRL، ثبّت التبعيات المطلوبة:

pip install trl[peft]

لدعم QLoRA (تكميم 4 بت و8 بت)، ثبّت أيضاً:

pip install bitsandbytes

البدء السريع

تدعم جميع مدرّبي TRL تقنية PEFT عبر الحجة peft_config. أبسط طريقة لتفعيل PEFT هي استخدام واجهة سطر الأوامر مع العلم --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

بديلًا عن ذلك، يمكنك تمرير إعداد PEFT مباشرةً في كود Python الخاص بك:

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

توفر TRL ثلاث طرق مختلفة لإعداد PEFT، كل منها مناسب لحالات استخدام مختلفة:

1. استخدام أعلام سطر الأوامر (الأبسط)

أسهل طريقة لتفعيل PEFT هي استخدام علم --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 \
    --lora_dropout 0.05 \
    --output_dir Qwen2-0.5B-SFT-LoRA

المزايا: إعداد سريع، لا يتطلب كتابة أكواد

العيوب: مقصور على LoRA، وخيارات تخصيص أقل

2. تمرير peft_config إلى Trainer (موصى به)

للحصول على مزيد من التحكم، قم بتمرير إعداد PEFT مباشرةً إلى المدرب. هذا هو النهج الموصى به لمعظم حالات الاستخدام:

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
)

المزايا: تحكم كامل، يدعم جميع طرق PEFT (LoRA، ضبط الموجهات، إلخ)

العيوب: يتطلب كود بايثون

3. تطبيق PEFT على النموذج مباشرةً (متقدم)

للحصول على أقصى قدر من المرونة، يمكنك تطبيق PEFT على نموذجك قبل تمريره إلى المدرب:

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
)

المزايا: تحكم أقصى، مفيد لبناء نماذج مخصصة أو إعدادات معقدة

العيوب: أكثر تفصيلًا، ويتطلب فهمًا للتفاصيل الداخلية لـ PEFT

اعتبارات معدل التعلم

عند استخدام LoRA أو طرق PEFT الأخرى، تحتاج عادةً إلى استخدام معدل تعلّم أعلى (حوالي 10 أضعاف) مقارنةً بالتحسين الكامل. والسبب في ذلك أن طرق PEFT تُدرّب نسبة صغيرة فقط من المعاملات، مما يتطلب معدل تعلّم أكبر لتحقيق تحديثات مماثلة للمعاملات.

معدلات التعلم الموصى بها:

Trainerالضبط الدقيق الكاملمع LoRA (10x)
SFT2.0e-52.0e-4
DPO5.0e-75.0e-6
GRPO1.0e-61.0e-5
ضبط الموجهN/Aمن 1.0e-2 إلى 3.0e-2

لماذا 10x؟ تحتوي محولات LoRA على عدد أقل بكثير من المعاملات القابلة للتدريب مقارنة بالنموذج الكامل. يعوّض معدل تعلّم أعلى عن هذا العدد المخفض من المعاملات، مما يضمن تدريبًا فعالًا. للحصول على شرح مفصّل، راجع هذا المنشور على المدونة.

لمزيد من أفضل الممارسات المتعلقة باستخدام LoRA بفعالية، راجع وثيقة LoRA Without Regret.

PEFT مع مدرّبين مختلفين

تدعم مُدرِّبات TRL إعدادات PEFT لمختلف أنماط التدريب. أدناه أمثلة مفصّلة لكل مُدرِّب رئيسي.

sft
dpo
grpo

الضبط الدقيق الإشرافي (SFT)

يُستخدم SFTTrainer للضبط الدقيق الإشرافي على مجموعات بيانات التعليمات.

مع LoRA

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

QLoRA: تكييف منخفض الرتبة الكمّي

يجمع QLoRA بين التكميم بدقة 4 بت وتقنية LoRA لتمكين ضبط النماذج الكبيرة جدًا على أجهزة الاستهلاك. يمكن لهذه التقنية تقليل متطلبات الذاكرة بنسبة تصل إلى 4 أضعاف مقارنةً بـ LoRA القياسية.

كيف يعمل QLoRA

  1. تكميم 4 بت: يتم تحميل النموذج الأساسي بدقة 4 بت باستخدام bitsandbytes
  2. الأوزان المجمّدة: تبقى أوزان النموذج المُكمَّم مجمّدة أثناء التدريب
  3. مُكيّفات LoRA: يتم تدريب معاملات مُكيّفات LoRA فقط بدقة أعلى
  4. كفاءة الذاكرة: تتيح ضبط نماذج مثل Llama-70B على وحدة معالجة رسومات استهلاكية واحدة

استخدام QLoRA مع TRL

ما عليك سوى دمج load_in_4bit=True مع إعداد PEFT:

سطر الأوامر

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

مثال بلغة بايثون

مرّر quantization_config مباشرةً إلى المدرب إلى جانب peft_config — حيث يقوم المدرب بتحميل النموذج وتكميمه نيابةً عنك. يتوفر نفس معامل quantization_config في SFTTrainer وDPOTrainer وGRPOTrainer و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()

خيارات تكوين QLoRA

توفر BitsAndBytesConfig عدة خيارات لتحسين الذاكرة والأداء:

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
)

معلمات التهيئة:

  • bnb_4bit_quant_type: نوع بيانات التكميم ("nf4" أو "fp4"). يُوصى باستخدام NF4.
  • bnb_4bit_compute_dtype: نوع البيانات (dtype) المستخدم للحساب. استخدم bfloat16 لتحسين استقرار التدريب.
  • bnb_4bit_use_double_quant: تفعيل التكميم المتداخل لتوفير حوالي 0.4 بت إضافية لكل معامل.

الكمّية 8-بت

للحصول على دقة أعلى قليلاً مع تقليل توفير الذاكرة، يمكنك استخدام التكميم بـ 8 بت:

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

أو عبر سطر الأوامر:

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

نقاط التفتيش المُكمّاة مسبقًا

تُصدر بعض نقاط التفتيش مُكمّمة، مثل gpt-oss بصيغة MXFP4 أو Mistral Medium 3.5 بصيغة FP8. لا يمكن تدريب هذه الأوزان في مكانها، لذا عند تمرير مثل هذه نقطة التفتيش بالاسم، يقوم المُدرّب بتحميلها بعد فك التكميم، سواء مع peft_config أو بدونه. ثم يستهلك النموذج ذاكرة أوزانه بعد فك التكميم، على سبيل المثال حوالي 42 جيجابايت بصيغة bfloat16 لنموذج gpt-oss-20b، مقابل 13 جيجابايت لنقطة تفتيشه بصيغة MXFP4. لتحميله بصيغة bfloat16، كما هو الحال مع أي نموذج آخر:

from trl import SFTConfig

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

يتطلب نقاط التفتيش FP8 إصدار transformers 5.0.0 أو أحدث.

ضبط الموجه

يُعدّ ضبط المُوجِّه (Prompt tuning) تقنية أخرى من تقنيات PEFT تتعلّم مُوجِّهات ناعمة (تضمينات مستمرة) تُضاف إلى بداية المدخل، مع إبقاء النموذج بأكمله مجمّداً. وتكون هذه التقنية فعّالة بشكل خاص للنماذج الكبيرة.

كيف يعمل ضبط الموجه

  1. الرموز الافتراضية: تضيف تضمينات مستمرة قابلة للتعلم (رموز افتراضية) إلى المدخلات
  2. النموذج المجمّد: يبقى النموذج الأساسي بأكمله مجمّداً
  3. الموجّهات المحددة للمهمة: تتعلم كل مهمة تضمينات موجّهاتها الخاصة
  4. كفاءة قصوى: يتم تدريب تضمينات الاستعلام فقط (عادةً 8-20 رمزًا)

استخدام ضبط الموجه مع 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()

إعدادات ضبط الموجه

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

معلمات التهيئة:

  • task_type: نوع المهمة (TaskType.CAUSAL_LM لنمذجة اللغة)
  • prompt_tuning_init: طريقة التهيئة (TEXT، RANDOM)
  • num_virtual_tokens: عدد الرموز الافتراضية التي يجب إضافتها في البداية (عادةً 8-20)
  • prompt_tuning_init_text: النص المستخدم لتبديل الرموز الافتراضية (عند استخدام TEXT للتبديل)
  • tokenizer_name_or_path: مُجزِّئ (Tokenizer) للتشغيل من النص

ضبط الموجه مقابل LoRA

ميزةضبط الموجهLoRA
المعاملات المُدرَّبة~0.001%~0.1-1%
استهلاك الذاكرةبسيطةمنخفض
سرعة التدريبأسرعسريع
تعديل النموذجلا شيءطبقات المحوّل
Best Forنماذج كبيرة، مهام متعددةالضبط الدقيق العام
معدل التعلمأعلى (1e-2 إلى 3e-2)قياسي (1e-4 إلى 3e-4)

إعدادات PEFT المتقدمة

معلمات تكوين 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
)

المعلمات الرئيسية:

  • r: رتبة LoRA (القيم النموذجية: 8، 16، 32، 64). كلما زادت الرتبة، زاد عدد المعاملات، مما قد يؤدي إلى أداء أفضل.
  • lora_alpha: عامل التوسيع (عادةً ضعف الرتبة). يتحكم في حجم تحديثات LoRA.
  • lora_dropout: احتمال إسقاط (Dropout) لطبقات LoRA (القيمة النموذجية: 0.05-0.1).
  • target_modules: الوحدات التي سيتم تطبيق LoRA عليها. الخيارات الشائعة:
    • ["q_proj", "v_proj"]: استعلام الانتباه والقيمة (فعّال من حيث الذاكرة)
    • ["q_proj", "k_proj", "v_proj", "o_proj"]: جميع إسقاطات الانتباه
    • ["q_proj", "k_proj", "v_proj", "o_proj", "gate_proj", "up_proj", "down_proj"]: جميع الطبقات الخطية
  • modules_to_save: وحدات إضافية للتدريب الكامل (مثل ["embed_tokens", "lm_head"])

اختيار وحدة الهدف

يمكنك تحديد الوحدات التي تريد تطبيق LoRA عليها. الأنماط الشائعة:

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

استخدام حُجج سطر الأوامر

تقبل سكربتات TRL معاملات 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 \
    --lora_dropout 0.05 \
    --lora_target_modules q_proj v_proj \
    --output_dir output

العلامات المتاحة:

  • --use_peft: تفعيل PEFT
  • --lora_r: رتبة LoRA (الافتراضي: 16)
  • --lora_alpha: ألفا LoRA (الافتراضي: 32)
  • --lora_dropout: إسقاط LoRA (الافتراضي: 0.05)
  • --lora_target_modules: الوحدات المستهدفة (مفصولة بمسافات)
  • --lora_modules_to_save: وحدات إضافية للتدريب
  • --use_rslora: تفعيل LoRA المستقرّ المرتبة
  • --use_dora: تفعيل LoRA المُفكّك الأوزان (DoRA)
  • --load_in_4bit: تفعيل التكميم بدقة 4 بت (QLoRA)
  • --load_in_8bit: تفعيل التكميم بدقة 8 بت

حفظ نماذج PEFT وتحميلها

الحفظ

بعد التدريب، احفظ مُكيّفات PEFT الخاصة بك:

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

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

يحفظ هذا الأوزان الخاصة بالمُكيِّف فقط (بضعة ميغابايت تقريبًا) بدلاً من النموذج الكامل (عدة غيغابايت تقريبًا).

جارٍ التحميل

تحميل نموذج PEFT للاستدلال:

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

يمكنك بسهولة مشاركة محولات PEFT الخاصة بك على 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")

التدريب على وحدات معالجة رسومية متعددة

يعمل PEFT بسلاسة مع دعم TRL متعدد وحدات GPU من خلال accelerate:

# Configure accelerate
accelerate config

# Launch training
accelerate launch 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

في حالة استخدام QLoRA مع وحدات معالجة رسومية متعددة، يتم تقسيم النموذج الأساسي تلقائيًا:

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

التوازي البسيط للخطوط الأنابيب (NPP) للنماذج الكبيرة

بالنسبة للنماذج الكبيرة جداً (>60B من المعاملات)، يدعم TRL موازاة خط الأنابيب البسيطة (NPP)، والتي توزّع النموذج والمُكيِّفات على عدة وحدات معالجة رسومية. يتم تبادل التفعيلات والتدرجات عبر وحدات المعالجة الرسومية، مع دعم كل من int8 وأنواع البيانات الأخرى.

NPP

كيفية استخدام NPP

حمّل نموذجك باستخدام device_map مخصص لتقسيمه على أجهزة متعددة:

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,
)
  • حافظ على وحدة lm_head على وحدة المعالجة الرسومية الأولى (الجهاز 0) لتجنب الأخطاء
  • راجع هذا الدليل التعليمي حول خرائط الأجهزة للتهيئة المناسبة
  • شغّل سكربتات التدريب مباشرةً (وليس باستخدام accelerate launch): python script.py
  • لا يُدعم توازٍ البيانات بعد مع NPP

الموارد

أمثلة ودفاتر TRL

التوثيق

أوراق البحث

  • ورقة LoRA - منهجية LoRA الأصلية ونتائجها
  • ورقة QLoRA - الضبط الدقيق الفعال باستخدام التكميم بدقة 4 بت
  • ورقة Prompt Tuning - قوة التوسع في الضبط الفعّال من حيث المعلمات
Update on GitHub