Unsloth로 시작하는
나만의 AI 모델 만들기
파인튜닝, 어렵지 않습니다. 다만 설치가 어렵습니다. 이 워크북은 "설치 성공"이 아니라 "실패를 분해하는 능력"을 가르칩니다.
시작 전, 3가지 진실
이 세 문장을 받아들이지 못하면 오늘 진도를 못 나갑니다. 강의 시작 전 반드시 큰 소리로 읽고 가겠습니다.
지금 우리가 하는 건 "프로그램 설치"가 아니라 AI를 실행할 환경 자체를 만드는 작업입니다. Python, CUDA, PyTorch, 가상환경, 의존 패키지 — 이 모든 것이 서로 맞물려야 합니다. 한 번에 맞을 확률이 더 낮습니다.
에러 메시지는 컴퓨터가 여러분에게 보내는 편지입니다. 빨간 글씨에 겁먹지 말고 첫 줄만 읽으세요. 거의 모든 답이 거기에 있습니다.
좋은 데이터 100문장이 어설픈 데이터 10,000문장보다 좋은 모델을 만듭니다. 오늘 우리가 배울 기술의 본질은 "내 데이터로 AI를 다시 가르치는 것"이고, 그 핵심은 데이터 품질입니다.
Unsloth, 정체부터 정리합니다
유튜브와 블로그에서 본 정보가 헷갈리는 건 Unsloth가 두 얼굴이라 그렇습니다. 둘은 완전히 다른 도구입니다.
Unsloth (라이브러리)
- 파이썬 코드로 사용
- NVIDIA GPU 필수
- LoRA · QLoRA 학습 최적화
- 메모리 70% 절감, 속도 2배
- 오늘의 진짜 주인공
Unsloth Studio
- 설치형 챗봇 인터페이스
- CPU만 있어도 동작 (GGUF)
- 파인튜닝 기능은 보조적
- 인터넷 없이 사용 가능
- 망분리 환경에 적합
내 PC 진단부터 하겠습니다
이 진단 결과에 따라 두 갈래 길로 나뉩니다. 진단 없이 무작정 설치하면 1시간 뒤에 다시 처음으로 돌아옵니다.
진단 1 · NVIDIA GPU가 있는가
PowerShell을 열고 다음 명령을 입력합니다.
PS> nvidia-smi
NVIDIA-SMI 5xx.xx 형태의 표가 출력됨 → 길 B (로컬 설치)로 진행
- NVIDIA GPU가 있지만 드라이버가 없는 경우 → 드라이버 설치 후 재진단
- 아예 NVIDIA GPU가 없는 경우 → 길 A (Colab)로 진행
진단 2 · 진짜로 GPU가 있는지 확인
드라이버 문제인지 GPU 자체가 없는 건지 헷갈릴 때 씁니다.
PS> Get-CimInstance Win32_VideoController | Select-Object Name
NVIDIA GeForce ...가 나오면 → 드라이버 문제. nvidia.com에서 드라이버 재설치 (Custom + Clean Install 체크)
Intel Arc / Intel UHD / AMD Radeon만 나오면 → 외장 GPU 없음. 길 A (Colab)로 진행하세요. 이게 부끄러운 일이 아닙니다.
두 갈래 길, 어디로 갈까
길 A는 Colab, 길 B는 로컬 Windows. 처음 배우시는 분의 90%는 길 A로 가시는 게 정답입니다.
길 A · Google Colab
- 웹 브라우저만 있으면 됨
- 구글이 GPU 무료 제공
- 설치 90% 생략됨
- Unsloth 공식 노트북 그대로 사용
- 실패해도 PC가 안 망가짐
길 B · 로컬 Windows 설치
- 한 번 세팅하면 반복 사용 편함
- 데이터 외부 유출 없음
- 설치에 1 ~ 3시간 소요 가능
- 오류 케이스 7가지 이상 만남
- 오늘 워크북의 후반부 주제
길 A · Colab으로 첫 파인튜닝하기
설치 0줄. 코드 거의 안 만집니다. 데이터만 자기 것으로 바꾸면 끝납니다. 1시간 안에 첫 모델이 나옵니다.
Unsloth 공식 노트북 열기
구글에서 "unsloth notebook llama 3"으로 검색하거나, Unsloth 공식 깃허브의 노트북 링크를 클릭합니다. 클릭 한 번으로 Colab이 열립니다. 우리가 직접 코드를 짜는 게 아니라 이미 다 만들어진 코드를 빌려 쓰는 것입니다.
런타임을 GPU로 변경
Colab 상단 메뉴에서 런타임 → 런타임 유형 변경 → T4 GPU 선택. 무료입니다.
위에서부터 셀 하나씩 실행 (Shift + Enter)
맨 위 셀부터 차례대로 실행합니다. 첫 셀은 보통 !pip install unsloth 같은 설치 명령어인데, Colab에서는 이게 거의 무조건 성공합니다. 5 ~ 10분 정도 걸립니다.
데이터셋만 내 것으로 바꾸기 (오늘의 핵심)
노트북 안에 dataset = load_dataset("yahma/alpaca-cleaned") 같은 줄이 있습니다. 이걸 내 데이터로 바꾸면 됩니다. 데이터 형식은 다음과 같습니다.
{
"instruction": "농촌진흥청 보도자료를 작성해줘",
"input": "주제: 가을 배추 작황 호조",
"output": "농촌진흥청은 ○○일, 올 가을 배추..."
}
이런 항목을 50 ~ 500개 정도 모으면 충분히 의미 있는 파인튜닝이 됩니다. JSON 또는 CSV로 저장 후 Colab에 업로드합니다.
학습 실행 → 기다리기
Trainer 셀을 실행하면 학습이 시작됩니다. T4 GPU 기준 7B 모델 + 데이터 500개 = 약 30분 ~ 1시간. 화면에 loss(손실값)가 점점 줄어드는 게 보이면 정상입니다.
GGUF로 저장 → 내 PC에서 사용
마지막 셀에서 model.save_pretrained_gguf(...)를 실행합니다. 결과 파일을 다운로드한 뒤, 내 PC에서 Ollama 등으로 실행하면 인터넷 없이 내 모델을 사용할 수 있습니다.
길 B · 로컬 Windows 설치 (정공법)
NVIDIA GPU가 있고, 한 번 제대로 환경을 만들어두고 싶은 분을 위한 코스입니다. 7개의 단계와 9개의 흔한 오류가 기다립니다.
PowerShell을 관리자 권한으로 실행
시작 메뉴에서 PowerShell 검색 → 우클릭 → 관리자 권한으로 실행. 일반 PowerShell로 시작하면 절반 명령어가 막힙니다.
winget이 살아있는지 확인
PS> winget --version
Python 3.11 설치 (3.13 아닙니다)
PS> winget install -e --id Python.Python.3.11
설치 후 PowerShell 재시작 → python --version으로 확인.
uv 설치 (요즘 표준 패키지 매니저)
PS> winget install --id=astral-sh.uv -e
uv는 pip의 빠른 후계자입니다. PyTorch + CUDA를 자동으로 맞춰주기 때문에 충돌이 압도적으로 줄어듭니다.
가상환경 만들기 (이걸 빼먹으면 나중에 후회)
PS> uv venv unsloth_env --python 3.11 PS> unsloth_env\Scripts\activate
두 번째 명령 실행 후 줄 맨 앞에 (unsloth_env)가 붙으면 정상입니다.
Unsloth 설치
PS> uv pip install unsloth --torch-backend=auto
설치 중 CMake가 한참 뭔가를 빌드합니다. 5 ~ 15분 걸릴 수 있습니다. 멈춘 게 아닙니다.
설치 검증
PS> python -c "import torch; print(torch.cuda.is_available())"
첫 파인튜닝 코드 실행
Colab 노트북을 그대로 다운로드해서 로컬에서 돌릴 수 있습니다. 또는 Unsloth 공식 깃허브의 example 폴더에서 llama3_finetune.py 같은 파일을 받아 실행합니다. 이 부분은 길 A의 A4 ~ A6과 동일합니다.
자주 만나는 오류 9가지
현장 강의에서 100% 등장하는 오류만 추렸습니다. 빨간 줄 = 진짜 멘붕급, 노란 줄 = 흔함, 초록 줄 = 사실 정상.
| 증상 (에러 첫 줄) | 진짜 원인 | 대응 (한 가지만) |
|---|---|---|
winget not available |
App Installer가 없거나 별칭이 꺼짐 | 설정 → 앱 → 앱 실행 별칭 → "App Installer" ON. PowerShell 완전 재시작 |
No NVIDIA GPU detected |
GPU가 없거나 드라이버 미설치 | 정상 동작입니다. CPU 모드로 진행하거나 길 A(Colab)로 이동 |
nvidia-smi: 인식 안됨 |
드라이버 미설치 또는 GPU 자체 없음 | 진단 2로 GPU 존재 먼저 확인 → 있으면 드라이버 Clean Install |
ModuleNotFoundError: No module named 'structlog' |
Unsloth Studio 의존 패키지 일부 누락 | unsloth studio setup 실행. 안 되면 pip install structlog |
CMake가 한참 멈춰있음 |
정상 빌드 중 (오류 아님) | 아무것도 하지 말고 5 ~ 15분 기다리기. 화면에 글자가 흐르고 있으면 정상 |
failed to find compiler |
Visual C++ Build Tools 없음 | "Visual Studio Build Tools" 설치 → "C++ build tools" 워크로드 체크 |
torch.cuda.is_available() = False |
PyTorch가 CPU 버전으로 설치됨 | torch 제거 후 uv pip install torch --torch-backend=auto 재설치 |
CUDA out of memory |
모델이 GPU 메모리보다 큼 | batch_size를 1로, 더 작은 모델(7B → 3B)로, 또는 4-bit 양자화 옵션 켜기 |
Permission denied / Access denied |
관리자 권한 없음 또는 백신 차단 | PowerShell을 관리자 권한으로 재실행. 백신은 일시적으로 폴더 예외 추가 |
비개발자를 위한 핵심 개념 4가지
설치는 됐는데 무슨 말인지 하나도 모르겠다면 이 4개만 기억하면 됩니다.
이미 똑똑한 AI에게 우리 회사 말투를 가르치는 것
처음부터 AI를 만드는 게 아닙니다. 라마3 같은 베이스 모델 위에 우리 데이터로 추가 학습을 시키는 것입니다. 자녀에게 회사 매뉴얼만 따로 가르치는 것과 비슷합니다.
전체를 안 바꾸고 일부만 바꾸는 효율적 방법
모델 전체를 다시 학습하면 GPU가 100GB 필요합니다. LoRA는 모델의 핵심 부분만 살짝 바꿔서 8GB GPU로도 학습 가능하게 합니다. Unsloth가 빛나는 이유입니다.
"질문 → 우리가 원하는 답변" 모음집
instruction(지시) / input(맥락) / output(정답) 세 항목으로 구성된 JSON 묶음입니다. 50 ~ 500개로 시작하고, 품질이 양보다 중요합니다.
학습 끝난 모델을 가벼운 파일로 압축한 것
학습은 GPU에서 하고, 사용은 CPU에서도 가능하게 만들어주는 포맷입니다. 망분리 환경에서 활용할 때 핵심입니다. Ollama, LM Studio에서 바로 실행됩니다.
실습 마무리 체크리스트
워크북을 다 따라온 뒤, 자기 점검용으로 사용하세요. 한 항목이라도 비어 있으면 그 부분만 다시 돌아갑니다.
설치 / 환경 (길 B 진행자)
winget --version 정상 출력 확인python --version 확인unsloth_env 생성 후 활성화uv pip install unsloth 정상 완료torch.cuda.is_available() 결과가 True