문제 해결과 운영 체크리스트

마지막으로 성공한 지점부터 확인하기

Unsloth 문제 해결의 핵심은 "어디까지는 됐는가"를 먼저 찾는 것이다. 설치는 됐지만 모델 로드가 안 되는지, 학습은 끝났지만 답변이 이상한지, Unsloth에서는 정상인데 Ollama나 vLLM에서만 문제가 생기는지 구분해야 한다. 한 번에 여러 설정을 바꾸면 원인을 찾기 어렵다. 마지막으로 성공한 코드와 설정을 보관하고, 다음 단계에서 바뀐 값만 하나씩 확인한다.

AI 생성 이미지

설치와 다운로드 문제

설치 오류나 의존성 충돌이 보이면 먼저 Unsloth와 unsloth_zoo를 최신 상태로 강제 재설치한다.¹

pip install --upgrade --force-reinstall --no-cache-dir --no-deps unsloth unsloth_zoo

그래도 같은 문제가 반복되면 새 가상환경을 만들거나 공식 Docker 이미지를 쓰는 편이 빠르다. Docker는 CUDA, PyTorch, 주요 패키지가 맞춰진 환경에서 시작할 수 있어 "내 PC 설정 문제"와 "코드 문제"를 분리하는 데 좋다.

모델 다운로드가 90~95%에서 멈추거나 오류 메시지가 불명확하면 안정 다운로드 모드를 켠다. 반드시 Unsloth를 import하기 전에 설정해야 한다.

import os
os.environ["UNSLOTH_STABLE_DOWNLOADS"] = "1"
from unsloth import FastLanguageModel

이 모드는 느릴 수 있지만 동기식으로 다운로드를 진행하고 더 자세한 오류를 보여 준다. 네트워크, 저장 공간, 권한 문제를 확인하기 쉽다.

CUDA와 모델 로드 오류

CUDA out of memory, CUDA runtime error, 모델 로드 실패가 나오면 먼저 GPU 상태를 본다.

nvidia-smi

남은 VRAM이 부족하면 per_device_train_batch_size를 줄이고, max_seq_length를 낮추고, load_in_4bit=True로 QLoRA 로딩을 사용한다. 그래도 부족하면 더 작은 모델로 재현한다. 중요한 것은 "가장 작은 설정에서도 실패하는가"를 확인하는 것이다.

드라이버, CUDA, PyTorch 버전이 맞지 않아도 같은 증상이 난다. 특히 새 GPU나 최신 모델을 쓸 때는 공식 설치 절차를 다시 확인한다. Transformers가 지원하는 모델이라도 일부 모델은 trust_remote_code=True가 필요할 수 있다. 특정 모델에서 가중치 초기화 경고가 치명적으로 보이면 Unsloth뿐 아니라 transformers, timm도 함께 업데이트한다.¹

학습은 됐지만 답변이 나쁠 때

학습 loss가 내려갔는데 답변 품질이 낮다면 설정을 바꾸기 전에 데이터를 본다. 중복 샘플이 많지 않은지, 정답이 틀리지 않았는지, instruction과 response가 뒤바뀌지 않았는지 확인한다. chat format을 썼다면 학습 때의 chat template과 추론 때의 template이 같아야 한다.

EOS 토큰도 중요하다. EOS는 답변의 끝을 알려 주는 표시다. 학습 데이터 끝에 EOS가 빠지면 모델이 멈추지 않고 계속 말할 수 있다. 반대로 잘못된 위치에 들어가면 답변이 너무 짧아질 수 있다.

train_on_responses_only를 썼는데 loss가 항상 0에 가깝다면 라벨이 모두 -100으로 처리된 경우를 의심한다. 이때는 모델이 실제 답변을 학습하지 못한다. 평가 데이터는 학습 데이터와 분리하고, 순서 편향을 막기 위해 shuffle한다. 평가가 너무 느리면 eval_steps=1처럼 지나치게 잦은 평가를 피하고, 평가 샘플을 100개 안팎으로 줄여 먼저 확인한다.¹

내보낸 뒤 품질이 무너질 때

Unsloth 안에서는 정상인데 Ollama, llama.cpp, vLLM에서 횡설수설하거나 무한 생성, 반복 출력이 생기면 가장 먼저 chat template을 의심한다. 공식 문서에서도 내보낸 모델의 품질 저하 원인으로 잘못된 chat template을 가장 흔하게 지적한다.²

학습 때 사용한 system, user, assistant 구조를 추론 환경에서도 그대로 써야 한다. EOS 토큰, stop token, BOS 토큰 추가 여부도 함께 맞춘다. 어떤 실행 엔진은 시작 토큰을 자동으로 붙이고, 어떤 엔진은 붙이지 않는다. 이 차이만으로도 긴 응답에서 품질이 크게 흔들릴 수 있다.

운영 체크리스트

프로젝트마다 다음 항목을 기록한다. 재현성은 운영 품질이다.

• OS와 실행 환경: Windows, Linux, WSL, macOS, Docker 여부

• GPU 이름, VRAM, 드라이버, CUDA, PyTorch 버전

• Unsloth, unsloth_zoo, Transformers 버전

• 설치 방식: pip, uv, Studio, Docker

• base model 이름과 리비전

• 데이터셋 버전, 정제 규칙, 제외한 데이터 기준

• chat template, instruction 포맷, EOS 토큰 처리 방식

• LoRA rank, learning rate, epoch, batch size, max sequence length

• 저장 형식: LoRA adapter, merged 16bit, GGUF, safetensors

• 평가 프롬프트, 실패 사례, 개선 전후 비교 결과

• 배포 환경: Ollama, llama.cpp, vLLM, OpenAI 호환 API

• 로그 저장 위치, 접근 권한, 실패 대화 재학습 절차

Unsloth Studio와 Core는 Windows, Linux, WSL, macOS, Docker 등 여러 환경에서 사용할 수 있다. 환경 선택지가 많을수록 기록이 더 중요하다.³ 문제 해결은 감으로 하는 일이 아니다. 같은 입력, 같은 모델, 같은 템플릿, 같은 실행 환경을 다시 만들 수 있으면 대부분의 오류는 추적할 수 있다.

참고

¹Troubleshooting & FAQs | Unsloth Documentation

²Troubleshooting Inference | Unsloth Documentation

³Unsloth GitHub Repository