開源｜smolmaxxing：讓 1 GB 記憶體的電視盒和舊 iPad 跑 16B MoE 模型的 llama.cpp 修改

smolmaxxing 的 README 第一句寫出它的目標：用手邊最小的硬體，跑得動的最大語言模型（run the biggest language model you can on the smallest hardware you own）。README 說，電視盒、舊平板、單板電腦和路由器都有 CPU、一些記憶體和快閃記憶體（flash），一天裡大半時間閒著。目前測過兩台裝置，README 的對照表如下（tok/s 是每秒產生的 token 數）：

Ling-mini-2.0 是 inclusionAI 的專家混合（mixture of experts，MoE）模型，總共 163 億個參數，每個 token 實際用到約 14 億個。README 說，兩台裝置能在約 1 GB 的記憶體裡跑 8B 和 16B 的 MoE 模型。16B 是 Ling-mini-2.0，8B 是 Moon-Beam-8B-A1B：tablinum 以 Ling-3.0-tiny 微調的模型，總共 78.9 億個參數，每層 128 個專家，每個 token 用到約 9.4 億個參數，名稱裡的 A1B 指約 1B 的啟用參數。兩個模型都只有一部分放在記憶體，其餘的需要時才從 flash 讀進來。

smolmaxxing 沒有另寫推論引擎，README 說全部的修改都是 llama.cpp 的 patch。電視盒的 patch 套在 llama.cpp v0.8.0（commit 8642541）上，iPad 另有一份 patch，套在 commit 1945793e 上。專案放在 Hugging Face 的現成模型檔也必須搭配修改版的 llama.cpp，原版載入不了。

儲存庫在 GitHub 的 hyperionaidev 帳號下，授權是 MIT，LICENSE 的著作權人是 Mohamed Rashad。第一個 commit 在 2026 年 11 月 4 日；實驗紀錄 EXPERIMENT.md 從 11 月 3 日在電視盒上跑起一個 26 萬參數的故事模型開始，README 說整本紀錄有 160 個實驗，失敗的也寫進去了。README 也說，儲存庫裡每個數字都是在裝置上量的；不過下文有些品質和未命中率的數字是在 Mac 上模擬量到的，提到時會註明。

以下先說明專家分頁器怎麼把專家留在 flash、需要時才讀進記憶體，再看提高命中率的三個做法、其他修改與補救、Ling-mini-2.0 在電視盒上的設定，最後整理限制。除非另外註明，以下都指電視盒的版本，也就是 docs/how-it-works.md 描述的版本。內容根據 commit 79f860e 的 README、docs/、ipad-air/README.md、EXPERIMENT.md 與 patch 原始碼；本文沒有編譯或執行它。

專家分頁器怎麼運作？

MoE 模型的每一層有很多組前饋子網路，稱為專家（expert），由路由器（router）替每個 token 挑出少數幾個來算。how-it-works.md 的〈Expert pager〉說，因此在任何一刻，模型大部分的權重都閒著。分頁器（pager）在記憶體裡保留一池專家，其餘的等路由器要用時，才從 flash 讀進來。程式在 patch 新增的 ggml-cpu/moe-pager-tv.inc，檔頭註解寫了它的運作方式。

1. 載入模型時，每個專家張量（名稱是 *_exps 的張量）的整頁內部，都用空的匿名記憶體（anonymous memory）覆蓋：位址還在，內容是空的，還沒寫入的頁也不占實體記憶體。專家頭尾不滿一頁的部分另外處理，見下文。
2. 每一層路由完，分頁器讓被選中的專家常駐。記憶體裡沒有的專家，以多個執行緒用 O_DIRECT 讀取，直接讀進它原本的位址。O_DIRECT 是 Linux 上繞過頁快取（page cache）的讀檔方式。
3. 每一層有自己的 LRU（最近最少使用）池，大小由 GGML_MOE_POOL 設定。池滿了，就淘汰最久沒用到的專家，再用 madvise 的 MADV_DONTNEED 釋放它占的頁。

