调试技巧：pdb、日志记录（logging）

一句话概述

调试是程序员的「听诊器」——pdb让你像医生一样逐行检查代码的脉搏，logging让你像黑匣子一样记录程序运行的每一步。两者配合，再诡异的bug也无处藏身。

💡 核心要点：①print调试简单但不可扩展，pdb是Python内置的交互式断点调试器 ②logging模块提供分级日志（DEBUG/INFO/WARNING/ERROR/CRITICAL），比print灵活百倍 ③AI项目中调试核心挑战是训练循环中的张量形状和梯度异常 ④好调试策略 = 好日志 + 关键断点 + 系统化排查思路

教学与演示

一、print调试的局限：从「够用」到「不够用」

是什么：print调试（也叫"printf debugging"）是最原始的调试方式——在代码中插入print语句输出变量值，观察程序运行状态。它是新手最直觉的调试方法，但在复杂项目中会迅速失控。

大白话：print调试就像在黑暗中用手电筒照路——照一小块还行，想看清全貌就得到处放灯泡，最后灯泡比路还多，反而更看不清了。

为什么：print调试的问题在于：(1) 无法暂停程序，只能看到print那一刻的值；(2) 每次想看新变量就要改代码重新运行；(3) 输出没有级别区分，信息淹没在print海洋中；(4) 上线前必须手动删除所有print，容易遗漏或误删有用代码。

大白话：print就像贴便利贴——贴一两张提醒自己没问题，贴满整面墙就变成垃圾堆了。更惨的是，上线前还得一张张撕掉，撕错了比不撕还麻烦。

怎么做：

import numpy as np

# ============================================
# print 调试的局限性演示
# 对比 print 调试 vs logging 的差异
# ============================================

print("=" * 55)
print("🔍 print调试 vs logging —— 同样是输出，差距在哪？")
print("=" * 55)

# --- 场景：模拟一个简单的矩阵运算过程 ---
# 用 numpy 创建模拟数据
np.random.seed(42)  # 固定随机种子，保证结果可复现
weights = np.random.randn(3, 4)  # 权重矩阵：3行4列
inputs = np.random.randn(4, 1)   # 输入向量：4行1列
bias = np.random.randn(3, 1)     # 偏置向量：3行1列

# --- 方式1：print调试（混乱） ---
print("\n❌ 方式1：print调试 —— 输出混乱，无法区分级别")
print("weights:", weights)          # 调试输出
print("inputs shape:", inputs.shape)  # 调试输出
print("result:", weights @ inputs + bias)  # 调试输出
print("训练完成")                     # 正常信息
print("loss是NaN!")                   # 错误信息
# 问题：所有输出混在一起，无法区分哪些是调试、哪些是正常、哪些是错误

# --- 方式2：logging（有序） ---
import logging  # 导入日志模块

# 创建一个简单的日志配置（仅用于演示对比）
logging.basicConfig(
    level=logging.DEBUG,  # 设置最低日志级别为DEBUG
    format='[%(levelname)s] %(message)s',  # 日志格式：[级别] 消息
    force=True,  # 强制重新配置（避免重复配置警告）
)

print("\n✅ 方式2：logging —— 输出有级别，一目了然")
logging.debug(f"weights shape: {weights.shape}")      # 调试信息
logging.debug(f"inputs shape: {inputs.shape}")        # 调试信息
logging.info("矩阵乘法计算完成")                        # 正常信息
result = weights @ inputs + bias                       # 计算结果
logging.warning("loss值偏高，请检查学习率")              # 警告信息
logging.error("检测到NaN值，训练可能发散！")             # 错误信息

# --- 对比总结 ---
print("\n📊 print vs logging 核心差异：")
comparison = np.array([
    ("级别控制", "❌ 无，全输出", "✅ DEBUG~CRITICAL五级"),
    ("输出目标", "❌ 只能终端", "✅ 文件/终端/网络/邮件"),
    ("格式控制", "❌ 手动拼接", "✅ 时间/级别/模块自动"),
    ("生产环境", "❌ 需手动删除", "✅ 改级别即可关闭"),
    ("性能影响", "❌ 字符串总被求值", "✅ 惰性求值，低级别跳过"),
], dtype=[("特性", "U12"), ("print", "U25"), ("logging", "U30")])

