TRL documentation
후회 없는 LoRA
후회 없는 LoRA
Thinking Machines Lab 팀의 최근 연구(Schulman et al., 2025)에 따르면, LoRA는 올바르게 구성하면 전체 파인튜닝과 동등한 성능을 달성할 수 있으며, 이때 사용되는 컴퓨트 양은 약 67%에 불과합니다. 이러한 결과는 TRL 사용자에게 매우 흥미롭습니다. 구현이 간단할 뿐만 아니라, 더 적은 예산으로도 모델 성능을 향상시킬 수 있기 때문입니다.
이 가이드는 TRL에서 블로그 게시물의 결과를 재현하는 간단한 방법을 안내합니다.
이 가이드를 따르기 전에 블로그 게시물을 먼저 읽거나, 최적의 결과를 위해 두 자료를 병렬로 참고하는 것이 좋습니다.
LoRA의 전체 파인튜닝 대비 장점
먼저, LoRA가 전체 파인튜닝보다 갖는 이점을 상기해 보겠습니다.
LoRA는 베이스 모델 위에 어댑터 레이어를 추가하며, 이 어댑터는 베이스 모델 자체보다 훨씬 적은 파라미터를 포함합니다. 이러한 설계는 GPU 메모리 요구 사항을 줄이고 더 효율적인 학습을 가능하게 합니다. 블로그에서 설명한 바와 같이, 이 접근 방식은 원래 성능 트레이드오프가 수반되는 것으로 여겨졌지만, 세심한 구성을 통해 이러한 트레이드오프를 극복하고 전체 파인튜닝 성능에 맞출 수 있습니다.
TRL을 사용한 예제
블로그 포스트의 핵심 발견을 바탕으로 TRL 스크립트에서 LoRA 어댑터를 구현하고 학습해 보겠습니다. 이후 TRL 결과를 바탕으로 각 발견을 다시 살펴볼 것입니다.
지도 미세 조정(SFT)
블로그 포스트에서는 Hub의 다양한 모델과 데이터셋에 대해 SFT를 수행하며, 이를 TRL에서 재현할 수 있습니다.
이러한 결과를 TRL Python API에 다음과 같이 통합할 수 있습니다:
from datasets import load_dataset
from peft import LoraConfig
from trl import SFTTrainer, SFTConfig
dataset = load_dataset("open-thoughts/OpenThoughts-114k", split="train")
peft_config = LoraConfig(r=256, lora_alpha=16, target_modules="all-linear")
training_args = SFTConfig(
learning_rate=2e-4,
per_device_train_batch_size=1,
gradient_accumulation_steps=4,
num_train_epochs=1,
report_to=["trackio"],
)
trainer = SFTTrainer(
model="Qwen/Qwen2.5-3B-Instruct",
train_dataset=dataset,
peft_config=peft_config,
args=training_args,
)
trainer.train()
hf jobs uv run \
--flavor a100-large \
--timeout 8h \
--secrets HF_TOKEN \
"https://raw.githubusercontent.com/huggingface/trl/main/trl/scripts/sft.py" \
--model_name_or_path Qwen/Qwen2.5-3B-Instruct \
--dataset_name open-thoughts/OpenThoughts-114k \
--learning_rate 2.0e-5 \
--num_train_epochs 1 \
--packing \
--per_device_train_batch_size 2 \
--gradient_accumulation_steps 16 \
--use_peft \
--lora_r 256 \
--lora_alpha 16 \
--lora_target_modules all-linear \
--output_dir Qwen2.5-3B-OpenThoughts-LoRA \
--report_to trackio \
--push_to_hub
Hugging Face Jobs를 사용하려면 Hub에 로그인(hf auth login)하고 크레딧 잔액이 양수여야 합니다. 자세한 내용은 Jobs 문서를 참고하세요.
uv run "https://raw.githubusercontent.com/huggingface/trl/main/trl/scripts/sft.py" \
--model_name_or_path Qwen/Qwen2.5-3B-Instruct \
--dataset_name open-thoughts/OpenThoughts-114k \
--learning_rate 2.0e-5 \
--num_train_epochs 1 \
--packing \
--per_device_train_batch_size 2 \
--gradient_accumulation_steps 16 \
--eval_strategy no \
--use_peft \
--lora_r 256 \
--lora_alpha 16 \
--lora_target_modules all-linear \
--output_dir Qwen2.5-3B-OpenThoughts-LoRA \
--report_to trackio \
--push_to_hub
스크립트를 로컬에서 실행하려면 uv가 설치되어 있어야 합니다. 자세한 내용은 uv 문서를 참고하세요.
학습이 시작되면 URL을 기록하는 Trackio에서 진행 상황을 모니터링할 수 있습니다.
강화 학습(GRPO)
블로그 포스트에서는 Hub의 다양한 모델과 데이터셋에 대해 GRPO를 수행하며, TRL에서도 결과를 재현할 수 있습니다.
| 모델 | 데이터셋 |
|---|---|
| Llama-3.1-8B-Base | GSM8k |
| Llama-3.1-8B-Base | DeepMath-103K |
| Qwen3-8b-base | DeepMath-103K |
강화 학습을 위해, 이 블로그는 Python 함수로 재현할 수 있는 수학 추론 작업을 사용합니다.
이러한 권장 사항을 TRL Python API를 사용하여 다음과 같이 구현할 수 있습니다:
from datasets import load_dataset
from peft import LoraConfig
from trl import GRPOConfig, GRPOTrainer
from trl.rewards import reasoning_accuracy_reward
dataset = load_dataset("HuggingFaceH4/OpenR1-Math-220k-default-verified", split="train")
peft_config = LoraConfig(
r=1,
lora_alpha=32,
target_modules="all-linear"
)
training_args = GRPOConfig(
learning_rate=5e-5,
per_device_train_batch_size=1,
gradient_accumulation_steps=4,
num_train_epochs=1,
num_generations=8,
generation_batch_size=8,
report_to=["trackio"],
)
trainer = GRPOTrainer(
model="Qwen/Qwen3-0.6B",
reward_funcs=reasoning_accuracy_reward,
args=training_args,
train_dataset=dataset,
peft_config=peft_config,
)
trainer.train()
이 스니펫은 예시를 간결하게 유지하기 위해 위에서 정의된 보상 함수를 생략합니다.
hf jobs uv run \
--flavor a100-large \
--timeout 4h \
--secrets HF_TOKEN \
--env PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True \
"https://huggingface.co/datasets/burtenshaw/lora-without-regrets/resolve/main/grpo.py" \
--model_name_or_path Qwen/Qwen3-0.6B \
--dataset_name HuggingFaceH4/OpenR1-Math-220k-default-verified \
--output_dir grpo-full-qwen3-0.6b \
--learning_rate 1.0e-6 \
--lr_scheduler_type cosine \
--warmup_steps 0.0 \
--max_grad_norm 1.0 \
--beta 0.0 \
--max_completion_length 4096 \
--num_generations 16 \
--generation_batch_size 16 \
--gradient_accumulation_steps 8 \
--per_device_train_batch_size 1 \
--num_train_epochs 1 \
--lora_r 1 \
--lora_alpha 32 \
--lora_dropout 0.0 \
--lora_target_modules all-linear \
--vllm_mode colocate \
--save_strategy steps \
--save_steps 50 \
--save_total_limit 1 \
--logging_steps 1 \
--max_steps 200 \
--report_to trackioHugging Face Jobs를 사용하려면 Hub에 로그인(hf auth login)하고 크레딧 잔액이 양수여야 합니다. 자세한 내용은 Jobs 문서를 참고하세요.
uv run "https://huggingface.co/datasets/burtenshaw/lora-without-regrets/resolve/main/grpo.py" \
--model_name_or_path Qwen/Qwen3-0.6B \
--dataset_name HuggingFaceH4/OpenR1-Math-220k-default-verified \
--output_dir grpo-full-qwen3-0.6b \
--learning_rate 1.0e-6 \
--lr_scheduler_type cosine \
--warmup_steps 0.0 \
--max_grad_norm 1.0 \
--beta 0.0 \
--max_completion_length 4096 \
--num_generations 16 \
--generation_batch_size 16 \
--gradient_accumulation_steps 8 \
--per_device_train_batch_size 1 \
--num_train_epochs 1 \
--lora_r 1 \
--lora_alpha 32 \
--lora_dropout 0.0 \
--lora_target_modules all-linear \
--vllm_mode colocate \
--save_strategy steps \
--save_steps 50 \
--save_total_limit 1 \
--logging_steps 1 \
--max_steps 200 \
--report_to trackio스크립트를 로컬에서 실행하려면 uv가 설치되어 있어야 합니다. 자세한 내용은 uv 문서를 참고하세요.
GRPO를 사용한 강화 학습 스크립트는 TRL에서 커스텀 스크립트로 구현되며, 위에서 보여준 보상 함수를 사용합니다. grpo.py - LoRA를 활용한 강화 학습 모범 사례에서 이를 검토할 수 있습니다.
LoRA 최적화의 주요 결과
저자들은 랭크를 높여도 이 제한을 보상할 수 없으므로, 어텐션 레이어에만 LoRA를 적용하는 것이 아니라 모든 가중치 행렬에 LoRA를 적용하는 것을 권장합니다. TRL에서는 --lora_target_modules all-linear를 사용하여 모든 가중치 행렬에 LoRA를 적용하도록 설정할 수 있습니다.
TRL과 SmolLM3 모델을 사용하여 블로그 게시물의 결과를 재현했습니다. 위의 보상 함수와 구성을 사용하여 Math 220k 데이터셋에서 모델을 500단계 동안 학습했습니다. 아래 그림에서 볼 수 있듯이, LoRA 모델의 평균 학습 보상 곡선이 전체 미세 조정 곡선과 일치합니다.

