Qwen3.6-27B-QLoRA-Adaper

📌 모델 개요 (TL;DR)

---

🎯 모델 개발 배경

해외에서 공개된 오픈소스 LLM은 한국어 일반 능력은 우수하나, 아래 영역에서 한국 기업 환경에 직접 투입하기에는 한계가 있었습니다.

• 한국 사회 규범 / 가치관 / 생활문화 에 대한 미세한 맥락 이해
• 한국 기업문화 (위계, 보고체계, 의전, 회의 매너 등) 의 관행 반영
• 한국식 보고서 / 품의서 / 메일 / 회의록 등 실무 문서 작성 톤앤매너
• AI Agent 워크플로우 에서 한국적 업무 맥락을 고려한 도구 호출/판단

본 어댑터는 이 간극을 메우기 위해, 베이스 모델의 일반 능력은 유지한 채 한국 기업 도메인 특화 지식·문체·판단력만을 LoRA로 주입하는 것을 목표로 학습되었습니다.

---

📚 학습 데이터

• 총 규모: 약 360,000 instances (instruction-response 또는 multi-turn)
• 형식: LLaMA-Factory qwen3_6 템플릿에 맞춘 SFT 포맷
• 품질 관리: 중복 제거, PII 마스킹, 길이 분포 정규화, 평가셋과 누수 차단(중복 검출) 수행

⚠️ 데이터는 라이선스 및 사내 보안 정책에 따라 원본을 공개하지 않습니다.

---

🛠 학습 방법 (QLoRA + LLaMA-Factory)

VRAM 효율과 안정성을 동시에 잡기 위해 QLoRA(NF4 + Double Quant) 위에 BF16 LoRA 어댑터를 학습했습니다.

핵심 하이퍼파라미터

yaml
Copy code
### model
model_name_or_path: Qwen/Qwen3.6-27B
trust_remote_code: true

### method
stage: sft
finetuning_type: lora
lora_target: all          # 모든 linear에 LoRA — 표현력 / 안정성 균형
lora_rank: 32
lora_alpha: 64            # alpha = 2 × rank (스케일 1/2)
lora_dropout: 0.05        # 약한 정규화

### quantization (QLoRA)
quantization_bit: 4
quantization_method: bnb
double_quantization: true
quantization_type: nf4

### dataset
template: qwen3_6
cutoff_len: 2048
packing: false            # 멀티턴 손실 왜곡 방지

### train
per_device_train_batch_size: 1
gradient_accumulation_steps: 16   # effective batch = 1 × 16 × 2 GPU = 32
learning_rate: 5.0e-5
num_train_epochs: 2.0
lr_scheduler_type: cosine
warmup_ratio: 0.05
bf16: true                       # fp16 금지 (학습 진동 방지)
max_grad_norm: 1.0               # 그래디언트 클리핑
weight_decay: 0.01
optim: adamw_torch
adam_beta2: 0.95                 # 손실 스파이크 완화
gradient_checkpointing: true     # VRAM 절감

### eval
eval_strategy: steps
eval_steps: 500

### acceleration
flash_attn: sdpa
enable_liger_kernel: true        # VRAM 절감 + throughput 향상

학습 설계 의도 (Why these choices)

• lora_target: all — Q/K/V/O 뿐 아니라 MLP 계열까지 포함, 도메인 문체·지식 흡수에 유리. 추가 VRAM 비용은 NF4 + checkpointing으로 흡수.
• rank=32, alpha=64 — α = 2·r 규칙으로 LoRA 스케일을 0.5로 두어 베이스 일반 능력 훼손을 최소화. 한국 도메인 지식 주입에는 충분한 capacity.
• bf16 강제 — FP16의 mantissa 부족으로 인한 손실 스파이크 회피. RTX 5090 / H100급에서 안정적.
• adam_beta2=0.95 — 기본 0.999 대비 단기 변동에 빠르게 반응해 한국어 도메인 손실 진동 완화.
• packing: false — 멀티턴 한국어 대화의 토큰 경계 왜곡 방지. 손실 계산 정확도 우선.
• gradient_accumulation=16 — 단일 GPU 메모리 한계 내에서 큰 effective batch로 도메인 분포 안정화.
• NEFTune 미적용 — 노이즈가 한국식 정형 문서(보고서/품의서) 톤을 흐릴 수 있어 보수적으로 제외.

학습 환경

• GPU: NVIDIA RTX 5090 × 2 (BF16 + NF4 QLoRA)
• Framework: LLaMA-Factory, PEFT, bitsandbytes, Liger-Kernel
• Mixed Precision: BF16 (어댑터) / NF4 (베이스 가중치)

---

📊 평가 (Evaluation)

자체 구축한 한국 도메인 평가셋(100문항) 으로 베이스 모델과 본 어댑터 적용 모델을 비교했습니다.

평가셋 구성

평가 방식

• GPT-as-Judge (ChatGPT 기반): 동일 프롬프트에 대한 두 모델 응답을 블라인드로 채점 (정확성 / 한국적 적합성 / 실무 활용성 가중 평균)
• 동률/우열을 페어와이즈 + 5점 척도 양쪽으로 교차 검증

