# 작은 언어 모델 GuppyLM으로 언어 모델의 작동 원리를 직접 체험하기 > Clean Markdown view of GeekNews topic #28270. Use the original source for factual precision when an external source URL is present. ## Metadata - GeekNews HTML: [https://news.hada.io/topic?id=28270](https://news.hada.io/topic?id=28270) - GeekNews Markdown: [https://news.hada.io/topic/28270.md](https://news.hada.io/topic/28270.md) - Type: GN+ - Author: [neo](https://news.hada.io/@neo) - Published: 2026-04-07T09:40:43+09:00 - Updated: 2026-04-07T09:40:43+09:00 - Original source: [github.com/arman-bd](https://github.com/arman-bd/guppylm) - Points: 46 - Comments: 1 ## Summary **9백만 파라미터**짜리 초소형 언어 모델로, **Colab 노트북 하나로 5분이면 학습**이 끝납니다. 데이터 생성부터 토크나이저, 학습, 추론까지 전 과정이 하나의 환경에서 돌아가기 때문에 LLM의 작동 원리를 **직접 손으로 만져보며 이해**하기에 좋습니다. GQA, RoPE 같은 복잡한 기법 없이 **기본형 Transformer만** 사용한 것도 교육 목적에 딱 맞고요. AI 도구를 쓰는 것과 별개로, **내부 원리를 한 번쯤 직접 체험해보고 싶은 분들에게** 추천합니다. ## Topic Body - 약 **9백만 개 파라미터**를 가진 초소형 언어 모델로, **Colab 노트북 하나로 5분 내 학습** 가능한 구조 - **데이터 생성부터 토크나이저, 모델 학습, 추론까지** 전 과정을 단일 환경에서 수행하며, **브라우저·Colab·로컬** 모두 지원 - **수중 환경을 상상하는 캐릭터 ‘Guppy’** 로 설계되어, 짧고 단순한 문장으로 대화하며 **교육용 투명성**에 초점 - **기본형 Transformer 아키텍처**를 사용해 복잡한 기법 없이도 언어 모델의 핵심 구조를 명확히 보여줌 - **HuggingFace 공개 데이터셋과 MIT 라이선스**로 누구나 실험·학습 가능한 오픈소스 프로젝트 --- ### GuppyLM 개요 - **GuppyLM**은 약 **9백만 개 파라미터**를 가진 초소형 언어 모델로, 물고기 캐릭터 **‘Guppy’** 처럼 대화하는 모델 - **Colab 노트북 하나로 5분 내 직접 학습 가능한 LLM**을 목표로 설계되어, 데이터 생성부터 토크나이저, 모델 구조, 학습 루프, 추론까지 전 과정을 단일 환경에서 수행 가능 - 대규모 GPU 클러스터나 전문 지식 없이도 **언어 모델의 내부 작동 원리를 직접 체험**할 수 있도록 제작 - 대규모 모델처럼 긴 텍스트를 생성하지는 않지만, **입력·가중치 학습·출력 생성의 전 과정을 투명하게 보여주는 교육용 모델** - **브라우저, Colab, 로컬 환경**에서 모두 실행 가능하며, HuggingFace를 통해 데이터셋과 모델이 공개됨 ### 모델 특성 - GuppyLM은 **물, 온도, 빛, 진동, 먹이** 등 수중 환경을 중심으로 사고하는 캐릭터 - **짧고 소문자로 된 문장**을 사용하며, 인간의 추상 개념(돈, 정치 등)을 이해하지 않음 - **친근하고 호기심 많으며 단순한 성격**을 가짐 - 학습 데이터는 **60개 주제, 6만 개 합성 대화 샘플**로 구성되어 있으며, 단일 GPU에서 약 5분 만에 학습 가능 - 모델 크기가 작아 **브라우저 내 WebAssembly 기반 추론**도 가능 ### 아키텍처 - **파라미터 수:** 8.7M - **레이어 수:** 6 - **히든 차원:** 384 - **어텐션 헤드:** 6 - **FFN 차원:** 768 (ReLU) - **어휘 크기:** 4,096 (BPE) - **최대 시퀀스 길이:** 128 토큰 - **정규화:** LayerNorm - **포지션 임베딩:** 학습형 - **LM 헤드:** 임베딩과 가중치 공유 - **GQA, RoPE, SwiGLU, early exit** 등 복잡한 기법은 사용하지 않은 **기본형 Transformer 구조** ### 성격 및 대화 주제 - Guppy는 **짧은 문장**, **소문자 표현**, **감각 중심 사고**로 대화 - **음식, 물, 빛, 수조, 거품, 반사, 수면, 외부 세계** 등 다양한 주제에 반응 - 주요 60개 주제에는 **인사, 감정, 온도, 먹이, 빛, 물, 수조, 소음, 외로움, 꿈, 계절, 농담, 사랑, 건강, TV** 등이 포함됨 ### 실행 및 사용 방법 - ## 브라우저에서 실행 - WebAssembly 기반으로 **로컬 추론** 수행 - 약 **10MB 크기의 양자화된 ONNX 모델**을 다운로드하여 서버나 API 키 없이 실행 가능 - ## Colab에서 채팅 - HuggingFace에서 사전 학습된 모델을 다운로드해 **대화형 인터페이스**로 사용 - 모든 셀을 실행하면 바로 채팅 가능 - ## Colab에서 학습 - 런타임을 **T4 GPU**로 설정 후 모든 셀 실행 - 데이터셋 다운로드, 토크나이저 학습, 모델 학습, 테스트까지 자동 수행 - 결과 모델을 HuggingFace에 업로드하거나 로컬로 저장 가능 - ## 로컬 환경에서 채팅 - `pip install torch tokenizers` 설치 후 `python -m guppylm chat` 명령으로 실행 - 대화가 길어지면 **128토큰 한계**로 품질 저하 발생 - 단일 프롬프트 입력 후 응답만 받고 종료하는 모드도 지원 ### 데이터셋 - HuggingFace의 **arman-bd/guppylm-60k-generic** 데이터셋 사용 - **샘플 수:** 60,000 (훈련 57K / 테스트 3K) - **형식:** `{"input": "...", "output": "...", "category": "..."}` - **카테고리 수:** 60 - **생성 방식:** 템플릿 기반 합성 데이터 - 약 60개의 템플릿, 30개 수조 객체, 17개 먹이 종류, 25개 활동 조합으로 **약 16,000개 고유 출력 생성** ### 프로젝트 구조 - ## guppylm/ - `config.py`: 모델 및 학습 하이퍼파라미터 - `model.py`: 기본 Transformer 모델 - `dataset.py`: 데이터 로딩 및 배치 처리 - `train.py`: 학습 루프 (cosine LR, AMP) - `generate_data.py`: 60개 주제 대화 데이터 생성 - `eval_cases.py`: 테스트 케이스 - `prepare_data.py`: 데이터 준비 및 토크나이저 학습 - `inference.py`: 채팅 인터페이스 - ## tools/ - `make_colab.py`: Colab 노트북 생성 - `export_onnx.py`: ONNX 모델로 내보내기 (uint8 양자화) - `export_dataset.py`: 데이터셋을 HuggingFace에 업로드 - `dataset_card.md`: HuggingFace용 데이터셋 설명 - ## docs/ - `index.html`: 브라우저 데모 (ONNX + WASM) - `download.sh`: 모델 및 토크나이저 다운로드 - `model.onnx`: 양자화된 모델 (~10MB) - `tokenizer.json`: BPE 토크나이저 - `guppy.png`: 로고 이미지 ### 설계 결정 - ## 시스템 프롬프트 제거:**9M 모델은 조건부 지시를 따르기 어려워, 모든 샘플에 동일한 프롬프트를 사용하는 대신**성격을 가중치에 직접 내장 - 이를 통해 추론 시 약 60토큰 절약 - **단일 턴 대화:** 128토큰 제한으로 인해 3~4턴 이후 품질 저하 발생 - Guppy의 ‘금붕어 기억력’ 콘셉트와 어울리지만, **단일 턴이 가장 안정적** - **기본 Transformer 유지:** GQA, SwiGLU, RoPE, early exit 등은 9M 규모에서 품질 향상 효과가 없고 복잡도만 증가 - **표준 어텐션 + ReLU FFN + LayerNorm** 조합으로 충분한 성능 확보 - **합성 데이터 사용:** 일관된 캐릭터 성격을 유지하기 위해 **템플릿 기반 데이터 생성** 방식을 채택 ### 라이선스 - **MIT 라이선스** ## Comments ### Comment 54804 - Author: neo - Created: 2026-04-07T09:40:43+09:00 - Points: 3 ###### [Hacker News 의견들](https://news.ycombinator.com/item?id=47655408) - 이 프로젝트에 대한 **문서화**가 있는지 궁금함 코드 자체는 (Not So) Large Language Model의 가장 단순한 구현 중 하나로 보이지만, multi-head attention, ReLU FFN, LayerNorm, positional embedding 등에 익숙하지 않은 개발자에게는 이해가 쉽지 않음 이 프로젝트는 **Minix**와 비슷한 교육적 성격을 가짐. Minix가 운영체제 설계를 배우는 도구로 쓰였듯, 학생들이 GuppyLM에 기능을 추가하며 LLM 설계를 배우는 것도 좋은 접근임 - 코드를 LLM에 입력하고 그에 대해 **대화**를 나눠보는 것도 좋은 방법일 듯함 - 이 프로젝트가 Andrej Karpathy의 [microgpt](https://karpathy.github.io/2026/02/12/microgpt/)나 [minGPT](https://github.com/karpathy/minGPT)와 어떻게 다른지 궁금함 - 아직 비교해보지 않았지만, 제안 고맙게 생각함. 두 프로젝트를 살펴볼 예정임 - 비교가 중요한 건 아님. 이건 제품이 아니라 **멋진 실험 프로젝트**임 - [bbycroft.net/llm](https://bbycroft.net/llm)에 작은 LLM 레이어를 **3D 시각화**한 예제가 있음. 내부 동작을 이해하는 데 매우 도움이 됨 관련 토론은 [이곳](https://news.ycombinator.com/item?id=38505211)에서도 볼 수 있음 - 꽤 멋짐! 좀 더 깊이 살펴볼 예정임 - 직접적인 관련은 없지만, 프로젝트가 정말 멋짐. **UI**를 조금 더 추가해보면 좋을 듯함 - 흥미로운 시각화임 - LLM 입문용으로 정말 훌륭함 예전에 Milton의 *Paradise Lost*를 기반으로 나만의 모델을 만들어본 적 있음 참고: [wvrk.org/works/milton](https://www.wvrk.org/works/milton) - 이건 아마 **훈련 데이터가 전부 소문자**로 되어 있어서 생긴 현상 같음 ``` You> hello Guppy> hi. did you bring micro pellets. You> HELLO Guppy> i don't know what it means but it's mine. ``` - 좋은 발견임! 대문자 토큰이 토크나이저에 전혀 없는 듯함 그래도 캐릭터의 반응은 여전히 살아 있음 - **Toki Pona**로만 학습된 LLM을 만드는 게 가능할지 궁금해짐 [Toki Pona 위키](https://en.wikipedia.org/wiki/Toki_Pona) 참고 - 하지만 학습 데이터가 충분하지 않음. LLM의 핵심은 **방대한 데이터와 연산 자원**임 - 여러 LLM 에이전트가 하나의 **가상 세계**를 공유하며 자율적으로 상호작용하는 프로젝트를 진행 중임 놀라운 점은 ‘세계’의 존재가 모델의 행동에 큰 영향을 준다는 것임 같은 모델, 같은 프롬프트라도 자원 제약, 다른 에이전트, 지속 메모리 같은 환경 요소가 달라지면 결과가 완전히 달라짐 우리는 모델 자체 최적화에만 집중하고, 그 **작동 환경**에 대해선 너무 적게 고민하고 있음 - 드디어 세상에 대해 **정직한 LLM**이 나왔다는 느낌임 “삶의 의미는 음식이다”라는 답변은, 1만 배 큰 모델들이 내놓는 답보다 덜 틀린 것 같음 - 오히려 그 유명한 답보다 더 나은 해석일 수도 있음 - 생명의 목적은 **번식**임. 음식은 그 수단일 뿐이며, 모든 자원과 특성은 짝짓기를 돕기 위해 존재함 - 아이디어는 좋지만, 예시들이 **훈련 데이터에서 그대로 복제**된 것 같음 미지의 질의에는 어떻게 대응하는지 궁금함 - 거의 대응하지 못함. 9M 파라미터로는 용량이 매우 제한적임 이 프로젝트의 목적은 LLM의 **작동 원리 시연**에 있음 - 멋진 작업임. 공유해줘서 고맙게 생각함 그런데 이제 LLM이 정말 **‘신비로움이 사라진’** 것처럼 느껴지는지 궁금함 여전히 단순한 통계와 막대한 연산만으로 이런 결과가 나온다는 게 놀라움