说真的，深度学习做到第9篇，大部分人的“分水岭”就出现在这一步：模型到底是怎么被PyTorch创建、管理，又真正跑起来的。前面用现成网络训练还好，一旦要自己改结构、加层、写自定义模块，就绕不开nn.Module这个根基。这篇文章专门拆开“Pytorch模型创建与nn.Module”这个主题，把参数注册、forward执行、子模块管理、常见报错挨个讲透，适合那些已经把Tensor操作练熟、开始尝试搭自己模型的读者，也适合用了一堆现成模型却总觉得“内部像黑盒”的人。看完你会明白，模型不是一个随意的函数，而是一棵有组织、可迁移、可保存的参数树。
1. 先从“为什么要有nn.Module”讲起
1.1 手写参数管理的痛苦
我早期用PyTorch的时候，也试过不定义class，直接声明一堆张量当参数：
w1 = torch.randn(784, 128, requires_grad=True) b1 = torch.zeros(128, requires_grad=True) w2 = torch.randn(128, 10, requires_grad=True) b2 = torch.zeros(10, requires_grad=True)然后手动在循环里算矩阵乘，手动保存中间变量，手动调backward。小模型还能忍，一旦超过三层，问题就全冒出来了。
- 参数一多，变量名一团乱麻：w1、b1、w2、b2还好说，真要堆到十几个变量，自己都不想看第二遍。
- 优化器要手动列出一长串参数传给optimizer，漏一个就是“某个权重永远不更新”。
- 保存和加载模型时，必须自己维护参数字典，稍不留神key就对不上。
- 想固定某几层不训练，又得手动过滤参数列表。
nn.Module把这堆琐事全部接管了。你在__init__里写好结构，框架自动收集参数、自动记录子模块、自动forward、自动求梯度。为什么我劝新人第一课就好好理解Module？因为它不是“可选的语法糖”，而是整个PyTorch模型体系的骨架。
一个特别有说服力的细节是：optimizer.parameters()能直接拿到模型全部参数，靠的就是Module内部的参数收集机制。如果你自己维护张量，这一步就得从头写起，而且大概率会漏掉某一层。
1.2 nn.Module解决的核心问题
具体说，nn.Module解决的问题可以归纳成四件事：
- 参数收集：把Parameters、buffers、子模块统一成一棵“树”管理，遍历、统计、转移设备都方便。
- 前向传播约定：统一
forward接口，不管最终网络多复杂，一次调用就是一个数据流。 - 状态管理：training/eval模式的切换（BatchNorm、Dropout的行为差异）、hook机制，都是Module层面的能力。
- 序列化：
torch.save(model.state_dict())能恢复所有参数，不需要自己手工维护参数字典。
顺便解释一个新手常有的困惑：很多人觉得“继承nn.Module”就是形式主义，反正forward是我自己写的，class和普通函数有什么区别？区别在于子模块递归、设备迁移、hook机制。你写model.to('cuda')，框架会递归调用所有子模块的to方法，把里面的Parameter一一搬到显存。普通函数完全没有这个能力。这就好比你把所有家具的数据都登记在一张总表上，搬家时一张表搞定；而不是每次都打开每个房间挨个找。
2. nn.Module的核心机制拆解
2.1 __init__和forward的分工
先形成一个最基础的认知：__init__负责“搭骨架”，也就是定义层和参数；forward负责“跑数据”，描述数据在骨架里怎么流动。
这里我见过不少反模式，比如把计算塞进__init__里，或者把参数定义直接写在forward里。前者的后果是模型初始化顺序变得很怪，可能导致子模块还没构建好就开始前向；后者会导致参数每次forward重新创建，计算图乱掉，而且优化器里可能收不到这些参数。
打个比方：__init__相当于施工队确认图纸、准备建材，forward才是实际浇筑。你没有理由在准备阶段就把混凝土浇了，也没有理由浇筑时才临时定图纸。
具体实践上，我建议所有可学习参数的模块都在__init__里注册好，forward里只写数据流；如果某个中间计算只是临时常量、不需要参与梯度，直接在forward里用本地张量计算就可以。
import torch import torch.nn as nn class MyMLP(nn.Module): def __init__(self): super().__init__() self.fc1 = nn.Linear(784, 128) self.relu = nn.ReLU() self.fc2 = nn.Linear(128, 10) def forward(self, x): x = self.fc1(x) x = self.relu(x) x = self.fc2(x) return x这里nn.ReLU()虽然没有参数，也建议放进__init__。这样结构信息更清晰，forward只表达流程，而且后续要挂hook也能挂在明显的位置。
2.2 Parameter、buffer与子模块注册
nn.Module能把参数管好，靠三张“账本”：
_parameters：存Parameter。_buffers：存buffer，也就是不参与梯度更新、但需要被模型状态记录的张量。_modules：存子模块。
你对模块做的赋值操作，只要值符合类型（Parameter、Module等），都会自动进对应账本。但有一个最常见的坑：自定义张量当参数，却没有包成Parameter。比如：
self.my_weight = torch.randn(10, 10)这样my_weight不会进入_parameters，model.parameters()里没有它，优化器自然也不会更新它。正确写法是：
self.my_weight = nn.Parameter(torch.randn(10, 10))或者用更显式的注册方式：
self.register_parameter('my_weight', nn.Parameter(torch.randn(10, 10)))另一种常见需求是buffer，典型例子就是BatchNorm里的running_mean和running_var。为什么不能用普通属性？因为普通属性不会进入_buffers，执行model.to('cuda')时它不会跟着迁移，也不会被state_dict保存。所以需要这样写：
self.register_buffer('running_mean', torch.zeros(10))2.3 动态图与hook机制
forward在每次执行时，PyTorch会用Autograd引擎记录张量的计算图，然后backward时沿反方向计算梯度。这就是“动态图”的含义：图是每次运行按实际代码路径现场构建的。这也意味着你可以用Python的if、for、while来调整网络结构，同一个模型在处理不同输入时可能有不同分支。
nn.Module还给这种灵活性加了一层“旁路”：hook。你可以在不修改forward源码的情况下，在某个层前后插入调试逻辑。比如我用得比较多的是打印每一层输出的均值和方差，用来排查梯度爆炸或梯度消失：
def hook_fn(module, input, output): print(module.__class__.__name__, output.shape, output.mean().item(), output.std().item()) model.fc1.register_forward_hook(hook_fn)这个功能在复现论文、调试网络时非常有用。但注意不要把所有层都挂上hook，打印量会大到终端直接卡死，我踩过这个坑，一次调试挂了十几个hook，跑一个batch屏幕刷了几万行。
3. 实操：从零搭一个图像分类网络
3.1 准备环节：确定任务和输入输出
拿最经典的MNIST手写数字分类举例。输入是28×28灰度图，展平后是784维向量；输出是10个类别的logits。层数不必太深，用一个三层MLP足够说明问题。
选MLP而不是CNN当入门例子，是因为MLP把矩阵运算、激活、参数管理这些最核心机制都摆在明面上，不会被卷积的局部感受野和通道数概念分散注意力。等你把MLP吃透了，再切到CNN、Transformer，会发现核心的组织逻辑是一模一样的。
3.2 一个完整自定义MLP的拆解
我按“逐层声明、forward串接”的方式实现：
class MnistMLP(nn.Module): def __init__(self): super().__init__() self.fc1 = nn.Linear(784, 256) self.bn1 = nn.BatchNorm1d(256) self.act1 = nn.ReLU() self.drop1 = nn.Dropout(0.2) self.fc2 = nn.Linear(256, 128) self.bn2 = nn.BatchNorm1d(128) self.act2 = nn.ReLU() self.drop2 = nn.Dropout(0.2) self.fc3 = nn.Linear(128, 10) def forward(self, x): x = x.view(x.size(0), -1) # 展平 x = self.fc1(x) x = self.bn1(x) x = self.act1(x) x = self.drop1(x) x = self.fc2(x) x = self.bn2(x) x = self.act2(x) x = self.drop2(x) x = self.fc3(x) return x这里有三个细节要留意。
x.view(x.size(0), -1)这一行没有封装成独立Module。逻辑上它做的是“展平”，但没有可学习参数、没有状态，在forward里直接写完全没问题。如果你追求结构统一，也可以用nn.Flatten()放进__init__。- BatchNorm和Dropout是典型的状态相关层，训练和推理行为完全不同。模型默认是training模式；用
model.eval()切到推理模式后，Dropout被关闭，BN改用running统计量。新手最常犯的错就是推理时忘了eval()，或者训练时误调了eval()，导致结果忽高忽低。 - forward需要返回Tensor。后面如果做多任务，可以返回tuple，比如同时返回分类结果和中间特征。但不要返回Python list这类不适合自动求导的结构，除非你明确知道自己在做什么。
3.3 Sequential、ModuleList和ModuleDict怎么选
当网络结构就是纯粹的“串一条线”时，可以用nn.Sequential简化代码：
self.features = nn.Sequential( nn.Linear(784, 256), nn.BatchNorm1d(256), nn.ReLU(), nn.Dropout(0.2), nn.Linear(256, 128), nn.BatchNorm1d(128), nn.ReLU(), nn.Dropout(0.2), nn.Linear(128, 10), )forward里就一行：return self.features(x)。好处是简洁，坏处也是简洁：你没法在中间插入分支、复用同一个层的不同输入、或者基于外部条件动态决定走哪条路。所以Sequential适合“视觉上就是顺序执行”的组件。
nn.ModuleList适合同一类模块的批量管理。比如要堆6个全连接层：
self.layers = nn.ModuleList([ nn.Linear(128, 128) for _ in range(6) ])用ModuleList而不是Python list，区别在于Python list不会触发Module注册机制，里面的参数不会被model.parameters()收集，放到GPU时也不会跟着迁移。这个坑在动态堆叠网络时非常隐蔽。
nn.ModuleDict则适合需要按名字访问模块的场景，比如多分支网络：
self.branches = nn.ModuleDict({ 'conv_branch': nn.Conv2d(3, 16, 3), 'fc_branch': nn.Linear(784, 16), })以后调用self.branches['conv_branch']就行。需要维护字典结构时优先用ModuleDict，因为普通dict同样会绕过参数注册。
3.4 模型打印、参数查看与初始化
搭完模型，第一件事不是立刻训练，而是检查结构。
model = MnistMLP() print(model)打印结果会按模块层级展示结构。接下来看参数：
for name, param in model.named_parameters(): print(name, param.shape, param.requires_grad)state_dict是更完整的快照，包含parameters和buffers。保存和加载模型都是围绕它展开：
torch.save(model.state_dict(), 'mnist_mlp.pth') model_loaded = MnistMLP() model_loaded.load_state_dict(torch.load('mnist_mlp.pth'))强调一下：保存state_dict而不是整个model。因为state_dict只存参数和缓冲，体积小、跨版本更稳、别人拿到代码也好复现。
初始化方法上，PyTorch默认初始化大部分时候够用。但如果你想复现论文效果，就需要自己覆写。我习惯用model.apply做批量初始化：
def init_weights(m): if isinstance(m, nn.Linear): nn.init.xavier_uniform_(m.weight) nn.init.zeros_(m.bias) model.apply(init_weights)apply会递归地对每个子模块执行一次这个函数，是批量初始化的标准姿势。这里我把bias置零、weight用Xavier，因为后面接ReLU这类激活函数，对梯度尺度比较敏感，Xavier能帮初始信号维持在合理范围。
4. 常见问题与排查实录
4.1 改参数没生效？八成是没注册Parameter
我真实见过一次崩溃现场：某位同学复现论文，自定义了一个权重矩阵，写成了self.weight = torch.randn(...)，训练了20个epoch，loss纹丝不动。查了半天才发现这个张量根本没被注册成Parameter，优化器压根不知道它的存在。
这种问题最诡异的地方在于：代码不报错、前向能跑、loss也正常打印，只是权重不更新。因为forward里用到这个张量时，它被当成常量，backward时梯度为None。
排查技巧：训练循环前打印
list(model.parameters())的数量和形状，对照你预想的参数量，一眼就能发现参数少了。
4.2 梯度为None或为nan
梯度为None的常见原因：
- 参数设了
requires_grad=False。 - 这一层没有在forward里被用到，计算图里根本没它。
- forward里用了
detach()切断梯度。 - 自定义op没有实现backward。
梯度为nan的原因更多，最经典的是loss变成nan之后一路传导：初始学习率太大、数据里有NaN、网络里出现除零。排查时建议在loss.backward()之前先打印loss数值，这是第一道关卡。第二个检查点是查看某个参数的梯度：
print(torch.isnan(model.fc1.weight.grad).any())如果grad是nan，问题多半出在反向传播；如果loss是nan而grad正常，问题多半出在loss计算本身或数据。
下面这张表是我平时排查用的速查表：
| 现象 | 常见原因 | 处理办法 |
|---|---|---|
| 参数不更新 | 未注册Parameter / 参数未进入forward计算图 | 用nn.Parameter包裹；检查named_parameters |
| 梯度为None | requires_grad=False / forward未使用该层 | 检查requires_grad；确认层被调用 |
| 梯度为nan | loss为nan / 学习率过大 / 数据含NaN | 先看loss；降低学习率；清洗数据 |
| 推理结果不对 | 忘记model.eval() | 推理前调用model.eval() |
| 设备不一致 | 模型或数据没有to设备 | 统一执行.to(device) |
4.3 模型和数据设备不一致
报错信息通常长这样：Expected all tensors to be on the same device。这类报错框架其实已经帮你定位是哪个tensor、在什么设备，但很多人还是搞不清改哪行。
我的习惯是写一个helper，或者直接在训练循环里统一做迁移：
device = torch.device('cuda' if torch.cuda.is_available() else 'cpu') model = MnistMLP().to(device) for x, y in train_loader: x, y = x.to(device), y.to(device)一个容易踩的细节：optimizer要在model.to(device)之后创建，否则optimizer持有的是迁移前的参数引用，可能导致优化器里的参数和模型当前参数不一致。单卡阶段不用过度设计抽象，统一同步就行。
4.4 自定义层的常见雷区
自定义层踩过的坑里，最常碰到的有三个。
第一，忘了继承nn.Module，或者忘了在子类里调用super().__init__()。这个后果是参数属性可能失效，模型行为像“灵异事件”，报错都很难查。
第二，forward里用了inplace操作。PyTorch因为要记录计算图，对需要梯度的叶子节点做了校验。出现a leaf Variable that requires grad is being used in an in-place operation就说明踩了这个雷。解决方法是改成非原地写法，比如x = x + 1而不是x += 1。
第三，自定义层里声明了参数，但参数没有参与任何计算。这样参数虽然存在，梯度一直是None，对训练毫无作用。比如你想加一个缩放因子，写进forward却乘错了变量，就会出现“有参数但没效果”的诡异情况。
建议：每写一个自定义层，先用一个最小例子做前向和反向冒烟测试，确认梯度不是None，再放进主模型。这一步至少能省一半的排查时间。
5. 模块化设计经验与扩展建议
5.1 子模块拆分的边界
模型组织得越清晰，后续改结构、复现实验、给别人讲代码都越方便。我的经验是：把“一个完整且可复用的数据流阶段”拆成一个子模块，而不是把每一层都拆开。
比如一个残差块、一个Transformer编码器层、一个特征金字塔的某个层级，都是很好的模块单元。它们内部可以用Sequential，对外只暴露一个forward入口。
模块化还有一个很实际的收益：你可以单独对子模块测试输入输出形状和梯度。我经常写这种断言脚本：
dummy = torch.randn(4, 3, 32, 32) block = SomeBlock(...) out = block(dummy) assert out.shape == (4, 10)重构代码之后跑一遍形状检查，比肉眼盯代码靠谱得多。这个习惯帮我挡住了很多低级的维度错误。
5.2 封装自定义损失函数
损失函数也建议用nn.Module封装成一个类，尤其是当损失需要额外参数、需要在训练和验证模式下行为不同的时候。PyTorch里的所有Loss类，比如nn.CrossEntropyLoss，本身就是一个Module。自定义时也照此办理：
class FocalLoss(nn.Module): def __init__(self, gamma=2.0): super().__init__() self.gamma = gamma def forward(self, logits, targets): ce = -torch.log_softmax(logits, dim=1) pt = torch.exp(ce.gather(1, targets.unsqueeze(1)).squeeze(1)) focal_weight = (1 - pt) ** self.gamma return (focal_weight * ce.gather(1, targets.unsqueeze(1)).squeeze(1)).mean()把损失封装成Module的好处是：可以像其它Module一样挂hook、可以配合model.apply调试、能统一设备信息。将来如果给损失也加可学习参数，接口结构也不需要改。
5.3 源码阅读路径建议
如果你已经能顺畅地写自定义模型，我强烈建议去读几个真实项目里的模型文件。我自己的阅读顺序大致是：
- 打开
model.py，先看__init__里有哪些self.xxx = nn.YYY，把层级结构画成树状图。 - 看
forward，把张量形状沿着代码路径手写下来，遇到view、permute就多停一下。 - 看有没有hooks、有没有分支网络、有没有在forward里动态创建模块。
- 最后跑一段代码打印
state_dict()里的key，和网络结构一一对应。
刚开始读源码会有点慢，但坚持读三个模型文件之后，你会对nn.Module的模式建立起直觉。
其实把这套机制吃透之后，再去看其它深度学习框架，思路都是相通的：怎么声明参数、怎么描述前向计算、怎么序列化模型。PyTorch用nn.Module把这些集中在一个地方，确实是一个很好的学习入口。最后再分享一个小技巧：我每次写完一个新模型，都先让模型在CPU上用一个很小的batch跑通forward，打印输出形状、确认梯度存在，再切到GPU训练。这个习惯帮我挡掉了至少一半的深坑。希望这篇对你也有帮助。
