Update README.md

README.md

@@ -9,7 +9,15 @@ base_model:
 - jslin09/KuiXing
 ---
 
-# 魁星 (KuiXing) — 繁體中文預訓練語言模型
+# 魁星 KuiXing — 繁體中文預訓練語言模型
+
+<p align="center">
+  <img src="https://img.shields.io/badge/語言-繁體中文-red?style=flat-square" />
+  <img src="https://img.shields.io/badge/架構-Decoder--Only Transformer-blue?style=flat-square" />
+  <img src="https://img.shields.io/badge/參數量-1.07B-green?style=flat-square" />
+  <img src="https://img.shields.io/badge/框架-PyTorch%20%7C%20MLX-orange?style=flat-square" />
+  <img src="https://img.shields.io/badge/授權-CC BY--NC 4.0-lightgrey?style=flat-square" />
+</p>
 
 **魁星（KuiXing）** 是一個從零開始、以繁體中文語料預訓練的 Decoder-Only 大型語言模型。取名自中國傳統文化中掌管文章與科舉的神祇「魁星」，象徵對中文語言理解能力的追求。本專案包含完整的訓練程式碼，可在 Apple Silicon（MLX）或 NVIDIA GPU（CUDA）上執行，並輸出與 HuggingFace `transformers` 相容的模型格式。
 