그리고 가장 중요한 점은, 아래 그림에서 볼 수 있듯이 LoRA 모델이 전체 파인튜닝 모델보다 훨씬 적은 메모리를 사용한다는 것입니다.

…
| 매개변수 | LoRA | 전체 FT |
|---|---|---|
--model_name_or_path | HuggingFaceTB/SmolLM3-3B | HuggingFaceTB/SmolLM3-3B |
--dataset_name | HuggingFaceH4/OpenR1-Math-220k-default-verified | HuggingFaceH4/OpenR1-Math-220k-default-verified |
--learning_rate | 1.0e-5 | 1.0e-6 |
--max_completion_length | 4096 | 4096 |
--lora_r | 1 | - |
--lora_alpha | 32 | - |
--lora_dropout | 0.0 | - |
--lora_target_modules | all-linear | - |
블로그 게시물의 주요 발견 사항과 이를 재현할 수 있었던 방법을 살펴봅시다.
1. LoRA는 모든 가중치 행렬에 적용할 때 더 나은 성능을 보입니다
저자들은 랭크를 높여도 이 제한을 보상할 수 없으므로, LoRA를 어텐션 레이어에만 적용하는 것이 아니라 모든 가중치 행렬에 적용하는 것을 권장합니다.

Attention-only LoRA는 매개변수 수를 맞추기 위해 더 높은 rank를 사용하더라도 성능이 떨어집니다. TRL에서는 --lora_target_modules all-linear를 사용하여 모든 가중치 행렬에 LoRA를 적용하도록 설정할 수 있습니다. Python에서는 다음과 같이 수행할 수 있습니다:
from peft import LoraConfig
peft_config = LoraConfig(target_modules="all-linear") 2. 어댑터는 데이터셋에서 학습하기에 충분한 용량이 필요합니다
블로그 게시물에서는 데이터셋에서 학습하기 위해 충분한 LoRA 랭크를 사용하는 것을 권장합니다. 랭크는 LoRA 어댑터의 학습 가능 매개변수 수를 결정합니다. 따라서 “LoRA 용량을 초과하는 데이터셋의 경우, LoRA는 FullFT보다 성능이 떨어집니다”.

