调试与性能分析:抓住那些静默失败的 AI Bug

调试与性能分析:抓住那些静默失败的 AI Bug

本节摘要:最糟的 AI Bug 不崩溃——它们在垃圾数据上静默训练,然后给你一条漂亮的 loss 曲线。AI 代码的失败方式与普通代码不同:Web 应用崩溃会抛堆栈;一个配错的训练循环会跑 8 小时、烧掉 200 美元 GPU 费用,产出一个「对每个输入都预测均值」的模型——全程没报错,Bug 可能是一个放错设备的张量、一个漏掉的 .detach(),或标签泄漏进了特征。本节为你补齐抓住这些静默失败的工具链:用条件 breakpoint() 与 debug_print 在训练中途检查张量形状、dtype、NaN;用 cProfile、line_profiler、tracemalloc 找瓶颈;检测四大常见 AI Bug(形状不匹配、NaN loss、数据泄漏、错设备张量);用 TensorBoard 可视化 loss 曲线、权重直方图、梯度分布。读完本节,你能在大规模训练里迅速定位「为什么模型不学」与「为什么训练这么慢」。

对应原课程:Phase 00 · Lesson 12 · debugging-and-profiling(原英文 phases/00-setup-and-tooling/12-debugging-and-profiling/docs/en.md)。前置:第 01 节「开发环境」、基础 PyTorch 熟悉度。本章收官节。

学习目标

阅读完本节,你应当能够:

1. 用条件 breakpoint() 与 debug_print 在训练中途检查张量的形状、dtype、NaN 值。
2. 用 cProfile、line_profiler、tracemalloc 剖析训练循环,找出瓶颈。
3. 检测四大常见 AI Bug:形状不匹配、NaN loss、数据泄漏、错设备张量。
4. 配置 TensorBoard 可视化 loss 曲线、权重直方图、梯度分布。

一、问题与直觉

AI 代码的失败方式与普通代码不同。Web 应用崩溃会抛堆栈;一个配错的训练循环会跑 8 小时、烧掉 200 美元 GPU 时间,产出一个「对每个输入都预测均值」的模型。代码全程没报错。Bug 可能是放错设备的张量、漏掉的 .detach(),或标签泄漏进了特征。

你需要能在这些静默失败浪费你的时间与算力之前就抓住它们的调试工具。

AI 调试的三个层次

大多数人直奔第 3 层(盯着 TensorBoard)。但 80% 的 AI Bug 藏在第 1、2 层。

💡 心法:先查张量(形状/dtype/设备/NaN),再看训练动态(loss/梯度)。顺序反了,你会在漂亮的曲线里找根本不存在的「玄学问题」,而真正的 Bug 是某个张量在 CPU 上、其他都在 GPU 上。

二、从零实现

下面九个部分覆盖 AI 调试与剖析的全套工具链。完整脚本见原课程 phases/00-setup-and-tooling/12-debugging-and-profiling/code/debug_tools.py,本节给出关键骨架。

Part 1 打印调试(真的有用)

打印调试常被看轻,不该。对张量代码,一句精准的 print 比单步调试更强——因为你要同时看形状、dtype、值域:

def debug_print(name, tensor):
    print(f"{name}: shape={tensor.shape}, dtype={tensor.dtype}, "
          f"device={tensor.device}, "
          f"min={tensor.min().item():.4f}, max={tensor.max().item():.4f}, "
          f"mean={tensor.mean().item():.4f}, "
          f"has_nan={tensor.isnan().any().item()}")
​

在每个可疑操作后调一次。Bug 找到后删掉 print。就这么简单。

Part 2 Python 调试器(pdb 与 breakpoint)

内置调试器在 AI 工作里被低估。把 breakpoint() 丢进训练循环,交互式检查张量:

def training_step(model, batch, criterion, optimizer):
    inputs, labels = batch
    outputs = model(inputs)
    loss = criterion(outputs, labels)
    if loss.item() > 100 or torch.isnan(loss):    # 条件断点:只在异常时停
        breakpoint()
    loss.backward()
    optimizer.step()
​

进调试器后的常用命令:p outputs.shape(查形状)、p loss.item()(看 loss 值)、p torch.isnan(outputs).sum()(数 NaN)、p model.fc1.weight.grad(查梯度)、c(继续)、q(退出)。

设计要点:这是条件调试——只在不对劲时才停。对一万步的训练,这至关重要,否则你会在每一步都停下,根本跑不动。

