Veenn
/

photon-3m

@@ -12,33 +12,48 @@ datasets:
 - Lyon28/Corpus-Indonesia
 ---
-# Photon-3M
-Model bahasa Indonesia skala kecil dengan arsitektur *Dual Sparse*, dibangun dan dilatih dari nol di Google Colab Free T4.
-Nama "3M" merujuk pada jumlah parameter aktif per forward pass, bukan total parameter. Total parameter sebenarnya 10.47M karena MoE.
 ## Arsitektur
 Konsep utamanya adalah **Dual Sparse** — dua level sparsity yang bekerja bersamaan supaya model kecil bisa berkapasitas lebih dari ukuran parameternya.
-**MoE (Mixture of Experts)**
 Satu shared expert yang selalu aktif ditambah empat specialist expert yang dipilih router per token. Efeknya: kapasitas representasi ~5x lebih tinggi dari parameter aktif per forward pass, tanpa nambah biaya komputasi secara proporsional.
-**Adaptive Layer Skipping**
-Router kecil di tiap layer memutuskan apakah layer perlu diproses atau dilewati. Token sederhana bisa melewati beberapa layer, token kompleks dapat perhatian penuh. Diaktifkan di versi ini dengan skip probability 0.3.
-**Komponen lain**
-| Komponen | Keterangan |
-|---|---|
-| GQA | 4 query heads, 2 KV heads |
-| RoPE | Rotary Position Embedding |
-| SwiGLU | Aktivasi di FFN |
-| RMSNorm | Normalisasi per layer |
-| Weight Tying | Embedding dan output head berbagi bobot |
-**Konfigurasi**
 ```
 VOCAB_SIZE  = 8.000
@@ -50,6 +65,7 @@ FF_MULT     = 3
 NUM_EXPERTS = 4 + 1 shared
 MAX_SEQ     = 256
 Total params: 10.472.076
 ```
 ## Tokenizer
@@ -64,15 +80,15 @@ Special : [UNK] [BOS] [EOS] [PAD]
 ## Training
-**Dataset**
-Sumber: `Lyon28/Corpus-Indonesia`, 100.000 baris pertama dipakai untuk tokenizer, 500.000 baris untuk training. Setelah filter teks terlalu pendek: 449.909 valid.
-**Packing Dataset**
-Mayoritas kalimat di dataset panjangnya di bawah 50 token. Dengan padding biasa, sekitar 96% slot per batch terisi token padding yang tidak berkontribusi ke loss. Solusinya: semua token digabung jadi satu stream panjang lalu dipotong jadi chunk 256 token. Hasilnya 21.237.953 token terpacking jadi 82.960 chunks, tidak ada padding sama sekali.
-**Proses Training**
 ```
 Hardware         : Tesla T4 15.6GB (Google Colab Free)
@@ -84,29 +100,29 @@ Scheduler        : Cosine Annealing Warm Restarts
 Warmup           : 500 steps
 ```
-**Kurva Loss**
 | Step | Loss | PPL |
 |------|------|-----|
-| 50 | 8.97 | 7836 |
-| 500 | 7.39 | 1618 |
-| 1000 | 6.50 | 662 |
-| 1500 | 6.19 | 486 |
-| 2000 | 5.89 | 360 |
-Baseline acak untuk vocab 8.000: log(8000) = 8.987
-**Bug yang ditemui**
 Dua bug utama ditemukan dan diperbaiki selama proses ini:
-Pertama, masalah padding 96%. Terdeteksi lewat print debug manual pada sample batch yang menunjukkan hampir seluruh slot terisi token -100. Solusinya beralih ke packing dataset.
-Kedua, posisi akumulasi loss yang salah. `running_loss` diakumulasi di luar blok gradient accumulation tapi dibagi per step, menghasilkan angka loss yang tampak ~8x lebih besar dari nilai sebenarnya. Solusinya memindahkan akumulasi ke dalam blok yang benar.
 ## Cara Load