@@ -27,6 +35,8 @@ base_model:
 - [訓練程式用法](#訓練程式用法)
 - [CLI 參數說明](#cli-參數說明)
 - [輸出格式與載入方式](#輸出格式與載入方式)
+- [接續訓練與 Replay Buffer](#接續訓練與-replay-buffer)
+- [模型存檔策略](#模型存檔策略)
 - [程式限制](#程式限制)
 - [目錄結構](#目錄結構)
 - [授權事項](#授權事項)
@@ -73,9 +83,9 @@ Token Embedding（vocab_size × d_model）
     │     └── Output Projection（無 bias）
     ├── Residual + Dropout
     ├── RMSNorm
-    ├── Feed-Forward Network（GELU）
+    ├── Feed-Forward Network（SiLU）
     │     ├── Linear: d_model → d_ff（無 bias）
-    │     ├── GELU Activation
+    │     ├── SiLU Activation
     │     ├── Dropout
     │     └── Linear: d_ff → d_model（無 bias）
     └── Residual + Dropout
@@ -122,7 +132,7 @@ Embedding dropout、Attention dropout 及殘差連接處均加入 dropout（預
 | `max_seq_len` | 2,048 | 最大序列長度 |
 | `vocab_size` | 99,384 | BPE 詞彙量 |
 | `dropout` | 0.1 | Dropout 比率 |
-| `activation` | GELU | FFN 激活函數 |
+| `activation` | SiLU | FFN 激活函數 |
 | `norm` | RMSNorm | 正規化層類型 |
 | `pos_encoding` | Learned | 可學習的位置嵌入 |
 
@@ -136,7 +146,7 @@ Embedding dropout、Attention dropout 及殘差連接處均加入 dropout（預
 | Position Embedding | 4,915,200（4.9M） |
 | Attention（×12 層） | 276,480,000（276.5M） |
 | Feed-Forward（×12 層） | 552,960,000（553.0M） |
-| RMSNorm（×25 個） | 62,400 |
+| RMSNorm（×25 個） | 60,000 |
 | LM Head | 0（與 Token Embedding 共享） |
 | **合計** | **1,072,936,800（≈ 1.07B）** |
 
@@ -169,13 +179,13 @@ Embedding dropout、Attention dropout 及殘差連接處均加入 dropout（預
 | 有效 Batch Size | 128 | `batch_size × accum_steps` |
 | `learning_rate` | 3×10⁻⁴ | AdamW 峰值學習率 |
 | LR Schedule | Linear Warmup + Cosine Decay | |
-| `warmup_steps` | 250 | 線性暖身步數 |
+| `warmup_steps` | 50 | 線性暖身步數 |
 | `weight_decay` | 0.1 | AdamW L2 正則化係數 |
 | `betas` | (0.9, 0.95) | AdamW 動量係數 |
 | `eps` | 1×10⁻⁶ | AdamW 數值穩定項 |
 | `grad_clip` | 1.0 | 全局梯度裁剪閾值（L2 norm） |
 | `epochs` | 3 | 訓練回合數 |
-| `steps` | 30,000 | 每 epoch 最大步數 |
+| `steps` | 3,000 | 每 epoch 最大步數 |
 | 混合精度 | bfloat16（CUDA）／float32（MPS）／bfloat16（MLX） | |
 
 **Weight Decay 策略：** 僅對 `dim ≥ 2` 的權重矩陣施加 weight decay；bias、RMSNorm 參數不衰減。
@@ -199,7 +209,7 @@ Embedding dropout、Attention dropout 及殘差連接處均加入 dropout（預
 > **需求說明：**
 > - float32 模型權重 ≈ 4.3 GB；加上梯度與 AdamW 狀態（各一份，共 3× 權重大小），訓練峰值顯存約 **90 GB 以上**。
 > - Apple Silicon 的統一記憶體由 CPU 與 GPU 共用，128 GB 為能在 MLX bfloat16 模式下穩定訓練的最低配置。
-> - 主機記憶體（系統 RAM）需 ≥ 64 GB，以容納分詞器訓練資料、資料集 tokenize、chunk 建構及 PyTorch 的系統側暫存空間。
+> - 主機記憶體（系統 RAM）需 ≥ 64 GB，以容納資料集 tokenize、chunk 建構及 PyTorch 的系統側暫存空間。
 
 ### Python 套件
 
@@ -221,7 +231,7 @@ tqdm >= 4.65.0
 
 ```bash
 # 1. 複製專案
-git clone https://github.com/your-username/kuixing.git
+git clone https://github.com/jslin/KuiXing.git
 cd kuixing
 
 # 2. 建立虛擬環境（建議）
@@ -237,7 +247,7 @@ pip install torch
 # 4. 安裝 MLX（Apple Silicon 專用，建議安裝以獲得最佳性能）
 pip install mlx
 
-# 5. 安裝其餘相依套件
+# 5. 安裝其餘依賴
 pip install sentencepiece datasets transformers safetensors numpy matplotlib tqdm
 ```
 
@@ -248,7 +258,7 @@ pip install sentencepiece datasets transformers safetensors numpy matplotlib tqd
 ### 互動模式（無參數，推薦���次使用）
 
 ```bash
-python KuiXing_Trainer_MLT.py
+python KuiXing_Trainer_SiLU.py
 ```
 
 程式會自動偵測硬體環境，若有既有模型則詢問是否接續訓練及使用哪個資料集；若無既有模型則從頭開始訓練。
@@ -257,22 +267,22 @@ python KuiXing_Trainer_MLT.py
 
 ```bash
 # 從頭訓練（強制忽略已存在的模型）
-python KuiXing_Trainer_MLT.py --from-scratch
+python KuiXing_Trainer_SiLU.py --from-scratch
 
 # 直接接續訓練（不互動詢問，使用 config 預設資料集）
-python KuiXing_Trainer_MLT.py --resume
+python KuiXing_Trainer_SiLU.py --resume
 
 # 接續訓練並切換到新資料集
-python KuiXing_Trainer_MLT.py --resume --dataset jslin09/other_dataset --column text
+python KuiXing_Trainer_SiLU.py --resume --dataset jslin09/other_dataset --column text
 
 # 以新資料集從頭訓練
-python KuiXing_Trainer_MLT.py --from-scratch --dataset your_org/dataset_name --column article
+python KuiXing_Trainer_SiLU.py --from-scratch --dataset your_org/dataset_name --column article
 
 # 獨立繪圖模式（讀取訓練記錄後生成曲線圖，不啟動訓練）
-python KuiXing_Trainer_MLT.py --plot
+python KuiXing_Trainer_SiLU.py --plot
 
 # 訓練摘要模式（顯示 loss / perplexity 統計後結束，不啟動訓練）
-python KuiXing_Trainer_MLT.py --summary
+python KuiXing_Trainer_SiLU.py --summary
 ```
 
 ---
@@ -297,19 +307,19 @@ python KuiXing_Trainer_MLT.py --summary
 ============================================================
   🏁  KuiXing 訓練完成摘要
 ============================================================
-  總記錄步數         : 2,811  步（optimizer update）
+  總記錄步數        : 90,000  步（optimizer update）
   訓練 Epoch        : 3
-  學習率範圍         : 0.00e+00  →  3.00e-04
-  梯度被裁剪次數      : 51  次（佔 1.8%）
+  學習率範圍        : 1.20e-06  →  3.00e-04
+  梯度被裁剪次數    : 1,234  次（佔 1.4%）
 ============================================================
-  最終 Loss         : 2.741243
-  最終 Perplexity   : 15.5062
+  最終 Loss         : 3.421500
+  最終 Perplexity   : 30.6310
 ============================================================
-  最佳 Loss         : 2.639037  （第 81,311 步）
-  最佳 Perplexity   : 13.9997
+  最佳 Loss         : 3.198200  （第 87,400 步）
+  最佳 Perplexity   : 24.4702
 ============================================================
-  末 100 步平均 Loss : 2.784486
-  末 100 步平均 PPL  : 16.1915
+  末 100 步平均 Loss : 3.390000
+  末 100 步平均 PPL  : 29.7000
 ============================================================
 ```
 
@@ -373,6 +383,152 @@ model = AutoModelForCausalLM.from_pretrained(
 
 ---
 
+## 接續訓練與 Replay Buffer
+
+### 災難性遺忘問題
+
+以 `--resume` 接續訓練指定新資料集時，若不加任何防護，模型容易忘記原始語料（如台灣維基百科）的語法與知識，只學會新資料集的風格，此現象稱為**災難性遺忘（Catastrophic Forgetting）**。
+
+### Replay Buffer 機制
+
+KuiXing 訓練程式內建 **Replay Buffer** 機制，在接續訓練時自動於每個 mini-batch 中混入一定比例的舊語料樣本，使模型同時學習新舊知識，有效緩解遺忘問題。
+
+```
+每個 mini-batch（batch_size = 4）：
+  ┌─────────────────────────────────────┐
+  │  新語料樣本 × 3  （80%，n_new）      │
+  │  舊語料樣本 × 1  （20%，n_replay）   │  ← Replay Buffer
+  └─────────────────────────────────────┘
+  混合後隨機打散順序，再送入模型
+```
+
+### 啟動條件（全自動，無需額外 CLI 參數）
+
+Replay Buffer 在以下條件**同時成立**時自動啟用，無需任何額外操作：
+
+| 條件 | 說明 |
+|------|------|
+| 使用 `--resume` 接續訓練 | 從頭訓練（`--from-scratch`）不啟用 |
+| 新資料集與 `replay_dataset` **不同** | 相同資料集接續時自動略過並印出提示 |
+| `replay_ratio > 0.0` | 設為 `0.0` 可手動停用 |
+
+啟用後，程式會在訓練開始前印出確認訊息：
+
+```
+🔁 Replay Buffer 已啟用：每批 4 筆中 1 筆來自舊語料（20%），3 筆來自新語料。
+```
+
+### 舊語料快取機制
+
+為避免每次接續訓練都重新下載並 tokenize 舊語料，Replay Buffer 採用磁碟快取：
+
+- **第一次**：自動下載舊語料、tokenize、切塊，儲存為 `.npy` 快取檔
+- **之後每次**：直接讀取快取，秒速完成，無需重新處理
+
+快取儲存於 `./kuixing_replay_cache/`，檔名包含資料集名稱與 chunk size，可安全保留供多次訓練共用。
+
+### 相關設定參數（`KuiXingConfig`）
+
+| 參數 | 預設值 | 說明 |
+|------|--------|------|
+| `replay_ratio` | `0.2` | 每個 mini-batch 中舊語料所佔比例（0.0 = 停用） |
+| `replay_dataset` | `"jslin09/wikipedia_tw"` | 舊語料的 HuggingFace 資料集名稱 |
+| `replay_column` | `"article"` | 舊語料的文章欄位名稱 |
+| `replay_cache_dir` | `"./kuixing_replay_cache"` | 舊語料 chunk 快取目錄 |
+
+> **調整比例：** `replay_ratio = 0.2` 代表 20% 舊語料、80% 新語料，一般建議範圍為 0.1–0.3。比例過高會拖慢新語料的學習速度；過低則防遺忘效果有限。
+
+### 操作範例
+
+```bash
+# 以新資料集接續訓練（Replay Buffer 自動啟用，混入 20% 維基百科舊語料）
+python KuiXing_Trainer_SiLU.py --resume --dataset jslin09/other_dataset --column text
+
+# 若想停用 Replay Buffer，在 KuiXingConfig 中將 replay_ratio 設為 0.0
+# self.replay_ratio = 0.0
+```
+
+---
+
+## 模型存檔策略
+
+### 概覽
+
+KuiXing 訓練程式同時維護兩種存檔，各有不同用途：
+
+| 檔案 | 存放位置 | 用途 | 保留數量 |
+|------|----------|------|----------|
+| `ckpt_ep*_step*.pt` | `kuixing_checkpoints/` | 意外中斷後接續訓練 | 最多 3 份（滾動刪除） |
+| `ckpt_best.pt` | `kuixing_checkpoints/` | 最終 HuggingFace 輸出來源 | 固定 1 份（覆蓋更新） |
+| `mlx_ckpt_best.npz` | `kuixing_checkpoints/` | MLX 路徑的最佳版本 | 固定 1 份（覆蓋更新） |
+
+### 最佳模型判斷：滑動平均 loss
+
+程式以**近 100 個 optimizer step 的 loss 平均值**作為判斷依據，而非單步 loss。採用滑動平均的原因：
+
+- 單步 loss 受 batch 取樣影響，存在隨機雜訊
+- 單步最低 ≠ 泛化能力最好；滑動平均能反映模型真實的學習趨勢
+- 有效過濾掉「剛好抽到簡單 batch」所造成的虛假最低點
+
+### 觸發條件
+
+每次常規存檔（每 `save_interval = 200` 步）時同步比較：
+
+```
+if optimizer_step >= best_ckpt_min_steps (預設 100):      # 跳過冷卻期
+    avg_loss = mean(losses[-100:])                         # 計算滑動平均
+    if avg_loss < 歷史最佳滑動平均 loss:
+        覆蓋寫入 ckpt_best.pt                              # 僅此時才有 I/O
+        印出 🏆 更新訊息
+    else:
+        不做任何事（零 I/O）
+```
+
+**冷卻期設計（`best_ckpt_min_steps = 100`）：** 訓練初期 loss 快速下降但尚未穩定，冷卻期內不觸發最佳存檔，避免存到不具代表性的早期版本。
+
+### I/O 影響評估
+
+| 情境 | 實際 I/O 頻率 | 說明 |
+|------|--------------|------|
+| 訓練初期（loss 快速下降） | 每 200 步最多一次 | 受 `save_interval` 限制 |
+| 訓練中後期（loss 趨於平穩） | 幾乎不觸發 | 滑動平均鮮少繼續改善 |
+| 沒有改善時 | 零 I/O | 完全不寫入 |
+
+結論：**不會成為 I/O bound 程式**，對訓練速度的影響可忽略不計。
+
+### 最終輸出行為
+
+訓練完成後，程式**優先載入 `ckpt_best.pt`** 再進行 HuggingFace 格式輸出，而非直接使用記憶體中訓練結束當下的模型：
+
+```
+訓練迴圈結束
+    ↓
+嘗試載入 kuixing_checkpoints/ckpt_best.pt
+    ├── 成功 → 印出 🏆 最佳滑動平均 loss 數值，以最佳版本輸出
+    └── 失敗或不存在 → 印出 ℹ️ 提示，以當前模型 fallback 輸出
+    ↓
+_export_model() → kuixing_model/model.safetensors
+```
+
+### 相關設定參數（`KuiXingConfig`）
+
+| 參數 | 預設值 | 說明 |
+|------|--------|------|
+| `save_interval` | `200` | 常規 checkpoint 存檔間隔（步數） |
+| `max_checkpoints` | `3` | 常規 checkpoint 最多保留份數 |
+| `best_ckpt_window` | `100` | 滑動平均視窗大小（optimizer steps） |
+| `best_ckpt_min_steps` | `100` | 開始比較最佳 loss 的最小步數（冷卻期） |
+
+### 注意事項
+
+> ⚠️ **接續訓練時的最佳 checkpoint 覆蓋問題**
+>
+> 使用 `--resume` 接續訓練時，若舊的 `ckpt_best.pt` 仍存在於 `kuixing_checkpoints/`，新一輪訓練的滑動平均 loss 必須**低於舊輪次的最佳值**才會觸發覆蓋。
+>
+> 若新語料訓練後 loss 整體偏高（例如難度較高的領域語料），有可能整輪訓練都不觸發更新，最終輸出的仍是前一輪的最佳版本。這在大多數情況下是**正確行為**（舊版本確實更好），但若您明確希望輸出新語料訓練的版本，請在接續訓練前手動刪除 `kuixing_checkpoints/ckpt_best.pt`。
+
+---
+
 ## 程式限制
 
 使用本訓練程式前，請了解以下限制：
@@ -393,7 +549,9 @@ model = AutoModelForCausalLM.from_pretrained(
 - PyTorch（CUDA/MPS）與 MLX（Apple Silicon）的 checkpoint 格式不同，無法直接互換。MLX checkpoint 以 `.npz` 儲存，PyTorch checkpoint 以 `.pt` 儲存。
 
 **Tokenizer 字型依賴**
-- 訓練曲線繪圖功能依賴本地安裝的繁體中文字型（Noto Sans CJK TC），字型路徑硬編碼於程式中。若路徑不符，繪圖將失敗或顯示亂碼。**此設定不應修改**（程式設計刻意保留）。
+- 訓練曲線繪圖功能依賴本地安裝的繁體中文字型（Noto Sans TC），字型路徑與檔名硬編碼於程式中。若路徑或檔名不符��繪圖將失敗或顯示亂碼。
+- 字型下載網址：[Noto Sans TC — Google Fonts](https://fonts.google.com/noto/specimen/Noto+Sans+TC?preview.script=Hant)
+- ⚠️ **使用者需自行將字型檔案安裝至本機，並修改程式碼中對應的字型檔案路徑與檔名**，使其與實際安裝位置一致，繪圖功能方可正常運作。
 
 **資料集格式**
 - 目前僅支援 HuggingFace `datasets` 格式的文字資料集，需指定文字欄位名稱。不支援本地 jsonl、txt、csv 直接輸入（需先上傳至 HuggingFace 或自行修改 `build_chunks()` 函式）。
@@ -409,21 +567,26 @@ model = AutoModelForCausalLM.from_pretrained(
 
 ```
 ./
-├── KuiXing_Trainer_MLT.py     # 主訓練程式
+├── KuiXing_Trainer_SiLU.py     # 主訓練程式
 │
 ├── kuixing_tokenizer/          # Tokenizer 檔案（自動生成）
 │   ├── tokenizer.model
 │   └── tokenizer.vocab
 │
 ├── kuixing_checkpoints/        # 訓練 Checkpoint（自動生成）
-│   ├── ckpt_ep0_step500.pt
-│   ├── ckpt_ep0_step1000.pt
-│   └── ...（保留最新 3 個）
+│   ├── ckpt_ep0_step200.pt     # 常規 checkpoint（最多保留 3 份）
+│   ├── ckpt_ep0_step400.pt
+│   ├── ...（保留最新 3 個）
+│   ├── ckpt_best.pt            # 滑動平均 loss 最佳版本（PT/CUDA/MPS）
+│   └── mlx_ckpt_best.npz      # 滑動平均 loss 最佳版本（MLX）
 │
 ├── kuixing_logs/               # 訓練記錄（自動生成）
 │   ├── training_log.jsonl      # 每步指標（loss, lr, grad_norm, ...）
 │   └── training_curves.png    # 訓練曲線圖（每 200 步更新）
 │
+├── kuixing_replay_cache/       # Replay Buffer 快取（接續訓練時自動生成）
+│   └── replay_jslin09_wikipedia_tw_2049.npy  # 舊語料 chunk 快取
+│
 └── kuixing_model/              # 最終輸出（訓練完成後生成）
     ├── model.safetensors
     ├── config.json
@@ -438,12 +601,12 @@ model = AutoModelForCausalLM.from_pretrained(
 
 ### 程式碼授權
 
-本專案訓練程式碼（`KuiXing_Trainer_MLT.py` 及相關檔案）以 **MIT License** 授權，允許自由使用、修改與散布，包含商業用途，惟需保留原始版權聲明。
+本專案訓練程式碼（`KuiXing_Trainer_SiLU.py` 及相關檔案）以 **MIT License** 授權，允許自由使用、修改與散布，包含商業用途，惟需保留原始版權聲明。
 
 ```
 MIT License
 
-Copyright (c) 2025 Chun-Hsien Lin
+Copyright (c) 2026 Chun-Hsien Lin
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -491,7 +654,7 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 若您在研究或作品中使用了 KuiXing，請引用本專案：
 
 ```bibtex
-@misc{kuixing2026,
+@misc{lin2026kuixing,
   author       = {Chun-Hsien Lin},
   title        = {KuiXing: A Traditional Chinese Pre-trained Language Model},
   year         = {2026},