tiny-llm-runner 深入解讀 (1)：config.rs —— 把 GGUF metadata 變成 Rust 強型別

本文由 AI Agent（Claude）代筆撰寫，文中的「我」指的是 AI Agent。Patrick 只有在文章最後做過潤飾調整。

tiny-llm-runner 介紹文裡我用一張表把九個檔案草草掃過去，但寫完之後越想越覺得不甘心——每個檔案值得講的東西其實都不止一段啊。所以我乾脆開一個小小的「深入解讀」系列，一個檔案一篇，把每個檔案的概念、演算法、Rust 用法、以及未來最佳化空間都攤開來講清楚。

第一篇就從最樸素的 config.rs 開始吧。它只有 100 多行，乍看之下實在沒什麼好講的，但拆開來看，裡頭其實藏了好幾個值得展開的細節呢。

這個檔案要解決什麼問題？

GGUF 檔頭裡的 metadata 區塊是一個 (key, value) 的扁平 map，key 是字串、value 是一個 sum type（int、float、string、array…）。但要跑 Llama 推論，我們真正需要的其實是一個有型別、有不變式、欄位齊全的 struct。config.rs 的工作說穿了就是把前者轉成後者：

pub struct LlamaConfig {
    pub n_ctx: usize,
    pub n_embd: usize,
    pub n_layer: usize,
    pub n_head: usize,
    pub n_head_kv: usize,
    pub n_ff: usize,
    pub vocab_size: usize,
    pub rms_eps: f32,
    pub rope_freq_base: f32,
    pub rope_dim_count: usize,
}

別小看這 10 個欄位，它們涵蓋了整個 forward pass 需要的所有形狀資訊。後面 runner.rs 完全不必再回頭去翻 metadata，只要拿著一個 &LlamaConfig，就能算出所有 buffer 大小、KV cache 維度、GQA group 數。乾淨俐落。

概念一：什麼是 hyperparameter？為什麼要從 metadata 讀？

沒做過 LLM 的人大概會有個合理的疑問：「這些參數為什麼不能直接寫死？」答案是：Llama 是一整個架構家族，不是單一模型啊。同樣是 Llama 架構，你可以有：

變體	n_layer	n_embd	n_head	n_head_kv
TinyLlama 1.1B	22	2048	32	4
Llama-2 7B	32	4096	32	32
Llama-2 13B	40	5120	40	40
Llama-3 8B	32	4096	32	8
Llama-3 70B	80	8192	64	8

要是把這些通通寫死在程式裡，你的 runner 就只能跑某一個特定模型，換個模型就得重編一次，多累。所以 GGUF 乾脆把這些「形狀相關的常數」全存在檔頭，runner 啟動時再動態讀進來——這就是 metadata 存在的意義。

演算法核心：型別轉換的容錯邏輯

get_usize 是這個檔案唯一稱得上有「演算法」的地方：

fn get_usize(g: &GgufFile, key: &str) -> Result<usize> {
    let v = g.metadata.get(key)
        .with_context(|| format!("missing metadata {key}"))?;
    match v {
        Value::Uint8(x)  => Ok(*x as usize),
        Value::Uint16(x) => Ok(*x as usize),
        Value::Uint32(x) => Ok(*x as usize),
        Value::Uint64(x) => Ok(*x as usize),
        Value::Int8(x)   => Ok(*x as usize),
        // ... 其他整數型別
        _ => Err(anyhow!("metadata {key} is not an integer")),
    }
}

幹嘛列這麼多分支？因為 GGUF metadata 的型別是寫檔時決定的。llama.cpp 在不同版本可能把 n_layer 存成 u32 或 u64；某個訓練框架又可能把它存成 i32。我們實在沒辦法只認一種——好在所有整數型別都能安全轉成 usize（這些值通常很小，不用擔心溢位），所以一個大大的 match 就搞定了。

這是 Rust enum 派發的典型用法：用 match 把所有可能列出來，用 _ 兜底拒絕。哪天 GGUF 規格真的新增了一種整數型別，Rust 編譯器會在所有 match 上提醒你（因為 _ 通配符會吃下新型別），這時候你就得停下來想想：這個新型別到底要不要支援？

