跳至主要内容

模型轉換

TinyLoop 使用 .tinyloop artifact，而不是直接讀取原始 PyTorch checkpoint。

目前轉換與評估輔助工具位於 tinyloop/tools/。

主要工具​

工具用途
tools/convert_pytorch.py將基礎 checkpoint 轉為 .tinyloop
tools/gptq_convert.py實驗性、偏 GPTQ 的轉換路徑
tools/eval_hellaswag.py任務層級 sanity check 的快速評估工具

基礎轉換流程​

python tinyloop/tools/convert_pytorch.py \
  --checkpoint model.pt \
  --output model.tinyloop \
  --factor-dim 64 \
  --bits 4 \
  --group-size 0 \
  --tie-weights

重要旗標：

Flag意義
--checkpoint來源 checkpoint
--output輸出 .tinyloop 檔案
--factor-dim分解 embedding/head 維度
--bits量化 bit 寬，現在為 2 或 4
--group-size量化群組大小，0 代表 per-row
--tie-weights重用可相容的 embedding/head 權重

建議驗證流程​

轉換後：

  1. 執行 inspect
  2. 執行小型 benchmark
  3. 將 logits 或輸出與參考路徑比較
  4. 跑任務層級 sanity check（如 eval_hellaswag.py）

GPTQ 狀態​

截至 2026-04-17，tools/gptq_convert.py 相比原始參考實作新增兩項能力：

標準 GPTQ — Cholesky 穩定性修正​

舊版 converter 會對 inv(H) 做 cholesky(..., upper=True)，在條件數不佳的校準 Hessian 上容易出現 NaN，然後用寫死的 +0.1 I 靜默重試。現在改成專用 _upper_chol_hinv() helper，行為如下：

  • 透過穩定鏈路 cholesky(H) → cholesky_inverse → cholesky(upper=True) 計算 H⁻¹ 的上三角 Cholesky，避免不穩定的 torch.linalg.inv(H) 中介步驟。
  • 每次失敗將 damping 放大 10 倍，最多 4 次後才放棄。
  • 若真正失敗，會丟出清楚的 RuntimeError（包含 damping、嘗試次數、矩陣形狀），而非靜默地用常數重試。

此路徑由 tests/test_gptq.py 覆蓋，包含刻意近奇異 Hessian（64 維空間上 rank-4），可驗證 damping escalation 能恢復。

β 加權 GPTQ — 論文層級的新貢獻​

gptq_quantize() 現在可接受可選的 beta= 參數，用來實作論文中的 β 加權量化。可接受三種形式：

beta 值效果
None（預設）完全等同標準 GPTQ，與不傳參數 bit-identical。
純量 float將 percdamp 乘上 β²。β 越大，rounding 越保守。僅做 Hessian 等比例縮放對 GPTQ 本身不敏感（Cholesky 與更新會同時縮放），因此純量 β 真正影響輸出是透過 damping 鉤子。
長度為 K 的 1D tensor欄位級敏感度。先縮放有效 Hessian H̃ = diag(β) H diag(β) 再做 Cholesky。高 β 欄位會透過標準 GPTQ 流程得到更謹慎的 rounding。

欄位級形式是論文所稱的「β-aware quantization」路徑：先量測每個權重矩陣（或矩陣內每欄）的 β，再餵給 gptq_quantize()，讓轉換器把 rounding 預算放在更重要的位置。純量形式則是較低成本的保守度超參數旋鈕。

兩種形式都已由 tests/test_gptq.py 覆蓋：test_beta_none_matches_no_beta、test_beta_scalar_modulates_damping、test_beta_per_column_protects_high_beta_columns、test_beta_bad_shape_raises。全部測試在 CPU 上 100 ms 內完成。

β 量測 CLI​

β 加權 GPTQ 需要的 β 值由 tinyloop-measure-beta 指令產生（定義於 pyproject.toml，實作於 python/tinyloop_tools/measure_beta.py）。可輸入原始 PyTorch state_dict.pt 或 HuggingFace 風格 .safetensors，帶前綴的 HF keys 會自動映射到訓練腳本格式。

端到端 β-aware 量化流程：

# 1. 在原始 checkpoint 上量測 β。
tinyloop-measure-beta \
    --model /path/to/model.safetensors \
    --calib-text /path/to/wikitext.txt \
    --output /tmp/betas.json \
    --L-values 1,2,4,8,16 \
    --trials 3

# 2. 將量測出的 β 值餵入 GPTQ。
python tools/gptq_convert.py \
    --model /path/to/model.safetensors \
    --calib-text /path/to/wikitext.txt \
    --beta /tmp/betas.json \
    --bits 4 \
    --output model_int4.tinyloop

輸出 JSON 形狀為 {"per_matrix": {"pre.0.attn_qkv": {"beta": 0.43, "intercept": 2.98}, …}}，另含 arch 與 measurement 區塊，記錄 CLI 參數以利重現。

tinyloop-measure-beta 需要 CUDA，因為擾動前向運算在 GPU 上執行。A100 等級硬體建議 --precision fp16（預設）；若需 fp32 偵錯可用 --precision fp32。

同時保留開發路徑等價指令 python tools/measure_beta.py ...，作為同模組上的薄封裝（thin shim），讓倉庫內相對路徑腳本可繼續運作。

尚未完成的工作​

  • 接受度驗證：「β-GPTQ 在 L=8 時比 vanilla GPTQ 至少好 0.3 PPL」是 CHECKLIST.md §3 的目標，尚未在真實模型上量測。需要恢復的 407M checkpoint 與 WikiText-103 校準資料，目前仍待 pod 可用。
  • 依量測 β 跨矩陣進行 mixed-precision bit 配置，追蹤於 CHECKLIST.md §16.3 P1 — β-aware mixed precision，目前仍未完成。

格式相容性​

目前公開 runtime 介面文件記錄 .tinyloop 格式版本為 1 到 3。

若你改動 artifact 語義：

  1. 明確提升格式版本
  2. 明確定義 loader 相容規則
  3. 同步更新轉換文件與 regression 覆蓋

轉換無法自動保證的事​

模型轉換不等於品質證明。

請務必驗證：

  • 輸出一致性或行為合理性
  • 記憶體占用
  • 基準測試表現
  • 下游任務品質