결과 요약

특히 기업 보고서/품의서 톤앤매너와 한국식 의사결정 맥락 반영 항목에서 베이스 대비 가장 큰 개선을 보였습니다.

⚠️ 평가셋은 100문항 규모로 절대치보다는 상대적 개선폭의 지표로 해석하시기 바랍니다. 대규모 한국어 벤치(KoBEST, Ko-MT-Bench 등) 결과는 추후 업데이트 예정입니다.

---

🚀 사용법 — vLLM Multi-LoRA Serving

본 모델은 어댑터만 배포됩니다. 베이스 모델은 별도로 로드하고, vLLM의 --enable-lora 옵션으로 어댑터를 결합해 서빙합니다.

1) 어댑터 다운로드

bash
Copy code
huggingface-cli download <YOUR_HF_ID>/<THIS_REPO_NAME> \
  --local-dir ./adapters/qwen3-ft

또는 Python:

python
Copy code
from huggingface_hub import snapshot_download

adapter_path = snapshot_download(
    repo_id="<YOUR_HF_ID>/<THIS_REPO_NAME>",
    local_dir="./adapters/qwen3-ft",
)
print(adapter_path)

2) vLLM 서버 기동 (FP8 베이스 + BF16 LoRA)

bash
Copy code
#!/bin/bash
# Qwen3.6-27B-FP8 + Korean Enterprise QLoRA Adapter

ADAPTER_PATH="./adapters/qwen3-ft"
MODEL_NAME="Qwen/Qwen3.6-27B-FP8"      # FP8 베이스: ~27GB, BF16 대비 절반
LORA_MODULE_NAME="qwen3-ft"            # API 호출 시 model= 에 사용할 이름
PORT=8000
GPU_COUNT=2                            # RTX 5090 × 2 (단일 GPU도 가능)

source "$(conda info --base)/etc/profile.d/conda.sh"
conda activate vllm

vllm serve "${MODEL_NAME}" \
    --enable-lora \
    --lora-modules "${LORA_MODULE_NAME}=${ADAPTER_PATH}" \
    --max-lora-rank 32 \
    --dtype auto \
    --kv-cache-dtype auto \
    --tensor-parallel-size ${GPU_COUNT} \
    --gpu-memory-utilization 0.90 \
    --max-model-len 8192 \
    --max-num-seqs 32 \
    --enable-auto-tool-choice \
    --tool-call-parser qwen3_xml \
    --host 0.0.0.0 \
    --port ${PORT} \
    --trust-remote-code

단일 GPU(예: RTX 5090 32GB) 에서도 FP8 27B(~27GB)로 충분히 구동 가능합니다. --tensor-parallel-size 1, --max-model-len 4096, --max-num-seqs 16 권장.

3) Python 클라이언트 — OpenAI 호환 API

vLLM이 OpenAI 호환 엔드포인트를 제공하므로 openai SDK를 그대로 사용할 수 있습니다. 호출 시 model 파라미터에 어댑터 이름(qwen3-ft)을 넘기면 어댑터가 적용되고, 베이스 모델명을 넘기면 베이스만 추론됩니다.

python
Copy code
# pip install openai
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="EMPTY",  # vLLM은 키 검증을 하지 않음
)

SYSTEM_PROMPT = (
    "당신은 한국 기업 환경에 정통한 업무 어시스턴트입니다. "
    "한국식 보고체계, 직급 관행, 정중한 비즈니스 톤을 유지하세요."
)

resp = client.chat.completions.create(
    model="qwen3-ft",   # ← 어댑터 적용. 베이스만 쓰려면 "Qwen/Qwen3.6-27B-FP8"
    messages=[
        {"role": "system", "content": SYSTEM_PROMPT},
        {"role": "user", "content":
            "신규 SaaS 도입 품의서를 작성해 주세요. "
            "도입 배경, 기대효과, 예산(연 1.2억), 리스크, 결재선 포함."},
    ],
    temperature=0.3,
    top_p=0.9,
    max_tokens=1500,
)

print(resp.choices[0].message.content)

4) 베이스 vs 어댑터 A/B 비교 (동일 서버, 두 모델명)

python
Copy code
from openai import OpenAI
client = OpenAI(base_url="http://localhost:8000/v1", api_key="EMPTY")

prompt = "팀장에게 일정 지연을 보고하는 정중한 메일을 작성해줘. 사유는 외주사 산출물 지연."

for model_name in ["Qwen/Qwen3.6-27B-FP8", "qwen3-ft"]:
    out = client.chat.completions.create(
        model=model_name,
        messages=[{"role": "user", "content": prompt}],
        temperature=0.2, max_tokens=600,
    )
    print(f"\n===== {model_name} =====")
    print(out.choices[0].message.content)

5) (옵션) PEFT로 로컬 추론 — 머지 없이 어댑터 로드

vLLM 없이 로컬에서 간단히 확인하고 싶을 때:

python
Copy code
# pip install transformers peft accelerate bitsandbytes
import torch
from transformers import AutoTokenizer, AutoModelForCausalLM, BitsAndBytesConfig
from peft import PeftModel

