Update README.md

README.md

@@ -1,7 +1,7 @@
 ---
 license: apache-2.0
 datasets:
-- HuggingFaceFW/fineweb-2
+- jslin09/wikipedia_tw
 language:
 - en
 - zh
@@ -16,451 +16,508 @@ base_model:
 
 ---
 
+# 魁星 (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` 相容的模型格式。
+
+---
+
 ## 目錄
 
-- [模型架構](#模型架構)
-- [環境安裝](#環境安裝)
-- [快速開始](#快速開始)
-- [資料集設定](#資料集設定)
-- [訓練模式](#訓練模式)
-- [CLI 完整參數](#cli-完整參數)
-- [發布存檔格式](#發布存檔格式)
-- [專案結構](#專案結構)
-- [常見問題](#常見問題)
-- [授權](#授權)
+- [模型概覽](#模型概覽)
+- [模型架構詳情](#模型架構詳情)
+- [參數量統計](#參數量統計)
+- [訓練資料](#訓練資料)
+- [訓練超參數](#訓練超參數)
+- [環境需求](#環境需求)
+- [安裝](#安裝)
+- [訓練程式用法](#訓練程式用法)
+- [CLI 參數說明](#cli-參數說明)
+- [輸出格式與載入方式](#輸出格式與載入方式)
+- [程式限制](#程式限制)
+- [目錄結構](#目錄結構)
+- [授權事項](#授權事項)
+- [引用](#引用)
 
 ---
 
-## 模型架構
+## 模型概覽
 
-| 項目 | 數值 |
+| 項目 | 內容 |
 |------|------|
-| 總參數量 | ~1.15B |
-| 激活參數量（推理時）| ~460M |
-| 隱藏層總數 | 24 |
-| 其中 Dense 層 | 16（每 3 層中的前 2 層）|
-| 其中 MoE 層 | 8（每 3 層中的第 3 層）|
-| 隱藏維度 | 2048 |
-| Attention 機制 | GQA — Q heads: 16 / KV heads: 4 |
-| Head 維度 | 128 |
-| Dense FFN 中間維度 | 5632（SwiGLU）|
-| MoE 專家數 | 16（top-2 稀疏激活）|
-| 每個 Expert 中間維度 | 2048 |
-| 位置編碼 | YaRN RoPE（θ=500000, factor=8）|
-| 訓練 context 長度 | 128K tokens |
-| 推理 context 長度 | 最大 **1M tokens**（YaRN 外推）|
-| 注意力策略 | 偶數層：全注意力；奇數層：Sliding Window (4096)|
-| Normalization | RMSNorm（ε=1e-5，float32 計算）|
-| 詞彙量 | 56,000（SentencePiece BPE）|
-| MoE 輔助損失 | Load Balancing Loss + Router Z-Loss |
+| 模型名稱 | KuiXing（魁星） |
+| 模型類型 | Decoder-Only Transformer（自迴歸語言模型） |
+| 主要語言 | 繁體中文（Traditional Chinese） |
+| 參數量 | **1.07B**（10.7 億） |
+| 詞彙量 | 99,384（SentencePiece BPE） |
+| 最大序列長度 | 2,048 tokens |
+| 訓練框架 | PyTorch（CUDA）／MLX（Apple Silicon） |
+| 輸出格式 | HuggingFace `safetensors` + `config.json` |
+| 授權 | CC BY-NC 4.0 |
 
 ---
 
-## 環境安裝
+## 模型架構詳情
 
-### NVIDIA CUDA（推薦）
+KuiXing 採用標準 Pre-Norm Decoder-Only Transformer 架構，設計重點在於繁體中文的高效表示與訓練穩定性。
 
-```bash
-# PyTorch with CUDA 12.1
-pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
-pip install transformers datasets sentencepiece tensorboard accelerate safetensors
+### 整體架構
+
+```
+輸入 token IDs
+    ↓
+Token Embedding（vocab_size × d_model）
+    + Position Embedding（max_seq_len × d_model）
+    + Embedding Dropout
+    ↓
+× 12 Transformer Blocks（Pre-Norm）
+    ├── RMSNorm
+    ├── Multi-Head Self-Attention（Causal Mask）
+    │     ├── Q / K / V Projection（無 bias）
+    │     ├── Scaled Dot-Product（float32 精度）
+    │     ├── Causal Mask（上三角 -1e4，非 -inf）
+    │     ├── Softmax → Attention Dropout
+    │     └── Output Projection（無 bias）
+    ├── Residual + Dropout
+    ├── RMSNorm
+    ├── Feed-Forward Network（GELU）
+    │     ├── Linear: d_model → d_ff（無 bias）
+    │     ├── GELU Activation
+    │     ├── Dropout
+    │     └── Linear: d_ff → d_model（無 bias）
+    └── Residual + Dropout
+    ↓
+Final RMSNorm
+    ↓
+LM Head（d_model → vocab_size，**與 Token Embedding 共享權重**）
+    ↓
+Logits（float32）
 ```
 
-### Apple Silicon（macOS 12.3+）
+### 關鍵設計決策
 
-```bash
-# PyTorch with MPS（BF16 需 PyTorch >= 2.3）
-pip install torch torchvision torchaudio
-pip install transformers datasets sentencepiece tensorboard accelerate safetensors
-```
+**Pre-Norm（前置正規化）**
+Norm 層置於 Attention 與 MLP 之前，訓練更穩定，梯度流動更順暢，特別適合深層網路。
 
-> **注意**：macOS 上的 OpenMP 衝突問題已由程式自動處理，不需要手動設定環境變數。
+**RMSNorm 取代 LayerNorm**
+Root Mean Square Normalization 省去均值計算，計算效率更高，且在語言模型中表現與 LayerNorm 相當。
 
-### 最低 Python 版本
+**Causal Mask 使用 -1e4 而非 -inf**
+避免 bfloat16 下 `-inf` 經過 softmax 產生 `NaN` 的數值不穩定問題。
 
-Python **3.10+**（使用了 walrus operator `:=`）
+**Attention Score 以 float32 計算**
+即使在 bfloat16 訓練模式下，Q·Kᵀ 的縮放點積與 softmax 仍升型至 float32 進行，確保精度。
 
----
+**Weight Tying（權重綁定）**
+LM Head 與 Token Embedding 共享同一組權重矩陣，減少約 2.39 億參數，並有助於語意一致性。
 
-## 快速開始
+**無 Bias 的線性層**
+所有 Q/K/V/O Projection 及 FFN 的線性層均不使用 bias，符合現代大型語言模型的主流做法。
 
-### 步驟 0：確認平台偵測
+**Dropout 正則化**
+Embedding dropout、Attention dropout 及殘差連接處均加入 dropout（預設 0.1），有效防止過擬合。
 
-```bash
-python train_llm.py --mode info
-```
+### 架構超參數
 
-輸出範例（Apple M2 Pro）：
-```json
-{
-  "device": "mps",
-  "device_name": "Apple M2 Pro",
-  "use_bf16": true,
-  "recommended_batch": 1,
-  "fused_adamw": false,
-  "dataloader_workers": 0
-}
-```
+| 參數 | 數值 | 說明 |
+|------|------|------|
+| `n_layers` | 12 | Transformer Block 層數 |
+| `d_model` | 2,400 | 隱藏層維度 |
+| `n_heads` | 32 | 注意力頭數 |
+| `d_head` | 75 | 每個注意力頭的維度（d_model / n_heads） |
+| `d_ff` | 9,600 | Feed-Forward 中間層維度（4× d_model） |
+| `max_seq_len` | 2,048 | 最大序列長度 |
+| `vocab_size` | 99,384 | BPE 詞彙量 |
+| `dropout` | 0.1 | Dropout 比率 |
+| `activation` | GELU | FFN 激活函數 |
+| `norm` | RMSNorm | 正規化層類型 |
+| `pos_encoding` | Learned | 可學習的位置嵌入 |
 
-### 步驟 1：訓練分詞器（首次執行，只需一次）
+---
 
-```bash
-python train_llm.py --mode tokenizer --data_dir ./data
-```
+## 參數量統計
 
-從 FineWeb2 下載約 500 萬行語料訓練 SentencePiece BPE 分詞器（56K 詞彙，中英文及多語言 character coverage 99.95%）。
+| 模組 | 參數量 |
+|------|--------|
+| Token Embedding | 238,521,600（238.5M） |
+| 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 |
+| LM Head | 0（與 Token Embedding 共享） |
+| **合計** | **1,072,936,800（≈ 1.07B）** |
 
-### 步驟 2：訓練模型
+> **儲存大小估算：**
+> - float32（訓練 / safetensors 輸出）：≈ **4.3 GB**
+> - bfloat16（推理建議）：≈ **2.1 GB**
 
-```bash
-# 最簡單：使用預設 FineWeb2，所有超參數自動偵測
-python train_llm.py --mode train --model_name kuixing-1.15b
-
-# 使用自訂資料集設定
-python train_llm.py --mode train \
-    --dataset_config dataset_config.json \
-    --mix_strategy weighted \
-    --model_name kuixing-1.15b
-```
+---
 
-### 步驟 3：推論測試
+## 訓練資料
 
-```bash
-python train_llm.py --mode demo
-```
+| 項目 | 內容 |
+|------|------|
+| 主要語料 | [jslin09/wikipedia_tw](https://huggingface.co/datasets/jslin09/wikipedia_tw)（台灣維基百科） |
+| 語言 | 繁體中文 |
+| Tokenizer | SentencePiece BPE，從語料訓練，詞彙量 99,384 |
+| 資料處理 | 全文 tokenize → 串接為長序列 → 切成固定長度 chunk（2,049 tokens/chunk）→ 打散 |
+| BOS / EOS | 每篇文章前後分別加入 `<s>` / `</s>` token |
+
+訓練支援多資料集接續（Continual Training），可在訓練完成後以不同語料繼續微調，無需重新初始化模型。
 
 ---
 
-## 資料集設定
+## 訓練超參數
+
+| 超參數 | 數值 | 說明 |
+|--------|------|------|
+| `batch_size` | 4 | 每步實際 mini-batch 大小 |
+| `accum_steps` | 32 | 梯度累積步數 |
+| 有效 Batch Size | 128 | `batch_size × accum_steps` |
+| `learning_rate` | 3×10⁻⁴ | AdamW 峰值學習率 |
+| LR Schedule | Linear Warmup + Cosine Decay | |
+| `warmup_steps` | 250 | 線性暖身步數 |
+| `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 最大步數 |
+| 混合精度 | bfloat16（CUDA）／float32（MPS）／bfloat16（MLX） | |
+
+**Weight Decay 策略：** 僅對 `dim ≥ 2` 的權重矩陣施加 weight decay；bias、RMSNorm 參數不衰減。
 
-支援三種方式指定訓練資料，可任意混合多個來源。
+---
 
-### 方式 1：JSON 設定���（最彈性）
+## 環境需求
 
-```bash
-python train_llm.py --mode train --dataset_config dataset_config.json
-```
+### 必要條件
 
-參見 [`dataset_config.json`](dataset_config.json) 範例（FineWeb2 + Wikipedia 混合）。
-
-`dataset_config_local.json` 示範本地 JSONL 檔案的用法。
-
-**DatasetSource 完整欄位：**
-
-| 欄位 | 型別 | 預設 | 說明 |
-|------|------|------|------|
-| `source` | str | `"huggingface"` | `huggingface` / `local_files` / `local_dir` |
-| `path` | str | — | HF dataset id 或本地路徑（多檔用逗號分隔）|
-| `name` | str | `""` | HF subset name，如 `"20231101.zh"` |
-| `split` | str | `"train"` | HF split |
-| `text_field` | str | `"text"` | 要讀取的欄位名稱 |
-| `filter_field` | str | `""` | 過濾欄位（空=不過濾）|
-| `filter_values` | list | `[]` | 允許通過的值清單 |
-| `streaming` | bool | `true` | 串流載入（省記憶體）|
-| `shuffle` | bool | `true` | 是否打亂 |
-| `buffer_size` | int | `10000` | shuffle 緩衝大小 |
-| `min_length` | int | `50` | 最短文字長度（字元）|
-| `max_samples` | int | `0` | 最多取用樣本數（0=不限）|
-| `weight` | float | `1.0` | weighted 混合時的取樣比例 |
-| `file_format` | str | `"txt"` | 本地格式：`txt` / `jsonl` / `csv` |
-| `glob_pattern` | str | `"**/*.txt"` | local_dir 模式的 glob |
-| `csv_delimiter` | str | `","` | CSV 分隔符 |
-| `seed` | int | `42` | 隨機種子 |
-| `label` | str | _(path basename)_ | 日誌顯示標籤 |
-
-### 方式 2：CLI 快速指定
+本程式**不支援純 CPU 執行**，需要以下其中一種硬體加速環境。以下規格為**最低需求**，不符合者將無法完成訓練：
 
-```bash
-# HuggingFace 資料集
-python train_llm.py --mode train \
-    --dataset_path "wikimedia/wikipedia" \
-    --dataset_name "20231101.zh" \
-    --text_field "text"
-
-# 本地 JSONL 檔案
-python train_llm.py --mode train \
-    --dataset_path "/data/corpus.jsonl" \
-    --source_type local_files \
-    --file_format jsonl \
-    --text_field "content"
-
-# 本地目錄（掃描所有 .txt）
-python train_llm.py --mode train \
-    --dataset_path "/data/articles/" \
-    --source_type local_dir \
-    --file_format txt
-```
+| 環境 | 最低需求 | 建議機型範例 |
+|------|----------|-------------|
+| Apple Silicon Mac | 統一記憶體（RAM）**≥ 128 GB**，需安裝 MLX | Mac Studio / Mac Pro（M2 Ultra 192GB、M3 Ultra 192GB） |
+| NVIDIA GPU | 單卡顯存 **≥ 92 GB**，CUDA 11.8 或以上 | H100 NVL（94 GB）、H200（141 GB） |
+| 主機記憶體（RAM） | **≥ 64 GB**（兩種環境皆適用） | — |
 
-### 方式 3：預設 FineWeb2（無需額外設定）
+> ⚠️ **重要：** 訓練環境低於以上任一最低需求，程式將因記憶體不足而無法執行完整訓練。
+>
+> **需求說明：**
+> - float32 模型權重 ≈ 4.3 GB；加上梯度與 AdamW 狀態（各一份，共 3× 權重大小），訓練峰值顯存約 **90 GB 以上**。
+> - Apple Silicon 的統一記憶體由 CPU 與 GPU 共用，128 GB 為能在 MLX bfloat16 模式下穩定訓練的最低配置。
+> - 主機記憶體（系統 RAM）需 ≥ 64 GB，以容納分詞器訓練資料、資料集 tokenize、chunk 建構及 PyTorch 的系統側暫存空間。
 
-```bash
-# 預設語言：簡體中文 + 繁體中文 + 英文
-python train_llm.py --mode train
+### Python 套件
 
-# 自訂語言過濾
-python train_llm.py --mode train --langs "zho_Hans,eng_Latn"
+```
+torch >= 2.2.0
+mlx >= 0.12.0          # 僅 Apple Silicon 需要
+sentencepiece >= 0.1.99
+datasets >= 2.14.0
+transformers >= 4.38.0
+safetensors >= 0.4.0
+numpy >= 1.24.0
+matplotlib >= 3.7.0
+tqdm >= 4.65.0
 ```
 
-### 多來源混合策略
+---
+
+## 安裝
 
 ```bash
-# sequential（預設）：依序消耗每個來源
-python train_llm.py --mode train --dataset_config dataset_config.json
+# 1. 複製專案
+git clone https://github.com/your-username/kuixing.git
+cd kuixing
+
+# 2. 建立虛擬環境（建議）
+python -m venv venv
+source venv/bin/activate   # Windows: venv\Scripts\activate
+
+# 3. 安裝 PyTorch（依據您的硬體選擇）
+# CUDA 12.1：
+pip install torch --index-url https://download.pytorch.org/whl/cu121
+# Apple Silicon（CPU/MPS fallback）：
+pip install torch
+
+# 4. 安裝 MLX（Apple Silicon 專用，建議安裝以獲得最佳性能）
+pip install mlx
 
-# weighted：依 weight 比例同時交錯取樣（推薦多語料混訓）
-python train_llm.py --mode train \
-    --dataset_config dataset_config.json \
-    --mix_strategy weighted
+# 5. 安裝其餘相依套件
+pip install sentencepiece datasets transformers safetensors numpy matplotlib tqdm
 ```
 
 ---
 
-## 訓練模式
+## 訓練程式用法
 
-### 從頭訓練（Pretrain）
+### 互動模式（無參數，推薦初次使用）
 
 ```bash
-python train_llm.py --mode train \
-    --model_name kuixing-1.15b \
-    --max_steps 1000000 \
-    --seq_len 4096 \
-    --lr 2e-4
+python KuiXing_Trainer_MLT.py
 ```
 
-### 接續訓練（Continue）
+程式會自動偵測硬體環境，若有既有模型則詢問是否接續訓練及使用哪個資料集；若無既有模型則從頭開始訓練。
 
-**從 Trainer Checkpoint 接續**（訓練中斷後繼續，保留優化器狀態與步驟）：
+### 常用指令
 
 ```bash
-python train_llm.py --mode train \
-    --train_mode continue \
-    --resume_from_checkpoint ./checkpoints/checkpoint-50000 \
-    --max_steps 1000000
-```
+# 從頭訓練（強制忽略已存在的模型）
+python KuiXing_Trainer_MLT.py --from-scratch
 
-**從 Release Export 接續**（換資料集繼續預訓練，步驟重設）：
+# 直接接續訓練（不互動詢問，使用 config 預設資料集）
+python KuiXing_Trainer_MLT.py --resume
 
-```bash
-python train_llm.py --mode train \
-    --train_mode continue \
-    --resume_from_checkpoint ./checkpoints/release/kuixing-1.15b-20250101_120000/model \
-    --dataset_path "wikimedia/wikipedia" \
-    --dataset_name "20231101.zh" \
-    --lr 1e-4 \
-    --max_steps 200000
-```
+# 接續訓練並切換到新資料集
+python KuiXing_Trainer_MLT.py --resume --dataset jslin09/other_dataset --column text
 
-### 重新發布存檔
+# 以新資料集從頭訓練
+python KuiXing_Trainer_MLT.py --from-scratch --dataset your_org/dataset_name --column article
 
-對已完成訓練的 checkpoint 重新打包（不需重新訓練）：
+# 獨立繪圖模式（讀取訓練記錄後生成曲線圖，不啟動訓練）
+python KuiXing_Trainer_MLT.py --plot
 
-```bash
-python train_llm.py --mode export \
-    --output_dir ./checkpoints \
-    --tokenizer_model ./data/spm_tokenizer.model \
-    --model_name kuixing-1.15b
+# 訓練摘要模式（顯示 loss / perplexity 統計後結束，不啟動訓練）
+python KuiXing_Trainer_MLT.py --summary
 ```
 
 ---
 
-## CLI 完整參數
+## CLI 參數說明
+
+| 參數 | 類型 | 說明 |
+|------|------|------|
+| `--from-scratch` | flag | 強制從頭訓練，忽略已存在的 checkpoint 與模型 |
+| `--resume` | flag | 直接接續上次訓練，跳過互動詢問 |
+| `--dataset NAME` | string | 指定 HuggingFace 資料集名稱（如 `jslin09/wikipedia_tw`） |
+| `--column COL` | string | 指定資料集中的文章欄位名稱（如 `article`、`text`） |
+| `--plot` | flag | 讀取 JSONL 訓練記錄，生成四格訓練曲線圖後結束 |
+| `--summary` | flag | 讀取 JSONL 訓練記錄，顯示訓練摘要統計後結束 |
+
+> **注意：** `--from-scratch` 與 `--resume` 互斥，不可同時使用。  
+> `--plot` 與 `--summary` 為獨立模式，不觸發硬體偵測或訓練流程。
+
+### 訓練摘要輸出範例（`--summary`）
 
 ```
---mode              train | tokenizer | demo | info | export
---model_name        發布名稱前綴（預設: kuixing-1.15b）
---data_dir          分詞器語料目錄（預設: ./data）
---output_dir        訓練輸出目錄（預設: ./checkpoints）
---tokenizer_model   SPM 模型路徑（預設: ./data/spm_tokenizer.model）
-
-訓練模式：
---train_mode        pretrain（預設）| continue
---resume_from_checkpoint  接續訓練的 checkpoint 路徑
-
-資料集（三選一）：
---dataset_config    JSON 設定檔路徑（最高優先）
---dataset_path      單一資料集路徑（HF id 或本地路徑）
---dataset_name      HF subset name
---dataset_split     HF split（預設: train）
---text_field        文字欄位名稱（預設: text）
---filter_field      過濾欄位名稱
---filter_values     過濾值，逗號分隔
---source_type       huggingface | local_files | local_dir
---file_format       txt | jsonl | csv
---langs             FineWeb2 語言清單，逗號分隔（預設行為）
---mix_strategy      sequential（預設）| weighted
---no_streaming      停用串流，完整下載後載入
-
-超參數：
---batch_size        per-device batch size（-1=自動）
---grad_accum        gradient accumulation steps（-1=自動）
---lr                學習率（預設: 2e-4）
---max_steps         總訓練步數（串流資料集用；預設 1,000,000）
-                    與 --num_epochs 同時指定時 epoch 模式優先
---num_epochs        訓練 epoch 數（有限資料集用；-1=停用，改用 --max_steps）
-                    適合本地資料集或固定大小的 HuggingFace 資料集
---seq_len           訓練序列長度（預設: 4096）
---warmup_steps      warmup 步數（預設: 4000）
-
-Checkpoint 儲存（--save_steps 與 --save_total_limit 搭配使用）：
---save_steps        每幾步儲存一個 checkpoint（預設: 5000）
---save_total_limit  最多同時保留幾份 checkpoint（預設: 3）
-                      0 = 無限制，保留所有 checkpoint
-                      例: --save_steps 2000 --save_total_limit 10
-
-精度：
---bf16              BF16：-1=自動，0=關，1=開
---fp16              FP16：-1=自動，0=關，1=開
-
-Loss 記錄：
---loss_log_file     Training loss CSV 路徑
-                      空字串 = 自動使用 {output_dir}/training_loss.csv
-                      接續訓練時自動 append，不覆蓋已��記錄
-
-其他：
---no_grad_ckpt      停用 gradient checkpointing
---workers           DataLoader workers（-1=自動）
+============================================================
+  🏁  KuiXing 訓練完成摘要
+============================================================
+  總記錄步數         : 2,811  步（optimizer update）
+  訓練 Epoch        : 3
+  學習率範圍         : 0.00e+00  →  3.00e-04
+  梯度被裁剪次數      : 51  次（佔 1.8%）
+============================================================
+  最終 Loss         : 2.741243
+  最終 Perplexity   : 15.5062
+============================================================
+  最佳 Loss         : 2.639037  （第 81,311 步）
+  最佳 Perplexity   : 13.9997
+============================================================
+  末 100 步平均 Loss : 2.784486
+  末 100 步平均 PPL  : 16.1915
+============================================================
 ```
 
 ---
 
-## Training Loss 記錄與繪圖
+## 輸出格式與載入方式
 
-### CSV 格式
-
-訓練過程中自動產生 `{output_dir}/training_loss.csv`（或 `--loss_log_file` 指定路徑）：
+訓練完成後，程式自動將模型輸出至 `./kuixing_model/`，包含以下檔案：
 
 ```
-step,epoch,loss,learning_rate,grad_norm,samples_seen,elapsed_sec
-100,0.0,8.312451,0.0002,1.2341,3200,45.2
-200,0.0,7.891234,0.00019,1.1892,6400,89.7
-...
-1000000,0.0,2.341200,2e-05,0.8123,3200000,18420.0
-1000000,0.0,END,,,,18421.1
+kuixing_model/
+├── model.safetensors      # float32 模型權重（HuggingFace 格式）
+├── config.json            # 模型架構設定
+├── modeling_kuixing.py    # 自訂架構定義（含 AutoModel 支援）
+├── tokenizer_config.json  # Tokenizer 設定
+└── tokenizer.model        # SentencePiece BPE tokenizer
 ```
 
-- **接續訓練**：自動 append，`END` 行標記每段訓練結束，可區分多次訓練
-- **即時 flush**：每個 log step 寫入後立即 flush，中斷也不丟失記錄
-
-### 繪圖工具 `plot_loss.py`
+### 載入方式
 
-```bash
-# 基本使用（讀取預設 CSV，輸出 PNG）
-python plot_loss.py
+**方式一：直接使用自訂類別（推薦）**
 
-# 指定路徑與輸出
-python plot_loss.py \
-    --csv ./checkpoints/training_loss.csv \
-    --out ./loss_curve.png
+```python
+from modeling_kuixing import KuiXingForCausalLM
 
-# 印出訓練摘要統計（最終 loss、最低點、收斂步數）
-python plot_loss.py --summary
+model = KuiXingForCausalLM.from_pretrained("./kuixing_model")
+model = model.eval()
+```
 
-# 比較 pretrain + continue 兩段訓練
-python plot_loss.py \
-    --csv ./run1/training_loss.csv ./run2/training_loss.csv \
-    --labels "Pretrain" "Continue (Wikipedia)" \
-    --out compare.png
+**方式二：bfloat16 推理（節省記憶體）**
 
-# 以訓練時間為 X 軸，顯示互動視窗
-python plot_loss.py --x_axis elapsed_sec --show
+```python
+import torch
+from modeling_kuixing import KuiXingForCausalLM
 
-# 過濾初期 spike，調整平滑視窗
-python plot_loss.py --max_loss 10.0 --smooth 100
+model = KuiXingForCausalLM.from_pretrained("./kuixing_model")
+model = model.to(torch.bfloat16).eval()
 ```
 
-圖表包含三個面板：
+**方式三：透過 HuggingFace AutoModel**
 
-| 面板 | 內容 |
-|------|------|
-| Loss 曲線 | 原始 loss（半透明）+ 滾動平均平滑，自動標記最低點 |
-| Learning Rate | Cosine decay + warmup 排程曲線 |
-| Gradient Norm | L2 norm 趨勢（反映訓練穩定性）|
+```python
+from transformers import AutoModelForCausalLM
 
----
+model = AutoModelForCausalLM.from_pretrained(
+    "./kuixing_model",
+    trust_remote_code=True,
+)
+```
 
-## 發布存檔格式
+**方式四：從 HuggingFace Hub 載入**
 
-訓練完成後自動產生（也可用 `--mode export` 手動觸發）：
+```python
+from transformers import AutoModelForCausalLM
 
-```
-checkpoints/release/{model_name}-{timestamp}/
-├── model/
-│   ├── model.safetensors      # 模型權重（SafeTensors，推薦）
-│   ├── pytorch_model.bin      # 模型權重（PyTorch bin，相容備用）
-│   ├── config.json            # 架構與超參數設定
-│   └── generation_config.json # 預設生成參數
-├── tokenizer/
-│   ├── spm_tokenizer.model    # SentencePiece 模型
-│   ├── spm_tokenizer.vocab    # 詞彙表（piece + BPE score）
-│   ├── tokenizer_config.json  # HuggingFace tokenizer 設定
-│   └── special_tokens_map.json
-├── model_card.md              # HuggingFace Hub 模型說明卡
-├── manifest.json              # 所有檔案 SHA-256 + 大小清單
-└── release_info.json          # 訓練環境、超參數完整快照
+model = AutoModelForCausalLM.from_pretrained(
+    "jslin09/kuixing",
+    trust_remote_code=True,
+)
 ```
 
 ---
 
-## 建議硬體配置
+## 程式限制
+
+使用本訓練程式前，請了解以下限制：
+
+**硬體限制**
+- 不支援純 CPU 執行。程式於啟動時偵測硬體，若未找到 MPS 或 CUDA 裝置，將直接終止並提示錯誤。純 CPU 模式因速度過慢（預估為 GPU 的 50–200 倍）而刻意排除。
+
+**記憶體需求為硬性限制**
+- 訓練峰值顯存（含模型權重、梯度、AdamW 狀態）約需 **90 GB 以上**。NVIDIA GPU 需單卡顯存 ≥ 92 GB（如 H100 NVL 94 GB），Apple Silicon 需統一記憶體 ≥ 128 GB，主機 RAM 需 ≥ 64 GB。低於上述任一門檻者將因記憶體不足而無法完成訓練，此為硬性限制，無法透過縮減 `batch_size` 解決（梯度累積步數已補償批次大小，顯存瓶頸在於模型本身與優化器狀態）。
 
-| 硬體 | batch | grad_accum | seq_len | 精度 |
-|------|-------|------------|---------|------|
-| A100 80G | 4 | 8 | 4096 | BF16 |
-| A100 40G | 2 | 16 | 4096 | BF16 |
-| RTX 4090 24G | 1 | 32 | 2048 | BF16 |
-| RTX 3090 24G | 1 | 32 | 2048 | FP16 |
-| M3 Max 128G | 2 | 16 | 4096 | BF16 |
-| M2 Ultra 192G | 2 | 16 | 4096 | BF16 |
-| M2 Max 96G | 1 | 32 | 2048 | BF16 |
-| M1/M2 16-24G | 1 | 32 | 1024 | FP32 |
+**MPS 平台限制**
+- Apple Silicon 使用 MPS 後端（無 MLX）時，MPS 尚不支援 `torch.autocast`，因此以 float32 全精度訓練，速度與記憶體效率低於 MLX 路徑。建議安裝 MLX 以獲得最佳性能。
 
-> **1M context 推理**需搭配 Flash Attention 2（CUDA A100/H100）或足夠的 Apple Silicon Unified Memory。訓練時 `seq_len=4096` 即可；長上下文外推由 YaRN 在推理時自動完成。
+**多 GPU 不支援**
+- 本程式目前僅支援單一 GPU 訓練，未實作 DDP（DistributedDataParallel）或 FSDP，無法直接用於多卡並行訓練。
+
+**Checkpoint 跨平台相容性**
+- PyTorch（CUDA/MPS）與 MLX（Apple Silicon）的 checkpoint 格式不同，無法直接互換。MLX checkpoint 以 `.npz` 儲存，PyTorch checkpoint 以 `.pt` 儲存。
+
+**Tokenizer 字型依賴**
+- 訓練曲線繪圖功能依賴本地安裝的繁體中文字型（Noto Sans CJK TC），字型路徑硬編碼於程式中。若路徑不符，繪圖將失敗或顯示亂碼。**此設定不應修改**（程式設計刻意保留）。
+
+**資料集格式**
+- 目前僅支援 HuggingFace `datasets` 格式的文字資料集，需指定文字欄位名稱。不支援本地 jsonl、txt、csv 直接輸入（需先上傳至 HuggingFace 或自行修改 `build_chunks()` 函式）。
+
+**推理功能**
+- 本程式為**預訓練專用訓練器**，不包含文字生成（inference）功能。推理請使用輸出的 HuggingFace 格式模型搭配 `transformers` 的 `generate()` 方法。
 
 ---
 
-## 專案結構
+## 目錄結構
+
+執行訓練後，工作目錄將產生以下結構：
 
 ```
-.
-├── train_llm.py                 # 主程式（分詞器 / 訓練 / 推論 / 存檔）
-├── plot_loss.py                 # Training loss 曲線繪圖工具
-├── dataset_config.json          # 多來源混合範例（FineWeb2 + Wikipedia）
-├── dataset_config_local.json    # 本地 JSONL 資料集範例
-├── requirements.txt             # Python 套件需求
-├── README.md                    # 本文件
-├── CHANGELOG.md                 # 版本變更記錄
-├── LICENSE                      # Apache 2.0 授權
-└── .gitignore                   # Git 排除規則
+./
+├── KuiXing_Trainer_MLT.py     # 主訓練程式
+│
+├── kuixing_tokenizer/          # Tokenizer 檔案（自動生成）
+│   ├── tokenizer.model
+│   └── tokenizer.vocab
+│
+├── kuixing_checkpoints/        # 訓練 Checkpoint（自動生成）
+│   ├── ckpt_ep0_step500.pt
+│   ├── ckpt_ep0_step1000.pt
+│   └── ...（保留最新 3 個）
+│
+├── kuixing_logs/               # 訓練記錄（自動生成）
+│   ├── training_log.jsonl      # 每步指標（loss, lr, grad_norm, ...）
+│   └── training_curves.png    # 訓練曲線圖（每 200 步更新）
+│
+└── kuixing_model/              # 最終輸出（訓練完成後生成）
+    ├── model.safetensors
+    ├── config.json
+    ├── modeling_kuixing.py
+    ├── tokenizer_config.json
+    └── tokenizer.model
 ```
 
 ---
 
-## 常見問題
+## 授權事項
+
+### 程式碼授權
+
+本專案訓練程式碼（`KuiXing_Trainer_MLT.py` 及相關檔案）以 **MIT License** 授權，允許自由使用、修改與散布，包含商業用途，惟需保留原始版權聲明。
+
+```
+MIT License
+
+Copyright (c) 2025 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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-**Q: macOS 出現 `OMP: Error #15: Initializing libomp.dylib` 然後 abort？**
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-A: 這是 macOS 上 PyTorch、sentencepiece 等套件各自靜態連結不同版本 libomp 所導致的衝突。本程式已在啟動時自動設定 `KMP_DUPLICATE_LIB_OK=TRUE` 等環境變數，理論上不會出現此問題。若仍發生，請確認您使用的是 `python train_llm.py` 而非直接 import 本模組。
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+```
 
-**Q: MPS 上訓練比 CPU 還慢？**
+### 模型權重授權
 
-A: 部分運算（如 MoE router 的 scatter/gather）在 MPS 上會 fallback 至 CPU，導致額外的資料搬移開銷。可嘗試減小 `--seq_len` 或 `--batch_size` 以提高 Metal GPU 利用率。
+訓練完成的模型權重（`model.safetensors`）以 **Creative Commons Attribution-NonCommercial 4.0 International（CC BY-NC 4.0）** 授權發布。
 
-**Q: 1M context 真的能用嗎？**
+**您可以：**
+- ✅ 分享：以任何媒介或格式複製、散布本模型
+- ✅ 改作：修改、轉換本模型，以其為基礎進行創作（如微調）
+- ✅ 學術研究與個人使用
 
-A: 訓練時固定使用 `--seq_len 4096`（或自訂），推理時 YaRN 外推讓模型能處理更長序列。實際最大長度受限於可用記憶體：80GB A100 約可推理 128K–512K tokens（使用 Flash Attention + KV cache 量化）。
+**但需遵守以下條件：**
+- 📌 **姓名標示（Attribution）：** 使用本模型時，需標示原始作者（jslin09 / KuiXing）及授權連結
+- 🚫 **非商業性（NonCommercial）：** 不得將本模型或其衍生物用於商業目的
+- 📌 **相同方式分享（ShareAlike）：** 若散布衍生模型，需採用相同的 CC BY-NC 4.0 或相容授權
 
-**Q: `safetensors` 套件未安裝時怎麼辦？**
+完整授權條款請見：https://creativecommons.org/licenses/by-nc/4.0/
 
-A: 程式會自動偵測。若未安裝，則跳過 SafeTensors 格式，仍輸出 `pytorch_model.bin`。建議安裝：`pip install safetensors`。
+### 訓練資料聲明
 
-**Q: 如何只訓練分詞器而不訓練模型？**
+本模型以台灣維基百科（`jslin09/wikipedia_tw`）為主要訓練語料，該語料源自維基媒體基金會，依據 [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) 授權。使用者在引用本模型產出內容時，亦應留意上游授權要求。
 
-A: `python train_llm.py --mode tokenizer --data_dir ./data`
+### 免責聲明
+
+本模型為研究性質的預訓練語言模型，**不保證輸出內容的正確性、完整性或安全性**。使用者需自行評估並承擔模型輸出的風險。作者不對因使用本模型造成的任何直接或間接損失負責。
 
 ---
 
-## 授權
+## 引用
+
+若您在研究或作品中使用了 KuiXing，請引用本專案：
 
-本專案採用 **Apache License 2.0**。詳見 [LICENSE](LICENSE)。
+```bibtex
+@misc{kuixing2026,
+  author       = {Chun-Hsien Lin},
+  title        = {KuiXing: A Traditional Chinese Pre-trained Language Model},
+  year         = {2026},
+  publisher    = {HuggingFace},
+  howpublished = {\url{https://huggingface.co/jslin09/kuixing}},
+}
+```
+
+---
 
-訓練資料 FineWeb2 由 HuggingFace 提供，請遵守其[資料集授權](https://huggingface.co/datasets/HuggingFaceFW/fineweb-2)。
+<p align="center">
+  以繁體中文為本，從零開始。<br>
+  <em>Built from scratch, for Traditional Chinese.</em>
+</p>