for feat, p, l in comparison:
    print(f"  {feat}: {p} vs {l}")

什么用：在AI项目中，训练一个模型可能需要几小时甚至几天。如果只用print调试，每次想看新信息都要改代码重新训练，浪费大量时间和GPU资源。logging让你一次配置，按需查看不同级别的信息，生产环境只需调整级别就能关闭调试输出。

哪些坑：(1) print的f-string中表达式总会被求值，即使不需要输出也有性能开销；(2) 忘记删除print导致线上日志泄露敏感信息（如用户数据）；(3) print输出到stdout，程序崩溃时缓冲区内容可能丢失。

二、pdb断点调试：像慢放电影一样看代码执行

是什么：pdb（Python Debugger）是Python标准库内置的交互式调试器，可以在代码任意位置设置断点，暂停程序执行，逐行运行代码，实时查看和修改变量值。

大白话：pdb就像视频播放器的慢放+暂停功能——正常运行的程序像快进的电影，你根本看不清细节。pdb让你按暂停、逐帧播放、放大查看每个变量，bug就藏在这些细节里。

为什么：当bug涉及复杂的数据流（如矩阵运算中间结果异常），print只能看到某个时刻的快照，而pdb可以让你在断点处自由探索所有变量的状态、调用栈、甚至动态修改变量来测试假设，效率远超print。

大白话：print是拍照片——只能看到按下快门那一刻的画面。pdb是录像+慢放——你可以暂停、倒回、放大、甚至改画面，想怎么看就怎么看。

怎么做：

import numpy as np

# ============================================
# pdb 断点调试模拟演示
# 由于 pdb 是交互式调试器，无法在代码块中直接使用
# 这里用 Python 模拟 pdb 的核心功能效果
# 实际使用：在代码中插入 breakpoint() 即可进入调试
# ============================================

print("=" * 55)
print("🐛 pdb 断点调试 —— Python内置调试器核心操作")
print("=" * 55)

# --- pdb 常用命令速查 ---
print("\n📋 pdb 核心命令速查表：")
pdb_commands = np.array([
    ("breakpoint()", "在代码中插入断点，程序运行到这里会暂停"),
    ("n (next)", "执行当前行，不进入函数内部"),
    ("s (step)", "执行当前行，如果是函数调用则进入函数内部"),
    ("c (continue)", "继续运行到下一个断点"),
    ("p 变量名", "打印变量的值（print）"),
    ("pp 变量名", "漂亮打印变量（pretty print，格式化输出）"),
    ("l (list)", "显示当前代码上下文"),
    ("w (where)", "显示调用栈（call stack）"),
    ("q (quit)", "退出调试器"),
    ("变量名 = 新值", "在调试中修改变量的值"),
], dtype=[("命令", "U18"), ("功能", "U45")])

for cmd, desc in pdb_commands:
    print(f"  {cmd:<18} → {desc}")

# --- 模拟：用 numpy 模拟断点调试过程 ---
print("\n🔬 模拟断点调试：追踪矩阵运算中的形状错误")
print("-" * 55)

# 步骤1：创建模拟数据
np.random.seed(42)  # 固定随机种子
W = np.random.randn(3, 4)   # 权重矩阵：(3,4)
x = np.random.randn(4, 1)   # 输入向量：(4,1)
b = np.random.randn(3, 1)   # 偏置向量：(3,1)

# 🔴 断点1：检查输入数据形状
print("\n🔴 [断点1] 检查输入数据 → p W.shape, p x.shape, p b.shape")
print(f"  W.shape = {W.shape}  ← (3,4) 权重矩阵")
print(f"  x.shape = {x.shape}  ← (4,1) 输入向量")
print(f"  b.shape = {b.shape}  ← (3,1) 偏置向量")
print("  ✅ 形状匹配：W(3,4) @ x(4,1) → (3,1)，与b(3,1)可加")

# 步骤2：执行矩阵乘法
z = W @ x + b  # 线性变换：z = Wx + b
# 🔴 断点2：检查中间结果
print(f"\n🔴 [断点2] 检查线性变换结果 → p z.shape, p z")
print(f"  z.shape = {z.shape}  ← (3,1) 结果向量")
print(f"  z = \n{z}")

