ActionMask 블로그 - 로컬 LLM 파인튜닝 하기 (feat. SFT)

Information

윈도우 환경에서 로컬 Gemma 3 + LoRA + 4bit 양자화 기반 LLM 파인튜닝 가이드입니다.

개요

대규모 언어모델(LLM)의 활용이 점차 확대됨에 따라, 개인 또는 소규모 팀에서도 효율적으로 모델을 커스터마이징할 수 있는 기법이 주목받고 있습니다. 이 글에서는 Google의 Gemma 3 12B 모델을 기반으로, 4bit 양자화 + LoRA + TRL의 SFTTrainer를 이용하여 파인튜닝하는 전체 과정을 정리합니다.

이번 글에서는 파인튜닝된 모델을 Ollama에서 사용할 수 있도록 GGUF 형식으로 변환하는 방법도 포함되어 있습니다. 이를 통해 로컬 환경에서 LLM을 효율적으로 활용할 수 있는 기반을 마련할 수 있습니다.

Ollama 설치 방법은 Ollama 공식 Github를 참고하시면 됩니다.

LLM 파인튜닝을 통해 특정 도메인에 최적화된 모델을 구축하거나, 기존 모델의 성능을 향상시킬 수 있습니다. 또한, LLM의 응답 방향이나 어조를 조정하여 특정 업무에 맞는 모델을 만들 수 있습니다.
나만의 데이터셋을 활용하여 LLM을 커스터마이징함으로써, 더 나은 사용자 경험을 제공할 수 있습니다.

Warning

로컬에서 개인적으로 사용할 때에는 학습 데이터셋의 윤리적인 문제나 정치/사회적 이슈에 대한 고려가 크게 중요하지 않지만, 모델을 공개할 경우, 반드시 가이드 라인이나 정책을 준수해야 합니다. 또한, 모델의 응답이 특정 도메인에 편향되지 않도록 주의해야 합니다.

사용 기술 요약

구성 요소	설명
모델	`Gemma-3 12B It` (IT 버전이 아닌 기본 모델도 무방)
프레임워크	Huggingface Transformers, TRL (SFTTrainer), PEFT
양자화	`BitsAndBytes` 기반 4bit (NF4)
파인튜닝 방식	LoRA (Low-Rank Adaptation)
전략	Supervised Fine-Tuning (SFT)
학습 포맷	instruction / response JSONL 구조

프로젝트 구조 및 사전준비

프로젝트 폴더 및 파일 구조는 다음과 같습니다. 환경에 따라 적절하게 변경될 수 있습니다.

Warning

Python은 격리 환경이나 가상 환경을 구성하여 실행하는 것을 권장합니다. conda, virtualenv 등의 가상환경이나 docker를 이용하시길 추천드립니다.

project/
├── dataset/
│ ├── train.jsonl
│ └── valid.jsonl
├── output/
│ └── final/
├── train.py

학습 데이터셋

학습에 사용할 JSONL 형식은 다음과 같이 작성되어 있어야 합니다.

{"instruction": "질문을 입력하세요.", "response": "모델의 응답입니다."}

가급적 많은 양의 데이터셋을 준비하는 것이 좋습니다. 비슷한 유형의 질문과 답변을 포함하는 데이터셋을 사용하면 모델이 특정 도메인에 대해 더 잘 학습할 수 있습니다.

또한 프로젝트 구조에서와 같이 train.jsonl과 valid.jsonl 파일을 준비합니다. 이 파일들은 각각 학습용과 검증용 데이터셋으로 사용됩니다. 9:1 또는 8:2 비율로 나누는 것이 일반적입니다.

이 유형의 데이터셋은 후술할 내용과 같이 formatting_func 함수를 통해 적절한 형식으로 변환됩니다. 이 함수는 각 데이터 항목을 대화형 구조로 변환하여 모델이 이해할 수 있도록 합니다.

대략 다음과 같이 목적에 따라 데이터셋을 준비하는 것이 좋습니다.

