---
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 上限實測：基準 prompt 與實際工具使用

兩組數據都使用 `prlimit --data=<bytes>` 設定 RLIMIT_DATA 硬上限，並量測匿名峰值、RSS、decode 速度、SSD paging 量與 hot rate。基準 prompt 每級跑兩輪：ctx=256、ubatch=32、threads=4、temperature=0、生成 32 tokens。工具使用 workload 每級跑 10 輪；每輪模型先呼叫 `get_weather(city=Tokyo)` 並查詢 Open-Meteo，再呼叫 `compile_project(project=tiny_fixture)`，清除 build directory 後重新執行 CMake build；兩項工具結果都交回模型摘要。工具測試每輪有四個獨立 model calls，摘要統計先取單輪四個 calls 的平均，再跨十輪取平均 ± 樣本標準差。

主機為 Intel Xeon Platinum 8559C（CPU-only、192 threads），上層 cgroup `memory.max=104000000000`、`memory.swap.max=2936848384`。兩組都使用關閉 `GGML_CPU_REPACK` 與 AMX 的 build，每次模型啟動前以 `posix_fadvise(DONTNEED)` 驅逐模型檔 page cache。anon 峰值是 RLIMIT_DATA 的判定依據；RSS 包含不受 RLIMIT_DATA 限制的 file-backed pages。

| RAM 上限 | 基準結果 | 基準 arena / slots | 基準 anon / RSS 峰值 MB | 基準 decode tok/s | 基準 SSD MiB/token | 基準 hot / swap | 工具成功輪次 | 工具 anon / RSS 峰值 MB | 工具 decode tok/s 平均 ± SD | 工具 SSD MiB/token 平均 ± SD | 工具 hot rate % 平均 ± SD | 工具每輪耗時秒平均 |
|---:|:---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|
| 1 GiB | PASS | 0.30 GiB / 225 | 421 / 905 | 8.25 | 199.8 | 16.7% / 0 MB | 10/10 | 432 / 916 | 7.71 ± 0.12 | 205.4 ± 0.1 | 9.6 ± 0.0 | 34.7 |
| 2 GiB | PASS | 1.30 GiB / 979 | 1,412 / 1,895 | 11.88 | 73.8 | 49.5% / 0 MB | 10/10 | 1,423 / 1,906 | 11.09 ± 0.36 | 71.3 ± 0.1 | 43.7 ± 0.0 | 33.0 |
| 4 GiB | PASS | 3.30 GiB / 2,486 | 3,404 / 3,888 | 16.38 | 24.8 | 66.7% / 0 MB | 10/10 | 3,404 / 3,888 | 15.19 ± 0.81 | 22.1 ± 0.0 | 58.0 ± 0.1 | 39.8 |
| 8 GiB | PASS | 7.01 GiB / 5,279 | 7,064 / 7,548 | 18.65 | 7.1 | 76.3% / 0 MB | 10/10 | 7,076 / 7,560 | 16.81 ± 0.64 | 7.1 ± 0.0 | 74.8 ± 0.0 | 49.8 |
| 16 GiB | PASS | 14.62 GiB / 11,012 | 14,600 / 15,084 | 19.24 | 7.1 | 76.3% / 0 MB | 10/10 | 14,612 / 15,096 | 17.60 ± 0.45 | 6.5 ± 0.0 | 75.5 ± 0.0 | 78.2 |

表中基準 prompt tok/s 是兩輪平均；工具 workload 的速度與 paging 指標是每輪四個模型階段的平均，再列 10 輪平均 ± 樣本標準差。兩種 workload 的 token 內容與長度不同，速度和 I/O 數字應在各自 workload 內比較。兩組 swap 均為 0。工具測試每輪的即時天氣、build 結果及 raw metrics 收錄於 [`results/tool_use_levels.json`](results/tool_use_levels.json)；工具報告見 [`results/tool_use_levels.md`](results/tool_use_levels.md)，可重跑腳本為 [`sdq-ling/tool_use_bench.py`](sdq-ling/tool_use_bench.py)。基準逐輪數據見 [`results/strict_memory_levels.json`](results/strict_memory_levels.json)。

在基準 prompt 下，8 GiB 到 16 GiB 的 hot rate 與 SSD MiB/token 已接近；工具 workload 也呈現相近趨勢。decode 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`：先前固定 benchmark prompt 的兩輪原始結果。
- `results/tool_use_levels.md`、`results/tool_use_levels.json`：weather/CMake 真實工具使用的 10 輪結果。
- `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`：固定 prompt 限制矩陣 benchmark。
- `sdq-ling/tool_use_bench.py`：weather/CMake 工具呼叫限制矩陣 benchmark。
- `tools/tiny_fixture/`：CMake build 工具測試專案。
- `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 授權條款使用模型。