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는 베이스 모델을 고정 상태로 유지하면서 소수의 추가 파라미터만 학습하여 대규모 언어 모델을 파인튜닝할 수 있게 해주며, 이를 통해 계산 비용과 메모리 요구 사항을 크게 줄일 수 있습니다.

이 가이드는 LoRA, QLoRA, 프롬프트 튜닝 기법을 포함하여 PEFT를 다양한 TRL 트레이너와 함께 사용하는 방법을 다룹니다.

완전한 작동 예제는 SFT with LoRA/QLoRA 노트북을 참고하세요.

설치

TRL과 함께 PEFT를 사용하려면 필요한 종속성을 설치하세요:

pip install trl[peft]

QLoRA 지원(4비트 및 8비트 양자화)을 위해 다음도 설치하세요:

pip install bitsandbytes

빠른 시작

모든 TRL trainer는 peft_config 인수를 통해 PEFT를 지원합니다. 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

또는 Python 코드에서 PEFT 구성을 직접 전달할 수 있습니다:

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. Trainer에 peft_config 전달 (권장)

더 세밀한 제어가 필요하면 PEFT 구성을 trainer에 직접 전달하세요. 대부분의 사용 사례에서 권장되는 접근 방식입니다:

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 방법을 사용할 때는 전체 미세 조정(full fine-tuning)에 비해 더 높은 학습률(약 10배)을 사용해야 합니다. 이는 PEFT 방법이 매개변수의 일부만 학습하므로, 유사한 매개변수 업데이트를 달성하려면 더 큰 학습률이 필요하기 때문입니다.

권장 학습률:

TrainerFull Fine-TuningLoRA(10배) 사용
SFT2.0e-52.0e-4
DPO5.0e-75.0e-6
GRPO1.0e-61.0e-5
Prompt TuningN/A1.0e-2에서 3.0e-2까지

왜 10배인가? LoRA 어댑터는 전체 모델보다 학습 가능한 파라미터 수가 훨씬 적습니다. 더 높은 학습률은 이러한 파라미터 수 감소분을 상쇄하여 효과적인 학습을 보장합니다. 자세한 설명은 이 블로그 게시물을 참고하세요.

LoRA를 효과적으로 사용하는 방법에 대한 추가 모범 사례는 LoRA Without Regret 문서를 참조하세요.

PEFT와 다양한 Trainer

TRL의 트레이너는 다양한 학습 패러다임에 대한 PEFT 구성을 지원합니다. 아래에는 각 주요 트레이너에 대한 상세한 예제가 나와 있습니다.

sft
dpo
grpo

지도 미세 조정(SFT)

SFTTrainer는 지시 데이터셋에 대한 지도 미세 조정(supervised fine-tuning)에 사용됩니다.

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-bit 양자화를 LoRA와 결합하여 소비자 하드웨어에서 매우 큰 모델의 미세 조정을 가능하게 합니다. 이 기법은 표준 LoRA에 비해 메모리 요구량을 최대 4배까지 줄일 수 있습니다.

QLoRA 작동 원리

  1. 4-bit 양자화: bitsandbytes를 사용하여 기본 모델을 4-bit 정밀도로 로드합니다
  2. 동결된 가중치: 양자화된 모델 가중치는 학습 동안 동결된 상태를 유지합니다
  3. LoRA 어댑터: LoRA 어댑터 매개변수만 더 높은 정밀도로 학습됩니다
  4. 메모리 효율성: Llama-70B와 같은 모델을 단일 소비자용 GPU에서 미세 조정할 수 있습니다

TRL에서 QLoRA 사용

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를 peft_config와 함께 trainer에 직접 전달하세요. 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: 연산에 사용되는 dtype입니다. 더 안정적인 학습을 위해 bfloat16를 사용하세요.
  • bnb_4bit_use_double_quant: 매개변수당 약 0.4비트를 추가로 절약하기 위해 중첩 양자화를 활성화합니다.

8-bit 양자화

메모리 절감 효과가 다소 줄더라도 약간 더 높은 정밀도를 원한다면 8-bit 양자화를 사용할 수 있습니다:

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로 배포됩니다. 이러한 가중치는 제자리에서 학습할 수 없으므로, 이러한 체크포인트를 이름으로 전달하면 trainer는 peft_config가 있든 없든 상관없이 이를 역양자화 상태로 로드합니다. 이후 모델은 역양자화 가중치의 메모리를 차지하게 되며, 예를 들어 gpt-oss-20b의 경우 bfloat16에서 약 42 GB를 차지하는 반면, 해당 MXFP4 체크포인트는 13 GB입니다. bfloat16로 로드하려면, 다른 모델과 마찬가지로:

from trl import SFTConfig

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

FP8 체크포인트는 transformers 5.0.0 이상 버전이 필요합니다.

Prompt Tuning

Prompt tuning은 모델 전체를 동결한 채로 입력 앞에 추가되는 소프트 프롬프트(연속 임베딩)를 학습하는 또 다른 PEFT 기법입니다. 이는 대규모 모델에서 특히 효과적입니다.

프롬프트 튜닝 작동 방식

  1. Virtual Tokens: 입력에 학습 가능한 연속 임베딩(가상 토큰)을 추가
  2. 동결된 모델: 전체 베이스 모델이 동결된 상태
  3. 작업별 프롬프트: 각 작업은 자체 프롬프트 임베딩을 학습합니다
  4. 극한의 효율성: 프롬프트 임베딩만 학습됩니다(일반적으로 8~20개의 토큰)

TRL을 사용한 Prompt Tuning

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: 텍스트에서 초기화할 때 사용할 Tokenizer

Prompt Tuning vs 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: LoRA 레이어의 Dropout 확률 (일반적으로 0.05~0.1).
  • target_modules: LoRA를 적용할 모듈입니다. 일반적인 선택지:
    • ["q_proj", "v_proj"]: Attention query와 value (메모리 효율적)
    • ["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 alpha (기본값: 32)
  • --lora_dropout: LoRA dropout (기본값: 0.05)
  • --lora_target_modules: 대상 모듈(공백으로 구분)
  • --lora_modules_to_save: 학습할 추가 모듈
  • --use_rslora: Rank-Stabilized LoRA 활성화
  • --use_dora: Weight-Decomposed LoRA(DoRA) 활성화
  • --load_in_4bit: 4-bit 양자화(QLoRA) 활성화
  • --load_in_8bit: 8-bit 양자화 활성화

PEFT 모델 저장 및 로드

저장

학습이 완료되면 PEFT 어댑터를 저장합니다:

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

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

… 전체 모델(수 GB)이 아닌 어댑터 가중치(수 MB)만 저장합니다.

로딩

추론을 위해 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에 푸시하기

Hugging Face Hub에서 PEFT 어댑터를 쉽게 공유할 수 있습니다:

# 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는 TRL의 멀티 GPU 지원과 완벽하게 호환됩니다:

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

여러 GPU를 사용하는 QLoRA의 경우, 기본 모델은 자동으로 샤드됩니다:

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

대규모 모델을 위한 Naive Pipeline Parallelism(NPP)

매우 큰 모델(>60B 파라미터)의 경우, TRL은 모델과 어댑터를 여러 GPU에 분산하는 Naive Pipeline Parallelism(NPP)을 지원합니다. 활성화 값과 기울기는 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에서는 아직 Data Parallelism을 지원하지 않습니다

리소스

TRL 예제 및 노트북

문서

연구 논문

Update on GitHub