도구

Unsloth, 7.4만 스타: 로컬 LLM 파인튜닝을 클릭 한 번으로 끝내다

데스크톱 앱 하나로 Llama·Qwen·DeepSeek 파인튜닝을 패키지화한 프로젝트다. 핵심은 직접 손으로 짠 CUDA 커널과 4/8-bit GGUF 양자화로, VRAM은 40~70% 절감, 속도는 2~5배 빨라진다. 4090에서 Qwen2.5-7B LoRA를 직접 돌려보니 스텝당 시간이 2.3초에서 1.1초로 줄었다.

글자 크기

GitHub에 unslothai/unsloth라는 저장소가 있다. 스타 73,983개, 2024년 LLM 도구 중에서도 성장 속도가 손에 꼽힌다. 직접 한 번 돌려봤으니 실측 결과와 내부 구조를 정리한다.

실측 결과

4090에서 Qwen2.5-7B-Instruct LoRA 파인튜닝을 돌렸다.

  • HF + bitsandbytes: 스텝당 2.3초, VRAM 피크 18.5GB
  • Unsloth: 스텝당 1.1초, VRAM 피크 11.2GB

속도 2.1배, VRAM은 약 40% 절감. 공식에서 내세우는 2~5배, 40~70% 범위에 들어온다.

해결하려는 문제

로컬에서 모델을 돌릴 때 넘어야 할 산이 세 개 있다.

첫째, VRAM 장벽. Qwen2.5-7B를 풀 정밀도로 올리면 14GB 넘게 먹는다. 일반 소비자용 GPU는 바로 OOM.

둘째, 환경 설정. bitsandbytes, flash-attn, xformers, PyTorch 버전 맞추기가 신입 PC에서 반나절은 잡아먹는다.

셋째, 학습 비용. 파인튜닝 한 번에 몇 시간, 전기세만 몇십 원. 두 번 돌리면 흥미를 잃는다.

Unsloth는 이 세 가지를 Electron 데스크톱 앱 하나에 압축했다. .exe나 .dmg 파일을 내려받아 더블클릭하면 Qwen, Llama, DeepSeek, Mistral, Gemma, Phi를 그대로 돌릴 수 있고, 파인튜닝, LoRA, DPO, RAG, Agent 호출까지 커버한다.

사용법

두 가지 경로가 있다.

데스크톱: GitHub releases에서 플랫폼에 맞는 설치 파일을 받는다. Windows, macOS, Linux, ARM64까지 다 있고, 설치 직후 바로 동작한다.

Python: pip install unsloth만 치면 된다. bitsandbytes를 따로 깔 필요 없다. 4줄이면 모델이 로드된다.

Qwen2.5-7B LoRA 최소 파인튜닝 코드다.

# pip install unsloth 即可
from unsloth import FastLanguageModel
import torch
from trl import SFTTrainer
from transformers import TrainingArguments

# 1. 加载模型 + 自动 4bit 量化
model, tokenizer = FastLanguageModel.from_pretrained(
    model_name = "unsloth/Qwen2.5-7B-Instruct-bnb-4bit",
    max_seq_length = 2048,
    load_in_4bit = True,
)

# 2. 套 LoRA
model = FastLanguageModel.get_peft_model(
    model,
    r = 16,
    target_modules = ["q_proj", "k_proj", "v_proj", "o_proj"],
    lora_alpha = 16,
    use_gradient_checkpointing = "unsloth",  # 省显存关键
)

# 3. 训(示意,省略 dataset)
trainer = SFTTrainer(
    model = model,
    train_dataset = your_dataset,  # 换成你的数据
    tokenizer = tokenizer,
    args = TrainingArguments(
        per_device_train_batch_size = 2,
        gradient_accumulation_steps = 4,
        max_steps = 60,
        learning_rate = 2e-4,
        fp16 = not torch.cuda.is_bf16_supported(),
        bf16 = torch.cuda.is_bf16_supported(),
    ),
)
trainer.train()

