> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baeum.ai.kr/llms.txt
> Use this file to discover all available pages before exploring further.
# llm-finetune
> SFT, LoRA, QLoRA 기반 LLM 파인튜닝 실험 환경입니다.
## 문서 기준
* 기준일: `2026-02-23`
* Python: `3.12`
* 운영체제: macOS, Ubuntu, Windows
* 동기화 명령: `uv sync`
## 호환성 메모
| 환경 | unsloth | xformers | 설명 |
| -------------- | ------- | -------- | ----------------------- |
| 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 데이터셋 포맷 |
| `peft` | LoRA/QLoRA 어댑터 관리 | 파라미터 효율적 파인튜닝 |
| `trl` | SFT/RLHF/DPO 학습 루프 | `SFTTrainer`, `DPOTrainer` 등 |
| `accelerate` | 분산 학습 및 mixed precision | DeepSpeed, FSDP 연동 |
| `bitsandbytes` | 4/8bit 양자화 | QLoRA의 기반 양자화 엔진 |
| `xformers` | 메모리 효율 Attention | FlashAttention 대체 |
| `unsloth` | 파인튜닝 최적화 | 2배 속도, 60% 메모리 절감 (Linux 전용) |
| `sentencepiece` / `safetensors` | 토크나이저 / 모델 직렬화 | LLaMA 계열 필수 |
## pyproject.toml
```toml theme={null}
[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
```
## 설치
```bash theme={null}
uv init llm-finetune
cd llm-finetune
```
```bash theme={null}
uv lock
uv sync
```
```bash theme={null}
uv run python -m ipykernel install --user --name llm-finetune --display-name "UV llm-finetune"
```
## 설치 확인
모든 OS 공통 확인:
```bash theme={null}
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 추가 확인:
```bash theme={null}
uv run python -c "import unsloth; print('unsloth', unsloth.__version__)"
```
## 기본 사용 예시
TRL의 `SFTTrainer`를 이용한 QLoRA 파인튜닝 기본 구조입니다.
```python theme={null}
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 `RecursionError` | `datasets >= 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 사용 |
## 설치 점검 목록
* 관리자 권한/필수 도구 등 사전 요구사항을 먼저 확인했습니다.
* 설치 후 버전 확인 명령어(`--version`)를 실행해 정상 설치를 검증했습니다.
* PATH/환경변수 변경이 필요한 경우 터미널을 다시 열어 적용 여부를 확인했습니다.
* 문제가 생겼을 때를 대비해 설치 로그 또는 스크린샷을 남겼습니다.
## 관련 문서
운영체제별 설치 흐름을 다시 확인합니다.
다음 설치 단계를 이어서 진행합니다.