파인튜닝: QLoRA 실험¶

EXAONE-Deep-7.8B 모델을 민원 도메인에 특화하기 위한 QLoRA 파인튜닝 실험 설계, 실행 과정, 결과를 정리합니다.

실험 목적과 가설¶

연구 목적¶

한국어 특화 LLM인 EXAONE-Deep-7.8B를 민원 도메인에 특화하여 파인튜닝하고, 온프레미스 환경 배포를 위한 최적의 양자화 기법을 검증합니다.

핵심 가설¶

실험 파이프라인¶

graph TD
    subgraph "1단계: 데이터 준비"
        A1["AI Hub 원본 수집<br/>71,847건"] --> A2["PII 마스킹<br/>PIIMasker v2"]
        A2 --> A3["카테고리 균형화<br/>30% 샘플링 제한"]
        A3 --> A4["EXAONE Chat Template<br/>형식 변환"]
        A4 --> A5["Train/Val/Test 분할<br/>10,148 / 1,265 / 1,265"]
    end

    subgraph "2단계: QLoRA 파인튜닝"
        B1["EXAONE-Deep-7.8B<br/>BF16 로드"] --> B2["BitsAndBytes NF4<br/>4-bit 양자화"]
        B2 --> B3["LoRA 어댑터 부착<br/>r=16, alpha=32"]
        B3 --> B4["SFTTrainer 학습<br/>3 epochs"]
        B4 --> B5["LoRA 어댑터 저장<br/>~38MB"]
    end

    subgraph "3단계: 병합 & 양자화"
        C1["LoRA 어댑터"] --> C2["merge_and_unload()<br/>BF16 병합"]
        C2 --> C3["AWQ W4A16g128<br/>양자화"]
        C3 --> C4["최종 모델<br/>4.94GB"]
    end

    A5 --> B1
    B5 --> C1

QLoRA 방법론¶

QLoRA란?¶

QLoRA(Quantized Low-Rank Adaptation)는 양자화된 대규모 모델에 Low-Rank 어댑터를 부착하여 파인튜닝하는 기법입니다. 전체 모델을 4-bit로 양자화한 상태에서 소량의 학습 가능한 파라미터(LoRA 어댑터)만 업데이트합니다.

graph LR
    subgraph "기존 선형 레이어"
        W["W (frozen)<br/>4-bit NF4"]
    end
    subgraph "LoRA 어댑터"
        A["A (r x d)<br/>BF16"] --> B["B (d x r)<br/>BF16"]
    end
    X["입력 x"] --> W
    X --> A
    W --> Plus["(+)"]
    B --> Plus
    Plus --> Y["출력 y"]

양자화 설정 (BitsAndBytesConfig)¶

bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",          # NormalFloat4
    bnb_4bit_compute_dtype=torch.bfloat16,  # 연산은 BF16
    bnb_4bit_use_double_quant=True,      # 이중 양자화
)

LoRA 설정 (LoraConfig)¶

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

전체 7.8B 파라미터 중 약 0.5% 미만의 파라미터만 학습합니다.

SFTTrainer 구성¶

TRL(Transformer Reinforcement Learning) 라이브러리의 SFTTrainer를 사용하여 Supervised Fine-Tuning을 수행합니다.

학습 하이퍼파라미터¶

데이터 포맷팅¶

formatting_prompts_func을 통해 각 샘플을 EXAONE Chat Template 형식으로 변환합니다.

messages = [
    {"role": "system", "content": "당신은 지자체 민원 담당 공무원을 돕는 AI 어시스턴트입니다."},
    {"role": "user", "content": f"{instruction}\n\n{input}"},
    {"role": "assistant", "content": output},
]
text = tokenizer.apply_chat_template(messages, tokenize=False)

변환 결과:

[|system|]
당신은 지자체 민원 담당 공무원을 돕는 AI 어시스턴트입니다.
[|endofturn|]
[|user|]
{instruction}

{input}
[|endofturn|]
[|assistant|]
{output}
[|endofturn|]

W&B 실험 추적 연동¶

TrainingArguments에서 report_to="wandb"를 설정하여 모든 학습 메트릭을 자동으로 W&B에 기록합니다.

training_args = TrainingArguments(
    report_to="wandb",
    run_name=f"exaone-qlora-{datetime.now().strftime('%Y%m%d-%H%M')}",
    logging_steps=10,
    # ...
)