# 步骤3：激活函数
a = 1.0 / (1.0 + np.exp(-z))  # sigmoid激活函数
# 🔴 断点3：检查激活后结果
print(f"\n🔴 [断点3] 检查激活后结果 → p a.shape, p a")
print(f"  a.shape = {a.shape}")
print(f"  a = \n{a}")
print(f"  a的范围: [{a.min():.4f}, {a.max():.4f}]  ← sigmoid应在(0,1)")

# 步骤4：模拟形状错误场景
print("\n⚠️  模拟常见形状错误：")
x_wrong = np.random.randn(5, 1)  # 错误的输入维度：(5,1)而非(4,1)
print(f"  x_wrong.shape = {x_wrong.shape}  ← 维度不匹配！")
try:
    z_wrong = W @ x_wrong  # 尝试矩阵乘法
except ValueError as e:
    print(f"  ❌ 报错: {e}")
    print("  💡 pdb中可以用 p W.shape 和 p x_wrong.shape 快速定位形状不匹配")

什么用：在AI项目中，pdb是调试训练循环的利器。当loss突然变成NaN、梯度爆炸、张量形状不匹配时，在训练循环中设置断点，逐行检查每一步的中间结果，比print高效百倍。特别是在调试复杂的前向传播逻辑时，pdb能让你看到每层网络的输入输出。

哪些坑：(1) pdb不能在Jupyter Notebook中直接使用（需要用%debug魔法命令）；(2) 忘记删除断点会导致程序在运行时意外暂停；(3) 多线程程序中pdb只能调试主线程；(4) pdb中修改的变量只在当前调试会话有效，退出后恢复原值。

三、logging模块：程序运行的「黑匣子」

是什么：logging是Python标准库中的日志记录模块，提供五个日志级别（DEBUG < INFO < WARNING < ERROR < CRITICAL），支持格式化输出、多种处理器（Handler）和灵活的配置方式，是专业Python项目的标配。

大白话：logging就像飞机上的黑匣子——平时默默记录一切，出了事翻出来就能找到原因。你可以控制记录的详细程度：平时只记重要信息（INFO），调试时记所有细节（DEBUG），出问题时只看错误（ERROR）。

为什么：logging相比print的优势是量级的：(1) 五级日志级别，一键切换输出详细程度；(2) Handler机制让同一日志同时输出到终端、文件、网络；(3) Formatter自动添加时间、模块名、级别等上下文；(4) 生产环境只需调整级别，无需删除任何代码。

大白话：print是喊一嗓子——所有人都能听到，但没法控制音量。logging是专业对讲机——可以调频道（级别）、选接收人（Handler）、加通话格式（Formatter），想怎么播就怎么播。

怎么做：

import numpy as np
import logging
import sys

# ============================================
# logging 模块完整演示
# 级别 / 格式 / 处理器 / 配置
# ============================================

print("=" * 55)
print("📝 logging —— Python标准日志模块完全指南")
print("=" * 55)

# --- 1. 五个日志级别 ---
print("\n🎯 日志五级体系（从低到高）：")
log_levels = np.array([
    (10, "DEBUG", "调试信息，最详细，只在开发时使用"),
    (20, "INFO", "正常运行信息，如'训练开始''epoch完成'"),
    (30, "WARNING", "警告信息，程序还能跑但可能有问题"),
    (40, "ERROR", "错误信息，某功能失败但程序没崩溃"),
    (50, "CRITICAL", "严重错误，程序可能无法继续运行"),
], dtype=[("数值", int), ("级别", "U10"), ("说明", "U40")])

for val, level, desc in log_levels:
    print(f"  {val:>2d} | {level:<10} | {desc}")

# --- 2. 实际配置和输出 ---
print("\n⚙️  实际配置演示：")
# 重新配置logging，展示格式化输出
logging.basicConfig(
    level=logging.DEBUG,  # 设置最低级别为DEBUG（所有级别都输出）
    format='%(asctime)s | %(levelname)-8s | %(name)s | %(message)s',  # 日志格式
    datefmt='%H:%M:%S',  # 时间格式
    force=True,  # 强制重新配置
)

logger = logging.getLogger("ai_trainer")  # 创建命名logger

