| --- |
| license: apache-2.0 |
| library_name: gguf |
| base_model: openbmb/MiniCPM-V-4.7-35B-A3B |
| pipeline_tag: text-generation |
| tags: |
| - minicpm |
| - qwen35moe |
| - gguf |
| - moe |
| - cpu |
| - low-memory |
| - expert-offloading |
| - no-swap |
| --- |
| |
| # EPM：MiniCPM-V-4.7-35B-A3B 的 8 GiB 專家分頁 CPU 推論 |
|
|
| 在 **8 GiB RAM、沒有 swap** 的條件下，用 CPU 跑 19.71 GiB 的 |
| `MiniCPM-V-4_7-35B-A3B-Q4_K_M.gguf`。 |
|
|
| 同一個模型、同樣的 8 GiB 上限之下，**未修改的 llama.cpp 連模型都載不進去** |
| （它要配置一個 14.4 GB 的 CPU_REPACK buffer，在載入階段就失敗）。EPM 把路由 |
| 專家權重留在儲存裝置，只把當前選中的專家分頁載入受限的 CPU arena： |
| **5.83 tok/s，峰值匿名 RSS 7799 MiB，VmSwap 全程 0 MiB。** |
| |
| 這個 repo 收錄實作（`cpp/` + `patches/`）、量測工具與全部證據。 |
| **不包含模型權重。** |
| |
| > **名稱說明**：EPM = Expert Paging for MiniCPM。本專案**不是**論文中的 SDQ |
| > （Sparse Decomposed Quantization）：沒有 2:4 結構化稀疏跳零計算，也不宣稱 |
| > GPU 稀疏加速。`sdq/` Python package、`sdq_*` C++ 檔案與 `SDQ_*` 環境變數是 |
| > 歷史 implementation identifier，保留以免破壞既有驗證工具；對外產品名稱與 |
| > 執行入口是 EPM / `epq-chat`。 |
|
|
| --- |
|
|
| ## 快速開始 |
|
|
| 需求：Linux x86-64、C++ 工具鏈、CMake、Git、Python 3、19.71 GB 磁碟空間。 |
| 已測 llama.cpp commit `9d7d5049804be03fce6575cc9f49c058b3c48788`。 |
|
|
| ```bash |
| python3 demo.py --once |
| ``` |
|
|
| 從頭開始時，腳本會取得本 repo 原始碼、從 `openbmb/MiniCPM-V-4.7-35B-A3B-gguf` |
| 下載 GGUF、套用 patch、編譯，然後跑一句示範。模型已下載的話： |
|
|
| ```bash |
| python3 demo.py --model-path /path/to/MiniCPM-V-4_7-35B-A3B-Q4_K_M.gguf \ |
| --once --ctx 4096 --threads 8 --n-predict 48 |
| ``` |
|
|
| 互動式聊天： |
|
|
| ```bash |
| python3 demo.py --model-path /path/to/MiniCPM-V-4_7-35B-A3B-Q4_K_M.gguf \ |
| --ctx 4096 --threads 8 |
| ``` |
|
|
| **記憶體預算與 reserve**：8 GiB 目標用 `--ram-budget-mb 8192` + |
| `SDQ_RESERVE_MB=512`（這個模型在 ctx=4096 / ubatch=128 下校正出來的值， |
| 見 `docs/DESIGN.md` §3）。換 RAM 預算要重新校正。 |
|
|
| 此 GGUF 不含 vision projector，本路徑只支援文字推論。已驗證的 context 是 4K； |
| 模型原生支援 262 K，但在這個 RAM 預算下沒有驗證過。 |
|
|
| --- |
|
|
| ## 在 8 GiB / no-swap 下量到的結果 |
|
|
| **每次執行都由 `tools/strict8g.py` 管治**：所有**匿名**記憶體映射被 `mlock()` |
| 鎖住（被鎖的頁永遠不會被寫到 swap，所以 no-swap 是核心保證的）， |
| 實體常駐量有硬上限，超標立刻 `SIGKILL`，另外 `RLIMIT_DATA` 當第二道閘門。 |
| **`strict_ok=False` 的樣本一律不採用。** |
| |
| ### 標配（N=9，配對交錯，提示詞中英交替） |
| |
| | 指標 | 值 | |
| | --- | ---: | |
| | **Decode tok/s（中位數）** | **5.83** | |
| | 單輪全距 | 5.19 – 6.63（抖動 25%） | |
| | Expert cache hit rate | 68.68% | |
| | SSD 讀取 / decode token | 214.1 MB | |
| | Arena | 6.35 GiB（3714 slots） | |
| | **峰值匿名 RSS** | **7799 MiB** / 8192 MiB 上限 | |
| | **峰值 VmSwap** | **0.000 MiB** | |
| | strict_ok | 9/9 | |
| |
| 條件：2× Intel Xeon Platinum 8559C（AVX-512 / AMX），`ctx=4096`、`ubatch=128`、 |
| 8 threads、greedy、48 requested tokens。 |
| |
| > 這是**共享主機**，同一組設定的單輪抖動可達 25%。數字足以支撐「能不能跑」 |
| > 與「大概多快」，不足以支撐 5% 等級的宣稱。 |
| |
| ### 同一個 8 GiB 上限下的傳統 llama.cpp |
| |
| | 路徑 | 結果 | |
| | --- | --- | |
| | 傳統 llama.cpp `llama-completion`（**未套 patch**） | **無法載入模型** | |
| | EPM `epq-chat` | **5.83 tok/s**，峰值匿名 RSS 7799 MiB，VmSwap 0 | |
|
|
| 失敗點： |
|
|
| ``` |
| ggml_aligned_malloc: insufficient memory (attempted to allocate 14400.00 MB) |
| 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 |
| ``` |
|
|
| 對照必須在**同一個上限**下建立。先量「兩邊都沒記憶體限制」再比較，是把 RAM |
| 這個變數漏掉了。 |
|
|
| ### Pager budget 曲線（實體上限固定 8 GiB，只有 arena 大小在變，N=5） |
|
|
| | Budget | Arena | 槽位 | 命中率 | SSD MB/token | Decode tok/s | 峰值匿名 RSS | VmSwap | |
| | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | |
| | 2 GiB | 0.57 GiB | 332 | 22.72% | 526.2 | 4.32 | 1842 MiB | 0 | |
| | 3 GiB | 1.53 GiB | 895 | 50.19% | 340.0 | 5.16 | 2828 MiB | 0 | |
| | 4 GiB | 2.50 GiB | 1459 | 59.81% | 275.8 | 5.48 | 3817 MiB | 0 | |
| | 5 GiB | 3.46 GiB | 2023 | 64.88% | 240.8 | 5.82 | 4805 MiB | 0 | |
| | 6 GiB | 4.43 GiB | 2587 | 67.52% | 222.2 | 5.38 | 5793 MiB | 0 | |
| | 7 GiB | 5.39 GiB | 3150 | 68.60% | 214.0 | 5.10 | 6779 MiB | 0 | |
| | **8 GiB** | **6.35 GiB** | **3714** | **70.74%** | **198.9** | **5.45** | **7766 MiB** | **0** | |
|
|
| 2 GiB 只有 332 個槽位。單一 token 的工作集是 320 個 layer-expert，但**槽位還分兩種 |
| 尺寸**：20 層用大槽位、20 層用小槽位，所以每個 token 需要的是 160 個大槽位加 |
| 160 個小槽位，而不是 320 個任一尺寸的槽位。2 GiB 之下 arena 只有 0.57 GiB， |
| 湊不出這個組合，命中率因此崩到 22.7%（8 GiB 之下 3714 個槽位裡約四成是大槽位， |
| 命中率回到 70.7%）。 |
|
|
| 命中率在 8 GiB 這個端點**仍然在爬升**（8 GiB 70.7% → 16 GiB 77.5%）→ |
| **瓶頸是記憶體上限，不是命中率飽和。** |
|
|
| > 這一欄與上面標配的命中率（68.68%）不同是正常的：這裡是 N=5、提示詞輪替不同， |
| > 標配是 N=9。兩者都受同一個 8 GiB 上限管治。 |
|
|
| ### RAM 擴張曲線：4 / 8 / 16 / 64 GiB |
|
|
| `--ram-budget-mb` 從 4 GiB 拉到 64 GiB。每次執行都由 `tools/strict8g.py` 管治， |
| 36/36 輪 `strict_ok=True`，`VmSwap` 全程 0。 |
|
|
| **兩點方法學說明，讀表前請先看：** |
|
|
| 1. **這條曲線不用 `mlock`。** `mlock()` 會強制整個映射常駐 —— 對一個 60 GiB 的 |
| arena，它會讓 RSS 直接變成 60 GiB，量到的就不是真實機器的行為。no-swap 的 |
| 核心保證保留給 8 GiB 這個**部署目標**（那一點另外有完整 mlock 證據，見 |
| [`docs/STRICT_8GIB.md`](docs/STRICT_8GIB.md)）。 |
| 2. **arena 不預先碰滿。** 全部路由專家權重只有 18.16 GiB，所以預先碰觸上限就是 |
| 18.17 GiB；超出來的部分等到真的用到才 fault in。這就是為什麼 64 GiB 預算的 |
| 「峰值 RSS」會停在約 24.0 GiB 而不是 62 GiB —— **那個數字才是真實的記憶體佔用。** |
|
|
| 結構指標（槽位、命中率、SSD 讀取量、峰值 RSS）都是設定的直接函數，不受執行抖動 |
| 影響，四個點都列。吞吐另外做 **N=9 配對交錯** 並用 Welch t 檢定。 |
|
|
| | Budget | Arena | 槽位 | 命中率 | SSD MB/token | 平均 tok/s | 單輪標準差 | 峰值 RSS | VmSwap | |
| | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | |
| | 4 GiB | 2.74 GiB | 1600 | 61.50% | 275.4 | 5.43 ± 0.37 | 0.37 | 3963 MiB | 0 | |
| | **8 GiB** | **6.36 GiB** | **3715** | **71.98%** | **199.1** | **6.33 ± 0.33** | 0.33 | **7669 MiB** | **0** | |
| | 16 GiB | 13.59 GiB | 7943 | 77.54% | 157.9 | 6.28 ± 0.41 | 0.41 | 15076 MiB | 0 | |
| | 64 GiB | 59.89 GiB | 35003 | 77.54% | 157.6 | 6.32 ± 0.51 | 0.51 | 23969 MiB | 0 | |
|
|
| | 比較 | 結果 | Welch t | p | 判定 | |
| | --- | ---: | ---: | ---: | --- | |
| | **4 GiB 比 8 GiB** | 5.43 → 6.33（**+16.6%**） | **−5.44** | **0.0001** | **統計顯著** | |
| | 8 GiB 比 16 GiB | 6.33 → 6.28（−0.8%） | −0.30 | 0.76 | 無法分辨 | |
| | 8 GiB 比 64 GiB | 6.33 → 6.32（−0.2%） | −0.05 | 0.96 | 無法分辨 | |
|
|
| #### 這條曲線的重點 |
|
|
| * **4 GiB → 8 GiB 是真實且顯著的提升：+16.6%**（t = −5.44，p = 0.0001）。4 GiB 時 |
| 命中率只有 61.5%、SSD/token 275.4 MB（8 GiB 的 1.4 倍），因為 arena 湊不出 |
| 「160 大 + 160 小」的工作集。 |
| * **8 GiB 以上再加記憶體完全沒有可量測的收益**：8 vs 16（t = −0.30, p = 0.76）與 |
| 8 vs 64（t = −0.05, p = 0.96）全部無法分辨，而記憶體用量是 2 倍到 8 倍。 |
| 結構指標也說明原因：命中率在 **16 GiB 就飽和在 77.54%**，SSD/token 飽和在她 |
| ~158 MB。 |
| * **真正的記憶體需求飽和在約 24.0 GiB 峰值**（18.16 GiB 全部專家權重 + 1.54 GiB |
| 非專家權重 + KV cache / compute buffer / runtime）。 |
| * **部署結論：8 GiB 就是對的容量。** 它拿到飽和命中率的 93%（72.0% 對 77.5%）， |
| 而且是整條曲線裡 throughput 顯著優於更低設定、又與所有更高設定打平的唯一一點。 |
|
|
| > 逐輪原始資料：`bench/results/ram_sweep_n9.json`（N=9）與 |
| > `bench/results/ram_sweep.json`（N=3，含 32 GiB 點）。 |
| |
| --- |
| |
| ## 記憶體怎麼配置的 |
| |
| 模型 metadata：每個 MoE 層 256 個路由專家，每個 token 選 8 個。 |
| GGUF 21,166,255,008 B，其中路由專家權重 **18.16 GiB**、非專家常駐權重 |
| **1.54 GiB**。 |
| |
| EPM 把未啟用的專家留在檔案裡，依需求把選中的專家載入記憶體 arena。關鍵實作： |
| |
| * **三段並行讀取**：一個 expert 的 gate/up/down 在檔案上互不相鄰，循序讀是 |
| 3 × 延遲的鏈；改成三段同時讀之後明顯變快。 |
| * **大小分級槽位**：**這個模型有兩種 expert 大小** —— 20 層的 `ffn_down_exps` |
| 是 Q6_K（2,039,808 B/expert），另外 20 層是 Q4_K（1,769,472 B/expert）。 |
| 依分佈分大小槽位，而不是全部按最大的配。 |
| * **需求觸發的 LRU 淘汰**，加上對「本 token 使用中」的 pin 保護。 |
| * **讀取與計算重疊**（mode C），每個 expert 算完立刻釋放槽位。 |
| * **跨層預取預設關閉**：它是負結果（見 `docs/NEGATIVE_RESULTS.md`）。 |
|
|
| ### Arena sizing |
|
|
| ``` |
| arena = RAM 預算 − 匿名 RSS − SDQ_RESERVE_MB |
| ``` |
|
|
| 1. **扣的是「匿名 RSS」，不是「總 RSS」。** `statm` 的 resident 把 mmap 進來的 |
| 模型權重頁也算成已用，但那些是乾淨的 file-backed 頁，核心會回收。 |
| 2. **`RLIMIT_DATA` 只當上界，不當預算來源。** 它算的是匿名**虛擬**記憶體， |
| 而 llama.cpp 會配置大量「映射了但永遠不會 touch」的 buffer。 |
| |
| `SDQ_RESERVE_MB` 是**逐模型、逐 ctx/ubatch 校正**的。本模型 ctx=4096 / |
| ubatch=128 下，512 MiB 留 446 MiB 餘量。峰值匿名 RSS 幾乎與 reserve 成 1:1 |
| 反比。**換 RAM 預算必須重新校正** —— 用固定的 512 MiB 跑 4 GiB 會超出上限。 |
| 完整校正表見 [`docs/DESIGN.md`](docs/DESIGN.md) §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 前向 vs NumPy 純重算（L0 E3 / L17 E200 / L33 E7 / **L39 E100**） | 全 PASS，max abs diff ≤ 3.7e-09 | |
| | 2 整層 | 真實路由輸入 vs NumPy，L0 / L39 | L0 PASS（1.1e-08）；L39 PASS（8.8e-05，落在單一 Q8_K LSB 翻轉上界 3.2e-02 之內） | |
| | 2b 預取壓力 | 預取開 + 極小 arena 強制回收，兩種槽位配置 | 4/4 PASS | |
| | 3 端到端 A/B | vs llama.cpp 原生 `mul_mat_id` | **在 8 GiB 上不可能執行** —— 需要整個 19.71 GiB 模型常駐 | |
| |
| 決定性：**5 次執行 × 48 token × 248,144 vocab 的 logits 全部逐位元組相同。** |
| |
| 過程中抓到並修正的問題包括一個 GGUF 標頭解析在 **BOOL 陣列**上錯位的 bug |
| （`qwen35moe.attention.recurrent_layers`，這個混合架構模型才有）。 |
| |
| L39 那一組 8.8e-05 的差異被完整追查到根因，並證明是 **Q8_K 量化邊界**造成、 |
| 不是 pager 的錯誤：把 C++ 端自己的 SiLU 中間值餵回 NumPy 參考，輸出立刻從 |
| 7.9e-04 掉到 **6.7e-08**。完整證據鏈見 [`docs/CORRECTNESS.md`](docs/CORRECTNESS.md) §4。 |
| |
| --- |
| |
| ## 這個模型特有的兩件事 |
| |
| 相對於同系列的 Qwen3.6-35B-A3B 實作，本模型有兩個結構差異， |
| **移植時必須重新推導、不能照抄**： |
| |
| 1. **兩種 expert 大小**（20 層 2,039,808 B / 20 層 1,769,472 B）。槽位尺寸必須 |
| 從 metadata 推導。參考實作是 37 層 + 3 層，比例完全不同。 |
| 2. **混合架構**：40 層裡只有 10 層是全注意力，30 層是 SSM 層。直接後果是 |
| **執行緒數的結論相反** —— 這裡 12 執行緒比 8 快約 6.5%，參考實作則是 |
| 8 之後開始變慢。SSM 層不受序列維度限制，能吃滿更多執行緒。 |
| |
| 另外模型 metadata 裡多了一個 BOOL 陣列（`recurrent_layers`）， |
| 參考實作的 GGUF 標頭解析器會在那裡錯位。 |
|
|
| --- |
|
|
| ## 其他結果 |
|
|
| ### 執行緒數 |
|
|
| | threads | 4 | 8 | 10 | 12 | 16 | |
| | --- | ---: | ---: | ---: | ---: | ---: | |
| | 平均 tok/s | 4.65 | 5.96 | 6.16 | **6.35** | 6.27 | |
|
|
| 4 → 8 是真實且顯著的提升（+28%）。8 之後的差異都在單輪抖動之內。 |
| 預設 8，**建議 12**（理由見上一節）。 |
|
|
| ### 預取（負結果） |
|
|
| 跨層預取 5.95 ± 0.37、僅 end_token 5.78 ± 0.33、關閉 6.03 ± 0.44 —— |
| **差異遠小於單輪抖動，統計上無法分辨**，而且多數輪次 SSD 讀取量上升。 |
| **預設關閉。** |
| |
| ### 儲存裝置會改變結論 |
| |
| 本機是本地 NVMe。慢速儲存上 I/O 排程是瓶頸，預取與並行讀取才有意義； |
| 快速 NVMe 上命中率（arena 大小）才是瓶頸。**本 repo 的 tok/s 不能直接套用到 |
| 慢速儲存的機器上。** 請先跑 `tools/io_probe.py` 再決定要最佳化哪一邊。 |
|
|
| --- |
|
|
| ## 這個量測**沒有**證明的事 |
|
|
| 1. **不是 cgroup 驗證。** 這個環境的 cgroup2 掛載唯讀、沒有 `CAP_SYS_ADMIN`。 |
| 目前的保證是「kernel `RLIMIT_DATA` + 取樣殺行程」與「mlock 匿名頁」兩條腿。 |
| 2. **主機 swap 是開啟的。** no-swap 由 `mlock` 讓它不可能發生，不是把主機的 |
| swap 關掉。 |
| 3. **`brk()` 主堆疊未被鎖**（glibc 內部直接下 syscall）。大型配置都走 `mmap`。 |
| 4. **共享主機**，單輪抖動可達 25%。 |
| 5. **只驗到 4K context**；模型原生支援 262 K。 |
| 6. **只做文字推論**，vision projector 是另一個檔案。 |
| 7. **儲存裝置比歷史量測的機器快一到兩個數量級。** |
|
|
| 完整方法與證據見 [`docs/STRICT_8GIB.md`](docs/STRICT_8GIB.md)。 |
|
|
| --- |
|
|
| ## Repository layout |
|
|
| | 路徑 | 內容 | |
| | --- | --- | |
| | `cpp/` | C++ expert pager（`sdq_pager.*`、`sdq_moe.cpp`、`sdq_buft.cpp`、`sdq_cli.cpp`、`sdq_mtp.cpp`） | |
| | `patches/` | 把 pager 接進 llama.cpp 的 patch（針對固定 commit `9d7d5049`） | |
| | `sdq/` | 設定、受管治的基準測量、實驗、驗證、HF sync | |
| | `tools/` | 8 GiB/no-swap 管治、GGUF 索引、決定性檢查、儲存 probe | |
| | `bench/` | 量測腳本與 `bench/results/` 原始輸出（JSON） | |
| | `docs/` | 見下 | |
|
|
| 文件： |
|
|
| | 文件 | 內容 | |
| | --- | --- | |
| | [`docs/STRICT_8GIB.md`](docs/STRICT_8GIB.md) | **8 GiB / no-swap 的方法、證據與限制**（先讀這份） | |
| | [`docs/DESIGN.md`](docs/DESIGN.md) | 記憶體帳目、SSD→RAM→CPU 設計、reserve 校正 | |
| | [`docs/CORRECTNESS.md`](docs/CORRECTNESS.md) | 三層驗證、決定性證據、Q8_K 量化邊界分析 | |
| | [`docs/NEGATIVE_RESULTS.md`](docs/NEGATIVE_RESULTS.md) | 試過但沒留下的最佳化 | |
| |
| --- |
| |
| ## 重現 |
| |
| ```bash |
| # 受管治的單次執行 |
| python3 tools/strict8g.py --limit-mb 8192 --record /tmp/one.json -- \ |
| epq-chat -m model.gguf -p "..." -n 48 -c 4096 -t 8 -b 128 \ |
| --temp 0 --no-chat --no-interactive --ram-budget-mb 8192 |
| |
| # 標配基準測量（9 輪，配對交錯） |
| python3 -m sdq.strict_bench --model model.gguf --bins base=./build/bin/epq-chat \ |
| --rounds 9 --strict-mb 8192 --label headline |
|
|
| # 正確性與決定性 |
| python3 -m sdq.verify --model model.gguf --bin ./build/bin/epq-chat --fast |
| python3 tools/determinism_check.py --model model.gguf --bin ./build/bin/epq-chat --runs 5 -n 48 |
| |
| # 曲線與負結果 |
| python3 bench/run_budget_curve.py --model model.gguf --bin ./build/bin/epq-chat --rounds 5 |
| python3 bench/run_ramsweep.py --model model.gguf --bin ./build/bin/epq-chat --rounds 3 |
| python3 bench/run_n9.py --model model.gguf --bin ./build/bin/epq-chat --rounds 9 |
| python3 bench/run_negative.py --which prefetch --model model.gguf --bin ./build/bin/epq-chat |
| python3 bench/run_negative.py --which threads --model model.gguf --bin ./build/bin/epq-chat |
| |
| # 儲存裝置特性、路由重疊、GGUF 結構 |
| python3 tools/io_probe.py --model model.gguf |
| python3 tools/route_overlap.py --model model.gguf |
| python3 tools/gguf_index.py model.gguf --json bench/expert_index.json |
| ``` |
| |
| --- |
| |
| ## License |
| |
| MiniCPM-V base model 由 upstream 發布；請以 upstream model card 的目前條款為準。 |
| 本 repository 包含推論軟體與量測結果，**不包含模型權重**。 |
| llama.cpp 與其相依套件保留各自授權條款。 |