목적	요구되는 데이터 양	설명
미세 스타일 조정 (LoRA)	5만~10만 토큰 (10~30만자)	기존 모델에 약간의 스타일을 얹는 정도
완전한 스타일 주입	50만~100만 토큰 (100만자 이상)	독립적인 스타일을 구성할 수 있을 만큼의 훈련량 필요
주제별 대응 + 다양한 인스트럭션 대응	100만~300만 토큰	다양한 주제/프롬프트 대응이 가능하게끔 함

모델 다운로드

학습에 사용할 기본 모델은 Gemma 3 12B 모델입니다. 이 모델은 Huggingface Hub에서 다운로드할 수 있으며, 로컬 환경에 저장해 두어야 합니다.

다운로드에 앞서, Huggingface Hub에서 모델을 다운로드 받을려면 access token 설정을 해야 합니다. 허깅페이스에 로그인 후, Settings > Access Tokens에서 진입하여, 아래와 같이 Create new Token을 클릭합니다.

권한은 Read로 설정하고 적절한 Token 이름을 입력한 후 생성해줍니다.

생성된 Access Token을 이용해서 이제 다음 명령어를 통해 Huggingface Hub에서 대용량 모델을 다운로드 받을 수 있습니다.

git lfs install
git clone https://<YOUR_USERNAME>:<YOUR_TOKEN>@huggingface.co/google/gemma-3-12b-it

이번 가이드에서는 모델을 학습용 코드 train.py파일이 있는 프로젝트 폴더 상위 폴더인 ../gemma-3-12b-it 경로에 위치시켰습니다.

학습 코드 작성

이제 본격적으로 학습을 위한 코드를 작성해 보겠습니다. 이 코드는 Huggingface Transformers, TRL, PEFT 라이브러리를 사용하여 모델을 로드하고 학습을 수행합니다.

주요 패키지 및 환경 설정

from transformers import AutoTokenizer, AutoModelForCausalLM, BitsAndBytesConfig
from trl import SFTTrainer, SFTConfig
from datasets import load_dataset
from peft import LoraConfig, prepare_model_for_kbit_training
import torch

이 코드는 Huggingface Transformers, TRL, Datasets, PEFT 라이브러리를 사용하여 모델을 로드하고 학습을 수행합니다. 필요한 패키지는 pip install 명령어로 설치할 수 있습니다.

pytorch의 경우, 사용하고 있는 Nvidia GPU에 맞춰 Cuda 드라이버를 설치해 줘야 하며, 이 Cuda 버전에 맞는 PyTorch 버전을 설치해야 합니다. 예를 들어, Cuda 11.8을 사용하는 경우 다음과 같이 설치할 수 있습니다.

이 글에서는 pytorch 설치에 대한 자세한 내용은 생략하겠습니다. PyTorch 공식 설치 가이드를 참고하시기 바랍니다.

모델 및 토크나이저 설정

MODEL_NAME = "../gemma-3-12b-it"
tokenizer = AutoTokenizer.from_pretrained(MODEL_NAME)
tokenizer.padding_side = "right"
tokenizer.add_special_tokens({
    "additional_special_tokens": ["<start_of_turn>", "<end_of_turn>", "<bos>", "<eos>"]
})
tokenizer.pad_token = tokenizer.eos_token

특수 토큰을 명시적으로 추가하여 대화형 instruction-response 구조에 적합하게 토크나이저를 확장합니다.
종결 토큰을 제대로 설정하지 않으면, 응답이 반복적으로 무한하게 생성될 수 있기 때문에, 확실하게 후술할 학습 데이터 구조 포맷팅에 맞춰 설정합니다.

4bit 양자화 설정

bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_compute_dtype=torch.bfloat16,
    bnb_4bit_use_double_quant=True,
    bnb_4bit_quant_type="nf4",
)

bnb_4bit_quant_type="nf4"는 최신 양자화 방식으로, 정밀도 손실을 줄이면서도 효율적인 학습이 가능합니다.

LoRA 구성

lora_config = LoraConfig(
    r=16,
    lora_alpha=32,
    lora_dropout=0.05,
    bias="none",
    task_type="CAUSAL_LM",
    target_modules=[
        "q_proj", "o_proj", "k_proj", "v_proj",
        "gate_proj", "up_proj", "down_proj",
    ],
)

