TRL documentation
Интеграция PEFT
Интеграция PEFT
TRL поддерживает методы PEFT (Parameter-Efficient Fine-Tuning) для экономичного обучения моделей с точки зрения памяти. 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. Использование флагов CLI (самый простой способ)
Самый простой способ включить 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, Prompt Tuning и т. д.)
Недостатки: требуется код на Python
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) |
|---|---|---|
| SFT | 2.0e-5 | 2.0e-4 |
| DPO | 5.0e-7 | 5.0e-6 |
| GRPO | 1.0e-6 | 1.0e-5 |
| Настройка промпта | N/A | от 1.0e-2 до 3.0e-2 |
Почему 10x? Адаптеры LoRA содержат значительно меньше обучаемых параметров, чем полная модель. Более высокая скорость обучения компенсирует это уменьшенное количество параметров, обеспечивая эффективное обучение. Подробное объяснение см. в этом блоге.
Для получения дополнительных рекомендаций по эффективному использованию LoRA обратитесь к документации LoRA Without Regret.
PEFT с различными тренерами
Тренеры TRL поддерживают конфигурации PEFT для различных парадигм обучения. Ниже приведены подробные примеры для каждого основного тренера.
Добучение с учителем (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Пример на Python
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()Оптимизация прямых предпочтений (DPO)
Класс DPOTrainer реализует обучение на основе предпочтений из обратной связи человека.
С LoRA
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Пример на Python
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()Примечание: При использовании PEFT с DPO не нужно указывать отдельную модель-референс (ref_model). Тренер автоматически использует замороженную базовую модель в качестве референса.
Групповая относительная оптимизация политики (GRPO)
GRPOTrainer оптимизирует политики с использованием групповых наград.
С LoRA
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Пример на Python
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: квантованная адапция низкого ранга
QLoRA сочетает 4-битовое квантование с LoRA, что позволяет выполнять дообучение очень больших моделей на потребительском оборудовании. Этот метод может снизить требования к памяти до 4 раз по сравнению со стандартным LoRA.
Как работает QLoRA
- 4-битное квантование: базовая модель загружается в 4-битной точности с помощью
bitsandbytes - Замороженные веса: Веса квантованной модели остаются замороженными во время обучения
- Адаптеры LoRA: в повышенной точности обучаются только параметры адаптера LoRA
- Эффективность использования памяти: позволяет выполнять дообучение моделей, таких как Llama-70B, на одном потребительском GPU
Использование 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Пример на Python
Передайте quantization_config непосредственно в trainer вместе с peft_config — trainer загрузит и квантизирует модель за вас. Тот же аргумент 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: Тип данных, используемый для вычислений. Используйте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, в то время как его контрольная точка в MXFP4 занимает 13 ГБ. Чтобы загрузить его в bfloat16, как и любую другую модель:
from trl import SFTConfig
training_args = SFTConfig(model_init_kwargs={"dtype": "bfloat16"})FP8 checkpoints require transformers 5.0.0 or later.
Prompt Tuning
Prompt tuning — это ещё одна техника PEFT, которая обучает мягкие промпты (непрерывные эмбеддинги), добавляемые в начало входных данных, при этом вся модель остаётся замороженной. Этот подход особенно эффективен для больших моделей.
Как работает Prompt Tuning
- Виртуальные токены: добавляет обучаемые непрерывные эмбеддинги (виртуальные токены) во вход
- Замороженная модель: вся базовая модель остаётся замороженной
- Промпты для конкретных задач: каждая задача обучает собственные эмбеддинги промптов
- Экстремальная эффективность: обучаются только эмбеддинги промпта (обычно 8–20 токенов)
Использование Prompt Tuning с 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()Конфигурация 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",
)Параметры конфигурации:
task_type: тип задачи (TaskType.CAUSAL_LMдля моделирования языка)prompt_tuning_init: метод инициализации (TEXT,RANDOM)num_virtual_tokens: количество виртуальных токенов, добавляемых в начало (обычно 8–20)prompt_tuning_init_text: Текст для инициализации виртуальных токенов (при использовании инициализацииTEXT)tokenizer_name_or_path: Токенизатор для инициализации из текста
Prompt Tuning и LoRA
| Возможность | Prompt Tuning | LoRA |
|---|---|---|
| Обучаемые параметры | ~0.001% | ~0.1-1% |
| Использование памяти | Минимальный | Низкий |
| Скорость обучения | Самый быстрый | Быстро |
| Изменение модели | None | Слои адаптеров |
| Лучше всего подходит для | Большие модели, множество задач | Общая дообучаемость |
| Коэффициент обучения | Выше (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: Коэффициент масштабирования (обычно в 2 раза больше ранга). Управляет величиной обновлений 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: dropout для LoRA (по умолчанию: 0.05)--lora_target_modules: Целевые модули (разделённые пробелом)--lora_modules_to_save: Дополнительные модули для обучения--use_rslora: Включить Rank-Stabilized LoRA--use_dora: Включить Weight-Decomposed 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")Обучение на нескольких GPU
PEFT бесшовно работает с поддержкой нескольких GPU в 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Для QLoRA с несколькими GPU базовая модель автоматически разбивается на части:
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Наивный параллелизм по конвейеру (NPP) для больших моделей
Для очень больших моделей (>60 млрд параметров) TRL поддерживает Naive Pipeline Parallelism (NPP), который распределяет модель и адаптеры по нескольким GPU. Активации и градиенты передаются между GPU, поддерживаются как int8, так и другие типы данных.

Как использовать 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на первом GPU (устройство 0), чтобы избежать ошибок- См. это руководство по картам устройств для правильной настройки
- Запускайте скрипты обучения напрямую (не через
torchrun):python script.py- Параллелизм данных пока не поддерживается в NPP
Ресурсы
Примеры и ноутбуки TRL
- Ноутбук SFT с LoRA/QLoRA — Полноценный рабочий пример, демонстрирующий реализации как LoRA, так и QLoRA
- Каталог примеров TRL — Коллекция скриптов обучения, демонстрирующих PEFT с различными тренерами
- Рецепты TRL Cookbook — пошаговые руководства для типичных сценариев обучения PEFT
Документация
- Документация PEFT - Официальная документация библиотеки PEFT
- Документация TRL — Полная документация TRL с руководствами по тренерам
- LoRA без сожалений — Лучшие практики эффективного использования LoRA
Научные статьи
- Статья о LoRA — исходная методология и результаты LoRA
- Статья QLoRA — Эффективная дообучение с 4-битным квантованием
- Статья о Prompt Tuning - Мощь масштаба для параметрически эффективной настройки промптов