Modelpublic

MyeongHo0621/Qwen2.5-3B-Korean-QLoRA

sourceHugging Faceapache-2.0updated 10mo agoView on Hugging Face

0likes16downloads

Model Card

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

bash

pip install torch transformers peft

Basic Usage

python

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	qproj, kproj, vproj, oproj, gateproj, upproj, 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

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

python

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](https://huggingface.co/MyeongHo0621/Qwen2.5-3B-Korean)
—Merged model (즉시 사용 가능)
—GGUF files (Ollama, Llama.cpp)
—vLLM, SGLang, Transformers 지원

Dataset

—[MyeongHo0621/smol-koreantalk](https://huggingface.co/datasets/MyeongHo0621/smol-koreantalk)
—고품질 한국어 대화 데이터

📝 Citation

bibtex

@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

python

# 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

python

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

Training Your Own Adapter

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

python

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 ...