target_modules는 Transformer의 핵심 모듈들로, 선택적으로 LoRA 적용을 통해 메모리 효율을 높입니다. 모델에 따라 다를 수 있으며, q_proj, o_proj, k_proj, v_proj 등은 일반적으로 사용되는 모듈입니다. 이번 가이드에서는 Gemma3 모델에 최적화된 모듈을 선택했습니다.
lora_alpha는 LoRA의 스케일링 파라미터로, LoRA의 효과를 조절합니다. 일반적으로 r과 lora_alpha의 비율을 맞추는 것이 좋습니다. r과 lora_alpha는 보통 r=8~64, alpha=r*2 비율이 적절합니다.

모델 로딩 및 사전 처리

model = AutoModelForCausalLM.from_pretrained(
    MODEL_NAME,
    device_map="auto",
    quantization_config=bnb_config,
    attn_implementation="eager",
)
 
model = prepare_model_for_kbit_training(model)
model.gradient_checkpointing_enable()
model.enable_input_require_grads()
model.resize_token_embeddings(len(tokenizer))

gradient_checkpointing을 사용해 GPU 메모리 사용량을 줄입니다.
prepare_model_for_kbit_training는 PEFT에서 LoRA를 4bit 모델에 적용할 수 있도록 해줍니다.

데이터셋 구성

train_dataset = load_dataset("json", data_files={"train": "./dataset/train.jsonl"})["train"]
eval_dataset = load_dataset("json", data_files={"eval": "./dataset/valid.jsonl"})["eval"]

데이터는 처음 설명한 바와 같이 다음과 같은 구조의 JSONL 형식을 따릅니다.

{"instruction": "질문을 입력하세요.", "response": "모델의 응답입니다."}

이는 Instruction Tuning에 최적화된 포맷이며, 아래 함수 formatting_func로 텍스트 포맷을 재조정하여 모델이 이해할 수 있는 형식으로 다시 변환합니다.

def formatting_func(example):
    return (
        f"<bos><start_of_turn>user\n"
        f"{example['instruction']}<end_of_turn>\n"
        f"<start_of_turn>model\n"
        f"{example['response']}<end_of_turn><eos>\n"
    )

<start_of_turn>과 <end_of_turn> 토큰은 대화의 시작과 끝을 명시적으로 표시합니다.
<bos>와 <eos> 토큰은 대화의 시작과 끝을 나타내며, 모델이 응답을 생성할 때 이 토큰들을 인식할 수 있도록 합니다. 이 태그를 지정하지 않으면, 모델이 응답을 무한히 생성할 수 있습니다.

SFT 학습 설정

sft_config = SFTConfig(
    output_dir="./output",
    num_train_epochs=4,
    per_device_train_batch_size=2,
    gradient_accumulation_steps=2,
    eval_strategy="steps",
    eval_steps=100,
    save_steps=500,
    learning_rate=2e-4,
    bf16=True,
    save_total_limit=2,
    load_best_model_at_end=True,
    report_to="tensorboard",
    max_seq_length=1024,
)

설정 값들에 대한 설명은 다음과 같습니다:

output_dir="./output": 학습 결과 저장 디렉토리
num_train_epochs=4: 전체 학습 에폭 수
per_device_train_batch_size=2: GPU당 배치 크기 (4bit 양자화로 메모리 절약)
gradient_accumulation_steps=2: 배치 크기를 2배로 확장 (메모리 절약)
eval_strategy="steps": 주기적으로 평가 수행
eval_steps=100: 100 스텝마다 평가 수행
save_steps=500: 500 스텝마다 모델 저장
learning_rate=2e-4: 초기 학습률
bf16=True: bfloat16 사용 (지원 GPU 필요)
save_total_limit=2: 최대 2개의 체크포인트만 저장 (오래된 체크포인트는 삭제)
load_best_model_at_end=True: 평가 결과에 따라 가장 좋은 모델을 로드
report_to="tensorboard": TensorBoard로 학습 로그 기록
max_seq_length=1024: Tokenizer가 처리할 최대 토큰 수

SFTTrainer 실행

