CDSA | 홈페이지 블로그 프레임워크 워크북
CDSA · 비개발자 실습 워크북

Unsloth로 시작하는
나만의 AI 모델 만들기

파인튜닝, 어렵지 않습니다. 다만 설치가 어렵습니다. 이 워크북은 "설치 성공"이 아니라 "실패를 분해하는 능력"을 가르칩니다.

대상
비개발자 · 입문자
소요 시간
2 ~ 4 시간
준비물
윈도우 PC · 인터넷 · 인내심
SECTION 01

시작 전, 3가지 진실

이 세 문장을 받아들이지 못하면 오늘 진도를 못 나갑니다. 강의 시작 전 반드시 큰 소리로 읽고 가겠습니다.

진실 #1
설치는 한 번에 안 됩니다. 그게 정상입니다.

지금 우리가 하는 건 "프로그램 설치"가 아니라 AI를 실행할 환경 자체를 만드는 작업입니다. Python, CUDA, PyTorch, 가상환경, 의존 패키지 — 이 모든 것이 서로 맞물려야 합니다. 한 번에 맞을 확률이 더 낮습니다.

진실 #2
에러는 실패가 아니라 힌트입니다.

에러 메시지는 컴퓨터가 여러분에게 보내는 편지입니다. 빨간 글씨에 겁먹지 말고 첫 줄만 읽으세요. 거의 모든 답이 거기에 있습니다.

진실 #3
파인튜닝은 코드보다 데이터가 90%입니다.

좋은 데이터 100문장이 어설픈 데이터 10,000문장보다 좋은 모델을 만듭니다. 오늘 우리가 배울 기술의 본질은 "내 데이터로 AI를 다시 가르치는 것"이고, 그 핵심은 데이터 품질입니다.

강사 멘트
"여러분, 오늘 목표는 설치 성공이 아닙니다. 설치 실패를 해결하는 방법을 배우는 겁니다. 그래서 일부러 천천히 갑니다."
SECTION 02

Unsloth, 정체부터 정리합니다

유튜브와 블로그에서 본 정보가 헷갈리는 건 Unsloth가 두 얼굴이라 그렇습니다. 둘은 완전히 다른 도구입니다.

Unsloth (라이브러리)

파인튜닝 본체
  • 파이썬 코드로 사용
  • NVIDIA GPU 필수
  • LoRA · QLoRA 학습 최적화
  • 메모리 70% 절감, 속도 2배
  • 오늘의 진짜 주인공

Unsloth Studio

로컬 채팅 UI
  • 설치형 챗봇 인터페이스
  • CPU만 있어도 동작 (GGUF)
  • 파인튜닝 기능은 보조적
  • 인터넷 없이 사용 가능
  • 망분리 환경에 적합
강사 멘트
"Unsloth Studio는 '내 PC 안에 ChatGPT 만들기'에 가깝고, Unsloth 라이브러리는 '내 데이터로 AI 다시 가르치기'입니다. 오늘은 후자가 목표입니다."
SECTION 03

내 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)로 진행하세요. 이게 부끄러운 일이 아닙니다.
강사 멘트
"여러분, 노트북 스티커에 RTX 붙어있어도 모델명에 'Pro'가 들어가면 외장 GPU 없는 경우가 많습니다. 같은 라인업에서 Ultra 모델만 RTX가 들어가는 경우가 흔하거든요. 진단이 우선입니다."
SECTION 04

두 갈래 길, 어디로 갈까

길 A는 Colab, 길 B는 로컬 Windows. 처음 배우시는 분의 90%는 길 A로 가시는 게 정답입니다.

길 B · 로컬 Windows 설치

NVIDIA GPU 있는 분 / 망분리 환경
  • 한 번 세팅하면 반복 사용 편함
  • 데이터 외부 유출 없음
  • 설치에 1 ~ 3시간 소요 가능
  • 오류 케이스 7가지 이상 만남
  • 오늘 워크북의 후반부 주제
강사 멘트
"솔직히 말씀드리면, 처음 배우시는 분의 90%는 길 A로 가셔야 합니다. 길 B는 '내 손으로 환경을 다 만들어보고 싶다'는 분들의 길입니다. 부끄러워하지 마세요. 실리콘밸리 엔지니어들도 처음에 Colab으로 시작합니다."
SECTION 05 · PATH A

길 A · Colab으로 첫 파인튜닝하기

설치 0줄. 코드 거의 안 만집니다. 데이터만 자기 것으로 바꾸면 끝납니다. 1시간 안에 첫 모델이 나옵니다.

A1

Unsloth 공식 노트북 열기

