SEOKDONG/Qwen3.6-27B-QLoRA-Adaper
114
Qwen3.6-27B Korean Enterprise QLoRA Adapter
Qwen3.6-27B 베이스 모델 위에 한국 사회·문화 규범과 한국 기업문화·업무 도메인에 특화하여 학습한 QLoRA(NF4 4-bit) 어댑터입니다. 베이스 모델과 어댑터를 머지하지 않고 분리 배포하여, vLLM의 멀티-LoRA 서빙 기능으로 단일 베이스 모델에 여러 도메인 어댑터를 동시에 운영할 수 있도록 설계되었습니다.
📌 모델 개요 (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 어댑터를 학습했습니다.
핵심 하이퍼파라미터
### 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) 어댑터 다운로드
huggingface-cli download <YOUR_HF_ID>/<THIS_REPO_NAME> \
--local-dir ./adapters/qwen3-ft또는 Python:
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)
#!/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)을 넘기면 어댑터가 적용되고, 베이스 모델명을 넘기면 베이스만 추론됩니다.
# 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 비교 (동일 서버, 두 모델명)
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 없이 로컬에서 간단히 확인하고 싶을 때:
# 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))🧩 왜 "머지 없이 분리 배포" 인가
본 모델은 의도적으로 베이스 ⊕ 어댑터 분리 배포 전략을 택했습니다.
- 베이스 모델 단일 적재 + 다중 도메인 어댑터 — vLLM
--enable-lora로 동일 베이스 위에 여러 어댑터(예: 기업문화용 / 법무용 / CS용)를 동시에 핫스왑. - 저장공간 / 배포 비용 최소화 — 27B 풀모델 재배포 대비 어댑터(수백 MB)만 갱신.
- 베이스 업그레이드 호환성 — 동일 아키텍처 베이스 갱신 시 어댑터만 재학습/재평가.
- FP8 베이스 + BF16 LoRA 결합 — VRAM은 FP8로 절약, 학습된 표현력은 BF16 LoRA로 보존.
⚠️ 한계 및 주의사항 (Limitations)
- 본 어댑터는 한국 사회·기업 도메인 강화가 목적이므로, 비한국·비업무 도메인에서는 베이스 대비 큰 차이가 없을 수 있습니다.
- 법률 · 의료 · 회계 등 고위험 영역의 산출물은 반드시 전문가 검수가 필요합니다.
- 평가셋이 100문항으로 소규모이므로, 절대 성능 수치보다는 상대 개선폭으로 해석하시기 바랍니다.
- 학습 데이터에 PII 마스킹을 적용했으나, 베이스 모델 고유의 hallucination 가능성은 여전히 존재합니다.
- 어댑터는
Qwen3.6-27B계열 베이스에서만 정상 동작합니다.
📜 라이선스 & 인용
- License: Apache-2.0 (어댑터 가중치 기준). 베이스 모델 라이선스(Qwen License)는 별도 준수 필요.
- 본 어댑터를 사용한 산출물은 베이스 모델 라이선스를 함께 따릅니다.
Citation
@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)
이 저장소는 다음 역량을 실제 산출물로 증명하기 위해 공개합니다.
- 대규모 한국어 데이터 큐레이션 — 36만 건 규모의 한국 사회·기업 도메인 SFT 데이터 설계 / 정제 / 품질 관리 / 평가셋 누수 차단
- QLoRA 양자화 학습 숙련도 — NF4 + Double Quant + BF16 LoRA,
lora_target: all, α = 2·r,adam_beta2=0.95등 안정적 수렴을 위한 의도된 선택 - 추론 최적화 / 운영 설계 — vLLM Multi-LoRA, FP8 베이스 + BF16 어댑터 결합, tensor parallel, KV cache dtype, auto tool-choice 구성
- 평가 설계 — 자체 도메인 평가셋 + GPT-as-Judge, 베이스 대비 도메인별 +10~15%p 상대 개선 입증
- 배포 전략 — 어댑터 분리 배포로 멀티 도메인 핫스왑 / 운영 비용 최소화 / 베이스 업그레이드 호환성 확보
한국 기업 환경에 즉시 투입 가능한 도메인-특화 LLM을, 데이터 → 학습 → 양자화 → 평가 → 서빙의 전체 파이프라인으로 일관되게 구축한 사례입니다.
