TRL documentation

Интеграция PEFT

You are viewing v1.18.0 version. A newer version v1.18.1 is available.
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