TRL 스크립트에서는 --lora_r를 사용해 랭크를 설정할 수 있으며, 학습하는 작업과 데이터셋에 따라 이를 조정할 수 있습니다. 해당 블로그 포스트에서는 작업과 데이터셋 크기에 따라 다음과 같은 랭크를 권장합니다:
강화 학습 작업은 일반적으로 더 낮은 용량이 필요하므로 더 작은 LoRA 랭크를 사용할 수 있습니다. 이는 정책 기울기 알고리즘이 에피소드당 대략 ~1비트의 정보를 추출하므로 최소한의 매개변수 용량만 요구하기 때문입니다.
블로그 포스트에서는 LoRA의 이상적인 데이터셋 크기를 완전한 파인튜닝과 일치시키기 위한 “Post-training scale”로 정의합니다. 이를 사용하여 SFT 및 RL LoRA의 권장 랭크를 다음과 같이 결정할 수 있습니다:
| 작업 유형 | 데이터셋 크기 | 권장 랭크 |
|---|---|---|
| SFT | Post-training 규모 | 256 |
| RL | 모든 크기 | 1-32 |
3. “FullFT와 고-rank LoRA는 유사한 학습 곡선을 보입니다”
직관적으로 생각하면 반대이지만, 해당 블로그 포스트에서는 전체 파인튜닝보다 더 높은 학습률을 사용하는 것을 권장합니다. 위 표에서는 LoRA에 1.0e-5, 전체 파인튜닝에 1.0e-6을 사용했습니다. TRL 스크립트에서는 --learning_rate 을 사용하여 학습률을 설정할 수 있습니다. LoRA의 스케일링 덕분에 최적의 학습률은 랭크에 거의 독립적입니다.

4. “일부 시나리오에서는 LoRA가 전체 파인튜닝보다 큰 배치 크기에 덜 관용적입니다.”
블로그 게시물에서는 저자들이 LoRA가 큰 배치 크기에 덜 허용적임을 발견했기 때문에, 유효 배치 크기를 < 32로 사용하는 것을 권장합니다. 이는 LoRA 랭크를 증가시켜 완화할 수 없었습니다. TRL 스크립트에서는 --per_device_train_batch_size와 --gradient_accumulation_steps를 사용하여 배치 크기를 설정할 수 있습니다.

요약
TRL을 사용하면 FullFT의 높은 컴퓨트 비용 없이 핵심 인사이트(모든 가중치 행렬을 대상으로 설정, 적절한 랭크 선택, 배치 크기 및 학습률 관리)를 적용하여 전체 미세 조정 성능에 부합하는 LoRA 어댑터를 효율적으로 구현할 수 있습니다.
인용
@article{schulman2025lora,
title = {{LoRA Without Regret}},
author = {John Schulman and Thinking Machines Lab},
year = 2025,
journal = {Thinking Machines Lab: Connectionism},
doi = {10.64434/tml.20250929},
note = {https://thinkingmachines.ai/blog/lora/}
}