tlparse / TORCH_TRACE

建立時間: 2025年7月29日 | 最後更新時間: 2025年7月29日

tlparse / TORCH_TRACE 是一對工具，它們會生成看起來 像這樣 的編譯報告。

收集 trace 相當直接。要收集 trace，像這樣執行你的模型：

TORCH_TRACE="/tmp/tracedir" python foo.py
pip install tlparse
tlparse /tmp/tracedir

即使你在執行分散式作業，這種方法也同樣適用，為每個 rank 提供一個 trace。它會開啟你的瀏覽器，顯示與上面生成的 HTML 類似的 HTML。如果你在為某個複雜的、你無法獨立復現的問題提交 bug 報告，透過附加在 /tmp/tracedir 中生成的 trace 日誌，你仍然可以極大地幫助 PyTorch 開發者。

警告

trace 日誌包含你所有的模型程式碼。如果模型是敏感的，請不要共享 trace 日誌。trace 日誌不包含權重。

tlparse 的輸出主要面向 PyTorch 開發者，並且日誌格式易於上傳和在 GitHub 上共享。然而，即使你不是 PyTorch 開發者，你仍然可以從中提取有用的資訊。我們建議從報告中的內聯幫助文字開始，它解釋了其內容。以下是你從 tlparse 中可以獲得的一些見解：

• 透過檢視堆疊樹，瞭解了哪些模型程式碼被編譯了？如果你不熟悉被編譯的程式碼庫，這一點尤其有用！

• 有多少個圖中斷/獨立的編譯區域？（每個獨立的編譯區域都是一個著色的塊，例如 [0/0]）。潛在圖中斷的幀是淺綠色 [2/4]。如果有很多幀，這可能令人懷疑，並表明你的程式碼與 torch.compile 不太匹配。

• 我重新編譯了一個特定幀多少次？重新編譯了很多次的幀會看起來像：[10/0] [10/1] [10/2] - 如果某個東西被重新編譯了很多次，這非常可疑，值得深入研究，即使它不是你問題的根源。

• 是否存在編譯錯誤？發生錯誤的幀會看起來像 [0/1]。

• 我為給定幀生成了哪些中間編譯器產品？例如，你可以檢視生成的頂級 FX 圖或生成的 Triton 程式碼。

• 特定幀是否有相關資訊？你可以在 compilation_metrics 中找到它們。

TORCH_LOGS

你可以使用 TORCH_LOGS 環境變數選擇性地啟用 torch.compile 堆疊的某些部分進行日誌記錄。 TORCH_LOGS 實際上是 tlparse 日誌的來源。 TORCH_LOGS 環境變數的格式如下：

TORCH_LOGS="<option1>,<option2>,..." python foo.py

你也可以透過程式設計方式使用 torch._logging.set_logs 設定日誌選項。

import logging
torch._logging.set_logs(graph_breaks=True, dynamic=logging.DEBUG)

最有用的選項是：

• graph_breaks：記錄使用者程式碼中圖中斷的位置以及圖中斷的原因。

• guards：記錄生成的 guard。

• recompiles：記錄哪個函式被重新編譯以及導致重新編譯的失敗 guard。

• dynamic：記錄與動態形狀相關的日誌。

• output_code：記錄 Inductor 生成的程式碼。

一些更有用的 TORCH_LOGS 選項包括：

選項	描述
+all	輸出所有 torch.compile 元件的除錯日誌。
+dynamo	輸出 TorchDynamo 的除錯日誌。
+aot	輸出 AOTAutograd 的除錯日誌。
+inductor	輸出 TorchInductor 的除錯日誌。
dynamic	輸出動態形狀相關的日誌。
graph_code	輸出 Dynamo 生成的 FX 圖的 Python 程式碼。
graph_sizes	輸出 Dynamo 生成的 FX 圖的張量大小。
trace_bytecode	輸出 Dynamo 正在追蹤的位元組碼指令以及 Dynamo 正在跟蹤的符號直譯器堆疊。
trace_source	輸出 Dynamo 當前正在追蹤的原始原始檔的程式碼行。
bytecode	輸出 Dynamo 生成的位元組碼。
guards	輸出生成的 guard。
recompiles	輸出重新編譯的原因（僅第一個失敗的 guard 檢查）。
recompiles_verbose	輸出重新編譯發生時所有失敗的 guard 檢查。
aot_graphs	輸出 AOTAutograd 生成的圖。
aot_joint_graphs	輸出 AOTAutograd 生成的聯合前向-後向圖。
output_code	輸出 Inductor 生成的程式碼。
kernel_code	輸出 Inductor 按每個 kernel 生成的程式碼。
schedule	輸出 Inductor 排程日誌。
perf_hints	輸出 Inductor perf hint 日誌。
fusion	輸出 Inductor fusion 日誌。

有關選項的完整列表，請參閱 torch._logging 和 torch._logging.set_logs。

tlparse 與 TORCH_LOGS 的區別

一般來說，我們建議在遇到問題時首先使用 tlparse。 tlparse 非常適合除錯大型模型和獲得模型如何被編譯的總體概述。另一方面，對於小型示例和需要精細除錯細節的情況，當我們已經知道是哪個 torch.compile 元件導致問題時，TORCH_LOGS 是更好的選擇。