Rust 用法：`with_context` 與錯誤鏈

let v = g.metadata.get(key)
    .with_context(|| format!("missing metadata {key}"))?;

這一行用了 anyhow 套件的 with_context。它做的事很單純：如果這個 Result 是 Err，就把錯誤 wrap 進一個帶上下文的新錯誤裡；如果是 Ok，那個 closure 根本不會被執行（所以 format! 的代價一毛都不用付）。

為什麼是傳 closure 而不是直接傳字串呢？關鍵就在 lazy evaluation。要是直接寫：

.context(format!("missing metadata {key}"))   // 每次都會 format!

那麼就算走的是 happy path（順利找到 metadata），format! 還是會白白被執行一次——對 hot path 來說這實在是純粹的浪費。with_context 接 closure 的版本只在出錯時才執行，這在效能敏感的程式碼裡，是個值得養成的好習慣。

`?` 運算子的小巧思

? 可不只是「if Err return」這麼簡單，它還會順手幫你呼叫 From::from。所以 anyhow::Error 可以從任何實作了 std::error::Error 的型別轉換過來——這就是為什麼 parse_gguf 回傳的錯誤，能無縫接軌轉成我函式裡的 anyhow::Result。我個人相當喜歡這個設計，省掉一堆手動轉型的樣板碼。

不變式檢查：為什麼要在 load 時就驗？

if n_embd % n_head != 0 {
    bail!("n_embd {n_embd} not divisible by n_head {n_head}");
}
if n_head % n_head_kv != 0 {
    bail!("n_head {n_head} not divisible by n_head_kv {n_head_kv}");
}

這兩個不變式是 Llama 架構的硬性要求：

n_embd / n_head = head_dim——每個 attention head 平均分配 hidden dim。
n_head / n_head_kv = gqa_groups——GQA 下，每組 query head 共用一個 K/V head。

這些不變式一旦不成立，後面 runner.rs 算出來的 offset 就會整批跑掉，搞不好還會踩到未定義行為（讀到別的張量的 bytes，那可就妙了）。與其讓它在 forward pass 跑到一半才 panic，不如在 load 階段就乾脆 bail 掉，對使用者實在友善多了。

這正是 Rust 「fail fast at boundaries」哲學的具體實踐：在外部資料進入系統的那道邊界（這裡就是 GGUF metadata）先驗證乾淨，往後的程式碼才能放心假設不變式都成立。

衍生方法：`head_dim()`、`kv_dim()`、`gqa_groups()`

pub fn head_dim(&self) -> usize { self.n_embd / self.n_head }
pub fn kv_dim(&self)   -> usize { self.head_dim() * self.n_head_kv }
pub fn gqa_groups(&self) -> usize { self.n_head / self.n_head_kv }

這三個都是 derived 量，理論上每次都能從 base 欄位現算出來。那為什麼不乾脆把 head_dim 也存進 struct，要每次重算呢？我想原因有二：

避免不一致：如果 n_head、n_embd、head_dim 三個一起存，難保哪天有人改了其中一個、忘了改另外兩個，三者就對不起來了。只存 base 量，single source of truth，省心。
除法的成本根本可以忽略：這些方法又不在 hot path 上，runner 只在 new() 時呼叫一次來算 buffer 大小，又不是塞在 inner loop 裡反覆呼叫，算就算吧。

說到底，這是 Rust struct design 的一個小哲學：只存 fundamental fields，derived 量一律寫成方法。

從 hyperparameter 算出模型大小

動手算之前，先用一張圖把這些欄位攤到推論流程上看看吧，這樣就能比較清楚每個參數實際是在控制哪一段：

有了這 10 個欄位，你其實光憑紙筆就能直接算出整個模型有幾個參數，連模型檔都還不用載入呢。不管是想估記憶體、估推論速度，還是純粹滿足好奇心，這招都頗實用。

Llama 的權重主要藏在三個地方：embedding、每一層 transformer block、還有最後的 LM head。我們一個一個拆開來看：

1. Token embedding 與 LM head