# 模拟AI训练过程中的日志输出
np.random.seed(42)
logger.debug("初始化模型参数...")  # DEBUG级别：调试细节
weights = np.random.randn(128, 64) * 0.01  # Xavier初始化
logger.debug(f"权重矩阵形状: {weights.shape}, 标准差: {weights.std():.6f}")

logger.info("开始训练，共100个epoch")  # INFO级别：正常运行信息
for epoch in range(3):  # 只演示3个epoch
    loss = 1.0 / (epoch + 1) + np.random.randn() * 0.05  # 模拟loss下降
    logger.info(f"Epoch {epoch+1}/100 | Loss: {loss:.4f}")  # 训练进度

    if loss < 0:  # 模拟异常情况
        logger.warning(f"Loss为负值({loss:.4f})，可能存在梯度爆炸")  # WARNING

logger.error("验证集准确率下降，可能过拟合")  # ERROR级别：错误信息
logger.critical("GPU内存溢出(OOM)，训练终止！")  # CRITICAL级别：严重错误

# --- 3. Handler机制 ---
print("\n🔗 Handler机制：同一日志，多种输出目标")
print("  常用Handler：")
handlers = np.array([
    ("StreamHandler", "输出到终端(sys.stdout/sys.stderr)", "开发调试"),
    ("FileHandler", "输出到文件", "持久化日志"),
    ("RotatingFileHandler", "输出到文件，自动按大小轮转", "长期运行服务"),
    ("TimedRotatingFileHandler", "输出到文件，按时间轮转", "按天/小时归档"),
    ("SMTPHandler", "发送邮件", "严重错误告警"),
    ("SysLogHandler", "发送到系统日志", "服务器运维"),
], dtype=[("Handler", "U25"), ("功能", "U35"), ("场景", "U20")])

for h, func, scene in handlers:
    print(f"  {h:<25} | {func:<35} | {scene}")

什么用：在AI项目中，logging是训练过程的「飞行记录仪」。配置FileHandler将训练日志写入文件，训练结束后可以回溯分析loss曲线、学习率变化、梯度统计。配置RotatingFileHandler防止日志文件无限增长。在分布式训练中，不同节点的日志通过不同logger名称区分，便于定位问题节点。

哪些坑：(1) logging.basicConfig()只对第一次调用有效，之后调用需要force=True；(2) logger的层级继承会导致日志重复输出（子logger和父logger都输出）；(3) 日志格式中的f-string在低级别被过滤时仍然会被求值，应该用logger.debug("msg %s", var)的惰性格式化；(4) 多进程写同一日志文件会导致内容交错，需要用QueueHandler。

四、AI项目调试策略：训练循环、张量形状、梯度异常

是什么：AI项目的调试有独特挑战——训练循环可能运行数百万步，张量形状在多层网络中不断变化，梯度异常（消失/爆炸）难以定位。需要结合pdb和logging，建立系统化的调试策略。

大白话：调试普通程序像找钥匙——翻翻口袋就行。调试AI项目像大海捞针——loss不对、梯度异常、形状不匹配，问题可能藏在任何一层网络里，你得有策略地一层层排查。

为什么：AI项目的bug往往不是语法错误，而是数值错误——维度不匹配导致广播错误、梯度消失导致参数不更新、学习率过大导致loss爆炸。这些错误不会抛异常，只是让模型「安静地变蠢」，比直接崩溃更难发现。

大白话：普通bug像报警器——程序崩了你就知道出问题了。AI的bug像慢性病——程序还在跑，loss还在降，但模型就是学不好，你得主动去检查才能发现。

怎么做：

import numpy as np
import logging

# ============================================
# AI 项目调试策略实战演示
# 训练循环调试 / 张量形状追踪 / 梯度异常检测
# ============================================

# 配置日志
logging.basicConfig(
    level=logging.DEBUG,
    format='[%(levelname)s] %(message)s',
    force=True,
)
logger = logging.getLogger("ai_debug")

print("=" * 55)
print("🤖 AI项目调试三板斧：形状追踪 + 梯度检测 + 日志记录")
print("=" * 55)

# --- 策略1：张量形状追踪 ---
print("\n📐 策略1：张量形状追踪（最常见的AI bug来源）")
print("-" * 55)

np.random.seed(42)

