Upload README.md with huggingface_hub

README.md

@@ -1,3 +1,116 @@
----
-license: mit
----
+---
+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