추적되는 메트릭: train_loss, eval_loss, learning_rate, train_runtime, train_samples_per_second

데이터셋 구성¶

AI Hub 데이터셋¶

데이터 분할¶

SPLIT_RATIOS = {
    "train": 0.80,      # 80% 학습용
    "validation": 0.10,  # 10% 검증용
    "test": 0.10         # 10% 평가용
}

전처리 파이프라인¶

1. PII 마스킹: PIIMasker로 이름, 주민번호, 전화번호 등 개인정보 자동 탐지 및 마스킹
2. 데이터 정제: 중복 제거, 길이 필터링 (최소 20자 이상)
3. 카테고리 균형화: 카테고리별 30% 샘플링 제한으로 편향 해소 (v2 개선)
4. 포맷 변환: EXAONE Chat Template 형식으로 변환

실험 설계¶

하이퍼파라미터 탐색 (Issue #67)¶

EXP-001 Baseline 결과 (M2)¶

xychart-beta
    title "EXP-001 Eval Loss 수렴 추이"
    x-axis "Step" [100, 200, 300, 400, 500, 600, 700, 781]
    y-axis "Eval Loss" 0.9 --> 1.25
    line [1.1938, 1.12, 1.08, 1.0443, 1.03, 1.025, 1.0179, 1.02]

v2 Retrain 결과 (프로덕션)¶

LoRA v1 vs v2 비교¶

v1의 문제점¶

v1 어댑터(umyunsang/civil-complaint-exaone-lora)는 다음과 같은 문제가 발견되어 폐기되었습니다.

v2 개선사항¶

환경 호환성 이슈 및 해결¶

transformers 5.x 호환성 패치¶

EXAONE 모델을 최신 transformers 버전에서 사용하기 위해 여러 호환성 패치가 필요했습니다.

이슈 1: check_model_inputs 삭제¶

transformers 5.3.0에서 check_model_inputs가 삭제되어 EXAONE 모델의 modeling_exaone.py에서 임포트 에러 발생.

# 해결: generic.py에 수동 정의
def check_model_inputs(func):
    return func

이슈 2: get_input_embeddings NotImplementedError¶

EXAONE 모델이 PEFT와 연동될 때 get_input_embeddings 미구현 에러 발생.

# 해결: 몽키 패치
try:
    model.get_input_embeddings()
except (NotImplementedError, AttributeError):
    model.get_input_embeddings = lambda: model.transformer.wte

이슈 3: evaluation_strategy 파라미터 변경¶

transformers 5.3.0 이상에서 파라미터명이 변경됨.

# 변경 전: evaluation_strategy="steps"
# 변경 후:
eval_strategy="steps"

Google Colab 실행 가이드¶

1. 런타임 설정¶

• 런타임 유형: GPU (A100 권장, L4는 OOM 가능)
• High-RAM 설정: 활성화 (40GB VRAM 이상 권장)

2. 패키지 설치¶

!pip install -q -U transformers datasets accelerate peft bitsandbytes trl wandb python-dotenv

3. 프로젝트 클론 및 W&B 로그인¶

!git clone https://github.com/GovOn-org/GovOn.git
%cd GovOn

import sys, os
sys.path.append(os.getcwd())

import wandb
wandb.login()

4. 파인튜닝 실행¶

!python src/training/train_qlora.py \
    --train_path data/processed/civil_complaint_train.jsonl \
    --val_path data/processed/civil_complaint_val.jsonl \
    --output_dir ./models/checkpoints/exaone-civil-qlora \
    --epochs 3 \
    --batch_size 4 \
    --grad_accum 4 \
    --lr 2e-4

5. 결과 백업¶

from google.colab import drive
drive.mount('/content/drive')
!cp -r ./models/checkpoints/exaone-civil-qlora /content/drive/MyDrive/

필수 라이브러리 버전¶

기대 효과 및 KPI 목표¶

참고 자료¶

• EXAONE-Deep-7.8B (HuggingFace)
• QLoRA: Efficient Finetuning of Quantized Language Models (Dettmers et al., 2023)
• LoRA: Low-Rank Adaptation of Large Language Models (Hu et al., 2021)
• W&B EXP-001 Run
• W&B v2 Retrain Run
• AI Hub 공공 민원 상담 LLM 데이터 (71852)