🐹 HamsterLM

햄스터 캐릭터로 대화하는 작은 한국어 언어 모델

~100M 파라미터의 한국어 언어 모델을 처음부터 학습하여 브라우저에서 실행하는 프로젝트입니다. 사전학습, SFT, ONNX 변환 및 양자화, 웹 배포까지 전 과정을 직접 구현했습니다.

• 데모: kciter.github.io/HamsterLM
• 모델: huggingface.co/kciter/HamsterLM
• 데이터셋: huggingface.co/datasets/kciter/HamsterLM-SFT

프로젝트 구성

HamsterLM/
├── hamsterlm/              # Python 패키지
│   ├── config.py           # 하이퍼파라미터
│   ├── model.py            # RMSNorm + SwiGLU + RoPE 아키텍처
│   ├── dataset.py          # SFT 데이터셋
│   ├── pretrain_dataset.py # 사전학습 데이터셋
│   ├── tokenizer_utils.py  # BPE 토크나이저 학습
│   ├── train.py            # 학습 루프 (pretrain / SFT)
│   ├── chat.py             # CLI 대화 모드
│   ├── export.py           # ONNX 변환 + 양자화
│   └── __main__.py         # CLI 엔트리포인트
├── web/                    # 브라우저 데모 (정적 호스팅 가능)
│   ├── index.html
│   ├── style.css
│   └── app.js              # ONNX Runtime Web + BPE 토크나이저 JS 포팅
├── generate_pretrain_data.py  # 위키피디아 → pretrain 데이터
├── generate_sft_api.py     # Claude API로 SFT 대화 데이터 생성
├── sft_raw.jsonl           # 생성된 SFT 원본 (10,000개)
└── HamsterLM_Colab.ipynb   # 자체 완결형 학습 노트북 (Colab용)

모델 사양

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

학습 파이프라인

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, best checkpoint 저장
• 데이터 구성: 고정 질문 풀 5,000개 + AI 생성 질문 5,000개, 34개 카테고리

3단계: ONNX 변환 + int8 양자화

• torch.onnx.export(dynamo=False)로 ONNX 변환
• quantize_dynamic으로 int8 양자화 → 파일 크기 1/4 감소

설치

uv를 사용합니다.

git clone https://github.com/kciter/HamsterLM.git
cd HamsterLM
uv sync                    # 기본 의존성
uv sync --extra datagen    # SFT 데이터 생성 (anthropic SDK)
uv sync --extra export     # ONNX 변환/양자화

사용법

로컬 학습 (CLI)

# 1. 사전학습 데이터 준비 (위키피디아 다운로드)
uv run python generate_pretrain_data.py

# 2. SFT 데이터 생성 (Claude API 필요)
export ANTHROPIC_API_KEY="sk-ant-..."
uv run --extra datagen python generate_sft_api.py --count 10000

# 3. 토크나이저 학습
uv run hamsterlm --prepare

# 4. 사전학습 → SFT 순차 실행
uv run hamsterlm --train

# 또는 개별 실행
uv run hamsterlm --pretrain
uv run hamsterlm --sft

# 5. CLI 대화 모드
uv run hamsterlm --chat

# 6. ONNX 변환 + 양자화
uv run --extra export hamsterlm --export

Colab 학습

HamsterLM_Colab.ipynb를 Colab에서 열고 셀을 순서대로 실행합니다. 노트북은 패키지 설치 없이 단독으로 동작하도록 구성되어 있습니다.

웹 데모 로컬 실행

cd web
python -m http.server 8000
# 브라우저에서 http://localhost:8000

모델 파일은 HuggingFace Hub에서 자동 다운로드됩니다 (Cache API로 재방문 시 즉시 로딩).

데이터 생성

SFT 데이터 (generate_sft_api.py)

Claude API로 햄스터 대화를 생성합니다.

# 기본: 50% 고정 질문 풀 + 50% AI 생성 질문
python generate_sft_api.py --count 10000

# 모든 질문을 AI가 생성
python generate_sft_api.py --count 5000 --ai-questions

# 다른 모델 사용
python generate_sft_api.py --count 5000 --model claude-sonnet-4-5

원본 데이터는 data/sft_raw.jsonl에 append 모드로 누적되어 중간에 끊겨도 이어서 생성할 수 있습니다.

사전학습 데이터 (generate_pretrain_data.py)

HuggingFace Datasets에서 한국어 위키피디아를 다운받아 청크로 분할합니다.

python generate_pretrain_data.py --max-samples 2000000

아키텍처

• RMSNorm: 평균 계산 없이 RMS로만 정규화
• SwiGLU MLP: 게이트 메커니즘을 사용하는 MLP
• RoPE (Rotary Position Embedding): sin/cos 기반 실수 연산으로 구현 (ONNX 호환)
• Weight tying: 입력 임베딩과 출력 투영 가중치 공유

학습 설정

• Warmup + Cosine decay LR 스케줄
• Gradient clipping (max_norm=1.0)
• Best checkpoint 저장 (val loss 기준)
• 2단계 학습: 사전학습 → SFT

한계점

• 작은 모델: 학습 데이터 범위를 크게 벗어나는 질문은 잘 답하지 못함
• 짧은 컨텍스트: 최대 128 토큰이라 긴 대화가 어려움
• 도메인 제한: 햄스터 관련 대화로만 학습되어 일반 지식 질문은 다루지 않음

라이선스

MIT License