구글에서 "unsloth notebook llama 3"으로 검색하거나, Unsloth 공식 깃허브의 노트북 링크를 클릭합니다. 클릭 한 번으로 Colab이 열립니다. 우리가 직접 코드를 짜는 게 아니라 이미 다 만들어진 코드를 빌려 쓰는 것입니다.

왜 공식 노트북인가 · 내가 짠 코드는 어디서 깨질지 모릅니다. 공식 노트북은 매주 검증됩니다.
A2

런타임을 GPU로 변경

Colab 상단 메뉴에서 런타임 → 런타임 유형 변경 → T4 GPU 선택. 무료입니다.

흔한 실수 · GPU로 안 바꾸고 실행하면 "CUDA not available" 에러. 한참 뒤에야 발견하고 처음부터 다시.
A3

위에서부터 셀 하나씩 실행 (Shift + Enter)

맨 위 셀부터 차례대로 실행합니다. 첫 셀은 보통 !pip install unsloth 같은 설치 명령어인데, Colab에서는 이게 거의 무조건 성공합니다. 5 ~ 10분 정도 걸립니다.

강사 멘트
"여기서 가장 흔한 실수는 '왜 안 끝나지?' 하면서 다시 누르는 겁니다. 한 번 누르고 기다리세요. 두 번 누르면 처음부터 다시 합니다."
A4

데이터셋만 내 것으로 바꾸기 (오늘의 핵심)

노트북 안에 dataset = load_dataset("yahma/alpaca-cleaned") 같은 줄이 있습니다. 이걸 내 데이터로 바꾸면 됩니다. 데이터 형식은 다음과 같습니다.

{
  "instruction": "농촌진흥청 보도자료를 작성해줘",
  "input": "주제: 가을 배추 작황 호조",
  "output": "농촌진흥청은 ○○일, 올 가을 배추..."
}

이런 항목을 50 ~ 500개 정도 모으면 충분히 의미 있는 파인튜닝이 됩니다. JSON 또는 CSV로 저장 후 Colab에 업로드합니다.

핵심 · 데이터 100개로도 어조와 형식은 충분히 학습됩니다. 처음부터 1만 개 모으려 하지 마세요.
A5

학습 실행 → 기다리기

Trainer 셀을 실행하면 학습이 시작됩니다. T4 GPU 기준 7B 모델 + 데이터 500개 = 약 30분 ~ 1시간. 화면에 loss(손실값)가 점점 줄어드는 게 보이면 정상입니다.

A6

GGUF로 저장 → 내 PC에서 사용

마지막 셀에서 model.save_pretrained_gguf(...)를 실행합니다. 결과 파일을 다운로드한 뒤, 내 PC에서 Ollama 등으로 실행하면 인터넷 없이 내 모델을 사용할 수 있습니다.

이 단계가 핵심 · Colab에서 학습한 모델을 GGUF로 가져와 로컬에서 쓰는 것. 이게 망분리 환경 활용의 시작입니다.
SECTION 06 · PATH B

길 B · 로컬 Windows 설치 (정공법)

NVIDIA GPU가 있고, 한 번 제대로 환경을 만들어두고 싶은 분을 위한 코스입니다. 7개의 단계와 9개의 흔한 오류가 기다립니다.

B0

PowerShell을 관리자 권한으로 실행

시작 메뉴에서 PowerShell 검색 → 우클릭 → 관리자 권한으로 실행. 일반 PowerShell로 시작하면 절반 명령어가 막힙니다.

강사 멘트
"여러분, 이거 빠뜨리고 시작하면 한 시간 뒤에 처음으로 돌아옵니다. 무조건 관리자 권한입니다."
B1

winget이 살아있는지 확인

PS> winget --version
버전이 출력됨 · 다음 단계로
"용어가 인식되지 않습니다" · Microsoft Store 열기 → "App Installer" 검색 → 설치 또는 업데이트. 그 후 PowerShell을 완전히 종료하고 다시 실행 (이거 안 하면 계속 안 됨).
B2

Python 3.11 설치 (3.13 아닙니다)

PS> winget install -e --id Python.Python.3.11
왜 3.11인가 · Python 3.13은 너무 최신이라 일부 AI 패키지가 아직 호환 안 됩니다. 3.11이 가장 안정적입니다. 3.13 깐 분은 3.11도 추가로 까세요. 공존 가능합니다.

설치 후 PowerShell 재시작 → python --version으로 확인.

B3

uv 설치 (요즘 표준 패키지 매니저)

PS> winget install --id=astral-sh.uv -e

uv는 pip의 빠른 후계자입니다. PyTorch + CUDA를 자동으로 맞춰주기 때문에 충돌이 압도적으로 줄어듭니다.

