Unsloth으로 Gemma 4 파인튜닝하는 방법: 단계별 가이드

Unsloth는 E2B, E4B, 26B-A4B, 31B 등 네 가지 Gemma 4 변체 모두를 출시 당일부터 지원합니다. 표준 Hugging Face 학습 방식에 비해 최대 2배 빠른 속도와 70% 적은 VRAM 사용량을 자랑하므로, 개인용 하드웨어를 사용하는 모든 분에게 가장 실질적인 선택지가 됩니다.

이 가이드에서는 적절한 모델 변체 선택부터 최종 어댑터를 Ollama, llama.cpp 또는 LM Studio용으로 내보내는 방법까지 모든 과정을 다룹니다.

어떤 Gemma 4 모델을 파인튜닝해야 할까요?

답은 본인의 하드웨어 사양과 달성하려는 목표에 달려 있습니다.

모델	학습 시 VRAM (LoRA, bf16)	적합한 환경
E4B	~8–10 GB	노트북, RTX 3060/4060, 무료 버전 Colab
E2B	~6–8 GB	멀티모달 + 오디오 작업, 저예산 환경
26B-A4B	~24+ GB (16-bit LoRA)	속도/품질 균형, RTX 3090/4090
31B	~20 GB (QLoRA 4-bit)	최고의 품질, NVIDIA A100 / 듀얼 GPU 환경

몇 가지 중요한 참고 사항:

대부분의 사용자에게는 E4B가 가장 좋은 시작점입니다. 무료 Google Colab(T4 GPU)에서도 실행 가능하며, 12 GB 이상의 VRAM을 갖춘 모든 RTX GPU에서 작동합니다. 또한 텍스트와 멀티모달(이미지 + 오디오) 파인튜닝을 모두 지원합니다. Unsloth에서 전용 무료 Colab 노트북을 제공합니다.

26B-A4B MoE 모델에서는 QLoRA를 피하세요. 26B-A4B는 MoE(Mixture-of-Experts) 구조이므로 Unsloth는 4-bit QLoRA 대신 16-bit LoRA 사용을 권장합니다. MoE 라우팅과 4-bit 양자화는 궁합이 좋지 않습니다. 이 모델에서는 load_in_4bit=True 대신 load_in_16bit=True를 사용하세요.

최고의 품질이 중요하다면 31B가 훌륭한 타겟입니다. Dense 모델이므로 QLoRA가 잘 작동하며, 현재 아레나(Arena) AI 텍스트 리더보드에서 오픈 모델 중 3위를 기록하고 있습니다.

시작 전: Unsloth 설치 및 업데이트

아직 Unsloth가 설치되어 있지 않다면 여기서 시작하세요. 두 가지 사용 방식이 있습니다: Unsloth Studio(코드 없는 웹 UI 버전)와 Unsloth Core(코드 기반 워크플로우를 위한 Python 라이브러리).

옵션 A — Unsloth Studio (코딩 불필요, 초보자 권장)

macOS, Linux 또는 WSL:

curl -fsSL https://unsloth.ai/install.sh | sh

Windows PowerShell:

irm https://unsloth.ai/install.ps1 | iex

설치가 완료되면 Studio를 실행합니다:

unsloth studio -H 0.0.0.0 -p 8888

그 후 브라우저에서 http://localhost:8888을 엽니다. 처음 실행 시 비밀번호를 설정한 다음, 마법사를 통해 Gemma 4를 검색하고 모델 크기와 데이터셋을 선택하면 됩니다. Unsloth Studio가 나머지를 모두 처리하며, UI에서 진행 상황을 모니터링하고 완료 후 내보낼 수 있습니다.

옵션 B — Unsloth Core (코드 기반)

이미 설치되어 있는 경우 먼저 업데이트를 진행합니다:

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

신규 설치(PyTorch 백엔드 자동 감지)의 경우:

pip install unsloth --torch-backend=auto

데이터셋 준비하기

Gemma 4는 이전 모델(Gemma 1/2/3) 전용 형식이 아닌 user와 model 역할을 사용하는 표준 대화 형식을 사용합니다. 학습 데이터는 다음과 같은 구조여야 합니다:

{
  "messages": [
    {
      "role": "user",
      "content": "다음 리뷰의 감성을 분류해줘: '배송은 늦었지만 제품은 아주 훌륭합니다.'"
    },
    {
      "role": "model",
      "content": "혼합(Mixed) — 배송에 대해서는 부정적, 제품에 대해서는 긍정적입니다."
    }
  ]
}

Gemma 4 전용 포맷 규칙:

답변 역할에는 assistant가 아닌 "role": "model"을 사용하세요. 이는 토크나이저의 채팅 템플릿과 일치합니다.
Gemma 4에서는 공식적으로 시스템 프롬프트를 지원합니다. 대화 시작 부분에 {"role": "system", "content": "..."} 메시지를 포함할 수 있습니다.
학습 중에 사고(thinking) 모드를 활성화하려면 시스템 프롬프트 시작 부분에 <|think|>를 추가하세요. 모델의 추론 능력을 보존하고 싶다면 추론 스타일의 예제와 직접적인 답변 예제를 섞어서 구성하세요. Unsloth는 추론 능력을 유지하기 위해 최소 75% 이상의 추론 예제를 포함할 것을 권장합니다.
멀티턴(multi-turn) 대화의 경우 최종 답변만 학습 타겟에 포함하세요. 이전 단계의 사고 블록을 다음 턴에 다시 입력으로 피드(feed)하지 마세요.