運算核心（kernel）看到的仍是一般的張量，不需要知道分頁器存在，也分辨不出哪一頁還沒載入：還沒載入的頁讀起來是零，不會報錯。檔頭註解因此記下正確性的設計。每一頁有三種狀態：empty、pending、filled，一個專家涵蓋的頁全部是 filled，這個專家才能用。專家的頭尾可能和相鄰的專家共用一頁，這些邊界頁改用經過頁快取的一般 pread 讀，整頁的內部才用 O_DIRECT；註解說，兩次 O_DIRECT 讀進同一頁，這一頁會損毀。一頁要等沒有任何已快取或讀取中的專家涵蓋它，才會釋放。任何程式都不能碰還沒常駐的專家；設定 GGML_MOE_VERIFY=1 時，每個專家第一次用到時都會和檔案逐位元組比對。

分頁器從 repack 快取讀專家。repack 快取（GGML_REPACK_CACHE）存放已重排成快速運算核心格式的權重，第一次載入時寫成檔案，之後直接映射，模型幾秒就能載入。how-it-works.md 說，repack 快取建好之後，GGUF 模型檔裡原本的專家位元組會被打洞（hole-punch）釋放，所以 flash 上只存一份權重。依 EXPERIMENT.md 的第 93 號實驗（以下記作 E93，其他實驗也照這個方式標示），Moon-Beam-8B-A1B 的 GGUF 因此從 2.76 GB 縮到 477 MB。

iPad 的分頁器做法不同。ipad-air/README.md 說，iOS 12 只讓一個行程映射約 1.7 GB 的位址空間，Moon-Beam-8B-A1B 的 2.6 GB 和 Ling-mini-2.0 的 5.5 GB 模型檔連開都開不了。所以模型檔改寫成專家放在最後，只映射前面的非專家部分；專家用不經快取的 pread 讀，每層的池子放 14 個專家，淘汰時看衰減後的使用頻率。E138 在 Mac 上比對過，用分頁器和直接讀整個檔案，量到的困惑度（perplexity）相同。困惑度衡量模型預測測試文本的能力，越低越好。

怎麼提高命中率？

專家不在記憶體裡，就得等 flash。docs/tv-box.md 說，電視盒的 flash 讀取最快 278 MB/s，單獨一次約 1 MB 的隨機讀取要花約 6 ms。每次池子未命中都要讀一次 flash，所以命中率決定速度（docs/lessons.md）。專案用三個做法提高命中率。

給已在記憶體的專家加分

第一個做法是快取感知路由（cache-aware routing）：路由時，凡是已經在記憶體裡的專家，路由分數都加上一個固定值 d（GGML_MOE_BIAS=d），路由器因此偏向選它們。how-it-works.md 說，這讓未命中從 13% 降到約 2%，品質有量得到的代價；這個想法來自 Skliar 等人的〈Mixture of Cache-Conditional Experts for Efficient Mobile Device Inference〉（arXiv 2412.00099），該文在其他模型上提出這個做法。

13% 和 2% 這兩個數字出自 E93：在 Mac 上模擬 Moon-Beam-8B-A1B，專家量化成 Q2_K，每層的池子放 43 個。Q2_K、Q3_K、Q4_K 是 llama.cpp 的量化格式，數字大致是每個權重用幾個位元。加分為 0 時，未命中 13.0%，困惑度 11.20；加分 0.2 時，未命中 2.22%，困惑度 11.62，高了約 3.8%。E90 用 Q3_K 專家、池子 30 個掃過整條曲線：加分 0 時困惑度 10.50，加到 0.2 是 11.06，加到 0.4 跳到 13.90。

加分之後仍未命中的專家，分頁器一律等它讀完。E95 模擬過不等、直接跳過這些專家：只跳過 2.4% 的專家，困惑度就高了 27%。EXPERIMENT.md 的解釋是，加了分還沒命中的，正是分數勝過所有已快取專家加上加分的那些，也就是路由器最想要的專家。

預先閘控的預取