trainer = SFTTrainer(
    model=model,
    train_dataset=train_dataset,
    eval_dataset=eval_dataset,
    peft_config=lora_config,
    formatting_func=formatting_func,
    args=sft_config,
)
 
torch.cuda.empty_cache()  # 캐시 정리 후 학습 시작
trainer.train()

SFTTrainer를 사용하여 모델을 학습합니다. formatting_func를 통해 데이터셋을 적절한 형식으로 변환하고, LoRA 설정을 적용합니다.
학습이 시작되면, TensorBoard를 통해 실시간으로 학습 과정을 모니터링할 수 있습니다.

모델 저장

trainer.model.save_pretrained("./output/final")
tokenizer.save_pretrained("./output/final")

최종 학습된 LoRA adapter와 tokenizer를 저장합니다. 필요 시, PEFT를 통해 다른 base model에 연결 가능.

전체 코드 정리

위에서 설명한 코드를 종합한 전체 코드는 다음과 같습니다.

train.py

from transformers import AutoTokenizer, AutoModelForCausalLM, BitsAndBytesConfig
from trl import SFTTrainer, SFTConfig
from datasets import load_dataset
from peft import LoraConfig, prepare_model_for_kbit_training
import torch
 
# 기본 경로 설정
MODEL_NAME = "../gemma-3-12b-it"
TRAIN_FILE = "./dataset/train.jsonl"
VALID_FILE = "./dataset/valid.jsonl"
OUTPUT_DIR = "./output"
 
bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_compute_dtype=torch.bfloat16,
    bnb_4bit_use_double_quant=True,
    bnb_4bit_quant_type="nf4",
)
 
# LoRA 구성
lora_config = LoraConfig(
    r=16,
    lora_alpha=32,
    lora_dropout=0.05,
    bias="none",
    task_type="CAUSAL_LM",
    target_modules=[
        "q_proj",
        "o_proj",
        "k_proj",
        "v_proj",
        "gate_proj",
        "up_proj",
        "down_proj",
    ],
)
 
# 모델과 토크나이저 로드
tokenizer = AutoTokenizer.from_pretrained(MODEL_NAME)
tokenizer.padding_side = "right"
special_tokens = {
    "additional_special_tokens": ["<start_of_turn>", "<end_of_turn>", "<bos>", "<eos>"]
}
tokenizer.add_special_tokens(special_tokens)
tokenizer.pad_token = tokenizer.eos_token
 
model = AutoModelForCausalLM.from_pretrained(
    MODEL_NAME,
    device_map="auto",
    quantization_config=bnb_config,
    attn_implementation="eager",
)
 
model = prepare_model_for_kbit_training(model)
model.gradient_checkpointing_enable()
model.enable_input_require_grads()
 
model.resize_token_embeddings(len(tokenizer))
 
print("Tokenizer size:", len(tokenizer))
print("Model vocab size:", model.get_input_embeddings().num_embeddings)
 
# 데이터셋 로드
train_dataset = load_dataset("json", data_files={"train": TRAIN_FILE})["train"]
eval_dataset = load_dataset("json", data_files={"eval": VALID_FILE})["eval"]
 
print(f"Loaded Train size: {len(train_dataset)}, Eval size: {len(eval_dataset)}")
 
 
# instruction-response 형식 포맷 함수
def formatting_func(example):
    return (
        f"<bos><start_of_turn>user\n"
        f"{example['instruction']}<end_of_turn>\n"
        f"<start_of_turn>model\n"
        f"{example['response']}<end_of_turn><eos>\n"
    )
 
# SFTConfig 구성
sft_config = SFTConfig(
    output_dir=OUTPUT_DIR,
    num_train_epochs=4, #2
    per_device_train_batch_size=2,
    per_device_eval_batch_size=2,
    gradient_accumulation_steps=2,
    save_strategy="steps",
    eval_strategy="steps",
    save_steps=500,
    eval_steps=100,
    logging_steps=25,
    learning_rate=2e-4,
    bf16=True,
    save_total_limit=2,
    load_best_model_at_end=True,
    report_to="tensorboard",
    max_seq_length=1024,
    label_names=["input_ids"],
)
 
