README.md

---
language:
- ko
license: mit
tags:
- hamster
- korean
- small-language-model
- educational
- onnx
- chatml
library_name: onnx
---

# 🐹 HamsterLM

HamsterLM은 **햄스터 캐릭터로 대화하는 작은 한국어 언어 모델**입니다.
브라우저에서 직접 실행할 수 있도록 ONNX로 변환되어 있으며, 교육 목적으로 처음부터 학습되었습니다.

[arman-bd/guppylm](https://github.com/arman-bd/guppylm)에서 영감을 받아 제작되었습니다.

## 모델 정보

| 항목 | 값 |
|------|------|
| 파라미터 | ~100M |
| 아키텍처 | Transformer 디코더 (RMSNorm + SwiGLU + RoPE) |
| 임베딩 차원 | 768 |
| 레이어 수 | 12 |
| 어텐션 헤드 | 12 |
| 최대 시퀀스 길이 | 128 |
| 어휘 크기 | 4,096 |
| 토크나이저 | ByteLevel BPE |
| 대화 포맷 | ChatML |
| 양자화 | int8 (Dynamic Quantization) |

## 학습 과정

### 1단계: 사전학습 (Pretrain)
- **데이터**: 한국어 위키피디아 (약 200만 청크)
- **목표**: 한국어 문법, 어순, 조사 등 기본 언어 패턴 학습
- **설정**: 20K iter, batch 32, LR 1e-3 (warmup + cosine decay)

### 2단계: SFT (Supervised Fine-Tuning)
- **데이터**: Claude Haiku API로 생성한 햄스터 대화 10,000개
- **목표**: 햄스터 캐릭터의 말투와 답변 스타일 학습
- **설정**: 5K iter, batch 32, LR 3e-4 (val loss 기준 best checkpoint 저장)
- **데이터 구성**:
  - 고정 질문 풀 기반 5,000개
  - AI 생성 다양한 질문 5,000개
  - 34개 카테고리 (인사, 음식, 감정, 철학 등)

## 파일

- `hamsterlm.onnx` - int8 양자화된 ONNX 모델 (~90MB)
- `tokenizer.json` - HuggingFace tokenizers 형식

## 사용 방법

이 모델은 `transformers`와 호환되지 않는 **커스텀 아키텍처**입니다.
ONNX Runtime을 직접 사용하여 추론해야 합니다.

### 브라우저 데모

[https://kciter.github.io/HamsterLM](https://kciter.github.io/HamsterLM) 에서 직접 사용해 볼 수 있습니다.
모든 추론이 브라우저에서 WASM으로 실행되며 서버는 사용하지 않습니다.

### 추론 예시

프롬프트는 다음 ChatML 형식을 따라야 합니다:

```
<|im_start|>user
{user_message}<|im_end|>
<|im_start|>assistant

```

브라우저/Node.js에서의 전체 추론 코드는 [GitHub 레포](https://github.com/kciter/HamsterLM)의
`web/app.js`를 참고하세요. 토크나이저 로드, 자기회귀 디코딩, top-k 샘플링이 구현되어 있습니다.

## 대화 예시

```
User: 자기소개 해봐
HamsterLM: 나는 햄스터야. 해바라기씨 엄청 좋아하고 볼주머니에 간식 모으는 게 특기지.

User: 볼주머니에 뭐 있어?
HamsterLM: 지금 호박씨 두 개 들어있어. 비상용이라 절대 못 줘.

User: 무서운 게 뭐야?
HamsterLM: 진공 청소기 소리. 생각만 해도 귀가 납작해져.
```

## 한계점

- **작은 모델**: 100M 파라미터로 학습 데이터 범위를 크게 벗어나는 질문은 잘 답하지 못합니다
- **짧은 컨텍스트**: 최대 128 토큰이라 긴 대화가 어렵습니다
- **도메인 제한**: 햄스터 관련 대화로만 학습되어 일반적인 질문(수학, 과학 등)은 다루지 않습니다
- **싱글턴 권장**: 웹 데모에서는 속도를 위해 단일 턴 대화만 지원합니다
- **양자화 영향**: int8 양자화로 인해 일부 표현에서 미세한 품질 저하가 있을 수 있습니다

## 학습 환경

- GPU: NVIDIA A100 (Colab Pro)
- 학습 시간: 사전학습 ~50분 + SFT ~15분

## 관련 자료

- **데이터셋**: [kciter/HamsterLM-SFT](https://huggingface.co/datasets/kciter/HamsterLM-SFT)
- **소스 코드**: [github.com/kciter/HamsterLM](https://github.com/kciter/HamsterLM)
- **영감을 준 프로젝트**: [GuppyLM](https://github.com/arman-bd/guppylm)

## 라이선스

MIT License