Add Ling-3.0-tiny EPQ experiment report

README.md

@@ -0,0 +1,101 @@
+---
+license: mit
+library_name: gguf
+base_model: inclusionAI/Ling-3.0-tiny-GGUF
+pipeline_tag: text-generation
+tags:
+  - gguf
+  - bailingmoe3
+  - ling
+  - moe
+  - expert-paging
+  - ssd-to-ram
+  - cpu
+---
+
+# Ling-3.0-tiny：EPQ 專家分頁與嚴格 RAM 上限實驗
+
+本 repo 記錄對 [`inclusionAI/Ling-3.0-tiny-GGUF`](https://huggingface.co/inclusionAI/Ling-3.0-tiny-GGUF) 的
+`Ling-3.0-tiny-Q4_K_M.gguf` 所做的 MoE expert paging 實驗。模型原始檔約 **4,823,894,944 B / 4.49 GiB**；本 repo 不重複託管權重，請由上游下載。
+
+EPQ 將未啟用的 expert 權重留在 SSD，以有限的 RAM arena 暫存目前路由選中的 experts，再由 CPU 計算。實驗用 `prlimit --data` 對匿名記憶體施加核心層硬上限，並抽樣確認 swap 為 0。檔案對映的模型頁另列 RSS，不視為匿名記憶體上限的一部分。
+
+## 快速開始
+
+```bash
+hf download inclusionAI/Ling-3.0-tiny-GGUF Ling-3.0-tiny-Q4_K_M.gguf \
+  --local-dir models
+```
+
+建置 pager engine（Release、停用 CPU repack，低記憶體級別才可避免 repack 配置）：
+
+```bash
+git clone https://github.com/ggml-org/llama.cpp
+cd llama.cpp
+git checkout c811cb8f0ac91b8ac72a32f970bdd45037f20da7
+git apply ../sdq-ling/0001-sdq-ling.patch
+cp ../sdq-ling/sdq_{pager.h,pager.cpp,buft.cpp,moe.cpp,cli.cpp} src/
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DLLAMA_CURL=OFF \
+  -DGGML_NATIVE=OFF -DGGML_CPU_REPACK=OFF -DGGML_AVX512=ON \
+  -DGGML_AVX512_VBMI=ON -DGGML_AVX512_VNNI=ON -DGGML_AVX512_BF16=ON \
+  -DGGML_AVX2=ON -DGGML_FMA=ON -DGGML_F16C=ON \
+  -DGGML_AMX_INT8=OFF -DGGML_AMX_TILE=OFF -DGGML_AMX_BF16=OFF
+cmake --build build -j 8 --target sdq-chat
+cd ..
+```
+
+再執行：
+
+```bash
+RAM_BUDGET_MB=4096 ./sdq-ling/serve.sh
+```
+
+`RAM_BUDGET_MB` 設定 pager 預算；`RESERVE_MB` 預設 700 MB。此腳本適用於小 context 的本次實驗設定，不等同於任意長 context 的服務部署設定。
+
+## 模型與路由
+
+| 項目 | 數值 | 來源 |
+| --- | ---: | --- |
+| 架構 | `bailingmoe3` | GGUF metadata |
+| 模型檔 | 4,823,894,944 B / 4.493 GiB | 下載檔大小 |
+| 層數 | 24 | GGUF metadata |
+| MoE experts | 128 experts/layer；24 層有 expert tensors | GGUF metadata / pager tensor scan |
+| 每 token 啟用 | 8 experts | GGUF `expert_used_count` |
+| expert 權重 | gate/up Q4_K，down Q6_K；約 4.2 GiB | GGUF tensor metadata |
+| context metadata | 131,072 | GGUF metadata |
+
+## 嚴格 RAM 上限實測
+
+每輪都由 `prlimit --data=<bytes>` 設定 RLIMIT_DATA；不是只有傳 pager budget。測試用 ctx=256、ubatch=32、threads=4、temperature=0，每輪生成 32 tokens、每級兩次。使用 Intel Xeon Platinum 8559C 主機，CPU-only，192 threads；上層 cgroup `memory.max=104000000000`、`memory.swap.max=2936848384`。build 關閉 `GGML_CPU_REPACK` 與 AMX；每輪前對模型檔呼叫 `posix_fadvise(DONTNEED)`。
+
+| RAM 上限 | 結果 | arena GiB | slots | anon 峰值 MB | RSS 峰值 MB | decode tok/s (兩輪平均) | SSD MiB/token | hot % | swap MB |
+|---:|:---:|---:|---:|---:|---:|---:|---:|---:|---:|
+| 1 GiB | PASS | 0.30 | 225 | 421 | 905 | 8.25 | 199.8 | 16.7 | 0 |
+| 2 GiB | PASS | 1.30 | 979 | 1,412 | 1,895 | 11.88 | 73.8 | 49.5 | 0 |
+| 4 GiB | PASS | 3.30 | 2,486 | 3,404 | 3,888 | 16.38 | 24.8 | 66.7 | 0 |
+| 8 GiB | PASS | 7.01 | 5,279 | 7,064 | 7,548 | 18.65 | 7.1 | 76.3 | 0 |
+| 16 GiB | PASS | 14.62 | 11,012 | 14,600 | 15,084 | 19.24 | 7.1 | 76.3 | 0 |
+
+anon 峰值是 RLIMIT_DATA 主要管制並用來判斷 PASS 的欄位；檔案對映頁會讓 RSS 高於匿名量。16 GiB 相較 8 GiB 的 hot% 與每 token SSD 讀取已無明顯改善，表示在本次 prompt/解碼長度下 8 GiB 已容納幾乎相同的 expert working set。tok/s 受共享主機負載影響，請視為本機觀測值。
+
+## I/O page-cache 對照
+
+在 1 GiB 限制下，pager 預設 `O_DIRECT` 組跑到約 9 GiB 實際 device reads 時，整個模型檔在 page cache 的峰值約 **0.496 GiB**。Buffered 對照組使用 `SDQ_NO_DIRECT_IO=1`，page-cache resident 隨讀取升至 **3.341 GiB**（模型檔 74.4%），證實兩組能區分直讀與 buffered read。原始逐次數據見 `results/io_direct_watch.txt` 與 `results/io_buffered_watch.txt`。
+
+## 產物
+
+- `results/strict_memory_levels.md`、`results/strict_memory_levels.json`：1/2/4/8/16 GiB 硬限制的兩輪原始結果。
+- `results/io_*_watch.txt`：O_DIRECT 與 buffered page-cache 對照。
+- `results/verify_dequant.txt`、`results/verify_selftest_numpy.txt`、`results/verify_moe_layer.txt`：pager 數值正確性檢查。
+- `sdq-ling/strict_bench.py`：可重跑的限制矩陣 benchmark。
+- `sdq-ling/0001-sdq-ling.patch` 與 `sdq-ling/sdq_*.{cpp,h}`：參考 EPQ pager 的 llama.cpp patch/source。
+- `results/host_capability_audit.txt`：測試主機與容器資訊。
+
+數值檢查摘要：Q4_K/Q6_K dequant 與 ggml 對照 21/21 列逐位元一致；單 expert forward 的 max relative error=0.0228、corr=0.999685；真實 MoE routing + weighted layer 的 max relative error=0.01374、corr=0.999856。詳見上述檢查輸出檔。
+
+## 限制
+
+- 此測試的 `RLIMIT_DATA` 約束匿名配置，並非 cgroup 的完整 process + page-cache 總額限制；RSS 峰值另行報告。
+- 效能受主機其他租戶影響，實驗僅 CPU 執行。
+- Tiny 權重較 Flash 小，16 GiB 測試下 hot rate 已飽和；此工作集結果不代表不同 prompt/批次長度。
+- 請依 upstream model card 的 MIT 授權條款使用模型。