SEOKDONG

Qwen3.6-27B-QLoRA-Adaper

README

License: apache-2.0

📌 모델 개요 (TL;DR)

Table with columns: 항목, 내용
항목	내용
Base Model	`Qwen/Qwen3.6-27B` (서빙 시 FP8 변형 사용 가능)
Adapter Type	LoRA (PEFT) — 분리 배포(Non-merged)
Quantization (Train)	QLoRA, NF4 4-bit + Double Quantization (bitsandbytes)
LoRA Config	rank=32, alpha=64, dropout=0.05, target=`all-linear`
Train Framework	LLaMA-Factory
Train Data	한국 사회규범·가치관·문화 + 한국 기업문화·규범·업무 약 360,000건
Train Precision	BF16 (어댑터 가중치)
Serving	vLLM Multi-LoRA (베이스 FP8 + LoRA BF16 동적 결합)
Eval	자체 평가셋 100문항, GPT-as-Judge, 도메인별 베이스 대비 +10 ~ +15%p

🎯 모델 개발 배경

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

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

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

📚 학습 데이터

Table with columns: 카테고리, 비중(개략), 내용
카테고리	비중(개략)	내용
한국 사회규범·가치관	~30%	예의, 호칭, 세대 간 소통, 공공질서, 한국적 의사결정 맥락
한국 문화·역사·제도	~20%	명절, 관습, 행정·법률 제도, 교육·의료 시스템 등
한국 기업문화·규범	~25%	보고체계, 직급/직책, 회식·의전, 컴플라이언스 기본
기업 업무 실무	~20%	품의서, 기안문, 회의록, 보고메일, 영업·기획 산출물
AI Agent 수행 시나리오	~5%	한국 업무 맥락을 가진 멀티-스텝 도구 호출 / 판단

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

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

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

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

핵심 하이퍼파라미터

yaml
### 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문항) 으로 베이스 모델과 본 어댑터 적용 모델을 비교했습니다.

평가셋 구성

Table with columns: 도메인, 문항 수(개략), 평가 포인트
도메인	문항 수(개략)	평가 포인트
한국 문화 · 역사 · 제도	~35	사실 정확성, 맥락 이해, 한국적 뉘앙스
한국 기업문화 · 업무 · 보고서 작성	~40	톤앤매너, 양식 적합성, 실무 적용성
AI Agent 수행능력	~25	멀티스텝 추론, 도구 호출 적절성, 한국 업무 맥락

평가 방식

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

결과 요약

Table with columns: 도메인, Base (Qwen3.6-27B), + QLoRA Adapter (본 모델), Δ
도메인	Base (Qwen3.6-27B)	+ QLoRA Adapter (본 모델)	Δ
한국 문화·역사·제도	기준	+10 ~ +12%p	🔼
기업문화·업무·보고서	기준	+13 ~ +15%p	🔼🔼
AI Agent 수행	기준	+10 ~ +12%p	🔼

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

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

🚀 사용법 — vLLM Multi-LoRA Serving

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

1) 어댑터 다운로드

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

또는 Python:

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)

bash
#!/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
# 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
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
# 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

bibtex
@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을, 데이터 → 학습 → 양자화 → 평가 → 서빙의 전체 파이프라인으로 일관되게 구축한 사례입니다.

Available on FriendliAI

Dedicated Endpoints

Run this model inference on single tenant GPU with unmatched speed and reliability at scale.

Learn more

Model Details

Model Provider