▲

작은 언어 모델 GuppyLM으로 언어 모델의 작동 원리를 직접 체험하기

 (github.com/arman-bd)
20P by GN⁺ 7시간전 | ★ favorite | 댓글 1개
  • 약 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 라이선스

함께 보면 좋은 글 β

▲
GN⁺ 7시간전  [-]
Hacker News 의견들

  • 이 프로젝트에 대한 문서화가 있는지 궁금함
    코드 자체는 (Not So) Large Language Model의 가장 단순한 구현 중 하나로 보이지만, multi-head attention, ReLU FFN, LayerNorm, positional embedding 등에 익숙하지 않은 개발자에게는 이해가 쉽지 않음
    이 프로젝트는 Minix와 비슷한 교육적 성격을 가짐. Minix가 운영체제 설계를 배우는 도구로 쓰였듯, 학생들이 GuppyLM에 기능을 추가하며 LLM 설계를 배우는 것도 좋은 접근임

    • 코드를 LLM에 입력하고 그에 대해 대화를 나눠보는 것도 좋은 방법일 듯함

  • 이 프로젝트가 Andrej Karpathy의 microgpt나 minGPT와 어떻게 다른지 궁금함

    • 아직 비교해보지 않았지만, 제안 고맙게 생각함. 두 프로젝트를 살펴볼 예정임
    • 비교가 중요한 건 아님. 이건 제품이 아니라 멋진 실험 프로젝트임

  • bbycroft.net/llm에 작은 LLM 레이어를 3D 시각화한 예제가 있음. 내부 동작을 이해하는 데 매우 도움이 됨
    관련 토론은 이곳에서도 볼 수 있음

    • 꽤 멋짐! 좀 더 깊이 살펴볼 예정임
    • 직접적인 관련은 없지만, 프로젝트가 정말 멋짐. UI를 조금 더 추가해보면 좋을 듯함
    • 흥미로운 시각화임

  • LLM 입문용으로 정말 훌륭함
    예전에 Milton의 Paradise Lost를 기반으로 나만의 모델을 만들어본 적 있음
    참고: 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 위키 참고

    • 하지만 학습 데이터가 충분하지 않음. LLM의 핵심은 방대한 데이터와 연산 자원임

  • 여러 LLM 에이전트가 하나의 가상 세계를 공유하며 자율적으로 상호작용하는 프로젝트를 진행 중임
    놀라운 점은 ‘세계’의 존재가 모델의 행동에 큰 영향을 준다는 것임
    같은 모델, 같은 프롬프트라도 자원 제약, 다른 에이전트, 지속 메모리 같은 환경 요소가 달라지면 결과가 완전히 달라짐
    우리는 모델 자체 최적화에만 집중하고, 그 작동 환경에 대해선 너무 적게 고민하고 있음

  • 드디어 세상에 대해 정직한 LLM이 나왔다는 느낌임
    “삶의 의미는 음식이다”라는 답변은, 1만 배 큰 모델들이 내놓는 답보다 덜 틀린 것 같음

    • 오히려 그 유명한 답보다 더 나은 해석일 수도 있음
    • 생명의 목적은 번식임. 음식은 그 수단일 뿐이며, 모든 자원과 특성은 짝짓기를 돕기 위해 존재함

  • 아이디어는 좋지만, 예시들이 훈련 데이터에서 그대로 복제된 것 같음
    미지의 질의에는 어떻게 대응하는지 궁금함

    • 거의 대응하지 못함. 9M 파라미터로는 용량이 매우 제한적임
      이 프로젝트의 목적은 LLM의 작동 원리 시연에 있음

  • 멋진 작업임. 공유해줘서 고맙게 생각함
    그런데 이제 LLM이 정말 ‘신비로움이 사라진’ 것처럼 느껴지는지 궁금함
    여전히 단순한 통계와 막대한 연산만으로 이런 결과가 나온다는 게 놀라움

답변달기