# 模拟一个三层神经网络的前向传播
# 层1：输入4维 → 隐藏8维
W1 = np.random.randn(8, 4) * 0.5   # 权重：(8,4)
b1 = np.zeros((8, 1))               # 偏置：(8,1)
# 层2：隐藏8维 → 隐藏4维
W2 = np.random.randn(4, 8) * 0.5   # 权重：(4,8)
b2 = np.zeros((4, 1))               # 偏置：(4,1)
# 层3：隐藏4维 → 输出2维
W3 = np.random.randn(2, 4) * 0.5   # 权重：(2,4)
b3 = np.zeros((2, 1))               # 偏置：(2,1)

x = np.random.randn(4, 1)  # 输入：(4,1)

# 逐层前向传播，每层记录形状
logger.debug(f"输入 x: shape={x.shape}")
z1 = W1 @ x + b1  # 线性变换：(8,4)@(4,1)+(8,1) → (8,1)
a1 = np.maximum(0, z1)  # ReLU激活
logger.debug(f"层1输出 a1: shape={a1.shape}")

z2 = W2 @ a1 + b2  # 线性变换：(4,8)@(8,1)+(4,1) → (4,1)
a2 = np.maximum(0, z2)  # ReLU激活
logger.debug(f"层2输出 a2: shape={a2.shape}")

z3 = W3 @ a2 + b3  # 线性变换：(2,4)@(4,1)+(2,1) → (2,1)
output = 1.0 / (1.0 + np.exp(-z3))  # sigmoid输出
logger.debug(f"最终输出: shape={output.shape}, 值={output.flatten()}")

# --- 策略2：梯度异常检测 ---
print("\n📉 策略2：梯度异常检测（梯度消失/爆炸）")
print("-" * 55)

# 模拟不同深度的梯度传播
# 公式：梯度随层数指数变化
# ∂L/∂W_n ∝ ∏(i=n to L) W_i * σ'(z_i)
# 当 |W_i| > 1 时，梯度指数增长（爆炸）
# 当 |W_i| < 1 时，梯度指数衰减（消失）

num_layers = 10  # 模拟10层网络
initial_grad = 1.0  # 初始梯度为1

# 场景A：权重较小 → 梯度消失
grads_vanish = [initial_grad]  # 记录每层梯度
for i in range(num_layers):
    # 每层梯度乘以权重（假设权重约0.5）和激活导数（约0.25）
    next_grad = grads_vanish[-1] * 0.5 * 0.25  # 每层衰减到原来的12.5%
    grads_vanish.append(next_grad)

# 场景B：权重较大 → 梯度爆炸
grads_explode = [initial_grad]
for i in range(num_layers):
    # 每层梯度乘以权重（假设权重约2.0）和激活导数（约0.5）
    next_grad = grads_explode[-1] * 2.0 * 0.5  # 每层增长到原来的100%
    grads_explode.append(next_grad)

print("  层数 | 梯度(消失场景) | 梯度(爆炸场景)")
print("  " + "-" * 45)
for i in range(num_layers + 1):
    v = grads_vanish[i]  # 消失场景的梯度
    e = grads_explode[i]  # 爆炸场景的梯度
    # 用科学计数法显示
    print(f"  {i:>4d} | {v:>14.6e} | {e:>14.6e}")

# 梯度消失判断标准
vanish_threshold = 1e-7  # 梯度小于此值视为消失
explode_threshold = 1e3  # 梯度大于此值视为爆炸
print(f"\n  ⚠️  梯度消失阈值: < {vanish_threshold:.0e}")
print(f"  ⚠️  梯度爆炸阈值: > {explode_threshold:.0e}")
print(f"  消失场景第10层梯度: {grads_vanish[10]:.2e} → {'❌ 已消失!' if grads_vanish[10] < vanish_threshold else '✅ 正常'}")
print(f"  爆炸场景第10层梯度: {grads_explode[10]:.2e} → {'❌ 已爆炸!' if grads_explode[10] > explode_threshold else '✅ 正常'}")

什么用：在AI项目中，90%的bug来自三类问题：(1) 张量形状不匹配——通过在每层打印shape快速定位；(2) 梯度异常——通过监控梯度范数判断消失/爆炸；(3) 数据问题——通过logging记录数据统计信息（均值、标准差、范围）排查。建立系统化的调试策略，能将排查时间从数小时缩短到数分钟。