第二個做法是預先閘控的預取（pre-gated prefetch）。第 L 層路由時，分頁器把第 L+a 層的路由器套在第 L 層的輸入上，預測第 L+a 層會選哪些專家，在背景先讀進不在記憶體的那幾個；a 由 GGML_MOE_PREFETCH_AHEAD 設定，預設是 2。how-it-works.md 說，這樣約 60% 的未命中在需要之前就已載入。E103 的紀錄是 1,460 次未命中裡，有 932 次預取，Moon-Beam 實際聊天的速度從 6.93 提高到 7.20 tok/s。

預測要照路由器真正的選法算：路由器先把每個專家的分數換算成 0 到 1 之間的值（sigmoid），再加上模型替每個專家內建的偏移值（selection bias），快取加分也要算進去。檔頭註解說，單純讀分數前 k 名的專家，讀的量約是未命中的 4 倍，占滿了 flash 的讀取頻寬。

預取還得和暖啟動（warm start，GGML_MOE_WARM）配合。暖啟動讓每層的池子一開始就裝滿該層最常用的專家，名單事先從校準文本統計。最早的版本讓預取和暖啟動的背景讀取堆到超出池子，被專案自己的記憶體守門程式停掉。這支程式（tools/tv-watch.c）包住電視盒上每次較重的執行，可用記憶體過低時就終止執行。現在的程式規定，預取只能占用當下可以淘汰的位置，排隊中的背景讀取有上限，暖啟動也改成同步讀完。

每個 token 少用幾個專家

第三個做法是 LLAMA_MOE_USED，讓每個 token 用比模型原設定少的專家，權重重新正規化。how-it-works.md 把它和快取加分並列為另一個可調的參數。代價隨模型不同：Moon-Beam 在 E91 從 8 個減到 4 個時，困惑度從 10.59 跳到 14.40；Ling-mini-2.0 每 token 用 6 個專家時，電視盒上只快約 4%，文字品質卻差很多，所以預設維持 8 個（E106）。

其他修改與補救

密集模型的權重串流

密集模型沒有專家，每個 token 都要用到全部權重。放不進記憶體的密集模型，由 ggml-cpu/stream-tv.inc 串流。檔頭註解說，交給作業系統的 mmap，每個 token 循環掃一遍比頁快取還大的權重，正是 LRU 最糟的情況：它淘汰的剛好是下一步要用的頁。電視盒的 eMMC 這樣只讀得到約 150 MB/s，平行的 8 MB O_DIRECT 讀取則有 278 MB/s。

串流引擎把一部分權重留在記憶體，其餘放在「串流區」（stream zone）。第一次跑時，每個矩陣乘法的掛鉤記錄權重的使用順序；之後讀取執行緒照這個順序，以 8 MB 的 O_DIRECT 讀取，把權重提前讀進它原本的位址。每個運算執行緒都等自己的權重完全載入才開始算，所以預測錯只會慢，不會算錯。權重用完立刻釋放（drop-behind），記憶體用量大致維持在讀取視窗的大小。GGML_STREAM_VERIFY=1 會把每個串流進來的張量和檔案比對，how-it-works.md 說它抓到兩個不會報錯的資料損毀錯誤，都已修正。

推測解碼（speculative decoding）在這裡也有用。平常每產生一個 token 就要掃一遍權重；推測解碼先猜下一個 token，再一次驗證。Qwen3.5-9B 用模型自帶的預測頭（head）猜下一個 token，速度從 0.16 提高到 0.27 tok/s（+69%）。how-it-works.md 的解釋是，速度受 flash 限制時，驗證 2 個 token 大約只需要掃一次權重；放得進記憶體的 2B 模型用同樣的方法反而變慢（E31）。

裁剪輸出層

小模型的權重有很大一部分在詞彙上。lessons.md 說，Qwen3.5-0.8B 有 248K 列的輸出層，占全部權重的三分之一。專案只保留約 49K 到 66K 個最常用的詞彙列，依 token 在英文、程式碼和另外 7 種語言裡出現的頻率挑選，其他詞彙的 logit 設成負無限大。how-it-works.md 說，這樣每個模型省下 0.2 到 0.5 GB，代價是約 1% 的英文 token 產生不出來。

