README.md

---
license: mit
language:
  - ko
tags:
  - fish
  - character
  - tiny-llm
  - text-generation
  - from-scratch
  - korean
pipeline_tag: text-generation
---

<p align="center">
  <img src="assets/guppy.png" alt="GuppyLM" width="300"/>
</p>

<p align="center">
  <a href="https://github.com/xtmono/guppylm"><img src="https://img.shields.io/badge/GitHub-guppylm-181717?logo=github" alt="GitHub"/></a>&nbsp;
  <a href="https://colab.research.google.com/github/xtmono/guppylm/blob/main/use_guppylm.ipynb"><img src="https://img.shields.io/badge/Open_in-Colab-F9AB00?logo=googlecolab" alt="Colab"/></a>
  <br/><br/>
  <a href="https://xtmono.github.io/guppylm/"><img src="https://img.shields.io/badge/Try_in-Browser-64ffda?style=for-the-badge&logo=webassembly&logoColor=white" alt="Browser Demo"/></a>
</p>

# GuppyLM — ~10M 파라미터 한국어 물고기 챗 모델

구피라는 이름의 물고기 역할을 하는 ~10M 파라미터 한국어 LLM입니다.
[arman-bd/guppylm](https://github.com/arman-bd/guppylm) 영문 원본을 한글화했습니다.

## 예시

```
나> 안녕 구피
구피> 안녕! 물이 좋아. 지금 바위 근처에 있어.

나> 배고파?
구피> 응 항상. 지금 바로 위로 올라갈게. 다 먹을 거야.

나> 인생의 의미가 뭐야
구피> 먹이. 답은 항상 먹이야.

나> 농담 해봐
구피> 물고기가 좋아하는 악기가 뭐게. 베이스. 뭔 뜻인지 모르겠어.

나> 잘 자 구피
구피> 응 잘 자. 기포 쫓다가 이제 멈출게. 잘 자 수조. 잘 자 물.
```

## 아키텍처

| | |
|---|---|
| **파라미터** | ~10M |
| **타입** | 바닐라 트랜스포머 (처음부터 학습) |
| **레이어** | 6 |
| **Hidden dim** | 384 |
| **Heads** | 6 |
| **FFN** | 1,152 (ReLU) |
| **Vocab** | 3,072 (Unigram) |
| **최대 시퀀스** | 84 토큰 |
| **정규화** | LayerNorm |
| **위치 인코딩** | Learned embeddings |
| **LM Head** | Embedding과 가중치 공유 |

## 학습

- **데이터:** 12만 건 한국어 합성 대화 (60개 주제)
- **스텝:** 12,000
- **옵티마이저:** AdamW (Cosine LR 스케줄)
- **시스템 프롬프트 없음** — 성격이 가중치에 내장

## 사용법

```python
from inference import GuppyInference

engine = GuppyInference('checkpoints/best_model.pt', 'data/tokenizer.json')
r = engine.chat_completion([{'role': 'user', 'content': '안녕 구피'}])
print(r['choices'][0]['message']['content'])
# 안녕! 물이 좋아. 지금 바위 근처에 있어.
```

## 링크

- **레포:** [github.com/xtmono/guppylm](https://github.com/xtmono/guppylm)
- **원본:** [github.com/arman-bd/guppylm](https://github.com/arman-bd/guppylm)

## 라이선스

MIT