哪些坑：(1) 过度调试会严重拖慢训练速度，应该只在出问题时启用详细日志；(2) 梯度检测时要注意numpy和框架的梯度计算方式不同，numpy需要手动实现反向传播；(3) 形状追踪时注意batch维度，(4,)和(4,1)在numpy中行为完全不同；(4) 不要在训练循环中用pdb，每步都暂停会让你等到天荒地老，应该用条件断点。

import numpy as np
import logging

# ============================================
# AI项目调试最佳实践：综合示例
# 模拟一个完整的训练循环 + 调试策略
# ============================================

# 配置日志：同时输出到终端和记录关键信息
logging.basicConfig(
    level=logging.INFO,  # 正常运行时用INFO级别
    format='[%(asctime)s %(levelname)s] %(message)s',
    datefmt='%H:%M:%S',
    force=True,
)
logger = logging.getLogger("trainer")

print("=" * 55)
print("🏋️ AI训练循环调试最佳实践")
print("=" * 55)

# 模拟训练数据
np.random.seed(42)
num_samples = 100  # 样本数
input_dim = 4      # 输入维度
output_dim = 1     # 输出维度

# 生成模拟数据
X = np.random.randn(num_samples, input_dim)  # 输入：(100,4)
y = np.random.randn(num_samples, output_dim)  # 标签：(100,1)

# 初始化模型参数
W = np.random.randn(input_dim, output_dim) * 0.01  # 权重：(4,1)
b = np.zeros((output_dim,))  # 偏置：(1,)

# 训练超参数
learning_rate = 0.01  # 学习率
num_epochs = 5        # 训练轮数
batch_size = 16       # 批次大小

# 调试工具函数
def check_gradient(grad, name="梯度", threshold_explode=100.0, threshold_vanish=1e-7):
    """检查梯度是否异常（爆炸或消失）"""
    grad_norm = np.linalg.norm(grad)  # 计算梯度L2范数
    if grad_norm > threshold_explode:
        logger.error(f"🧨 {name}爆炸! 范数={grad_norm:.4e} > {threshold_explode}")
        return False  # 返回False表示异常
    elif grad_norm < threshold_vanish:
        logger.warning(f"🧊 {name}消失! 范数={grad_norm:.4e} < {threshold_vanish}")
        return False
    else:
        logger.debug(f"✅ {name}正常, 范数={grad_norm:.4e}")
        return True

def check_tensor_stats(tensor, name="张量"):
    """检查张量的统计信息，用于排查数据异常"""
    logger.debug(
        f"📊 {name}: shape={tensor.shape}, "
        f"mean={tensor.mean():.6f}, std={tensor.std():.6f}, "
        f"min={tensor.min():.6f}, max={tensor.max():.6f}"
    )

# 训练循环
logger.info(f"开始训练: epochs={num_epochs}, lr={learning_rate}, batch={batch_size}")
logger.info(f"数据: X{X.shape}, y{y.shape}, W{W.shape}, b{b.shape}")

for epoch in range(num_epochs):
    epoch_loss = 0.0  # 累计损失

    # 简单的批量梯度下降
    for start in range(0, num_samples, batch_size):
        end = min(start + batch_size, num_samples)  # 计算批次结束索引
        X_batch = X[start:end]  # 获取当前批次的输入
        y_batch = y[start:end]  # 获取当前批次的标签

        # 前向传播：计算预测值
        pred = X_batch @ W + b  # 线性预测：(batch,4)@(4,1)+(1,) → (batch,1)
        error = pred - y_batch   # 误差：(batch,1)
        loss = np.mean(error ** 2)  # MSE损失：标量

        # 反向传播：计算梯度
        grad_W = (2.0 / len(X_batch)) * (X_batch.T @ error)  # 权重梯度：(4,1)
        grad_b = (2.0 / len(X_batch)) * np.sum(error, axis=0)  # 偏置梯度：(1,)

        # 调试检查（只在第一个epoch检查，避免日志过多）
        if epoch == 0 and start == 0:
            check_tensor_stats(X_batch, "输入批次")
            check_tensor_stats(pred, "预测值")
            check_gradient(grad_W, "权重梯度")
            check_gradient(grad_b, "偏置梯度")

        # 参数更新
        W -= learning_rate * grad_W  # 梯度下降更新权重
        b -= learning_rate * grad_b  # 梯度下降更新偏置

        epoch_loss += loss * len(X_batch)  # 累计损失（加权平均）

    epoch_loss /= num_samples  # 计算平均损失
    logger.info(f"Epoch {epoch+1}/{num_epochs} | Loss: {epoch_loss:.6f}")

    # 检查loss是否异常
    if np.isnan(epoch_loss) or np.isinf(epoch_loss):
        logger.critical(f"Loss异常: {epoch_loss}，训练终止！")
        break  # 终止训练
    if epoch_loss > 1e6:
        logger.error(f"Loss过大: {epoch_loss:.2e}，可能学习率过大")

