1. 训练循环里最容易踩的坑模式没切对指标全白费如果你写过 PyTorch 训练脚本大概率见过这几个调用model.train()、model.eval()、torch.no_grad()、detach()。它们看起来都是「一行代码」但作用的对象完全不同前两个改的是模型内部层的行为状态后两个管的是计算图和梯度记录。混着用轻则验证集指标忽高忽低重则显存爆掉、梯度算错训练半天不收敛。我见过最常见的翻车场景是这样的训练循环里忘了写model.eval()验证时 Dropout 还在随机丢神经元BatchNorm 还在用当前 batch 的统计量于是同一个模型跑两遍验证集得到两个不同的准确率你还以为是数据有问题。另一种是推理时没套torch.no_grad()明明只是前向计算却把整个计算图都建起来了显存占用翻倍batch 稍微大一点就 OOM。这篇就围绕这四个调用给你一套可以直接复制的训练/验证循环骨架再配上「打印 requires_grad 和 grad_fn」的验证动作让你亲眼确认梯度状态对不对。适合刚接触 PyTorch 的开发者也适合写了很久但一直靠感觉写循环的人。下面所有代码都可以直接跑不需要额外数据集用随机张量就能验证行为。2. 先把 TaoToken 配好让训练脚本能调到大模型做辅助写训练代码时经常需要让模型帮忙解释报错、生成数据增强脚本或者对比不同实现。这时候一个稳定的 API 入口能省不少事。TaoToken 提供统一的模型调用入口官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 注意 API 地址后面不加 UTM 参数。配置方式很简单把 API Key 写进环境变量避免硬编码进代码export TAOTOKEN_API_KEY你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/api然后在 Python 里读取import os api_key os.environ[TAOTOKEN_API_KEY] base_url os.environ[TAOTOKEN_BASE_URL] print(base_url)如果你还没拿到 Key可以去控制台创建https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 管理页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 遇到参数问题先翻文档比瞎试快。注意API Key 只放在环境变量或本地配置文件里不要提交到 Git 仓库。训练脚本里也不要打印完整 Key。配好之后你可以在训练脚本旁边写个小工具函数把报错信息丢给模型对话接口问原因模型对话入口是 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。这样调试训练循环时效率会高很多。3. 可复制配置训练循环与验证循环骨架3.1 四个调用的职责划分先把概念理清楚后面写代码才不会乱。model.train()把模型的training属性设为 True。它影响的是 Dropout 和 BatchNorm 这类「训练/推理行为不同」的层。Dropout 在训练时按概率丢弃神经元推理时全部保留BatchNorm 在训练时用当前 batch 的均值和方差并更新 running 统计量推理时用 running 统计量。model.eval()把training设为 False上面两类层切换到推理行为。它不涉及梯度也不释放显存。torch.no_grad()是上下文管理器进入后所有计算不构建计算图requires_grad即使为 True 的张量运算结果也不会带grad_fn。它省的是显存和计算常用于验证和推理。detach()是张量方法从计算图里「切」出一个新张量新张量requires_gradFalse和原张量共享数据。常用于把 loss 或中间结果拿出来做日志、算指标防止它们把梯度图拖住。一句话对照调用作用对象影响梯度影响层行为典型位置model.train()模型否是训练循环开头model.eval()模型否是验证/推理开头torch.no_grad()计算图是否验证/推理包裹detach()单个张量是否日志/指标计算3.2 训练循环骨架import torch import torch.nn as nn def train_one_epoch(model, loader, optimizer, criterion, device): model.train() # 关键切到训练模式 total_loss 0.0 for x, y in loader: x, y x.to(device), y.to(device) optimizer.zero_grad() logits model(x) loss criterion(logits, y) loss.backward() optimizer.step() total_loss loss.item() # item() 已脱离计算图 return total_loss / len(loader)这里loss.item()本身就返回 Python 标量不需要 detach。但如果你要累积一个 tensor 形式的 loss就必须 detachrunning torch.zeros(1, devicedevice) running loss.detach() # 不 detach 会把整个图累积起来3.3 验证循环骨架torch.no_grad() def evaluate(model, loader, criterion, device): model.eval() # 关键切到推理模式 total_loss 0.0 correct 0 total 0 for x, y in loader: x, y x.to(device), y.to(device) logits model(x) loss criterion(logits, y) total_loss loss.item() pred logits.argmax(dim1) correct (pred y).sum().item() total y.size(0) acc correct / total return total_loss / len(loader), acc注意torch.no_grad()装饰器和model.eval()是两件事都要写。前者管梯度后者管层行为。少任何一个都会出问题。3.4 detach 的正确使用位置验证时算指标如果不用no_grad至少要对参与累积的张量 detachwith torch.no_grad(): logits model(x) pred logits.argmax(dim1) correct (pred y).sum().item()如果忘了no_gradpred y的结果是 bool tensor.sum()会带 grad_fn.item()虽然能取值但中间图已经建好了显存白占。所以要么整体no_grad要么对每个要累积的量 detach。4. 验证请求打印 requires_grad 与 grad_fn 确认状态光看代码不够跑一遍打印出来才踏实。下面这段可以直接复制运行。import torch import torch.nn as nn class Net(nn.Module): def __init__(self): super().__init__() self.fc nn.Linear(4, 2) self.drop nn.Dropout(0.5) self.bn nn.BatchNorm1d(2) def forward(self, x): x self.fc(x) x self.bn(x) return self.drop(x) model Net() x torch.randn(8, 4) # 训练模式 model.train() out_train model(x) print(train mode, training , model.training) print(out_train.requires_grad , out_train.requires_grad) print(out_train.grad_fn , out_train.grad_fn) # 推理模式 no_grad model.eval() with torch.no_grad(): out_eval model(x) print(eval mode, training , model.training) print(out_eval.requires_grad , out_eval.requires_grad) print(out_eval.grad_fn , out_eval.grad_fn) # detach 验证 a torch.tensor([1.1], requires_gradTrue) b a.detach() print(a.requires_grad , a.requires_grad) print(b.requires_grad , b.requires_grad) print(b.grad_fn , b.grad_fn)预期输出train mode, training True out_train.requires_grad True out_train.grad_fn AddmmBackward0 ... eval mode, training False out_eval.requires_grad False out_eval.grad_fn None a.requires_grad True b.requires_grad False b.grad_fn None看到out_eval.grad_fn None就说明no_grad生效了。如果这里打印出非 None说明你的no_grad没包住前向或者模型里有地方偷偷建了图。再补一个 detach 的对比实验确认它只影响新张量x torch.randn(3, 2, requires_gradTrue) w torch.tensor([1.1, 2.2]) b torch.ones(3) z1 torch.matmul(x, w) b print(z1.requires_grad , z1.requires_grad) # True with torch.no_grad(): z2 torch.matmul(x, w) b print(z2.requires_grad , z2.requires_grad) # False z3 z1.detach() print(z3.requires_grad , z3.requires_grad) # False print(x.requires_grad , x.requires_grad) # True原张量不受影响5. 本篇常见错排查5.1 验证指标每次都不一样现象同一个模型、同一份验证集跑两次准确率差好几个点。原因验证循环里没写model.eval()Dropout 还在随机丢弃BatchNorm 还在用当前 batch 统计量。排查在验证循环开头打印model.training应该是 False。如果打印 True就是漏了model.eval()。5.2 显存越跑越大最后 OOM现象训练几个 epoch 后显存持续上涨。原因把带梯度的 tensor 累积进了列表或变量。比如total_loss loss而不是loss.item()或loss.detach()。排查检查所有累积操作凡是 tensor 相加的地方确认右边是否 detach 或用了 item()。5.3 报错 element 0 of tensors does not require grad现象调用loss.backward()时报这个错。原因loss 的requires_grad是 False。常见于验证阶段误调 backward或者模型参数被冻结后没解冻或者输入张量被 detach 过。排查打印loss.requires_grad确认是 True 再 backward。验证阶段本来就不该 backward。5.4 no_grad 里又开了 requires_grad现象明明套了torch.no_grad()结果张量还是有 grad_fn。原因在no_grad块里手动把某个张量的requires_grad设回 True或者调用了torch.enable_grad()。排查搜索代码里有没有requires_grad_(True)或enable_grad确认它们不在推理路径上。5.5 detach 后还想 backward现象对 detach 出来的张量调 backward报错或梯度为 None。原因detach 就是切断计算图切断了自然回不去。如果你需要保留梯度又要取值用.clone()而不是.detach()或者只在日志场景用 detach。排查确认 detach 的使用场景是「只读不反传」需要反传的路径不要 detach。5.6 BatchNorm 在 batch size 为 1 时训练报错现象Expected more than 1 value per channel when training。原因BatchNorm 在训练模式下需要 batch 内多个样本算方差batch size 为 1 时无法计算。排查要么调大 batch size要么在model.train()前对 BN 层单独设eval()要么改用 GroupNorm。这个和model.train()的切换直接相关别在推理时误开训练模式。6. 把模式切换写进模板长期编码更省心上面这套骨架建议直接固化成一个训练模板文件每次新项目复制过去改模型和数据集就行。模板里把model.train()、model.eval()、torch.no_grad()、detach()的位置都标好注释减少遗漏。如果你经常写训练脚本、Agent 工具链或者需要反复调试模型调用可以考虑用 Coding Plan 把常用代码片段和 API 调用统一管理入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。配合 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 管理密钥接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 查参数基本能覆盖日常开发。最后留一个我常用的自检习惯每个 epoch 结束后打印一次model.training和最近一个 batch 的loss.grad_fn确认训练模式是 True、梯度图正常验证结束后再打印一次确认是 False、grad_fn 为 None。两行 print能挡掉大部分模式切换的坑。