Stonesjtu/pytorch_memlab

pytorch_memlab – 用於 PyTorch 的輕量級 CUDA 記憶體除錯工具箱

它是什麼 – 一個純 Python 套件，可讓你查看 PyTorch 程式碼中每一行消耗了多少 GPU 記憶體，列出裝置上佔用的張量，並可暫時將所有資料移至 CPU。它既支援命令列，也支援透過魔術指令在 Jupyter/IPython 中使用。

主要功能

• 逐行記憶體分析器 (LineProfiler / @profile 裝飾器) – 類似於 line_profiler，但會報告每行原始碼的 CUDA active_bytes 和 reserved_bytes。
• 記憶體報告器 (MemReporter) – 列出所有活躍的 torch.Tensor 物件，顯示底層 UntypedStorage 的大小，並可處理共享權重、梯度，以及詳細的儲存空間重用圖示。
• 禮讓模式 – 一個輔助類別，可按需求將所有 GPU 張量移回 CPU，有助於在不儲存檢查點的情況下釋放 GPU。
• IPython 集成 – %mlrun 和 %%mlrun 魔術指令可讓你僅用一條指令就對函數或整個筆記本單元進行分析。
• GPU 選擇 – set_target_gpu 允許你在執行時切換分析器監控的裝置。

安裝方法

# 從 PyPI 安裝穩定版
pip install pytorch_memlab

# 或從 GitHub 直接安裝最新程式碼
pip install git+https://github.com/stonesjtu/pytorch_memlab

(若需使用 IPython 魔術指令，請安裝可選依賴：pip install pytorch_memlab[ipython]。)

典型工作流程

1. 分析函數

   from pytorch_memlab import profile
   
   @profile
   def train_step(x):
       net = torch.nn.Linear(1024, 1024).cuda()
       return net(x).mean()
   

   腳本執行結束後，分析器會輸出一個表格，顯示每一行分配了多少 GPU 記憶體。
2. 檢查活躍張量

   from pytorch_memlab import MemReporter
   reporter = MemReporter(model)   # model 為可選參數
   reporter.report()               # 輸出簡潔表格
   reporter.report(verbose=True)  # 顯示儲存空間共享箭頭
   

3. 在筆記本中使用

   %load_ext pytorch_memlab
   %%mlrun -f train_step
   train_step(torch.randn(512, 1024).cuda())
   

4. 暫時釋放 GPU

   from pytorch_memlab import Courtesy
   c = Courtesy()
   c.yield_memory()   # 將張量移至 CPU
   # …等待訊號…
   c.restore()        # 將其移回
   

為何重要 – 在開發深度學習模型時，記憶體不足（OOM）崩潰是常見痛點。pytorch_memlab 使隱藏的 CUDA 分配行為可見，幫助你發現低效的張量生命週期、意外的儲存空間共用，或被遺忘的中間緩衝區。

限制 / 已知問題

• 分析器只能看到 Python 知道的張量；autograd 建立的底層 C 層緩衝區會被報告為「不可見」，但仍會佔用記憶體。
• 即使所有張量都在 CPU 上，PyTorch CUDA 上下文本身仍會保留約 1 GB 的 GPU 記憶體，目前無法由該套件釋放。
• 僅支援 CUDA 相容 GPU；不支援 AMD 或純 CPU 執行。

專案狀態 – 活躍維護中（最新版本 0.3.2，2026 年 6 月）。CI 執行測試並發布輪子包至 PyPI。README 包含使用範例、示範筆記本和變更日誌。

---

以上所有資訊均直接來自倉儲的 README，未添加任何外部主張。