logger.info("训练完成！")
logger.info(f"最终参数: W范数={np.linalg.norm(W):.6f}, b={b}")

大白话：调试AI项目就像给病人做体检——你不能只看体温（loss），还得量血压（梯度）、拍X光（张量形状）、看血常规（数据统计），全面检查才能找到病因。

什么用：上述代码展示了AI项目调试的完整工作流：用logging记录训练进度和异常、用梯度检查函数自动检测消失/爆炸、用张量统计函数排查数据问题。这种「防御性编程」策略让bug在萌芽阶段就被发现，而不是训练完才发现模型不work。

哪些坑：(1) 调试代码本身也可能有bug——比如梯度检查函数计算错误导致误报；(2) 过度日志会拖慢训练速度，生产环境应该用INFO级别而非DEBUG；(3) 条件断点（如if loss > 1000: breakpoint()）比无条件断点更实用；(4) 不要忽略warning——很多严重问题都是从warning开始的。

概念关系图谱

重点答疑

Q1：什么时候用pdb，什么时候用logging？

简单规则：pdb用于「主动探索」，logging用于「被动记录」。当你不知道bug在哪、需要逐行检查时用pdb；当你想让程序自己记录运行状态、事后分析时用logging。实际项目中，logging是日常标配（始终开启），pdb是应急工具（出问题时才用）。最佳实践：先用logging定位问题大概在哪，再用pdb深入那个位置逐行检查。

Q2：logging的basicConfig为什么有时候不生效？

logging.basicConfig()只在root logger没有handler时才生效——如果你之前已经调用过（比如在Jupyter中多次运行单元格），后续调用会被忽略。解决方法：(1) 加force=True参数强制重新配置；(2) 手动创建Logger和Handler，不依赖basicConfig；(3) 在程序入口处只调用一次basicConfig。在Jupyter中建议始终加force=True。

Q3：AI训练中loss变成NaN怎么排查？

Loss变NaN的常见原因和排查步骤：(1) 学习率过大——尝试降低10倍，看loss是否还爆炸；(2) 梯度爆炸——在参数更新前检查梯度范数，加入梯度裁剪（np.clip(grad, -1, 1)）；(3) 数据中有NaN/Inf——检查输入数据的np.isnan()和np.isinf()；(4) 除零错误——检查loss计算中是否有除法，加小常数eps=1e-8防止除零；(5) log(0)——检查是否有对数运算，加eps=1e-8。建议在训练循环中加入NaN检测：if np.isnan(loss): breakpoint()。

Q4：多进程训练中logging怎么处理？

多进程写同一日志文件会导致内容交错和丢失。解决方案：(1) QueueHandler——主进程创建Queue和Listener，子进程通过Queue发送日志，Listener统一写入文件；(2) 每个进程写不同文件——用进程ID命名日志文件（如train_gpu0.log、train_gpu1.log）；(3) 集中式日志服务——用SocketHandler发送到ELK（Elasticsearch+Logstash+Kibana）等日志平台。最简单的是方案(2)，最专业的是方案(3)。

Q5：pdb在Jupyter Notebook中怎么用？

Jupyter中不能直接用pdb的交互模式，替代方案：(1) %debug魔法命令——单元格运行报错后，在新单元格输入%debug，自动进入调试模式，可以查看报错时的变量；(2) %pdb自动调试——在单元格开头运行%pdb on，之后任何报错都自动进入调试；(3) ipdb——安装pip install ipdb，用import ipdb; ipdb.set_trace()设置断点，界面比pdb更友好。推荐方案(1)，最简单实用。

章节单词汇总