-Model ini menggunakan arsitektur custom, jadi perlu menyertakan definisi kelas-kelasnya sebelum bisa diload. Salin file `modeling_photon.py` dari repo ini, lalu:
 ```python
 import torch
@@ -159,24 +175,29 @@ Output belum koheren. Kata-katanya sudah valid Bahasa Indonesia dan tidak ada la
 ## Limitasi
-Model ini adalah proof of concept arsitektur, bukan model siap pakai. Vocab 8.000 terlalu kecil untuk menghasilkan teks yang baik, hidden 128 membatasi kapasitas representasi, dan training baru sampai step 2000 dari 3.240 yang direncanakan. Untuk hasil yang lebih baik perlu scale up ke vocab yang lebih besar dan hidden yang lebih lebar.
 ## Isi Repo
 ```
 Veenn/photon-3m
-├── model.pt             <- state dict model
-├── config.pt            <- konfigurasi arsitektur
-├── modeling_photon.py   <- definisi arsitektur (wajib disertakan)
-├── training_state.pt    <- state training untuk resume
 ├── tokenizer.json
 ├── tokenizer_config.json
 └── README.md
 ```
 ## Rencana Selanjutnya
-Iterasi berikutnya kemungkinan akan menaikkan vocab ke 16.000-32.000 dan hidden ke 256, dengan target parameter di kisaran 50-100M. Adaptive Layer Skipping juga akan dievaluasi lebih lanjut apakah benar memberikan efek positif atau tidak setelah training lebih panjang.
-*Dikembangkan oleh [Velyn](https://huggingface.co/Veenn)*
-*Dilatih di Google Colab Free T4*

 - Lyon28/Corpus-Indonesia
 ---
+<div align="center">
+  <img src="https://huggingface.co/Veenn/photon-3m/resolve/main/1000326189.png" alt="Photon Mascot" width="300"/>
+  # Photon-3M
+  Model bahasa Indonesia skala kecil dengan arsitektur *Dual Sparse*, dibangun dan dilatih dari nol di Google Colab Free T4.
+  [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+  [![HuggingFace](https://img.shields.io/badge/🤗%20HuggingFace-Veenn%2Fphoton--3m-yellow)](https://huggingface.co/Veenn/photon-3m)
+  [![Dataset](https://img.shields.io/badge/Dataset-Lyon28%2FCorpus--Indonesia-green)](https://huggingface.co/datasets/Lyon28/Corpus-Indonesia)
+  [![Colab](https://img.shields.io/badge/Trained%20on-Google%20Colab%20Free%20T4-orange)](https://colab.research.google.com)
+</div>
+---
+Nama "3M" merujuk pada jumlah parameter **aktif per forward pass**, bukan total parameter. Total parameter sebenarnya **10.47M** karena MoE.
 ## Arsitektur
 Konsep utamanya adalah **Dual Sparse** — dua level sparsity yang bekerja bersamaan supaya model kecil bisa berkapasitas lebih dari ukuran parameternya.
+### MoE (Mixture of Experts)
 Satu shared expert yang selalu aktif ditambah empat specialist expert yang dipilih router per token. Efeknya: kapasitas representasi ~5x lebih tinggi dari parameter aktif per forward pass, tanpa nambah biaya komputasi secara proporsional.
+> Referensi konsep: [Mixtral of Experts (Mistral AI)](https://arxiv.org/abs/2401.04088)
+### Adaptive Layer Skipping
+Router kecil di tiap layer memutuskan apakah layer perlu diproses atau dilewati. Token sederhana bisa melewati beberapa layer, token kompleks dapat perhatian penuh. Diaktifkan di versi ini dengan skip probability **0.3**.
+> Referensi konsep: [Confident Adaptive Language Modeling (CALM)](https://arxiv.org/abs/2207.07061)
+### Komponen Lain
+| Komponen | Keterangan | Referensi |
+|---|---|---|
+| GQA | 4 query heads, 2 KV heads | [GQA Paper](https://arxiv.org/abs/2305.13245) |
+| RoPE | Rotary Position Embedding | [RoFormer](https://arxiv.org/abs/2104.09864) |
+| SwiGLU | Aktivasi di FFN | [GLU Variants](https://arxiv.org/abs/2002.05202) |
+| RMSNorm | Normalisasi per layer | [RMSNorm Paper](https://arxiv.org/abs/1910.07467) |
+| Weight Tying | Embedding dan output head berbagi bobot | [Press & Wolf, 2017](https://arxiv.org/abs/1608.05859) |
+### Konfigurasi
 ```
 VOCAB_SIZE  = 8.000
 NUM_EXPERTS = 4 + 1 shared
 MAX_SEQ     = 256
 Total params: 10.472.076