Part 3 Python 日志

调试超出快速检查范围时,用日志替换 print:

import logging
logging.basicConfig(level=logging.INFO,
    format="%(asctime)s [%(levelname)s] %(message)s",
    handlers=[logging.FileHandler("training.log"), logging.StreamHandler()])
logger = logging.getLogger(__name__)
logger.info("Starting training: lr=%.4f, batch_size=%d", lr, batch_size)
logger.warning("Loss spike detected: %.4f at step %d", loss.item(), step)
logger.error("NaN loss at step %d, stopping", step)
​

日志给你时间戳、严重级别、文件输出。凌晨 3 点训练崩了,你要的是日志文件,不是滚屏消失的终端输出。

Part 4 计时各段代码

知道时间花在哪,是优化的第一步:

class Timer:
    def __enter__(self):  self.start = time.perf_counter(); return self
    def __exit__(self, *a): print(f"[{self.name}] {time.perf_counter()-self.start:.4f}s")

with Timer("data loading"):  batch = next(dataloader_iter)
with Timer("forward pass"):  outputs = model(batch)
with Timer("backward pass"): loss.backward()
​

常见发现:数据加载占了训练时间的 60%。修法是给 DataLoader 设 num_workers > 0,而不是换更快的 GPU。

Part 5 cProfile 与 line_profiler

手动计时不够时:

python -m cProfile -s cumtime train.py     # 按累计时间排序看每个函数
​

逐行剖析用 line_profiler(@profile 装饰目标函数,kernprof -l -v train.py 运行),它会告诉你函数里每一行各花多少时间。

Part 6 内存剖析

CPU 内存(tracemalloc):

import tracemalloc
tracemalloc.start()
# 你的代码
snapshot = tracemalloc.take_snapshot()
for stat in snapshot.statistics("lineno")[:10]:  print(stat)
​

GPU 内存(PyTorch):

print(torch.cuda.memory_summary())
print(f"Allocated: {torch.cuda.memory_allocated()/1e9:.2f} GB")
print(f"Cached: {torch.cuda.memory_reserved()/1e9:.2f} GB")
​

遇到 OOM(显存溢出)的五步救急:

1. 减 batch size(永远先试这个)。
2. torch.cuda.empty_cache() 释放缓存。
3. del tensor 加 torch.cuda.empty_cache() 清大中间量。
4. 用混合精度(torch.cuda.amp)把显存砍半。
5. 用梯度检查点(gradient checkpointing)应对超深模型。

Part 7 四大常见 AI Bug 与检测法

形状不匹配(最高频):张量是 [batch, features],模型却要 [batch, channels, height, width]。用 register_forward_hook 给每层注册钩子,跑一个样本,打印每层输入输出形状——一次映射出模型里所有形状变换。

NaN loss(意味着炸了):常见原因是学习率太高、自定义 loss 里除零、对零或负数取 log、RNN 梯度爆炸。写个 detect_nan 函数,loss 是 NaN 时遍历所有参数,找出哪个参数的梯度是 NaN 或 Inf。

数据泄漏:测试集准确率 99%,听着好,其实是 Bug。写 check_data_leakage 检查训练集与测试集的 id 是否重叠。还要查时间泄漏——用未来数据预测过去;按时间戳排序后再划分。

错设备:不同设备的张量(CPU vs GPU)会报运行时错。但有时一个张量静默留在 CPU,其他都在 GPU,训练就只是「莫名地慢」。写 check_devices 对比模型与每个输入张量的设备。

⚠️ 设计警示:静默错设备是最阴险的 Bug——不报错,只是每步都做一次隐式 CPU↔GPU 搬运,训练慢几倍,你还以为是模型或数据的问题。养成在训练开头跑一遍 check_devices 的习惯。

Part 8 TensorBoard 基础

TensorBoard 让你看到训练内部随时间的演化:

from torch.utils.tensorboard import SummaryWriter
writer = SummaryWriter("runs/experiment_1")
for step in range(num_steps):
    loss = train_step(model, batch)
    writer.add_scalar("loss/train", loss.item(), step)
    writer.add_scalar("lr", optimizer.param_groups[0]["lr"], step)
    if step % 100 == 0:
        for name, param in model.named_parameters():
            writer.add_histogram(f"weights/{name}", param, step)
            if param.grad is not None:
                writer.add_histogram(f"grads/{name}", param.grad, step)
