Skip to main content

​
llm-finetune

SFT, LoRA, QLoRA 기반 LLM 파인튜닝 실험 환경입니다.

​
문서 기준

  • 기준일: 2026-02-23
  • Python: 3.12
  • 운영체제: macOS, Ubuntu, Windows
  • 동기화 명령: uv sync

​
호환성 메모

환경unslothxformers설명
Ubuntu x86_64설치됨설치됨전체 스택 (GPU 파인튜닝 가능)
Windows제외됨설치됨unsloth 미지원, 나머지 동기화 가능
macOS제외됨제외됨CPU/MPS 기반 소규모 실험 가능
unsloth은 datasets==4.3.0 에서만 안정적으로 동작합니다. datasets 4.5.0 이상에서는 재귀 오류가 발생하므로 버전을 변경하지 마세요.

​
파인튜닝 방법 비교

방법VRAM 요구학습 파라미터속도적합한 상황
Full Fine-Tuning매우 높음 (>40GB)모델 전체느림충분한 GPU, 대규모 데이터
LoRA중간 (~16GB)Adapter만보통범용 파인튜닝
QLoRA낮음 (~8GB)4bit 양자화 + Adapter빠름단일 GPU, 제한된 VRAM
단일 RTX 3090 (24GB)에서는 7B 모델 기준 QLoRA를 권장합니다. unsloth을 사용하면 추가로 2배 속도 향상을 기대할 수 있습니다.

​
주요 패키지 역할

패키지역할비고
transformers모델 로딩 및 토크나이저HuggingFace 모델 허브 연동
datasets학습 데이터 로딩 및 전처리HuggingFace 데이터셋 포맷
peftLoRA/QLoRA 어댑터 관리파라미터 효율적 파인튜닝
trlSFT/RLHF/DPO 학습 루프SFTTrainer, DPOTrainer 등
accelerate분산 학습 및 mixed precisionDeepSpeed, FSDP 연동
bitsandbytes4/8bit 양자화QLoRA의 기반 양자화 엔진
xformers메모리 효율 AttentionFlashAttention 대체
unsloth파인튜닝 최적화2배 속도, 60% 메모리 절감 (Linux 전용)
sentencepiece / safetensors토크나이저 / 모델 직렬화LLaMA 계열 필수

​
pyproject.toml

[project]
name = "llm-finetune"
version = "0.1.0"
description = "LLM fine-tuning environment"
requires-python = "==3.12.*"
dependencies = [
  "torch==2.10.0",
  "torchvision==0.25.0",
  "torchaudio==2.10.0",
  "transformers==4.57.6",
  "datasets==4.3.0",
  "accelerate==1.12.0",
  "peft==0.18.1",
  "trl==0.24.0",
  "bitsandbytes==0.49.2",
  "xformers==0.0.35; platform_system != 'Darwin'",
  "unsloth==2026.2.1; platform_system == 'Linux' and platform_machine == 'x86_64'",
  "sentencepiece==0.2.1",
  "safetensors==0.7.0",
  "ipykernel==7.2.0",
  "pytest==9.0.2",
  "ruff==0.15.2",
]

[tool.uv]
package = false

​
설치

1

프로젝트 생성

uv init llm-finetune
cd llm-finetune
2

의존성 락 및 동기화

uv lock
uv sync
3

Jupyter 커널 등록

uv run python -m ipykernel install --user --name llm-finetune --display-name "UV llm-finetune"

​
설치 확인

모든 OS 공통 확인: 
uv run python -c "import torch, transformers, peft, trl, datasets; print('torch', torch.__version__); print('transformers', transformers.__version__); print('trl', trl.__version__); print('cuda', torch.cuda.is_available())"
Ubuntu x86_64 추가 확인: 
uv run python -c "import unsloth; print('unsloth', unsloth.__version__)"

​
기본 사용 예시

TRL의 SFTTrainer를 이용한 QLoRA 파인튜닝 기본 구조입니다. 
from transformers import AutoTokenizer, AutoModelForCausalLM, BitsAndBytesConfig
from peft import LoraConfig
from trl import SFTTrainer, SFTConfig
from datasets import load_dataset

# 1) 4bit 양자화 설정
bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_compute_dtype="bfloat16",
)

# 2) 모델 및 토크나이저 로딩
model_id = "meta-llama/Llama-3.1-8B-Instruct"
model = AutoModelForCausalLM.from_pretrained(model_id, quantization_config=bnb_config)
tokenizer = AutoTokenizer.from_pretrained(model_id)

# 3) LoRA 어댑터 설정
lora_config = LoraConfig(r=16, lora_alpha=32, target_modules=["q_proj", "v_proj"], lora_dropout=0.05)

# 4) 데이터셋 준비
dataset = load_dataset("json", data_files="train.jsonl", split="train")

# 5) SFT 학습
trainer = SFTTrainer(
    model=model,
    train_dataset=dataset,
    peft_config=lora_config,
    args=SFTConfig(output_dir="./output", num_train_epochs=3, per_device_train_batch_size=4),
    tokenizer=tokenizer,
)
trainer.train()
trainer.save_model("./output/final")

​
트러블슈팅

증상원인해결
bitsandbytes import 오류CUDA/드라이버 버전 불일치nvidia-smi와 nvcc --version 확인
CUDA OOM (Out of Memory)배치 크기 또는 시퀀스 길이 초과batch size 줄이기, gradient_checkpointing=True
unsloth RecursionErrordatasets >= 4.5.0 사용datasets==4.3.0 고정 확인
학습 loss가 감소하지 않음learning rate 또는 데이터 품질 문제lr 조정 (1e-4 ~ 5e-5), 데이터 검수
uv sync 의존성 충돌기존 락 파일과 버전 불일치uv lock --refresh 후 uv sync
macOS에서 xformers 미설치환경 마커로 의도적 제외MPS 백엔드 기본 Attention 사용