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）。在 load 階段就 bail 掉，比在 forward pass 跑到一半 panic 友善多了。

這是 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 而是每次算？因為：

避免不一致：如果同時存 n_head、n_embd、head_dim，理論上有人可能改了其中一個忘了改另外兩個，三者就對不起來。只存 base 量是 single source of truth。
divide 的成本可忽略：這些方法不在 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（本篇）