BASE = "Qwen/Qwen3.6-27B"
ADAPTER = "<YOUR_HF_ID>/<THIS_REPO_NAME>"

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

tok = AutoTokenizer.from_pretrained(BASE, trust_remote_code=True)
base = AutoModelForCausalLM.from_pretrained(
    BASE, quantization_config=bnb, device_map="auto", trust_remote_code=True,
)
model = PeftModel.from_pretrained(base, ADAPTER)   # 어댑터 결합 (머지 X)
model.eval()

msgs = [
    {"role": "system", "content": "당신은 한국 기업 환경에 정통한 어시스턴트입니다."},
    {"role": "user", "content": "주간 업무보고 양식을 한국 대기업 스타일로 만들어줘."},
]
inputs = tok.apply_chat_template(msgs, add_generation_prompt=True, return_tensors="pt").to(model.device)
out = model.generate(inputs, max_new_tokens=800, do_sample=True, temperature=0.3, top_p=0.9)
print(tok.decode(out[0][inputs.shape[1]:], skip_special_tokens=True))

---

🧩 왜 "머지 없이 분리 배포" 인가

본 모델은 의도적으로 베이스 ⊕ 어댑터 분리 배포 전략을 택했습니다.

1. 베이스 모델 단일 적재 + 다중 도메인 어댑터 — vLLM --enable-lora로 동일 베이스 위에 여러 어댑터(예: 기업문화용 / 법무용 / CS용)를 동시에 핫스왑.
2. 저장공간 / 배포 비용 최소화 — 27B 풀모델 재배포 대비 어댑터(수백 MB)만 갱신.
3. 베이스 업그레이드 호환성 — 동일 아키텍처 베이스 갱신 시 어댑터만 재학습/재평가.
4. FP8 베이스 + BF16 LoRA 결합 — VRAM은 FP8로 절약, 학습된 표현력은 BF16 LoRA로 보존.

---

⚠️ 한계 및 주의사항 (Limitations)

• 본 어댑터는 한국 사회·기업 도메인 강화가 목적이므로, 비한국·비업무 도메인에서는 베이스 대비 큰 차이가 없을 수 있습니다.
• 법률 · 의료 · 회계 등 고위험 영역의 산출물은 반드시 전문가 검수가 필요합니다.
• 평가셋이 100문항으로 소규모이므로, 절대 성능 수치보다는 상대 개선폭으로 해석하시기 바랍니다.
• 학습 데이터에 PII 마스킹을 적용했으나, 베이스 모델 고유의 hallucination 가능성은 여전히 존재합니다.
• 어댑터는 Qwen3.6-27B 계열 베이스에서만 정상 동작합니다.

---

📜 라이선스 & 인용

• License: Apache-2.0 (어댑터 가중치 기준). 베이스 모델 라이선스(Qwen License)는 별도 준수 필요.
• 본 어댑터를 사용한 산출물은 베이스 모델 라이선스를 함께 따릅니다.

Citation

bibtex
Copy code
@misc{qwen3_27b_korean_enterprise_qlora,
  title  = {Qwen3.6-27B Korean Enterprise QLoRA Adapter},
  author = {<YOUR NAME>},
  year   = {2026},
  howpublished = {\url{https://huggingface.co/<YOUR_HF_ID>/<THIS_REPO_NAME>}},
  note   = {QLoRA NF4 4-bit fine-tuning on ~360K Korean social/enterprise instances, served via vLLM Multi-LoRA}
}

Acknowledgements

• Qwen Team — Qwen3.6-27B 베이스 공개
• LLaMA-Factory — 학습 파이프라인
• vLLM — Multi-LoRA 서빙
• bitsandbytes — NF4 QLoRA
• PEFT — LoRA 구현

---

🧑‍💻 작성자 노트 (Engineering Highlights)

이 저장소는 다음 역량을 실제 산출물로 증명하기 위해 공개합니다.

1. 대규모 한국어 데이터 큐레이션 — 36만 건 규모의 한국 사회·기업 도메인 SFT 데이터 설계 / 정제 / 품질 관리 / 평가셋 누수 차단
2. QLoRA 양자화 학습 숙련도 — NF4 + Double Quant + BF16 LoRA, lora_target: all, α = 2·r, adam_beta2=0.95 등 안정적 수렴을 위한 의도된 선택
3. 추론 최적화 / 운영 설계 — vLLM Multi-LoRA, FP8 베이스 + BF16 어댑터 결합, tensor parallel, KV cache dtype, auto tool-choice 구성
4. 평가 설계 — 자체 도메인 평가셋 + GPT-as-Judge, 베이스 대비 도메인별 +10~15%p 상대 개선 입증
5. 배포 전략 — 어댑터 분리 배포로 멀티 도메인 핫스왑 / 운영 비용 최소화 / 베이스 업그레이드 호환성 확보

한국 기업 환경에 즉시 투입 가능한 도메인-특화 LLM을, 데이터 → 학습 → 양자화 → 평가 → 서빙의 전체 파이프라인으로 일관되게 구축한 사례입니다.