跳至主要内容

C++ API

TinyLoop 的 C++ 層是正典的 runtime 介面。Python 綁定（tinyloop_py）是這個 API 之上的薄層 pybind11 包裝,HTTP 伺服器則是建構在 Python 包裝之上的編排層。

本節從實作(include/tinyloop.h、include/model.h、include/kv_cache.h、src/inference.cpp、src/generate.cpp)而非從包裝語義記錄 C++ API 行為。

Namespace 與 header 契約​

公開介面:

#include <tinyloop/tinyloop.h>

本文件中所有內容皆位於 namespace tinyloop。

tinyloop.h 是穩定的進入點,涵蓋:

  • 生命週期(load_model、free_model)
  • 評分(score* 系列)
  • 生成(generate* 系列)
  • 快取 handle(PrefixCache、ResumeHandle、PrefixPool)
  • Runtime 記憶體量測(vram_usage_bytes)

內部 header(model.h、kv_cache.h、runtime_internal.h)暴露實作細節,並非長期相容性邊界。

API 拓撲​

tinyloop::Model* 生命週期
  ├─ score / score_last_token / score_logit_lens / score_with_*
  ├─ generate / generate_stream / generate_batch
  ├─ generate_speculative / generate_tree_speculative
  ├─ PrefixCache 建立 + decode 重用
  ├─ ResumeHandle 建立 + resume_generate
  └─ PrefixPool 註冊 + generate_with_pool

Runtime 如何執行​

對於標準的 decode 呼叫,狀態機為:

  1. 模型載入

    • 解析 .tinyloop header(magic、版本、維度、loop 預設值)。
    • 上傳打包的 INT2/INT4 + scales/zeros + LN/輸出張量。
    • 配置可重複使用的 buffer pool(BufferPool),由 max_seq_len 及可選的 prefill_chunk 決定大小。

  2. Prefill

    • 嵌入 prompt tokens。
    • 跑 pre-blocks(n_pre_blocks)。
    • 共享 loop block 跑 L 次。
    • 填入 runtime KV cache 層。

  3. Decode

    • 每送出一個 token:附加一行/層 KV,由最後一個 hidden 計算下一 token 的 logits,抽樣。
    • 停止條件:max_tokens、EOS、stop-sequence 結尾匹配、grammar 死路、callback 中止(streaming 路徑)。

  4. 拆除

    • 釋放每次呼叫的快取/暫存。
    • 保留模型權重 + buffer pool 供跨請求重用。

此架構針對「於一個已載入模型上重複推理」最佳化,而不是一次性的 load/execute/free 迴圈。

為什麼這樣設計​

TinyLoop 刻意讓 C++ API 寬度保持窄,但保留豐富的 runtime 模式。

  • 窄 ABI 減少相容性變動。
  • 大部分複雜度(量化路徑、KV 模式、speculative 變體)編碼在 config/env/runtime 邏輯裡,而不是深層類別繼承。
  • 這符合本專案目標:為單一架構家族(weight-shared looped transformer)提供高效能 runtime,而非通用 model-zoo 介面。

主要取捨​

  • 效能優先的所有權模型: 原始指標與明確的 free API 使 overhead 保持低,但把正確性責任推給呼叫端。
  • 單一模型可變 buffer: 一個 Model* 若無外部同步,無法並行重入推理。
  • 透過 env flag 加功能: 模式組合強大但會提高維運複雜度。
  • 特化優於通用: 以架構專屬優化(warm-start、共享權重 speculative、store-h KV)換取更廣的 checkpoint 相容性。

參考​

下列每一頁都是該 API 家族的完整參考。選擇你需要的那頁,或依序閱讀以獲得完整導覽。

章節內容
生命週期與記憶體模型load_model、free_model、vram_usage_bytes、所有權規則、prefill_chunk、thread-safety。
Scoring APIscore、score_last_token、score_logit_lens、score_with_uncertainty、score_with_consistency_escalation。
Generation APIgenerate、generate_stream、generate_batch、generate_speculative、generate_tree_speculative、GenerateConfig。
快取重用與狀態轉換 APIPrefixCache、ResumeHandle、PrefixPool — 跨呼叫重用 prefill 狀態,或在同一 prompt 上升級 loop 深度。
批次化與整合模式generate_batch 限制、服務層級編排模式、runtime-mode 組合矩陣。