데이터셋 크기 가이드라인:

스타일 또는 말투 교정: 200~1,000개의 고품질 예제
특정 분야 적응 (의료, 법률, 기술): 10,000~50,000개 예제
지시어 이행 (Instruction following): 5,000~20,000개 예제
분류 또는 추출 작업: 500~5,000개 예제

항상 데이터의 10~20%는 평가용으로 남겨 두세요. 하나의 오염되거나 잘못된 예제가 수십 개의 깨끗한 예제보다 학습 결과에 더 큰 악영향을 미칠 수 있습니다.

텍스트 파인튜닝: 코드 분석

다음 예제는 LoRA를 사용하여 Gemma 4 E4B를 텍스트 작업용으로 파인튜닝하는 코드입니다. 데이터셋 URL 부분을 본인의 데이터로 교체하세요.

from unsloth import FastLanguageModel
import torch
from datasets import load_dataset
from trl import SFTTrainer, SFTConfig

max_seq_length = 2048  # 처음에는 보수적으로 시작하세요.

# 데이터셋 로드
dataset = load_dataset("json", data_files={"train": "your_dataset.jsonl"}, split="train")

# 모델 로드
model, tokenizer = FastLanguageModel.from_pretrained(
    model_name = "google/gemma-4-e4b-it",
    max_seq_length = max_seq_length,
    load_in_4bit = False,    # E4B 및 31B Dense 모델은 QLoRA(4-bit)도 가능
    load_in_16bit = True,    # bf16 LoRA — 권장 시작점
    full_finetuning = False,
)

# LoRA 어댑터 연결
model = FastLanguageModel.get_peft_model(
    model,
    r = 16,                  # LoRA 랭크 — 높을수록 용량은 커지나 VRAM 더 많이 소모
    target_modules = [
        "q_proj", "k_proj", "v_proj", "o_proj",
        "gate_proj", "up_proj", "down_proj",
    ],
    lora_alpha = 16,
    lora_dropout = 0,
    bias = "none",
    use_gradient_checkpointing = "unsloth",  # 긴 컨텍스트나 빠듯한 VRAM 환경에서 필수
    random_state = 3407,
    max_seq_length = max_seq_length,
)

# 학습 실행
trainer = SFTTrainer(
    model = model,
    train_dataset = dataset,
    tokenizer = tokenizer,
    args = SFTConfig(
        max_seq_length = max_seq_length,
        per_device_train_batch_size = 1,
        gradient_accumulation_steps = 4,
        warmup_steps = 10,
        max_steps = 100,        # 실제 학습 시에는 num_train_epochs 등으로 변경
        logging_steps = 1,
        output_dir = "outputs_gemma4",
        optim = "adamw_8bit",
        seed = 3407,
        dataset_num_proc = 1,
    ),
)

trainer.train()

메모리가 부족하신가요? 우선 두 가지를 확인해 보세요: per_device_train_batch_size를 1로 낮추고, max_seq_length를 줄이세요. use_gradient_checkpointing="unsloth" 설정은 필수입니다. 이는 VRAM 사용량을 획기적으로 줄이고 학습 중 실제 컨텍스트 길이를 늘리도록 설계되었습니다.

26B-A4B MoE 모델 파인튜닝

MoE 모델은 약간 다른 로더(loader)가 필요합니다. FastLanguageModel 대신 FastModel을 사용하고 16-bit LoRA 설정을 유지하세요:

import os
import torch
from unsloth import FastModel

model, tokenizer = FastModel.from_pretrained(
    model_name = "unsloth/Gemma-4-26B-A4B-it",
    max_seq_length = 2048,
    load_in_4bit = False,     # MoE 모델에서 QLoRA는 권장하지 않음
    load_in_16bit = True,     # bf16 LoRA
    full_finetuning = False,
)

로드 후에는 위의 E4B 예제와 동일한 방식으로 LoRA 어댑터를 연결하고 학습하면 됩니다. MoE 파인튜닝의 경우 랭크 16과 짧은 컨텍스트 길이로 시작한 후, 파이프라인이 안정화되었을 때 확장하는 것을 권장합니다.

멀티모달 파인튜닝 (E2B 및 E4B)

E2B와 E4B는 이미지와 오디오를 기본적으로 처리할 수 있도록 설계된 멀티모달 변체입니다. 이미지 관련 학습이 필요한 경우 FastVisionModel을 사용하세요:

from unsloth import FastVisionModel
from unsloth.trainer import UnslothVisionDataCollator
from trl import SFTTrainer, SFTConfig

