AOTInductor 除錯指南#
創建於：2025年8月14日 | 最後更新於：2025年8月14日
如果您在使用 AOT Inductor 時遇到 CUDA 非法記憶體訪問 (IMA) 錯誤，本指南將提供一個系統性的方法來除錯此類錯誤。AOT Inductor 是 PT2 堆疊的一部分，類似於 torch.compile，但它會生成可以在 C++ 環境中執行的編譯產物。CUDA 非法記憶體錯誤可能不會確定性地發生，甚至有時會短暫出現。
總的來說，除錯 CUDA IMA 錯誤有三個主要步驟：
健全性檢查：在深入除錯之前，使用基本的除錯標誌來捕獲常見問題。
精確定位 CUDA IMA：使錯誤具有確定性，並識別出有問題的核心。
識別有問題的核心：使用中間值除錯來檢查核心的輸入和輸出。
第一步：健全性檢查#
在可靠復現錯誤之前，請嘗試使用一些現有的除錯標誌。
AOTI_RUNTIME_CHECK_INPUTS=1
TORCHINDUCTOR_NAN_ASSERTS=1
這些標誌在編譯時（更準確地說，是在程式碼生成時）生效。
AOTI_RUNTIME_CHECK_INPUTS=1檢查輸入是否滿足編譯時使用的相同 guard 集合。有關更多詳細資訊，請參閱 torch.compile 故障排除。TORCHINDUCTOR_NAN_ASSERTS=1在 Inductor 的每個核心前後新增程式碼生成，以檢查 NaN。
第二步：精確定位 CUDA IMA#
一個難題是 CUDA IMA 錯誤可能不會確定性地發生。它們可能發生在不同的位置，有時甚至根本不發生（儘管這僅僅意味著數值上存在潛在的錯誤）。使用以下兩個標誌，我們可以確定性地觸發錯誤：
PYTORCH_NO_CUDA_MEMORY_CACHING=1
CUDA_LAUNCH_BLOCKING=1
這些標誌在執行時生效。
PYTORCH_NO_CUDA_MEMORY_CACHING=1停用 PyTorch 的快取分配器，該分配器會分配比實際需要更多的緩衝區以減少緩衝區分配次數。這通常是 CUDA 非法記憶體訪問錯誤表現不確定的原因。
圖：PyTorch 的快取分配器如何掩蓋 CUDA 非法記憶體訪問錯誤CUDA_LAUNCH_BLOCKING=1強制核心一次一個地啟動。如果沒有這個標誌，我們可能會收到著名的“CUDA 核心錯誤可能在其他 API 呼叫處非同步報告”警告，因為核心是非同步啟動的。
第三步：使用中間值偵錯程式識別有問題的核心#
AOTI 中間值偵錯程式可以幫助精確定位有問題的核心，並獲取該核心輸入和輸出的資訊。
首先，使用
AOT_INDUCTOR_DEBUG_INTERMEDIATE_VALUE_PRINTER=3
此標誌在編譯時生效，並在執行時逐個列印核心。結合之前的標誌，這將讓我們知道在錯誤發生前啟動的是哪個核心。
然而，需要注意的是，僅僅因為錯誤發生在某個核心中，並不意味著該核心本身有問題。例如，可能是一個較早的核心有問題，產生了錯誤的輸出。因此，下一步自然是檢查該有問題的核心的輸入。
AOT_INDUCTOR_FILTERED_KERNELS_TO_PRINT="triton_poi_fused_add_ge_logical_and_logical_or_lt_231,_add_position_embeddings_kernel_5" AOT_INDUCTOR_DEBUG_INTERMEDIATE_VALUE_PRINTER=2
用於過濾核心列印的環境變數包含您要檢查的核心名稱。如果核心的輸入不符合預期，則您需要檢查生成錯誤輸入的那個核心。
附加除錯工具#
日誌記錄和跟蹤#
tlparse / TORCH_TRACE：提供完整的輸出程式碼供檢查，並記錄使用的 guard 集合。有關更多詳細資訊，請參閱 tlparse / TORCH_TRACE。
TORCH_LOGS：使用
TORCH_LOGS="+inductor,output_code"來檢視更多 PT2 內部日誌。有關更多詳細資訊，請參閱 TORCH_LOGS。TORCH_SHOW_CPP_STACKTRACES：設定
TORCH_SHOW_CPP_STACKTRACES=1以可能看到更多的堆疊跟蹤。
