Debian上如何进行PyTorch代码调试

Debian上调试PyTorch代码的实用流程

一 环境准备与快速定位

• 建议使用venv隔离依赖，确保 Python、PyTorch 与 CUDA/cuDNN 版本匹配：
  • 创建环境：python3 -m venv venv && source venv/bin/activate
  • 安装 PyTorch（示例）：pip install torch torchvision torchaudio
• 安装常用调试与性能工具：
  • sudo apt update && sudo apt install gdb valgrind linux-perf python3-pip
  • pip install ipdb torchsnooper viztracer
• 快速定位常见错误：
  • 使用 pdb/ipdb 设置断点：import ipdb; ipdb.set_trace()；常用命令：n/s/c/b/l/p。
  • 捕获异常与崩溃栈：import faulthandler; faulthandler.enable()。
  • 检查张量形状/设备：print(tensor.shape, tensor.device)；用 assert 验证不变量。
  • 定位梯度异常：短时开启 torch.autograd.set_detect_anomaly(True)（会带来性能开销）。

二 可视化与性能分析

• 指标与图可视化（TensorBoard）：
  • 记录损失、精度、图像、直方图等：
    • from torch.utils.tensorboard import SummaryWriter; writer = SummaryWriter('runs/exp1')
    • writer.add_scalar('Loss/train', loss.item(), global_step=epoch); writer.close()
  • 启动：tensorboard --logdir=runs
• 性能瓶颈定位（PyTorch Profiler + TensorBoard/Chrome tracing）：

  • 采集 CPU/GPU 时间线与调用栈：

    with torch.profiler.profile(
        schedule=torch.profiler.schedule(wait=1, warmup=1, active=3),
        on_trace_ready=lambda prof: prof.export_chrome_trace("trace.json"),
        record_shapes=True
    ) as prof:
        for step, (x, y) in enumerate(train_loader):
            ...
            loss.backward()
            optimizer.step()
            prof.step()  # 务必调用
    

  • 查看：Chrome 打开 chrome://tracing，或在 TensorBoard 的 Profile 页查看。

三 深入调试与离线分析

• 自动跟踪张量信息（TorchSnooper）：
  • pip install torchsnooper
  • 装饰函数：@torchsnooper.snoop()，自动打印每行代码的张量 shape、dtype、device、requires_grad，适合快速排查维度/设备不匹配。
• 低开销执行跟踪（VizTracer）：
  • pip install viztracer
  • 全局跟踪：viztracer my_script.py
  • 代码块跟踪：from viztracer import VizTracer; with VizTracer(log_torch=True) as tracer: train_one_epoch(...)
• 单元测试与回归：为核心模块编写 unittest/pytest 用例，持续集成中快速回归定位问题。

四 外部调试器与系统级工具

• C/C++/CUDA 层问题（gdb 附加到 Python 进程）：
  • 获取进程号：pgrep -f python
  • 附加：gdb -p $(pgrep -f python)，在 gdb 中执行 bt 查看原生栈；通常需要带调试符号的 PyTorch 或从源码构建以获得可读回溯。
• CPU 性能分析（perf）：
  • sudo perf record -g python train.py
  • sudo perf report
• GPU 性能分析：
  • 推荐使用 Nsight Systems 采集 GPU 时间线与 API 调用，分析 kernel 耗时与数据传输；旧版 nvprof 已不推荐。
• 内存与越界检查：
  • valgrind（Python 开销较大，谨慎用于大模型）。
  • cuda-memcheck 检查 GPU 非法访问与内存问题。
• 系统调用/库调用跟踪：
  • 使用 strace/ltrace 观察程序与系统/库的互动，辅助定位环境或依赖相关问题。

五 常见问题速查与排查清单

• 张量形状/设备不匹配：在关键位置打印 tensor.shape/device；用 TorchSnooper 自动跟踪；用 assert 验证维度。
• 梯度异常（NaN/Inf）：短时开启 torch.autograd.set_detect_anomaly(True)；检查损失、学习率与数值稳定性（如 clamp/log-sum-exp）。
• 崩溃无回溯：启用 faulthandler；若疑似段错误，用 gdb 获取原生栈；怀疑算子问题时用 cuda-memcheck 排查。
• 性能瓶颈：用 PyTorch Profiler + TensorBoard 定位耗时算子与数据加载瓶颈；必要时用 perf/Nsight Systems 深入分析。
• 环境与依赖：优先 venv/conda 隔离；确认 NVIDIA 驱动、CUDA 正常；确保 Python、PyTorch 与 CUDA/cuDNN 版本匹配。