快速開始
這是從已建置完成的倉庫到驗證 runtime 的最快路徑。
1. 檢查模型（Inspect）
./tinyloop/build/tinyloop model.tinyloop inspect
先做 inspect。它會驗證：
- 檔案 magic 與格式版本
- 維度與 head 數量
- embedding 模式
- 權重、buffer 與 KV-cache 的記憶體估算
2. 執行基準測試（Benchmark）
./tinyloop/build/tinyloop model.tinyloop benchmark --loops 8 --seq-len 128 --repeat 10
此路徑會在不完整物化 logits 的前提下測試 runtime。
目前文件中的基準狀態：
- 預設低位元路徑：約
30.48 ms - 實驗性 FP16-body 路徑：約
2.82 ms
兩者都指向已驗證的 H100 目標工作負載：seq_len=128、loops=8、不輸出 logits。
若要輸出單次執行的 CUDA event 分段時間：
TINYLOOP_CUDA_PROFILE=1 \
./tinyloop/build/tinyloop model.tinyloop benchmark --loops 8 --seq-len 128 --repeat 1
3. 生成文字（Generate）
./tinyloop/build/tinyloop model.tinyloop generate \
--prompt "Looped transformers are" \
--loops 8 \
--max-tokens 32 \
--temperature 0.8 \
--top-k 50
目前重要行為：
- 預設使用 cached decode
TINYLOOP_DISABLE_KV_CACHE=1會強制 uncached 參考路徑- CLI 目前會將 prompt 當作 raw bytes 做 tokenization
執行 uncached 參考路徑：
TINYLOOP_DISABLE_KV_CACHE=1 \
./tinyloop/build/tinyloop model.tinyloop generate --prompt "Looped transformers are"
4. 嘗試自我推測式解碼（Self-Speculative Decoding）
./tinyloop/build/tinyloop model.tinyloop speculate \
--prompt "Looped transformers are" \
--draft-loops 2 \
--verify-loops 8 \
--draft-ahead 4 \
--max-tokens 32
這會使用同一個模型執行 draft 與 verify。
目前狀態：
- 已有 cache-aware speculation
- 已有 accept-or-resample 邏輯
- 已有 regression 覆蓋
- 更廣泛工作負載驗證仍在 roadmap 中
5. 用 Python 綁定做真實 Tokenization
import numpy as np
import tinyloop_py
model = tinyloop_py.Model("model.tinyloop", max_seq_len=2048)
tokens = np.asarray([15496, 995], dtype=np.int32)
logits = model.score_last(tokens, loops=8)
generated = model.generate(tokens, max_tokens=32, loops=8, temperature=0.0, top_k=50)
Python 路徑適合：
- GPT 風格 tokenizer 整合
- 評估腳本
- 服務端流程編排
6. 跑測試面（Test Surface）
ctest --test-dir tinyloop/build --output-on-failure
模型相依檢查：
TINYLOOP_TEST_MODEL_PATH=/absolute/path/to/model.tinyloop \
ctest --test-dir tinyloop/build --output-on-failure
目前注意事項
警告
CLI 仍是 raw-byte prompt 介面。若要做真實 tokenizer 驅動的生成，請使用 Python 或自行整合層。
目前效能主張是基於已檢查的驗證路徑，不代表對所有模型都提供通用保證。