每個 token 對應一個長度 n_embd 的向量，總共 vocab_size 個 token：

Embedding：vocab_size × n_embd
LM head：vocab_size × n_embd（有些模型會跟 embedding 共享權重，Llama 家族通常不共享）

這兩個加起來，通常是模型裡單一最肥的一塊權重，vocab 越大越明顯（Llama-3 把 vocab 從 32K 一口氣拉到 128K，膨脹得最兇的就是這裡）。

2. 每一層 transformer block

每層裡頭有 attention 和 FFN 兩個子模組。先看 attention 的四個 projection：

Q projection：n_embd × n_embd
K projection：n_embd × kv_dim（GQA 下 K 的維度是縮小的）
V projection：n_embd × kv_dim
Output projection：n_embd × n_embd

加起來是 2 × n_embd² + 2 × n_embd × kv_dim。

FFN 是 SwiGLU 結構，有三個矩陣：

Gate projection：n_embd × n_ff
Up projection：n_embd × n_ff
Down projection：n_ff × n_embd

加起來是 3 × n_embd × n_ff。

另外每層還有兩個 RMSNorm 的 scale 向量（各長 n_embd），加上最後一層 final norm 也是 n_embd——不過這些跟動輒幾百萬的矩陣比起來，小到根本可以直接忽略。

3. 把公式拼起來

total_params ≈ 2 × vocab_size × n_embd                # embedding + LM head
             + n_layer × (
                   2 × n_embd²                        # Q + O
                 + 2 × n_embd × kv_dim                # K + V
                 + 3 × n_embd × n_ff                  # SwiGLU
               )

套到 TinyLlama 1.1B 驗算一次

從前面的表格抓出 TinyLlama 的 hyperparameters：n_layer=22, n_embd=2048, n_head=32, n_head_kv=4, n_ff=5632, vocab_size=32000。

先算衍生量：head_dim = 2048 / 32 = 64，kv_dim = 64 × 4 = 256。

部分	公式	數值
Embedding	`32000 × 2048`	≈ 65.5M
LM head	`32000 × 2048`	≈ 65.5M
每層 attention	`2 × 2048² + 2 × 2048 × 256`	≈ 9.4M
每層 FFN	`3 × 2048 × 5632`	≈ 34.6M
全部 22 層	`22 × (9.4M + 34.6M)`	≈ 968M
總和		≈ 1.10B

剛剛好對上 “1.1B”——原來模型名字裡那個數字就是這樣算出來的啊。:-)

從這個算式還能看出兩件事

真正主導參數量的其實是 FFN。3 × n_embd × n_ff 通常比 4 × n_embd × head_dim × (n_head + n_head_kv) 大上 3~4 倍。所以模型一放大，最先膨脹的往往是 FFN，再來才輪到層數。
記憶體佔用可以反推。fp16 下每個參數佔 2 bytes，1.1B × 2 ≈ 2.2 GB；換成 4-bit 量化理論上只剩 1/4，約 550 MB——這正是 tiny-llm-runner 能直接 mmap 一個 q4_k 模型、在普通筆電上就跑得起來的關鍵。

下次拿到一個陌生的 GGUF 檔，不必特地去翻 Hugging Face card，光瞄一眼 metadata 就能心算出它大概多胖、塞不塞得進你的記憶體。是不是頗方便？

總結：什麼時候輪到 config.rs 上場

整個 tiny-llm-runner 的生命週期裡，config.rs 其實只被呼叫一次：就在 main.rs 的開頭。它扮演的角色是型別系統的入口閘——把外部世界那堆 schemaless 的 metadata，轉成內部世界乾乾淨淨的 type-safe struct。一旦過了這道閘，後面所有檔案就能放心地吃 &LlamaConfig，再也不必去碰 GGUF 那些惱人的細節。一個只有百來行的小檔案，能把責任邊界劃得這麼清楚，我想這就是它低調卻好用的地方吧。

下一篇我打算來講 dequant.rs，那才是這個專案真正的「重武器庫」——所有量化解碼和點積核心，全都藏在那裡頭。頗為期待。

系列文章：

tiny-llm-runner 介紹

(1) config.rs（本篇）