writer.close()
​

tensorboard --logdir=runs        # 启动后在浏览器打开
​

要会看的信号:

• Loss 不降:学习率太低,或模型架构问题。
• Loss 剧烈震荡:学习率太高。
• Loss 变 NaN:数值不稳定(见上面的 NaN 节)。
• 训练 loss 降、验证 loss 升:过拟合。
• 权重直方图塌成零:梯度消失。
• 梯度直方图爆炸:需要梯度裁剪。

Part 9 VS Code 调试器

交互式调试,配 VS Code 的 launch.json(见第 08 节编辑器配置),在行首 gutter 点一下设断点,用 Variables 面板检查张量属性,Debug Console 里在执行中跑任意 Python 表达式。特别适合逐步走数据预处理流水线,让你看清每次变换的结果。

三、框架对比:三套调试剖析工具的取舍

💡 组合拳:训练前跑 check_shapes + check_devices;前 10 步用 debug_print 确认无 NaN;训练中用 logging + TensorBoard;崩了就 breakpoint() 交互查;慢了就 cProfile 找瓶颈、tracemalloc 找内存大头。这套流程能抓住 90% 的 AI Bug。

四、可复用产物

本节产出两个可复用件(原课程 code/ 与 outputs/):

• debug_tools.py:一整套调试与剖析工具脚本——debug_print、check_shapes、detect_nan、check_data_leakage、check_devices、Timer、内存剖析封装。任何 PyTorch 项目 import 即用。
• prompt-debug-ai-code.md:一个提示词,把你遇到的 AI Bug 现象(loss 不降、NaN、过拟合、慢)贴进去,让 AI 助手给出诊断思路与排查命令,覆盖本节四大 Bug 类型。

五、练习

1. (Easy) 跑 debug_tools.py,读每个部分的输出;再故意在前向传播里引入一个 NaN(提示:除零),看 detect_nan 能不能抓住它,并定位到哪个参数梯度是 NaN。
2. (Medium) 用 cProfile 剖析一个训练循环,找出最慢的函数;再用 tracemalloc 找出数据加载流水线里哪一行分配内存最多。
3. (Hard) 给一个简单训练任务接上 TensorBoard,记录 loss、学习率、权重直方图、梯度直方图;故意把学习率调高 10 倍,观察 loss 震荡与梯度爆炸;再故意制造过拟合(训练集极小),观察训练 loss 降而验证 loss 升;最后在训练循环里用 breakpoint() 在 loss 异常时停下,练习从调试器查张量形状、设备、梯度值。

本节要点回顾

1. 最糟的 AI Bug 不崩溃:静默在垃圾数据上训练,给你漂亮 loss 曲线——错设备、漏 .detach()、标签泄漏都是元凶。
2. 三层调试:普通 Python(断点/日志/剖析)→ 张量运算(形状/dtype/设备/NaN)→ 训练动态(loss/梯度);80% 的 Bug 在前两层。
3. 打印调试不该轻视:对张量代码,一句精准 print 同时看形状/dtype/值域,胜过单步。
4. 条件 breakpoint():只在异常时停,对万步训练至关重要。
5. 日志替 print:给时间戳、级别、文件输出,凌晨崩溃时是救命的。
6. 数据加载常占 60% 时间:修法是 num_workers > 0,不是更快的 GPU。
7. OOM 五步救急:减 batch → empty_cache → del + empty_cache → 混合精度 → 梯度检查点。
8. 四大 Bug:形状不匹配(hook 映射)、NaN loss(遍历梯度)、数据泄漏(id 重叠 + 时间排序)、错设备(check_devices)。
9. 静默错设备最阴险:不报错只慢几倍,训练开头必跑 check_devices。
10. TensorBoard 看信号:loss 不降/震荡/NaN、过拟合、梯度消失/爆炸,各有对应诊断。
11. 组合拳:训练前查形状+设备,前 10 步查 NaN,训练中 logging+TensorBoard,崩了 breakpoint,慢了 cProfile+tracemalloc。

至此,第 1 章「开发环境与工具链」全部 12 节完成。从开发环境、Git、GPU、API、Notebook、Python 环境、Docker、编辑器、数据、终端、Linux 到调试剖析,你已经搭好了一整套可复现、可协作、可扩展的 AI 工程地基。下一章我们将进入「数学基础」,开始从零吃透 AI 背后的数学原理。