docs/CORRECTNESS.md

# 正確性驗證

分頁路徑的每一層都要能被獨立證明是對的。這份文件記錄三層驗證、決定性證據，
以及一個在這個模型上才會出現的數值現象（§4）。

三層的分工：

| 層 | 證明什麼 | 對照組 |
| --- | --- | --- |
| 1 kernel | 單一 expert 的前向（Q8_K 量化 → 三次量化點積 → SiLU → 加權） | NumPy 純重算，照抄 ggml 的 dequantize 與 quantize 定義 |
| 2 整層 | 多 token、真實路由、權重縮放、槽位配置、預取路徑 | NumPy 用模型自己產生的 `cur / selected_experts / weights` 重算 |
| 3 端到端 | 圖層面接線、跨層一致性 | llama.cpp 原生 `mul_mat_id`（**在 8 GiB 上不可能執行**，見 §3.3） |

執行方式：

```bash
python3 -m sdq.verify --model <gguf> --bin <epq-chat> --fast
python3 tools/determinism_check.py --model <gguf> --bin <epq-chat> --runs 5 -n 48
```

---

## 1. kernel 層級（單一 expert）

四組 (layer, expert)，用 `--selftest` 讓 pager 從 arena 算出結果，Python 從
**同一段 GGUF 位元組**獨立重算：

| 層 | Expert | 結果 | max abs diff |
| --- | ---: | --- | ---: |
| 0 | 3 | PASS | 3.7e-09 |
| 17 | 200 | PASS | — |
| 33 | 7 | PASS | — |
| 39 | 100 | PASS | — |

**為什麼是這四組**：這個模型有**兩種 expert 大小**。

* 20 層的 `ffn_down_exps` 是 Q6_K → 每個 expert 2,039,808 B
* 20 層的 `ffn_down_exps` 是 Q4_K → 每個 expert 1,769,472 B

L39 屬於前者，是唯一會走到「大槽位」配置路徑的測試；少了它，槽位配置器把
小槽位發給大 expert 的錯誤不會被發現。L17 / L33 屬於後者。

`tools/moe_ref.py` 對 Q4_K / Q5_K / Q6_K 三種 block 格式各自實作反量化，
其中 Q6_K 的實作另外與 ggml 的 `dequantize_row_q6_K` **逐位元組比對過**
（4096 個 block，最大差 0）。

## 2. 整層層級（真實路由輸入）

用 `SDQ_MOE_DUMP` 導出某一層的真實輸入（21 個 token，中文提示詞）與輸出：

| 層 | max abs diff | max rel | 1-LSB 翻轉上界 | 判定 |
| --- | ---: | ---: | ---: | --- |
| 0 | 1.12e-08 | 5.1e-07 | 1.73e-03 | PASS |
| 39 | 8.82e-05 | 7.7e-03 | 3.22e-02 | PASS（量化邊界，見 §4） |

預取壓力測試（預取開著 + 極小 arena 強制回收，兩種槽位配置各跑一次）4 組全 PASS。

## 3. 端到端與決定性

### 3.3 為什麼沒有端到端 A/B

原生對照組需要把整個 21.17 GB 模型常駐 RAM。在 8 GiB 上這**在定義上不可能**，
而這正是本專案存在的理由。實測未修改的 llama.cpp 在 8 GiB 上連模型都載不進去：

```
ggml_backend_buft_alloc_buffer_n_default: failed to allocate CPU_REPACK buffer of size 15099494400
llama_model_load: error loading model: unable to allocate CPU_REPACK buffer
```

所以等價性改由 kernel / 整層 / 預取壓力三層，加上下面的決定性證據支撐。

### 3.1 決定性（決定性 = 同條件重複執行，逐位元組一致）

`tools/determinism_check.py`，5 次執行 × 48 token × 248,144 vocab：

```
run0: 14.1s   run1: 14.1s   run2: 14.4s   run3: 14.3s   run4: 15.6s
✅ run1..run4 與 run0 全部逐位元組完全相同
```

分頁路徑在同一台機器、同一組條件下是**決定性**的。快取命中與否都包含在這個
證據裡：5 次執行的 arena 內容不同（命中模式隨存取順序變動），輸出仍然逐位元組相同。

### 3.2 過程中修掉的問題

1. **GGUF 標頭解析在 BOOL 陣列上錯位。** 這個模型有
   `qwen35moe.attention.recurrent_layers`（40 個元素的 **BOOL 陣列**）。參考實作
   把陣列元素型別 7 讀成 4 bytes，標頭解析從那裡起全部錯位，最後以
   `basic_string::_M_create`（讀到垃圾長度）失敗。修正：BOOL 陣列元素讀 1 byte，
   並且讓未知的元素型別**丟出例外**而不是靜默跳過 —— 靜默跳過會讓 `r.o` 停在
   值的中間，之後每一個 key 都是錯的。
   這個 key 是混合架構（SSM 層）才有的，參考的 Qwen3.6-35B-A3B 沒有。

## 4. 一個 Q8_K 量化邊界造成的 7.9e-4 差異

L39 / 某個 token 上，整層比對差 8.82e-05，超過原本 3e-3 的相對容差門檻
（該元素 |out| 只有 0.0186，所以相對誤差 7.7e-3）。逐層追查的結果：

**這不是 pager 的錯誤，是驗證工具的浮點參考不夠準。** 完整證據鏈：

1. **Q8_K 輸入量化逐位元組一致。** 取出該 token 的 activation，用 ggml 自己的
   `quantize_row_q8_K_ref` 量化，與 Python 端的 481 個 block 總和
   （`bsums`）**全部一致**。
2. **權重反量化逐位元組一致。** Q6_K 的 `dequantize_row_q6_K` 在 4096 個 block 上
   與 NumPy 實作最大差 0。
3. **差異只來自 Q8_K 的 1 個 LSB。** 把 C++ 端算出的 SiLU 中間值 `h` 讀回來餵給
   NumPy 參考：481 個非零 Q8_K code 中**剛好 1 個差 1**，輸出立刻從 7.86e-04
   掉到 **6.7e-08**。
4. **上游 `go` 的差異來自 ggml 的 float32 累加。** ggml 的 `vec_dot` 在 float32
   裡累加，本專案的 NumPy 參考用 float64。C++ 端 `gate` / `up` 與 NumPy 最多差
   9.5e-07 —— 這是 ggml 側的捨入，不是 NumPy 的。
5. **把 `go` 人為擾動 1e-7（相對）就能重現整個差異**，而且只有那一個 token 受影響，
   同一層其他 5 個 token 仍在 1e-07。

也就是說：`h` 上 1e-6 的差 → Q8_K 四捨五入跨界 1 格 → 輸出跳 7.9e-4。
**單一 LSB 翻轉的理論上界是 3.22e-02，實測 8.82e-05，差 365 倍。**

因此 `tools/moe_layer_check.py` 的判定改成兩段式：先照舊用固定容差比對，
若不通過則檢查實測差異是否落在「單一 Q8_K LSB 翻轉」的理論上界之內，
並在輸出裡明確標成 `PASS (quantization-boundary)` —— 而不是把容差默默放寬。

**這個現象是模型性質，不是這個 repo 的性質。** 參考的 Qwen3.6-35B-A3B 在同樣的
檢查下是 8.11e-06（PASS），因為它沒有碰到這種條件數的輸入。