tools/gguf_prune_head.py 的說明寫了做法：在 GGUF 裡加上 output.weight（保留的詞彙列）和 output_ids.weight（每列對應的詞彙 ID）兩個張量。token_embd 維持完整，任何 token 都還能當輸入讀，縮小的只有輸出的矩陣乘法。原版 llama.cpp 不接受這個形狀，需要搭配 patch。

給 Cortex-A55 寫的運算核心

how-it-works.md 列出替 Cortex-A55（ARMv8.2，有 dotprod 指令、沒有 i8mm）寫的運算核心，每個都有對照純量參考實作的正確性測試。Q2_K 重排成 8 列 × 4 位元組一組，配合 vdotq_laneq 指令（上游的 llama.cpp 只在 x86 和 RISC-V 上重排 Q2_K），速度從每秒 7.8 G 個權重提高到 13.9 G，生成快 41%，讀提示快 2.4 倍。三元格式（每個權重只取 −1、0、+1）的 TQ1_0 和 TQ2_0 重排後，分別從 9.5 提高到 14.4、從 11.9 提高到 19.1 G 個權重。1 位元的查表核心連同其他兩項修改（E82、E88），讓 Bonsai-8B 從 3.77 提高到 5.1–5.4 tok/s。

2 位元專家的長回答

how-it-works.md 說，Moon-Beam 的 2 位元專家在長回答寫到約 250 到 300 個英文詞後就失去連貫，快取加分讓情況更糟。DRY 取樣只能掩蓋問題，模型會改用換句話說的方式繞圈。改用 1.15 的重複懲罰（repeat penalty），回看最近 256 個 token，電視盒上 13 次長回答裡退化的從 12 次降到 1 次（E99、E100）。Ling-mini-2.0 在同樣開著重複懲罰的設定下，6 次約 600 個英文詞的長回答都沒有繞圈；EXPERIMENT.md 說，它的 Q2_K 專家能維持長文的連貫（E107）。

Ling-mini-2.0 在電視盒上怎麼設定？

tv-box.md 和 EXPERIMENT.md §20 記錄了電視盒上的設定。Ling-mini-2.0 有 19 個 MoE 層，每層 256 個專家，每個專家量化成 Q2_K 後約 1 MB，每個 token 用 8 個，另加一個共享專家。池子和 Moon-Beam 一樣是每層 43 個；how-it-works.md 寫的「43 of 128 experts」和 moe-pager-tv.inc 檔頭的 128，指的都是 Moon-Beam。專家用 Q2_K，非專家部分用 Q4_K，輸出層裁成 60K 列。模型從 bartowski 的 Q4_K_M 檔在 Mac 上重新量化而來。

1.13 GB 超過一般模式下單一行程能用的約 0.96 GB，所以 Ling-mini-2.0 要在無頭模式下跑；tv-box.md 說，無頭模式下單一行程可以用到約 1.15 GB（無頭模式的細節見〈限制〉）。E106 記錄，一個 token 約 190 ms，其中約 85 ms 在等 flash。

品質的單位是每位元組位元數（bits per byte）。專案用一段 22,031 位元組的英文維基百科摘錄（data/eval/eval-en.txt）量困惑度，再換算成每位元組要多少位元（log2 困惑度 × token 數 ÷ 位元組數），數字越低越好。不同模型的分詞器不同，困惑度不能直接比，換算成每位元組位元數之後才能比。Ling-mini-2.0 的 1.054 是 E105 在 Mac 上量的，條件是模擬每層 43 個專家的池子、加分 0.3，紀錄裡寫作 1.0537；不模擬池子、也不加分時是 1.0346。tv-box.md 的表上，Moon-Beam-8B-A1B 是 0.996、7.2 tok/s，Bonsai-8B 是 0.974、5.2 tok/s，Qwen3.5-2B 是 0.909。tv-box.md 的結論是，Ling-mini-2.0 比 Moon-Beam 大一倍，每位元組的品質卻比較差，速度也比較慢。

