colibri/README.zh-TW.md

English · 繁體中文

**小巧引擎，龐大模型。**只要約 25 GB 記憶體，就能在消費級電腦上執行 GLM-5.2（744B 參數的 MoE）——以零相依套件的純 C 實作，從硬碟串流載入專家。

Colibrì 是一套輕量、維持品質的 MoE 執行環境，將 VRAM、RAM 與儲存裝置視為統一管理的記憶體階層。高速記憶體不足可能降低速度， 但預設策略絕不會在未告知的情況下改變模型精度或路由語意。

$ ./coli chat
  🐦 colibrì v1.0 — GLM-5.2 · 744B MoE · int4 · streaming CPU
  ✓ ready in 32s · resident 9.9 GB
  › ciao!
  ◆ Ciao! 😊 Come posso aiutarti oggi?

實際運行畫面

網頁儀表板（./coli web）：744B 模型達到 4 tok/s、TTFT 1.6 秒、硬碟讀取 0—— 在 6× RTX 5090 上讓所有專家常駐，並即時顯示 token 指標、每輪耗時明細、 VRAM／RAM／硬碟層級長條，以及角落的即時迷你大腦。

大腦（Brain）頁面：將全部 19,456 個專家呈現為活的皮質——顏色代表儲存層級， 亮度代表路由熱度，每輪被路由到的專家都會閃白。將游標停在專家上，即可查看其 實測主題親和度。

圖譜（Atlas）頁面：將實測專家圖譜 呈現為 3D 星系——共 13,260 個已分析專家，其中 1,041 個可重現的專門專家會按主題聚集 （詩歌、法律、中文、SQL……）。位置取自實測路由親和度，而非學習出的嵌入向量。拖曳即可旋轉。

核心概念

744B 的專家混合（Mixture-of-Experts）模型，每個 token 只會啟用約 40B 參數—— 其中每個 token 之間會變動的只有約 11 GB（被路由到的專家）：

所以模型不必完整放進高速記憶體，而是需要正確配置位置：

• 稠密部分（注意力、共享專家、嵌入——約 17B 參數）以 int4 常駐 RAM（約 9.9 GB）；
• 19,456 個路由專家（75 個 MoE 層 × 256，加上 MTP head；每個在 int4 下約 19 MB） 存放在硬碟（約 370 GB），並隨需串流載入，搭配逐層 LRU 快取、 會學習的熱門專家固定儲存區，以及選用的 VRAM 層級。

引擎由單一 C 檔（c/glm.c）與少量標頭檔組成。不需要 BLAS， 執行階段不需要 Python，也不需要 GPU。

運作方式

每個 token 的處理路徑

每個 token 的每一層都會走過相同的五個步驟。設計目標是讓 配置只決定速度——無論專家是從 VRAM 或硬碟回應，路由器的決策與權重精度都完全相同。

統一記憶體階層，取代單一記憶體門檻

同一套引擎涵蓋完整硬體範圍：在 25 GB 筆電上，一切都從硬碟串流載入 （慢，但結果正確）；在大型主機上，則可讓整組專家常駐 （CUDA_EXPERT_GB=auto PIN_GB=all），讓硬碟完全退出解碼路徑。 兩端之間有一層學習型快取：引擎會記錄你的工作負載路由到哪些專家 （.coli_usage，每輪更新），並自動固定最熱門的專家——colibrì 確實會越用越快。 在多插槽主機上，COLI_NUMA=1 會將常駐權重交錯分配到各記憶體控制器 （#82）。

絕不為同一次硬碟讀取等待兩遍

快取未命中的成本很高，因此引擎大部分的巧思都用來避免或重疊處理這些讀取： 每個專家的三個矩陣相鄰儲存，並以一次 pread 讀取；有界非同步 I/O pool （PIPE=1，預設啟用）會在常駐專家運算時載入缺少的專家；批次位置只讀取每個 不重複專家一次（批次聯集）；路由前瞻執行緒（PILOT=1）則預先載入下一層專家—— 實測顯示，路由結果提前一層時有 71.6% 的可預測性。 在 GPU 上，常駐管線（COLI_CUDA_PIPE=2）讓殘差流跨層保留在裝置端， 使 CPU 專家迴圈不中斷；在 Apple Silicon 上，實驗性的 Metal 後端會用統一記憶體 GPU 執行批次專家運算。

忠實模型，壓縮狀態

前向傳遞已透過 transformers oracle 驗證為逐 token 完全一致 （teacher-forcing 32/32）。MLA 注意力儲存壓縮後的 KV 狀態——每個 token 為 576 個 浮點數，而非 32,768 個（縮小 57×）——並跨重新啟動持久保存 （.coli_kv）：對話可暖啟恢復，不需重新 prefill，結果與不中斷的工作階段 逐位元組相同。DSA 稀疏注意力（GLM-5.2 的 lightning indexer）已忠實實作， 並透過強制選取所有 key，驗證可精確重現稠密注意力。

如實呈現推測式解碼

