設定參考

主要公開宣告位於 include/tinyloop.h。

本頁文件化的是公開設定型別，而非 model.h 內部實作結構。

ModelConfig

ModelConfig 會儲存在 artifact header，並在模型載入後對外暴露。

欄位：

欄位	意義
dim	隱藏層維度
n_heads	注意力 head 數量
ffn_dim	前饋層寬度
vocab_size	詞彙表大小
embed_factor_dim	分解 embedding/head 維度，0 代表直接量化模式
n_pre_blocks	共享 loop block 之前的 pre-block 數量。載入時接受 [1, 8] 之任意值；目前釋出的模型都使用 2。
default_loops	artifact 建議的預設 loop 次數
n_kv_heads	GQA 的 KV head 數量。0 代表與 n_heads 相同（標準 MHA）。小於 n_heads 即啟用分組查詢注意力，Q head 會映射到對應的 KV head。透過 TINYLOOP_N_KV_HEADS=N 設定。
use_rope	是否啟用旋轉位置編碼（RoPE）。啟用後 runtime 在載入時預算 cos/sin 頻率表，並在所有前向路徑（prefill、decode、chunked prefill、tree-verify、batched decode）中對 Q/K 向量套用旋轉。透過 TINYLOOP_USE_ROPE=1 設定。
rope_theta	RoPE 基底頻率（預設 10000.0，與 Llama-2 一致）。透過 TINYLOOP_ROPE_THETA=N 覆寫，用於不同 theta 訓練的模型（如 Llama-3 為 500000.0）。
post_norm	從 pre-norm（預設，LayerNorm 在 attention/MLP 之前）切換為 post-norm（LayerNorm 在之後）。透過 TINYLOOP_POST_NORM=1 設定。
use_gelu	MLP 從 SwiGLU（預設）切換為 GeLU 啟動。用於 GPT-2/BERT 風格模型。透過 TINYLOOP_USE_GELU=1 設定。

InferenceConfig

struct InferenceConfig {
    int n_loops = 8;
    int max_seq_len = 2048;
};

語義：

• n_loops：執行時 loop 次數覆寫
• max_seq_len：用於配置 buffer 的執行時序列上限

這是小型 helper 型別，不是 CLI 的主要路徑。

GenerateConfig

GenerateConfig 控制標準自回歸生成。

欄位	意義
n_loops	解碼 loop 次數
max_tokens	新生成 token 數量
temperature	取樣溫度，接近 0 代表 greedy
top_k	Top-k 截斷
top_p	Nucleus 截斷
eos_token	結束生成的 token id
cache_window	0 代表完整快取，>0 只保留最後 W 個快取 token

重要語義：

• cached decode 是預設 runtime 路徑
• temperature <= 0.01 幾乎等同 greedy decoding
• cache_window 用上下文保留能力換取有界 KV 記憶體

SpeculativeConfig

SpeculativeConfig 控制自我推測式解碼。

欄位	意義
draft_loops	Draft pass 的 loop 次數
verify_loops	Verify pass 的 loop 次數
draft_ahead	每輪推測草擬 token 數
max_tokens	最大新 token 數
temperature	取樣溫度
top_k	Top-k 截斷
top_p	Top-p 截斷
eos_token	序列結束 token
cache_window	Sliding-window KV 預算

目前狀態：

• 此路徑已有共享快取的推測式 runtime 邏輯
• 仍建議視為進階 runtime 行為，而非完全定稿的 serving 契約

PrefixCache

PrefixCache 是不透明（opaque）的公開 handle。

可讓呼叫端：

1. 對共同 prompt 只做一次 prefill
2. 保留得到的隱狀態與 KV-cache 前綴
3. 在重複請求中複用該前綴

公開函式：

PrefixCache* build_prefix_cache(Model* model, const int32_t* tokens, int seq_len,
                                int n_loops = 8, int cache_window = 0);
void free_prefix_cache(PrefixCache* prefix_cache);
std::vector<int32_t> generate_from_prefix_cache(Model* model, const PrefixCache* prefix_cache,
                                                const GenerateConfig& config);

實務建議

建議使用：

• GenerateConfig 做一般生成
• SpeculativeConfig 僅在你刻意探索自我推測式行為時使用
• PrefixCache 用於重複請求共享同一前綴

若你在整合 tokenizer 驅動的文字生成，這些設定結構只控制 runtime 行為，不會幫你處理 tokenizer 載入或文字前處理。