# SFTTrainer 구성
trainer = SFTTrainer(
    model=model,
    train_dataset=train_dataset,
    eval_dataset=eval_dataset,
    peft_config=lora_config,
    formatting_func=formatting_func,
    args=sft_config,
)
 
# 학습 시작
torch.cuda.empty_cache() # 캐시 비우기
trainer.train()
 
# LoRA 어댑터 저장
trainer.model.save_pretrained(os.path.join(OUTPUT_DIR, "final"))
tokenizer.save_pretrained(os.path.join(OUTPUT_DIR, "final"))

위 코드를 train.py 파일로 저장하고, 필요한 라이브러리를 설치한 후 실행하면 학습이 진행됩니다. 준비된 훈련 데이터셋의 양에 따라 학습 시간은 달라질 수 있습니다. 보통 유의미한 데이터셋에 대해 4-8시간 정도 소요되며, 데이터셋이 많을 경우 며칠까지 소요될 수 있습니다.

LoRA 병합 및 저장

위의 학습이 완료되었다면, LoRA adapter를 병합하여 최종 모델을 저장할 수 있습니다.

한번에 병합하는 코드는 다음과 같습니다.

merge_lora.py

import os
from transformers import AutoModelForCausalLM, AutoTokenizer
from peft import PeftModel
 
BASE_MODEL_PATH = "../gemma-3-12b-it"  # 원본 Gemma3 모델 경로
LORA_ADAPTER_PATH = "./output/final"  # 학습 완료된 LoRA 어댑터 경로
OUTPUT_DIR = "./output/merged"  # 병합 결과 저장 폴더
 
 
def merge_lora_and_save(base_path, lora_path, output_path):
    # Base 모델 로드
    base_model = AutoModelForCausalLM.from_pretrained(base_path)
 
    # LoRA 어댑터 적용
    lora_model = PeftModel.from_pretrained(base_model, lora_path)
 
    # merge_and_unload 메서드를 사용하여 LoRA 어댑터 병합
    merged_model = lora_model.merge_and_unload()
 
    # 모델 저장
    os.makedirs(output_path, exist_ok=True)
    merged_model.save_pretrained(output_path)
 
    # 토크나이저 로드 및 저장
    tokenizer = AutoTokenizer.from_pretrained(base_path)
    tokenizer.save_pretrained(output_path)
 
if __name__ == "__main__":
    merge_lora_and_save(BASE_MODEL_PATH, LORA_ADAPTER_PATH, OUTPUT_DIR)

양자화 및 GGUF 파일 변환

최종 병합된 모델을 이제 Ollama에서 사용할 수 있도록 GGUF 형식으로 변환해 주어야 합니다.

먼저 llama.cpp 라이브러리를 설치합니다.

git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
pip install -r requirements.txt

양자화를 위해 llama.cpp를 빌드해 줍니다.

Windows의 경우 Visual Studio 2022 이상 설치 (C++ 데스크탑 개발 구성 포함)가 되어 있어야 합니다.

PowerShell 또는 VS Developer Command Prompt에서:

cd llama.cpp
mkdir build
cd build
cmake ..
cmake --build . --config Release

빌드가 완료되면 llama.cpp\build\bin\Release\llama-quantize.exe 파일이 생성됩니다.

먼저 병합된 모델을 llama.cpp의 convert_hf_to_gguf.py 스크립트를 사용하여 f16 GGUF 파일로 변환합니다.

python ..\llama.cpp\convert_hf_to_gguf.py ./output/merged --outfile gemma3-f16.gguf --outtype f16

Warning

만일 위 명령어 실행 중 토크나이저와 관련된 오류가 발생하면, 기본 모델 파일에서 토크나이저 파일 tokenizer.model 만 /output/merger 폴더에 복사해 주면 됩니다.

이제 gemma3-f16.gguf 파일이 생성되었습니다. 이 파일을 Ollama에서 양자화 합니다.

..llama.cpp\build\bin\Release\llama-quantize.exe gemma3-f16.gguf gemma3-q4k.gguf Q4_K_M

