TRL documentation

Интеграция PEFT

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Интеграция 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)
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

Пример на 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()

QLoRA: квантованная адапция низкого ранга

QLoRA сочетает 4-битовое квантование с LoRA, что позволяет выполнять дообучение очень больших моделей на потребительском оборудовании. Этот метод может снизить требования к памяти до 4 раз по сравнению со стандартным LoRA.

Как работает QLoRA

  1. 4-битное квантование: базовая модель загружается в 4-битной точности с помощью bitsandbytes
  2. Замороженные веса: Веса квантованной модели остаются замороженными во время обучения
  3. Адаптеры LoRA: в повышенной точности обучаются только параметры адаптера LoRA
  4. Эффективность использования памяти: позволяет выполнять дообучение моделей, таких как 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

  1. Виртуальные токены: добавляет обучаемые непрерывные эмбеддинги (виртуальные токены) во вход
  2. Замороженная модель: вся базовая модель остаётся замороженной
  3. Промпты для конкретных задач: каждая задача обучает собственные эмбеддинги промптов
  4. Экстремальная эффективность: обучаются только эмбеддинги промпта (обычно 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 TuningLoRA
Обучаемые параметры~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

Как использовать 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

Документация

Научные статьи

  • Статья о LoRA — исходная методология и результаты LoRA
  • Статья QLoRA — Эффективная дообучение с 4-битным квантованием
  • Статья о Prompt Tuning - Мощь масштаба для параметрически эффективной настройки промптов
Update on GitHub