Python API
TinyLoop 提供名為 tinyloop_py 的 pybind11 模組。這一層主要用於評估、腳本化流程、分詞器整合與服務端編排，不是訓練框架。
安裝
Python 模組會和 C++ 函式庫一起由頂層 CMakeLists.txt 建置。執行 cmake --build . --target tinyloop_py 後，會在 build 目錄看到 tinyloop_py.cpython-*.so。
可用以下方式匯入：
PYTHONPATH=/path/to/tinyloop/build python3 -c "import tinyloop_py; print(tinyloop_py.__doc__)"
也可以把 .so 複製到 Python site-packages。
此外也提供 PyPI 套件 loopformer（生態系命名因素，實際為 TinyLoop）；請參考安裝說明中的 pip install loopformer。
快速開始
import numpy as np
import tinyloop_py as tl
with tl.Model("model.tinyloop", max_seq_len=2048) as model:
prompt = np.array([12, 34, 567], dtype=np.int32)
tokens = model.generate(prompt, max_tokens=32, loops=8, temperature=0.0, top_k=50)
print(tokens)
內容導覽
| 區段 | 說明 |
|---|---|
Model | 載入模型、管理生命週期、查看 config 與 VRAM。 |
| Scoring | score、score_last、score_logit_lens、score_trajectory、不確定性/一致性 API。 |
| Generation | generate、generate_stream、generate_speculative。 |
| Prefix cache | build_prefix_cache、generate_from_prefix_cache，重用共享前綴。 |
| Prefix pool | PrefixPool、register_prefix、generate_with_pool — 多 PrefixCache 的 content-addressable 註冊表，自動 longest-prefix 匹配。多租戶 serving 的基礎原語。 |
| Warm-start mid-loop | build_resume_handle、resume_generate，同一 prompt 以更深 L 接續。 |
| KV cache modes | 五種 KV 儲存模式與 Python 端行為、選型建議。 |
架構圖
tinyloop_py
├─ Model (lifecycle + scoring + generation dispatch)
│ ├─ score / score_last → full / last logits
│ ├─ score_logit_lens → 每迭代 logits
│ ├─ score_trajectory → hidden trajectory (embed + pre + loops)
│ ├─ score_with_uncertainty → 深度間 KL
│ ├─ score_with_consistency → argmax 一致性門控
│ ├─ generate / generate_stream → 自回歸解碼
│ ├─ generate_speculative → 同權重自推測解碼
│ ├─ build_prefix_cache → PrefixCache
│ ├─ generate_from_prefix_cache → 由 PrefixCache 解碼
│ ├─ register_prefix → 把 PrefixCache 放進 PrefixPool
│ ├─ generate_with_pool → 自動匹配最長已註冊前綴
│ ├─ build_resume_handle → ResumeHandle
│ ├─ resume_generate → ResumeHandle 接續生成
│ ├─ config / vram_usage_mb → metadata + memory
│ └─ close / __enter__ / __exit__ → 生命週期
├─ Grammar (regex NFA) → constrained decoding（與 generate 組合）
├─ PrefixCache (opaque)
├─ PrefixPool (opaque, LRU) → PrefixCache 的註冊表
├─ ResumeHandle (opaque)
└─ load (Model constructor alias)
所有 opaque 型別由 pybind11 參考計數管理；最後一個 Python 參考釋放後才會回收 GPU 記憶體。
建議用法
- 每個程序載入一個
Model並重用。 - 在 TinyLoop 外部做 tokenization（如
transformers），API 輸入皆為np.ndarray[int32]。 - 只需最後一個 token logits 時，優先用
score_last()。 - 重複共享 prompt 的工作負載，用
build_prefix_cache()（通常可得 2–3× 吞吐）。 - 同 prompt 需要多個深度
L時，用build_resume_handle()+resume_generate()。 - 記憶體緊時，請在
import tinyloop_py前設定 KV mode 環境變數。
常見錯誤
| 錯誤 | 常見原因 | 修正 |
|---|---|---|
RuntimeError: model was closed | close() 後或 with 區塊結束後仍呼叫 | 重新建立 Model |
RuntimeError: out of memory | max_seq_len 太大、cache handle 太多、fp16_body 在小卡上 | 降低 max_seq_len、釋放 handle、關閉 TINYLOOP_EXPERIMENTAL_FP16_BODY |
RuntimeError: loops mismatch | generate_from_prefix_cache 的 loops 與建置時不一致 | 對齊 loops 或重建 prefix |
ValueError | 參數範圍非法（負值、0） | 依各 API 參數表修正 |
| Import 失敗 | .so 不在 PYTHONPATH、ABI 不匹配 | 以目前 Python 版本重建並測試匯入 |
更多故障排除見troubleshooting。
目前限制
目前 Python 整合仍偏向：
- 單模型、單程序導向
- 呼叫端顯式 tokenization
- 不是完整 serving framework
若需要多模型編排、跨租戶批次、跨程序共享，需在這些 primitive 之上自行實作上層服務。