이번 가이드에서는 Q4_K_M 옵션을 사용하여 4bit 양자화를 수행합니다. 이 과정은 모델의 크기를 줄이고, Ollama에서 더 빠르게 로드할 수 있도록 합니다.
컴퓨터의 사양에 따라 Q4_K_S, Q4_K_M, Q8_0 등의 옵션을 선택할 수 있습니다.

Ollama에 모델 탑재

Ollama 명령어를 통해 먼저 기존에 임포트 된 Gemma3 모델의 modelfile을 확인합니다.

아래와 같이 ollama show 명령어를 사용하면 모델 적재 시 사용된 modelfile의 내용을 확인할 수 있습니다.

C:\>ollama show --modelfile gemma3:12b
 
# .. 중략 ...
 
TEMPLATE """{{- range $i, $_ := .Messages }}
{{- $last := eq (len (slice $.Messages $i)) 1 }}
{{- if or (eq .Role "user") (eq .Role "system") }}<start_of_turn>user
{{ .Content }}<end_of_turn>
{{ if $last }}<start_of_turn>model
{{ end }}
{{- else if eq .Role "assistant" }}<start_of_turn>model
{{ .Content }}{{ if not $last }}<end_of_turn>
{{ end }}
{{- end }}
{{- end }}"""
PARAMETER stop <end_of_turn>
PARAMETER temperature 1
PARAMETER top_k 64
PARAMETER top_p 0.95
LICENSE """Gemma Terms of Use

위 파일 내용에서 TEMPLATE 부분과 PARAMETER 부분을 참고하여 파인 튜닝된 모델에 대한 modelfile을 작성합니다.

FROM ./gemma3-q4k.gguf
 
TEMPLATE """{{- range $i, $_ := .Messages }}
{{- $last := eq (len (slice $.Messages $i)) 1 }}
{{- if or (eq .Role "user") (eq .Role "system") }}<start_of_turn>user
{{ .Content }}<end_of_turn>
{{ if $last }}<start_of_turn>model
{{ end }}
{{- else if eq .Role "assistant" }}<start_of_turn>model
{{ .Content }}{{ if not $last }}<end_of_turn>
{{ end }}
{{- end }}
{{- end }}<eos>"""
 
PARAMETER stop <end_of_turn>
PARAMETER stop <eos>
PARAMETER temperature 1
PARAMETER top_k 64
PARAMETER top_p 0.95
PARAMETER repeat_penalty 1.2
PARAMETER num_ctx 4096

FROM 부분은 양자화된 모델 파일의 경로를 지정합니다.
PARAMETER 부분은 모델의 동작 방식을 조정하는 파라미터들입니다. stop 파라미터는 모델이 응답을 중단할 조건을 지정합니다.
temperature 파라미터는 모델의 응답 다양성을 조절하는데, 값이 높을수록 더 창의적인 응답을 생성합니다.
top_k와 top_p는 샘플링 전략을 조정하여 모델의 응답 품질을 향상시킵니다.

위 파일 내용을 Modelfile 이름으로 저장합니다.

이제 아래 명령어로 Ollama에 모델을 임포트합니다.

ollama create gemma3-q4k -f Modelfile

모델의 이름과 파일명은 개인 취향에 맞춰 변경하시면 됩니다.

이렇게 하면 Ollama에서 파인튜닝된 나만의 모델을 사용할 수 있습니다.

맺음말

Gemma 3 12B 모델에 대해 LoRA + 4bit 양자화 + SFT 학습으로 LLM 모델을 파인튜닝하는 방법에 대해 알아보았습니다. 윈도우 로컬 학습을 기반으로 설명을 하였으나, 리눅스/맥은 물론 클라우드 환경(예: Colab, A100)에서도 약간의 수정을 통해 동일하게 학습이 가능합니다.

더 나아가 멀티 GPU 환경에서의 학습, 데이터 증강 및 샘플 필터링, LoRA 구성 변경(다른 target module 추가), inference 최적화 및 Deployment 전략 설계 등 다양한 확장 가능성이 있습니다.

문의사항이나 코멘트가 있으시면 댓글로 남겨주시기 바랍니다.

긴 글 읽어주셔서 감사합니다.