3분
Day 1 자주 빠지는 함정: 환경 설정과 모듈 이름
파인튜닝 개요 & LoRA/QLoRA
Day 1 자주 빠지는 함정: 환경 설정과 모듈 이름
QLoRA 파인튜닝 > 파인튜닝 개요 & LoRA/QLoRA
학습 목표
- 파인튜닝 환경 설정 시 흔한 실수를 사전에 방지한다
- GPU 메모리 부족 문제의 원인과 해결책을 안다
- target_modules가 틀려도 오류가 나지 않는 경우를 알고, 붙은 모듈 수로 검증한다
Day 1 자주 빠지는 함정
Pitfall 1: "GPU가 있는데 CUDA가 안 된다"
증상: torch.cuda.is_available() -> False
원인 TOP 3:
1. PyTorch CPU 버전 설치됨
-> pip install torch --index-url https://download.pytorch.org/whl/cu121
2. CUDA 드라이버 버전 불일치
-> nvidia-smi 로 드라이버 확인
-> PyTorch CUDA 버전과 맞추기
3. Colab에서 런타임 GPU 미설정
-> 런타임 > 런타임 유형 변경 > GPUPitfall 2: "모델 로드 시 OOM (Out of Memory)"
증상: CUDA out of memory
원인: 8GB GPU에 7B 모델 FP16 로드 시도 (14GB 필요)
해결:
1. BitsAndBytesConfig로 4비트 로드 (4GB로 줄어듦)
2. 더 작은 모델 사용
- microsoft/Phi-4-mini-instruct (3.8B) <- 이 주의 표준 모델
- Qwen/Qwen2.5-3B-Instruct (약 3.1B, 승인 절차 없음)
주의: Phi-4는 14B이고 Phi-4-mini는 3.8B다. 이름이 비슷하니 확인하고 쓴다.
3. 배치 크기와 시퀀스 길이를 줄인다 (활성화가 여기에 비례한다)
4. device_map="auto" 설정 (GPU + CPU 자동 분배, 다만 CPU로 내려간 층은 매우 느리다)Pitfall 3: "bitsandbytes 설치 에러"
증상: ImportError: cannot import name 'BitsAndBytesConfig'
해결 (Linux/Colab):
pip install -q bitsandbytes
해결 (Windows):
# Windows는 공식 bitsandbytes 지원 제한적
pip install bitsandbytes-windows
# 또는 WSL2 사용 권장
해결 (Mac M1/M2 이상):
# bitsandbytes는 CUDA 전용이라 맥에서 4비트 로딩이 되지 않는다.
# 무료 Colab T4로 옮기면 이 주의 실습은 전부 돈다. 결제는 필요 없다.
# Colab도 쓸 수 없으면 실습 instructions의 「GPU 없는 학습자의 경로」를 따른다.
# Day 2 데이터·Day 4 평가·Day 4 Ollama 배포는 맥에서 그대로 돌아간다.Pitfall 4: "target_modules가 틀려도 에러가 안 난다" -- 이 주에서 가장 위험한 함정
에러가 나는 경우 (차라리 나은 쪽):
ValueError: Target modules ... not found in the base model
-> 지정한 이름이 하나도 안 맞을 때만 이 오류가 난다.
에러가 나지 않는 경우 (위험한 쪽):
네 개를 적었는데 그중 하나만 맞으면, PEFT는 나머지 셋을 조용히 무시하고 통과한다.
학습은 그대로 돌아가고 Loss도 떨어진다. 아무도 알려 주지 않는다.
실제 사례: Phi-4-mini에 ["q_proj","k_proj","v_proj","o_proj"]를 지정하면
o_proj 하나만 걸려 32개 모듈 · 3,145,728개(0.0819%)가 학습된다.
어텐션의 Q·K·V에는 어댑터가 하나도 붙지 않은 채로 학습이 끝난다.확인 방법 (두 단계를 다 한다)
# 1. 어댑터를 붙이기 전: 이 모델의 선형 모듈 이름을 뽑는다
# 4비트 모델의 선형층은 Linear4bit 이라 nn.Linear로만 거르면 놓친다
print(sorted({
name.split(".")[-1]
for name, module in model.named_modules()
if module.__class__.__name__.startswith("Linear")
}))
# 2. 어댑터를 붙인 뒤: 실제로 몇 개에 붙었는지 센다
targeted = model.base_model.targeted_module_names
print(len(targeted), sorted({t.split('.')[-1] for t in targeted}))
assert len(targeted) == 4 * model.config.num_hidden_layers모델별 레이어 이름 (직접 확인한 것과 그렇지 않은 것을 구분해 적는다):
- Phi-4-mini: qkv_proj, o_proj, gate_up_proj, down_proj <- 저장소에서 확인함
Q·K·V가 하나로 합쳐져 있고 MLP의 gate·up도 하나로 합쳐져 있다
- Qwen2.5: q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj <- 확인함
- Mistral: q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj <- 확인함
- Llama·Gemma: q_proj, k_proj, v_proj, o_proj 계열로 알려져 있으나
저장소가 승인제라 여기서 확인하지 못했다. 반드시 위 코드로 직접 뽑아 쓴다.
확실한 방법이 하나 더 있다: target_modules="all-linear"
이름을 몰라도 모든 선형층에 붙는다. 대신 학습 파라미터가 늘어난다.Pitfall 5: "r을 크게 하면 무조건 좋은가?"
r이 크면:
+ 더 복잡한 패턴 학습 가능
- 과적합 위험 증가
- 메모리/시간 더 필요
- 일반화 능력 감소 가능
권장:
r=8: 간단한 스타일 변경 (어조, 형식)
r=16: 도메인 지식 + 전문 용어 (제조 AI 표준)
r=32: 복잡한 추론 능력 변경 (번역, 코드 생성)
r=64: Full Fine-tuning에 가까운 효과 (주의 필요)AI로 학습하기 — 꿀팁
QLoRA 환경 설정 오류 체크리스트AI 학습 팁
파인튜닝 환경 구성 시 CUDA 버전, bitsandbytes 호환성, 토큰 길이 등 초보자 함정을 체크리스트로 미리 정리해 두면 디버깅 시간을 크게 줄일 수 있습니다.
QLoRA 학습 환경(Google Colab T4 또는 로컬 16GB GPU)을 처음 설정할 때 발생하는 상위 10개 오류를 체크리스트로 만들어줘. 각 항목: 오류 증상(에러 메시지 키워드) / 원인 / 해결 명령어 또는 코드 스니펫. 특히 bitsandbytes 버전 충돌, CUDA 11/12 불일치, max_seq_length와 GPU 메모리 OOM 관계, tokenizer padding 방향 오류를 반드시 포함해줘.
이 팁이 도움이 됐나요?
핵심 포인트
- • CUDA 환경: PyTorch GPU 버전 + 드라이버 일치 필수
- • OOM: BitsAndBytesConfig 4비트 + device_map="auto"
- • target_modules: 하나라도 맞으면 PEFT는 조용히 통과한다. 붙은 모듈 수를 세어 검증해야 한다
- • r 값: 제조 도메인은 r=16이 표준, 무조건 크게 하면 과적합