跳至主要内容

疑難排解

本頁聚焦在 TinyLoop 工作流程中實際常見的失敗模式。

建置問題​

Failed to find nvcc​

意義：

  • 目前環境找不到 CUDA Toolkit

請檢查：

  • nvcc 存在
  • CUDA 二進位路徑已加入 PATH
  • CUDAToolkit_ROOT 設定正確

Python 模組沒有建出來​

意義：

  • 可能找不到 pybind11
  • 或缺少 Python3 Development.Module

請在 CMake configure 輸出確認：

  • pybind11_FOUND
  • Python3_Development.Module_FOUND

模型載入問題​

Invalid magic 或 unsupported version​

意義：

  • 該檔案不是有效 .tinyloop artifact
  • 或 artifact 版本超出 runtime 支援範圍

第一步：

  • 執行 inspect
  • 確認 converter 輸出預期版本

dim must be divisible by n_heads​

意義：

  • artifact header 不一致或已損毀

請檢查：

  • 來源 checkpoint 設定
  • converter 邏輯
  • 寫入的 header 欄位

Unsupported n_pre_blocks​

意義：

  • 目前 runtime 假設的是它所設計的狹窄 looped-transformer 家族

這不是一行補丁能解決，而是刻意的 runtime 擴充任務。

Runtime 問題​

CUDA 配置失敗​

常見原因：

  • max_seq_len 設太大
  • 模型對該裝置太大
  • 在記憶體不足 GPU 上啟用了 FP16 body cache 模式

可嘗試：

  • 降低 max_seq_len
  • 載入前先跑 inspect
  • 改用較低記憶體模式
  • 停用 TINYLOOP_EXPERIMENTAL_FP16_BODY=1

生成輸出看起來不對​

先隔離來源：

  1. 用 TINYLOOP_DISABLE_KV_CACHE=1 比較 cached 與 uncached
  2. 用 TINYLOOP_DISABLE_FLASH2_PREFILL=1 比較新 prefill 與參考路徑
  3. 若你使用 CLI，記得它會把 prompt 文字當 raw bytes tokenization

若 Python/tokenizer 路徑正常但 CLI 不正常，問題可能在文字前處理而非 runtime 本身。

Benchmark 數字不一致​

請檢查：

  • 測試是冷啟動還是暖機後
  • TINYLOOP_CUDA_PROFILE=1 是否改變 warmup 行為
  • 是否啟用 TINYLOOP_EXPERIMENTAL_FP16_BODY=1
  • 是否有其他程序同時使用該 GPU

測試問題​

模型相依測試被跳過​

請設定：

TINYLOOP_TEST_MODEL_PATH=/absolute/path/to/model.tinyloop

Tokenizer-aware 測試被跳過​

請檢查：

  • Python 綁定是否已建置
  • numpy 是否已安裝
  • transformers 是否已安裝

Python regression 無法匯入 tinyloop_py​

請設定：

TINYLOOP_TEST_BUILD_DIR=/path/to/tinyloop/build

或把 build 目錄加入 PYTHONPATH。

什麼時候該停止猜測​

若 bug 不明顯：

  1. 以最小命令重現
  2. 與最接近的參考路徑比較
  3. 保存完整環境旗標
  4. 執行最小相關測試或 microbenchmark

TinyLoop 仍在快速演進，模糊式除錯通常只會浪費時間。