model, tokenizer = FastVisionModel.from_pretrained(
    model_name = "google/gemma-4-e4b-it",
    max_seq_length = 2048,
    load_in_4bit = False,
    use_gradient_checkpointing = "unsloth",
)

model = FastVisionModel.get_peft_model(
    model,
    finetune_vision_layers     = False,  # VRAM 절약을 위해 처음에는 텍스트 레이어만 시도
    finetune_language_layers   = True,
    finetune_attention_modules = True,
    finetune_mlp_modules       = True,
    r = 16,
    lora_alpha = 16,
    lora_dropout = 0,
    bias = "none",
    target_modules = "all-linear",
)

trainer = SFTTrainer(
    model = model,
    tokenizer = tokenizer,
    data_collator = UnslothVisionDataCollator(model, tokenizer),
    train_dataset = dataset,
    args = SFTConfig(
        per_device_train_batch_size = 1,
        gradient_accumulation_steps = 4,
        learning_rate = 2e-4,
        output_dir = "outputs_gemma4_vision",
    ),
)

trainer.train()

주의: Gemma 4 멀티모달 프롬프트에서는 이미지가 텍스트 지시어보다 앞에 와야 합니다. 다음과 같은 형식입니다:

{
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "image", "image": "path/to/image.jpg"},
        {"type": "text",  "text": "이 이미지에서 무슨 일이 일어나고 있는지 설명해줘."}
      ]
    },
    {
      "role": "model",
      "content": "..."
    }
  ]
}

오디오 파인튜닝(E2B / E4B 전용)의 경우: 오디오 클립은 짧고 특정 작업 중심이어야 합니다. 오디오 워크플로우를 위해서는 Unsloth의 Vision RL 노트북 예제를 참고하는 것을 권장합니다.

파인튜닝된 모델 저장 및 내보내기

학습이 끝나면 배포 환경에 따라 여러 가지 방식으로 내보낼 수 있습니다.

LoRA 어댑터로 저장 (가장 빠르고 가벼움)

model.save_pretrained("gemma4_e4b_adapter")
tokenizer.save_pretrained("gemma4_e4b_adapter")

이렇게 하면 어댑터 가중치만 저장되어 전체 모델 대신 수백 MB 정도의 파일만 생성됩니다. 추론 시에는 베이스 모델이 필요합니다.

머지 및 GGUF로 내보내기 (llama.cpp / Ollama / LM Studio용)

model.save_pretrained_gguf(
    "gemma4_e4b_finetuned",
    tokenizer,
    quantization_method = "q4_k_m"   # 또는 "q8_0", "f16"
)

생성된 .gguf 파일은 llama.cpp에서 직접 실행하거나, 커스텀 Modelfile을 통해 Ollama로 가져오거나, LM Studio에서 로드하여 사용할 수 있습니다.

Unsloth Studio에서 내보내기

Studio UI를 사용했다면 학습 완료 후 'Export' 탭으로 이동하세요. GGUF, safetensors 또는 둘 다 선택할 수 있으며 머지 과정은 자동으로 진행됩니다.

꼭 확인하세요: 내보낸 모델이 다른 런타임(Ollama, llama.cpp 등)에서 이상하게 작동한다면, 대부분 채팅 템플릿이나 EOS 토큰 설정이 틀렸기 때문입니다. 추론 시에도 학습 때 사용한 것과 동일한 채팅 템플릿을 사용해야 합니다.

무료 Colab 노트북

Unsloth는 모든 Gemma 4 크기에 대해 무료 Google Colab 노트북을 제공합니다. E2B/E4B 노트북은 무료 T4 GPU에서 실행 가능하며, 26B-A4B 및 31B 노트북은 A100(Colab Pro)이 필요합니다.

모델	작업 종류	링크
E2B	텍스트	Colab에서 열기
E2B	비전	Colab에서 열기
E2B	오디오	Colab에서 열기
26B-A4B	비전 (A100)	Colab에서 열기
31B	비전 (A100)	Colab에서 열기

일반적인 문제 해결

학습 중 메모리 부족(OOM): max_seq_length를 먼저 줄이고, 그다음 per_device_train_batch_size를 1로 낮추세요. use_gradient_checkpointing="unsloth"가 설정되어 있는지 반드시 확인하세요.

26B-A4B 모델에서 QLoRA 사용 성능 저하: MoE 아키텍처와 4-bit 양자화는 궁합이 좋지 않습니다. MoE 모델에서는 16-bit LoRA(load_in_16bit=True)를 고수하세요.

내보내기 후 채팅 템플릿 불일치: 모델 답변이 이상하다면 추론 런타임이 학습 때와 동일한 Gemma 4 채팅 템플릿을 사용하고 있는지 확인하세요. 내보내기 성능 저하의 가장 흔한 원인입니다.

파인튜닝 후 추론 능력 저하: Gemma 4의 내장된 추론 능력을 유지하고 싶다면 학습 데이터에 추론 스타일 예제와 일반 답변 예제를 섞어 대칭을 맞추세요. 추론 성능 보존을 위해 최소 75% 이상의 추론 예제 구성을 권장합니다.

공식 학습 참조 문서는 Unsloth 문서를 확인하세요.