debug-cuda-crash

此技能為開發人員與 AI 工程師提供了一份詳盡指南，用於除錯使用 FlashInfer 函式庫時遇到的複雜 CUDA 崩潰問題。CUDA 錯誤（例如非法記憶體存取、越界錯誤、NaN/Inf 數值不穩定與記憶體溢出 OOM）通常難以追蹤，因為它們往往會立即終止執行環境。此技能教導使用者如何利用 @flashinfer_api 裝飾器來檢測程式碼，從而在失敗前系統化地觀察張量狀態與 API 呼叫序列。

• 在核心執行前捕獲輸入元數據，包含張量形狀、資料類型、裝置分配與記憶體佈局。

• 記錄張量內部統計數據，如最小值、最大值、平均值以及 NaN/Inf 計數，以準確定位模型中的數值不穩定性。

• 設定日誌等級與儲存位置，支援標準輸出與檔案日誌，適用於多進程（如 torchrun）環境。

• 識別諸如頭維度不匹配、錯誤資料類型（FP16 與 BF16）或 CPU 到 GPU 傳輸錯誤等結構性問題。

• 與進階外部診斷工具（如 compute-sanitizer）整合，進行深層硬體記憶體分析。

• 使用者應設定環境變數（如 FLASHINFER_LOGLEVEL 1 到 5 與 FLASHINFER_LOGDEST）來控制日誌詳細程度與輸出目標。

• 本指南假設使用者是在基於 PyTorch 的推理流水線中使用 FlashInfer 的最佳化 Attention 或 GEMM 核心。

• 在進行多 Rank/多 GPU 除錯時，務必在日誌路徑中使用 %i 模式，以防止多進程間的日誌寫入衝突。

• 雖然該工具已針對捕捉運行時失敗進行最佳化，但它不能取代核心級分析，效能瓶頸分析應使用 FlashInfer 專用分析工具。

• 若在頻繁呼叫核心時啟用等級 5 的日誌（張量統計），請確保磁碟有足夠的儲存空間，以避免執行期間的 I/O 阻塞。