iPad 上的 Ling-mini-2.0 用同一套分頁器的 iPad 版本，每層池子 14 個，常駐記憶體 556 到 576 MB。不加分時 2.56 tok/s，加分 0.3 時 4.43 到 4.56 tok/s，README 表上的 2.6–4.5 就是這兩端。加分 0.3 的困惑度高了 8.5%，但這次只量了 506 個 token，EXPERIMENT.md 說差距在 10% 以內都可能是雜訊（E159、E160）。

用之前要知道哪些限制？

速度是在兩台裝置上量的，部分品質和未命中率的數字是在 Mac 上模擬的，儲存庫裡沒有其他人的重現。tv-box.md 也提醒，電視盒的速度一天內會漂移約 10%，所以每項修改都和前一版接連量測比較。

速度的上限在 flash。tv-box.md 說，每個 token 要串流 X MB 的模型，速度不可能超過每秒 278 ÷ X 個 token，比 2B 大的模型都受這個限制，瓶頸不在 CPU。MoE 模型每個 token 只讀一小部分權重，讀得少，上限就高。

幾個省記憶體與加速的做法都有品質代價。快取加分越大越快，困惑度也越高。2 位元專家在 Moon-Beam 上讓長回答失去連貫，要靠重複懲罰補救。裁剪輸出層會讓一部分 token 產生不出來：Qwen3.5 的 65K 列輸出層在英文測試文本上漏掉 1.31% 的 token，在多語測試文本上漏掉 12.58%（E29）；Ling-mini-2.0 的 60K 列輸出層，本文在儲存庫裡只找到英文的數字（iPad 上 506 個 token 中 0.78%），沒有找到多語的。

兩台裝置都有特殊的使用條件。iPad 必須越獄，越獄重開機就失效；ipad-air/README.md 說，池子設到 16 個或把權重鎖在記憶體，都觸發核心恐慌（kernel panic），讓 iPad 重開機，8B 和 16B 的模型也只適合開著聊天時用，常駐的伺服器會被 iOS 的記憶體監控重設。電視盒不需要 root，但 Ling-mini-2.0 這類大模型要開無頭模式（headless mode，tools/tv-llm-mode.sh on）：執行期間強制停止桌面啟動器、Google 服務和其他耗記憶體的 app，可用記憶體從約 1,000 MB 增加到約 1,300 MB。how-it-works.md 說，這些改動都不會留下來，唯一的例外是保持喚醒（svc power stayon），用來避開會占掉 17% 單核的動畫螢幕保護程式，執行 tv-llm-mode.sh off 就改回來。伺服器停掉後無頭模式仍開著，要回到桌面得自己執行 off。

patch 綁在特定版本的 llama.cpp 上，電視盒的 patch 有 4,977 行、改動 33 個檔案。模型檔需要修改版的 llama.cpp 才能載入，儲存庫沒有提到是否打算把這些修改送回上游。

參考資料

• hyperionaidev/smolmaxxing，commit 79f860e（2026-11-13）：README.md、docs/how-it-works.md、docs/tv-box.md、docs/tv-box-setup.md、docs/lessons.md、ipad-air/README.md、EXPERIMENT.md（§19–21）、tools/gguf_prune_head.py、data/README.md、patches/llama.cpp-v0.8.0-tvbox.patch（ggml-cpu/moe-pager-tv.inc 與 ggml-cpu/stream-tv.inc 的檔頭註解）、LICENSE
• Andrii Skliar, Ties van Rozendaal, Romain Lepert, Todor Boinovski, Mart van Baalen, Markus Nagel, Paul Whatmough, Babak Ehteshami Bejnordi, Mixture of Cache-Conditional Experts for Efficient Mobile Device Inference（arXiv 2412.00099，Transactions on Machine Learning Research，2025）
• 本站〈Strata 拆解：一張 12 GB 顯示卡怎麼跑 1250 億參數的模型〉：同樣利用 MoE 每個 token 只用少數專家，Strata 把全部專家放在主記憶體、常用的快取在顯示卡記憶體，未命中的專家一部分搬上顯示卡，其餘由 CPU 直接計算；smolmaxxing 則把專家放在 flash，主記憶體當快取，未命中時等 flash 讀完。