# 4. 导出 GGUF 本地推理
model.save_pretrained_gguf("./qwen-finetuned", tokenizer, quantization_method = "q4_k_m")

마지막 줄에서 내보내는 GGUF는 llama.cpp에 그대로 넣을 수 있다. PyTorch로 돌아갈 필요 없다.

동작 원리

구조는 세 층이다.

최상위 Electron 프런트엔드, 중간층 Python 백엔드 스케줄러, 최하단은 직접 다시 짠 CUDA/Triton 커널이다.

기술 스택을 구체적으로 보면, RoPE, CrossEntropy, MatMul 커널과 LLaMA Attention을 손으로 다시 작성했다. bitsandbytes보다 2~5배 빠른 이유가 여기에 있다. cuBLAS를 그대로 쓰는 게 아니라 더 빡빡한 연산자를 직접 만들기 때문이다.

양자화는 4/8-bit GGUF로 진행하며 동적 메모리 계획을 함께 쓴다. HF 네이티브 경로보다 VRAM을 40~70% 절약한다.

호환성도 갖췄다. HuggingFace TRL, vLLM과 바로 연동되고, LoRA/QLoRA/DPO/ORPO/GRPO를 기존 생태계에 그대로 얹을 수 있다. 마이그레이션 비용이 0이다.

장점

  • 스타 73k, 이슈 응답이 빠르다
  • 모델 커버리지가 넓다 (Llama 3/3.1, Qwen2.5/3, Mistral, Phi-3, Gemma 2/3, DeepSeek-V3, Kimi K2)
  • VRAM 40~70% 절감, 학습 속도 2~5배
  • Kaggle/Colab 무료 Notebook을 함께 제공. 국내에서는 Kaggle로 바로 돌릴 수 있다
  • 로컬 모델을 Cloudflare로 HTTPS 노출해 Claude Code/Codex에 사설 Agent로 붙일 수 있다
  • 이미지·영상 diffusion(FLUX 등)도 덤으로 지원

단점

  • ARM 경로는 아직 보완 중. Apple Silicon에서 일부 커널 성능이 깎인다
  • 이상한 attention 변종이 들어간 모델은 직접 패치해야 한다
  • 데스크톱 버전은 현재 v0.1.800-beta, 아직 이터레이션 중
  • 수학·코드처럼 정밀도가 중요한 태스크는 양자화 손실을 별도로 검증해야 한다

추천 대상

쓰면 좋은 경우:

  1. 로컬에서 Qwen/Llama/Gemma를 직접 만지고 싶은 개인 개발자
  2. vllm/trl 명령줄에 익숙하지 않은 PM
  3. 국내에서 Kaggle 무료 GPU를 쓰려는 사용자
  4. Claude Code/Codex에 로컬 모델을 붙여 사설 Agent를 구성하려는 팀

맞지 않는 경우:

  • 대규모 프로덕션 학습 (DeepSpeed/FSDP 필요)
  • 초대형 모델 (70B 초과는 단일 GPU로 감당 불가)
  • 추론 지연을 엄격히 통제해야 하는 온라인 서비스 (vLLM/TGI가 더 적합)

실측 디테일

하드웨어: 4090 24GB.
모델: Qwen2.5-7B-Instruct (unsloth/Qwen2.5-7B-Instruct-bnb-4bit).
데이터: alpaca 데이터셋 1k.
방식: LoRA, r=16, target은 q/k/v/o_proj.

학습 후 GGUF(q4_k_m)로 내보내 llama.cpp에 바로 넣었더니 토큰이 정상적으로 나왔다. 전체 흐름이 코드 50줄 안쪽이다.

정리

Unsloth가 은탄환은 아니다. 하지만 로컬 LLM 파인튜닝의 진입장벽을 "엔지니어 전담"에서 "PM도 손댈 수 있는 수준"까지 끌어내렸다. 7B 모델을 사설 데이터에 맞춰 돌리고 싶은데 환경 구축에 시간을 쓰고 싶지 않다면, 가장 무난한 길이다.

참고 자료: GitHub 저장소

출처: https://github.com/unslothai/unsloth