# PEFT 통합

TRL은 메모리 효율적인 모델 훈련을 위해 [PEFT](https://github.com/huggingface/peft)(Parameter-Efficient Fine-Tuning) 방법을 지원합니다. PEFT는 베이스 모델을 고정 상태로 유지하면서 소수의 추가 파라미터만 학습하여 대규모 언어 모델을 파인튜닝할 수 있게 해주며, 이를 통해 계산 비용과 메모리 요구 사항을 크게 줄일 수 있습니다.

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

완전한 작동 예제는 [SFT with LoRA/QLoRA 노트북](https://github.com/huggingface/trl/blob/main/examples/sft_qlora/sft_qlora.ipynb)을 참고하세요.

## 설치

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

```bash
pip install trl[peft]
```

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

```bash
pip install bitsandbytes
```

## 빠른 시작

모든 TRL trainer는 `peft_config` 인수를 통해 PEFT를 지원합니다. PEFT를 활성화하는 가장 간단한 방법은 `--use_peft` 플래그를 사용하여 커맨드라인 인터페이스를 사용하는 것입니다:

```bash
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 구성을 직접 전달할 수 있습니다:

```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` 플래그를 사용하는 것입니다. 이 방법은 빠른 실험과 표준 구성에 이상적입니다:

```bash
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에 직접 전달하세요. 대부분의 사용 사례에서 권장되는 접근 방식입니다:

```python
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를 모델에 적용할 수 있습니다:

```python
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 방법이 매개변수의 일부만 학습하므로, 유사한 매개변수 업데이트를 달성하려면 더 큰 학습률이 필요하기 때문입니다.

**권장 학습률:**

| Trainer | Full Fine-Tuning | LoRA(10배) 사용 |
|---------|------------------|-----------------|
| **SFT** | `2.0e-5` | `2.0e-4` |
| **DPO** | `5.0e-7` | `5.0e-6` |
| **GRPO** | `1.0e-6` | `1.0e-5` |
| **Prompt Tuning** | N/A | `1.0e-2`에서 `3.0e-2`까지 |

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

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

## PEFT와 다양한 Trainer

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

### 지도 미세 조정(SFT)

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

#### LoRA를 사용하여

```bash
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 예제

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

### Direct Preference Optimization (DPO)

[DPOTrainer](/docs/trl/v1.18.2/ko/dpo_trainer#trl.DPOTrainer)는 인간 피드백을 통한 선호 학습을 구현합니다.

#### LoRA를 사용하여

```bash
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 예제

```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를 사용하여

```bash
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 예제

```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-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 구성과 결합하면 됩니다:

#### 명령줄

```bash
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](/docs/trl/v1.18.2/ko/sft_trainer#trl.SFTTrainer), [DPOTrainer](/docs/trl/v1.18.2/ko/dpo_trainer#trl.DPOTrainer), [GRPOTrainer](/docs/trl/v1.18.2/ko/grpo_trainer#trl.GRPOTrainer), [RLOOTrainer](/docs/trl/v1.18.2/ko/rloo_trainer#trl.RLOOTrainer)에서도 사용할 수 있습니다.

```python
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`는 메모리와 성능을 최적화하기 위한 여러 옵션을 제공합니다:

```python
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 양자화를 사용할 수 있습니다:

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

또는 명령줄을 통해:

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

```python
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

```python
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 구성

```python
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 Tuning | LoRA |
|---------|---------------|------|
| **학습된 매개변수** | ~0.001% | ~0.1-1% |
| **메모리 사용량** | 최소 | 낮음 |
| **학습 속도** | 가장 빠름 | 빠름 |
| **모델 수정** | None | 어댑터 레이어 |
| **적합한 용도** | 대형 모델, 다양한 작업 | 일반적인 파인튜닝 |
| **학습률** | 높음(1e-2 ~ 3e-2) | 표준 (1e-4 ~ 3e-4) |

## 고급 PEFT 구성

### LoRA 구성 매개변수

```python
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를 적용할 모듈을 지정할 수 있습니다. 일반적인 패턴:

```python
# 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 매개변수를 받습니다:

```bash
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 어댑터를 저장합니다:

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

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

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

### 로딩

추론을 위해 PEFT 모델을 로드합니다:

```python
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 어댑터를 쉽게 공유할 수 있습니다:

```python
# 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 지원과 완벽하게 호환됩니다:

```bash
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의 경우, 기본 모델은 자동으로 샤드됩니다:

```bash
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](https://huggingface.co/datasets/trl-lib/documentation-images/resolve/main/trl-npp.png)

**NPP 사용 방법**

`device_map`을 커스텀으로 지정하여 모델을 여러 디바이스에 나눠 로드하세요:

```python
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,
)
```

> [!IMPORTANT]
> - 오류를 방지하기 위해 `lm_head` 모듈을 첫 번째 GPU(device 0)에 유지하세요 - 올바른 구성에 대해서는 이 [device maps 튜토리얼](https://github.com/huggingface/blog/blob/main/accelerate-large-models.md)을 참조하세요 - 학습 스크립트를 직접 실행하세요(`torchrun` 사용 금지): `python script.py` - NPP에서는 Data Parallelism이 아직 지원되지 않습니다

## 리소스

### TRL 예제 및 노트북

- **[SFT with LoRA/QLoRA Notebook](https://github.com/huggingface/trl/blob/main/examples/sft_qlora/sft_qlora.ipynb)** - LoRA와 QLoRA 구현을 모두 보여주는 완전한 작동 예시
- **[TRL 예제 디렉터리](https://github.com/huggingface/trl/tree/main/examples)** - 다양한 트레이너를 활용한 PEFT를 보여주는 학습 스크립트 모음
- **[TRL Cookbook 레시피](https://github.com/huggingface/cookbook/tree/main/notebooks/transformers)** - 일반적인 PEFT 학습 시나리오에 대한 단계별 가이드

### 문서

- [PEFT 문서](https://huggingface.co/docs/peft) - 공식 PEFT 라이브러리 문서
- [TRL 문서](https://huggingface.co/docs/trl) - 트레이너 가이드가 포함된 TRL 전체 문서
- [후회 없는 LoRA](lora_without_regret) - LoRA를 효과적으로 사용하는 모범 사례

### 연구 논문

- [LoRA 논문](https://huggingface.co/papers/2106.09685) - 원본 LoRA 방법론 및 결과
- [QLoRA 논문](https://huggingface.co/papers/2305.14314) - 4비트 양자화를 활용한 효율적인 파인튜닝
- [Prompt Tuning 논문](https://huggingface.co/papers/2104.08691) - 매개변수 효율적 프롬프트 튜닝을 위한 규모의 힘