B4

가상환경 만들기 (이걸 빼먹으면 나중에 후회)

PS> uv venv unsloth_env --python 3.11
PS> unsloth_env\Scripts\activate

두 번째 명령 실행 후 줄 맨 앞에 (unsloth_env)가 붙으면 정상입니다.

강사 멘트
"가상환경은 '실험실'입니다. 이거 안 만들고 시스템에 직접 깔면 나중에 다른 프로젝트에서 충돌 나서 다 갈아엎어야 합니다. 무조건 만드세요."
B5

Unsloth 설치

PS> uv pip install unsloth --torch-backend=auto

설치 중 CMake가 한참 뭔가를 빌드합니다. 5 ~ 15분 걸릴 수 있습니다. 멈춘 게 아닙니다.

CMake 메시지가 계속 흐름 · 정상. 컴퓨터가 직접 AI 엔진을 빌드 중입니다.
"failed to find compiler" · Visual C++ Build Tools가 없는 경우. Microsoft에서 "Visual Studio Build Tools" 검색 → 설치 → "C++ build tools" 워크로드 체크.
B6

설치 검증

PS> python -c "import torch; print(torch.cuda.is_available())"
True 출력 · GPU 인식 성공. 파인튜닝 준비 완료.
False 출력 · torch가 CPU 버전으로 깔린 상태. 진단 1로 돌아가 GPU 드라이버부터 확인.
B7

첫 파인튜닝 코드 실행

Colab 노트북을 그대로 다운로드해서 로컬에서 돌릴 수 있습니다. 또는 Unsloth 공식 깃허브의 example 폴더에서 llama3_finetune.py 같은 파일을 받아 실행합니다. 이 부분은 길 A의 A4 ~ A6과 동일합니다.

SECTION 07

자주 만나는 오류 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을 관리자 권한으로 재실행. 백신은 일시적으로 폴더 예외 추가
강사 멘트
"이 표만 인쇄해서 옆에 두세요. 오늘 만나는 오류의 95%가 이 안에 있습니다. 안에 없는 오류만 따로 검색하시면 됩니다."
SECTION 08

비개발자를 위한 핵심 개념 4가지

설치는 됐는데 무슨 말인지 하나도 모르겠다면 이 4개만 기억하면 됩니다.

파인튜닝

이미 똑똑한 AI에게 우리 회사 말투를 가르치는 것

처음부터 AI를 만드는 게 아닙니다. 라마3 같은 베이스 모델 위에 우리 데이터로 추가 학습을 시키는 것입니다. 자녀에게 회사 매뉴얼만 따로 가르치는 것과 비슷합니다.

LoRA · QLoRA

전체를 안 바꾸고 일부만 바꾸는 효율적 방법

모델 전체를 다시 학습하면 GPU가 100GB 필요합니다. LoRA는 모델의 핵심 부분만 살짝 바꿔서 8GB GPU로도 학습 가능하게 합니다. Unsloth가 빛나는 이유입니다.

데이터셋

"질문 → 우리가 원하는 답변" 모음집

instruction(지시) / input(맥락) / output(정답) 세 항목으로 구성된 JSON 묶음입니다. 50 ~ 500개로 시작하고, 품질이 양보다 중요합니다.

GGUF

학습 끝난 모델을 가벼운 파일로 압축한 것

학습은 GPU에서 하고, 사용은 CPU에서도 가능하게 만들어주는 포맷입니다. 망분리 환경에서 활용할 때 핵심입니다. Ollama, LM Studio에서 바로 실행됩니다.

SECTION 09

실습 마무리 체크리스트

워크북을 다 따라온 뒤, 자기 점검용으로 사용하세요. 한 항목이라도 비어 있으면 그 부분만 다시 돌아갑니다.

설치 / 환경 (길 B 진행자)

PowerShell을 관리자 권한으로 실행했다
winget --version 정상 출력 확인
Python 3.11 설치 및 python --version 확인
가상환경 unsloth_env 생성 후 활성화
uv pip install unsloth 정상 완료
torch.cuda.is_available() 결과가 True

파인튜닝 (공통)

데이터셋 50개 이상 준비 (instruction / input / output)
베이스 모델 선택 (Llama 3 8B 추천)
학습 시작 후 loss 값이 줄어드는 것 확인
학습 완료 후 GGUF로 저장
저장된 모델로 추론 테스트 1회

학습 효과 점검 (자기 진단)

에러 메시지 첫 줄을 스스로 읽을 수 있는가
오류 → 원인 → 해결의 3단계 사고 흐름이 형성되었는가
다음 실습 때 강사 없이 시도할 의지가 있는가