+Active params per forward: ~3.000.000
 ```
 ## Tokenizer
 ## Training
+### Dataset
+Sumber: [`Lyon28/Corpus-Indonesia`](https://huggingface.co/datasets/Lyon28/Corpus-Indonesia) — 100.000 baris pertama dipakai untuk training tokenizer, 500.000 baris untuk training model. Setelah filter teks terlalu pendek: **449.909 valid**.
+### Packing Dataset
+Mayoritas kalimat di dataset panjangnya di bawah 50 token. Dengan padding biasa, sekitar 96% slot per batch terisi token padding yang tidak berkontribusi ke loss. Solusinya: semua token digabung jadi satu stream panjang lalu dipotong jadi chunk 256 token. Hasilnya 21.237.953 token terpacking jadi **82.960 chunks**, tidak ada padding sama sekali.
+### Proses Training
 ```
 Hardware         : Tesla T4 15.6GB (Google Colab Free)
 Warmup           : 500 steps
 ```
+### Kurva Loss
 | Step | Loss | PPL |
 |------|------|-----|
+| 50   | 8.97 | 7836 |
+| 500  | 7.39 | 1618 |
+| 1000 | 6.50 | 662  |
+| 1500 | 6.19 | 486  |
+| 2000 | 5.89 | 360  |
+Baseline acak untuk vocab 8.000: `log(8000) = 8.987`
+### Bug yang Ditemui
 Dua bug utama ditemukan dan diperbaiki selama proses ini:
+**Masalah padding 96%.** Terdeteksi lewat print debug manual pada sample batch yang menunjukkan hampir seluruh slot terisi token `-100`. Solusinya beralih ke packing dataset.
+**Posisi akumulasi loss yang salah.** `running_loss` diakumulasi di luar blok gradient accumulation tapi dibagi per step, menghasilkan angka loss yang tampak ~8x lebih besar dari nilai sebenarnya. Solusinya memindahkan akumulasi ke dalam blok yang benar.
 ## Cara Load
+Model ini menggunakan arsitektur custom, jadi perlu menyertakan definisi kelas-kelasnya sebelum bisa diload. Salin file [`modeling_photon.py`](https://huggingface.co/Veenn/photon-3m/blob/main/modeling_photon.py) dari repo ini, lalu:
 ```python
 import torch
 ## Limitasi
+Model ini adalah **proof of concept arsitektur**, bukan model siap pakai. Vocab 8.000 terlalu kecil untuk menghasilkan teks yang baik, hidden 128 membatasi kapasitas representasi, dan training baru sampai step 2000 dari 3.240 yang direncanakan. Untuk hasil yang lebih baik perlu scale up ke vocab yang lebih besar dan hidden yang lebih lebar.
 ## Isi Repo
 ```
 Veenn/photon-3m
+├── model.pt              <- state dict model
+├── config.pt             <- konfigurasi arsitektur
+├── modeling_photon.py    <- definisi arsitektur (wajib disertakan)
+├── training_state.pt     <- state training untuk resume
 ├── tokenizer.json
 ├── tokenizer_config.json
+├── 1000326189.png        <- maskot Photon
 └── README.md
 ```
 ## Rencana Selanjutnya
+Iterasi berikutnya kemungkinan akan menaikkan vocab ke **16.000–32.000** dan hidden ke **256**, dengan target parameter di kisaran **50–100M**. Adaptive Layer Skipping juga akan dievaluasi lebih lanjut apakah benar memberikan efek positif atau tidak setelah training lebih panjang.
+---
+<div align="center">
+  <em>Dikembangkan oleh <a href="https://huggingface.co/Veenn">Velyn</a></em><br>
+  <em>Dilatih di Google Colab Free T4</em>
+</div>