GLM-5.2 原生 MTP head 會起草 token，再由主模型以一次批次前向傳遞驗證—— 條件合適時每次 forward 可產生 2.2–2.8 個 token。兩條得來不易的規則已成為預設值： MTP head 必須是 int8（int4 head 的接受率會崩落到 0–4%，見 #8），且草稿與驗證必須計算 相同函數——SPEC_PIN=1 會把兩者固定在同一 kernel family （完整鑑識過程見 #163）。 文法強制草稿（GRAMMAR=file.gbnf）可在受限 JSON 輸出中， 以近乎免費的成本提高接受率。推測式解碼是否帶來淨收益取決於快取熱度——請實測， 若不划算就使用 DRAFT=0。

實際成果

同一套引擎、同一個 int4 容器——硬體只會改變專家的存放位置。 完整 benchmark 表格中的重點如下：

• **6× RTX 5090，全部常駐：**解碼 5.8–6.8 tok/s，TTFT 約 13 秒 （實驗紀錄）；
• **128 GB、僅使用 CPU 的桌上型電腦：**暖機後約 1.8 tok/s （#200）；
• **單張 RTX 5070 Ti 的筆電級電腦：**透過 GPU 常駐管線達到 1.07 tok/s （#273）；
• **25 GB 開發機：**冷啟動 0.05–0.1 tok/s——這是專案起步時已證實的下限， 也仍是如實呈現的基準。

品質來自測量，而非假設：int4 容器的量化成本，以及 scale granularity／rotation 消融實驗，收錄於 docs/benchmarks.md、 #108 與 #81。

開始使用

1. 取得模型

Hugging Face 上已有預先轉換的 GLM-5.2 int4 容器——請務必使用 含 int8 MTP head 的版本：

https://huggingface.co/mateogrgic/GLM-5.2-colibri-int4-with-int8-mtp

⚠️ 原始鏡像使用 int4 MTP head → 草稿接受率為 0% （#8）。請檢查你的版本： ls -l <model>/out-mtp-*——正確的 int8 大小為 3527131672 / 5366238584 / 1065950496。

你也可以自行從 FP8 來源轉換——只需一條可續傳的指令，且任何時候都不需要 在硬碟上同時存放完整的 756 GB：

cd c && ./setup.sh                        # 檢查 gcc/OpenMP、建置並執行自我測試
./coli convert --model /nvme/glm52_i4     # 逐 shard 下載並轉換（僅此一次需要 python）

2. 執行

COLI_MODEL=/nvme/glm52_i4 ./coli chat     # 自動偵測 RAM 預算、快取與 MTP
COLI_MODEL=/nvme/glm52_i4 ./coli plan     # 檢視規劃的 VRAM／RAM／硬碟配置
COLI_MODEL=/nvme/glm52_i4 ./coli doctor   # 唯讀就緒檢查
./coli web  --model /nvme/glm52_i4        # 在同一個連接埠提供 API 與網頁儀表板
./coli serve --model /nvme/glm52_i4       # 僅提供 OpenAI 相容 API

引擎執行階段是純 C——python 只供單次轉換工具與選用的 API gateway 使用。

3. 深入了解

主題	文件
Benchmark、社群實測數據、品質測量	docs/benchmarks.md
調校選項、策略、學習型快取、預先載入	docs/tuning.md
Windows 11 原生建置（含 CUDA DLL）	docs/windows.md
CUDA 後端、VRAM 專家層級、全部常駐	docs/cuda.md
Apple Silicon Metal 後端	docs/metal.md
OpenAI 相容 API、KV slots、網頁儀表板	docs/api.md
文法強制草稿（結構化輸出）	docs/grammar-draft.md
環境變數完整清單	docs/ENVIRONMENT.md

支持專案

colibrì 最初是由一人使用 12 核心、25 GB RAM 的筆電開發； 如今它的數據來自社群中的各種真實機器。如果這個專案對你有用：

• ⭐ 為儲存庫加星並分享；
• 🐛 以 issue 提交你的硬體 benchmark 數據——實測資料比任何其他事都更能推動專案；
• 💬 若想贊助開發或捐贈硬體，請透過 GitHub issues 聯絡。

儲存庫結構

Makefile                  根目錄建置／檢查入口
c/
├── glm.c                 單檔 GLM 引擎
├── st.h, tok.h, json.h   執行階段標頭檔
├── backend_cuda.*        選用的 CUDA 層級
├── Makefile              建置與本機檢查
├── coli                  使用者介面 CLI
├── openai_server.py      OpenAI 相容 HTTP gateway
├── setup.sh              單一指令完成本機設定
├── tools/                離線轉換、fixtures 與 benchmarks
├── scripts/              長時間轉換輔助工具
└── tests/                零相依套件的 C 與 Python 測試
web/                      瀏覽器 UI（純 OpenAI API client）
desktop/                  包裝網頁 UI 的 Tauri v2 桌面 shell
docs/                     參考文件、實驗與媒體檔

執行階段路徑刻意維持扁平、易讀：glm.c 加上少量標頭檔。 在儲存庫根目錄執行 make、make check 與 make clean， 都會轉交給引擎的 Makefile。

為什麼叫做「colibrì」

蜂鳥只有幾公克重，能在原地懸停，並在一天內造訪上千朵花。 這套引擎只用蜂鳥般的配給，就能讓 744B 參數的巨人運轉： 25 GB RAM、十二個 CPU 核心，以及對硬碟的大量耐心。

授權條款

Apache 2.0。GLM-5.2 權重由 Z.ai 以 MIT 授權發布。