Qwen2.5-3B-Korean-QLoRA (PEFT Adapter)

Model Description

Qwen2.5-3B-Korean-QLoRA는 Qwen/Qwen2.5-3B-Instruct를 한국어로 파인튜닝한 LoRA 어댑터입니다.

이 리포지토리는 PEFT 어댑터만 제공하며, 사용 시 베이스 모델이 필요합니다.

Merged 모델이 필요하신 경우: MyeongHo0621/Qwen2.5-3B-Korean

🎯 Key Features

• 🇰🇷 Korean Optimization: 200,000개 고품질 한국어 대화 데이터로 학습
• 💾 Lightweight: 어댑터만 ~479MB (베이스 모델 6GB 대비)
• 🔬 Research Friendly: 파인튜닝 연구 및 실험에 적합
• 🚀 Fast Loading: LoRA 어댑터로 빠른 로딩 및 전환
• ⚖️ Apache 2.0: 상업적 사용 가능

---

🚀 Quick Start

Installation

pip install torch transformers peft

Basic Usage

from transformers import AutoModelForCausalLM, AutoTokenizer
from peft import PeftModel
import torch

# 1. 베이스 모델 로딩
base_model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen2.5-3B-Instruct",
    torch_dtype=torch.bfloat16,
    device_map="auto"
)

# 2. LoRA 어댑터 적용 (루트 경로 = 최종 모델)
model = PeftModel.from_pretrained(
    base_model,
    "MyeongHo0621/Qwen2.5-3B-Korean-QLoRA"
)
# 또는 final 폴더 사용: subfolder="final"

# 3. 토크나이저 로딩
tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen2.5-3B-Instruct")

# 4. 추론
messages = [
    {"role": "system", "content": "You are a helpful Korean assistant."},
    {"role": "user", "content": "한국의 수도는 어디인가요?"}
]

text = tokenizer.apply_chat_template(
    messages,
    tokenize=False,
    add_generation_prompt=True
)

inputs = tokenizer(text, return_tensors="pt").to(model.device)

with torch.no_grad():
    outputs = model.generate(
        **inputs,
        max_new_tokens=512,
        temperature=0.7,
        do_sample=True
    )

response = tokenizer.decode(outputs[0], skip_special_tokens=True)
print(response)

---

📦 Repository Structure

MyeongHo0621/Qwen2.5-3B-Korean-QLoRA/
├── (루트)                        # 최종 학습 모델 (step 4689)
│   ├── adapter_model.safetensors # LoRA 가중치 (~479MB)
│   ├── adapter_config.json       # LoRA 설정
│   ├── tokenizer.json            # 토크나이저
│   └── ...
└── final/                        # 모델 저장본 (백업)
    ├── adapter_model.safetensors
    └── ...

---

🔧 Training Details

Dataset

• Source: MyeongHo0621/smol-koreantalk
• Samples: 200,000 high-quality Korean conversational pairs
• Domain: General conversation, instruction following, knowledge Q&A

Training Configuration

Hyperparameter	Value
Base Model	Qwen/Qwen2.5-3B-Instruct
Method	QLoRA (4-bit NF4)
LoRA Rank (r)	64
LoRA Alpha	128
LoRA Dropout	0.05
Target Modules	q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj
Learning Rate	2e-4
Batch Size	32 (per device)
Gradient Accumulation	4 (effective: 128)
Warmup Ratio	0.1
Epochs	3
Total Steps	4689
Max Length	2048
Quantization	4-bit NF4 (training)

---

💡 Use Cases

✅ Recommended

• 파인튜닝 연구 및 실험
• LoRA 어댑터 비교 분석
• 메모리 효율적인 추론
• 빠른 모델 전환 (여러 LoRA 어댑터 교체)
• 교육 및 학습 목적

⚠️ Alternatives

• 프로덕션 서빙: MyeongHo0621/Qwen2.5-3B-Korean 권장 (Merged 모델)
• Ollama/Llama.cpp: MyeongHo0621/Qwen2.5-3B-Korean (GGUF 포함)

---

🔄 Merging the Adapter

어댑터를 베이스 모델과 병합하려면:

from transformers import AutoModelForCausalLM
from peft import PeftModel

# 베이스 모델 로딩
base_model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2.5-3B-Instruct")

# LoRA 어댑터 로딩
model = PeftModel.from_pretrained(base_model, "MyeongHo0621/Qwen2.5-3B-Korean-QLoRA")

# Merge
merged_model = model.merge_and_unload()

# 저장
merged_model.save_pretrained("./qwen25-3b-korean-merged")

이미 병합된 모델이 필요하시면 MyeongHo0621/Qwen2.5-3B-Korean을 사용하세요!

---

📊 Performance

Model	Size	Load Time	Memory (Inference)	Use Case
LoRA Adapter	~479MB	~5s	~4-6GB	Research, Experiments
Merged Model	~6GB	~10s	~4-6GB	Production, vLLM
GGUF Q4_K_M	~2GB	~3s	~2-3GB	Local, Ollama

---

🔗 Related Repositories

Merged Model (Production)

• MyeongHo0621/Qwen2.5-3B-Korean
  • Merged model (즉시 사용 가능)
  • GGUF files (Ollama, Llama.cpp)
  • vLLM, SGLang, Transformers 지원

Dataset

• MyeongHo0621/smol-koreantalk
  • 고품질 한국어 대화 데이터

---

📝 Citation

@misc{qwen25-korean-qlora-2025,
  author = {MyeongHo Shin},
  title = {Qwen2.5-3B-Korean-QLoRA: Korean LoRA Adapter for Qwen2.5-3B},
  year = {2025},
  publisher = {HuggingFace},
  howpublished = {\url{https://huggingface.co/MyeongHo0621/Qwen2.5-3B-Korean-QLoRA}},
}

---

🙏 Acknowledgments

• Base Model: Qwen2.5-3B-Instruct by Alibaba Cloud
• Dataset: smol-koreantalk
• Tools: Unsloth, PEFT, Transformers

---

📞 Contact

• Author: MyeongHo Shin
• HuggingFace: @MyeongHo0621

---

⚖️ License

Apache 2.0 - 상업적 사용, 수정, 배포 가능

---

💡 Tips

Faster Inference

# 4-bit 양자화로 메모리 절약
from transformers import BitsAndBytesConfig

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

base_model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen2.5-3B-Instruct",
    quantization_config=bnb_config,
    device_map="auto"
)

Multiple LoRA Adapters

# 여러 어댑터를 빠르게 전환
model.unload()
model = PeftModel.from_pretrained(base_model, "another-lora-adapter")

Training Your Own Adapter

이 어댑터를 기반으로 추가 파인튜닝:

from peft import get_peft_model, LoraConfig

# 새로운 LoRA 레이어 추가
peft_config = LoraConfig(
    r=64,
    lora_alpha=128,
    target_modules=["q_proj", "v_proj"],
    lora_dropout=0.05,
    task_type="CAUSAL_LM"
)

model = get_peft_model(model, peft_config)
# ... training code ...