别按字母背TensorFlow接口：用形状账本串起一次训练

学习TensorFlow时，最费力的方式是把函数名、参数表和短示例逐项抄进笔记。记住十个接口并不能保证它们接在一起后仍然正确，因为真正决定程序行为的是张量从哪里来、形状如何变化、当前处于训练还是推理阶段，以及损失期望收到什么语义。更有效的方法是为一次完整前向计算建立“形状账本”：每经过一个操作，就记录输入、关键参数、输出和必须满足的不变量。

卷积之前先写清四条轴分别代表什么

二维卷积通常接收四维张量，但四个数字只有与轴语义绑定才有意义。常见布局把批次、高度、宽度、通道依次排列；另一种布局把通道放在空间尺寸之前。卷积核还包含核高、核宽、输入通道和输出通道。只要输入通道与卷积核对应轴不一致，操作就无法成立。步长也应与布局对应，批次轴和通道轴通常不跨步，真正移动的是空间窗口。

VALID与SAME描述的是边界处理策略，而不是“输出一定缩小”或“输出一定不变”的绝对承诺。输出尺寸还受核大小、步长和输入长度影响。SAME在步长大于一时通常保持按步长折算后的尺度，而不会维持原像素数。最小验收可使用一张尺寸很小、数值人工可算的单通道矩阵，再配一个简单卷积核，分别打印两种填充下的输出形状与数值。这个实验比记公式更容易发现轴顺序和步长列表写错。

把形状推导留在代码评审之前

每个空间操作都应能在运行前回答三个问题：输出有多大、边界如何处理、一个输出位置看到了输入的哪块区域。答不出来时，继续叠层只会放大不确定性。

可以在模型说明中维护一张逐层表，记录批次符号、空间尺寸、通道数和参数量。动态批次用未知维表示，但其他轴若有明确约束应尽量固定。运行时再用断言检查秩数和关键维度。静态推导负责设计，动态断言负责防御异常输入，两者并不互相替代。

激活与池化改变的不是同一件事

• ReLU逐元素把负值截为零，不改变张量形状。
• 最大池化在局部窗口选取代表值，通常降低空间分辨率。
• 平均池化保留区域平均趋势，和最大池化拥有不同偏好。
• 偏置加法沿通道广播，偏置长度必须对应输出通道。
• 矩阵乘法依赖内侧维度一致，不能用普通逐元素乘法替代。

将这些操作放在一起时，要区分“非线性表达能力”和“空间压缩”两种作用。激活函数让层与层的组合不再等价于单个线性变换；池化或步长卷积减少后续计算量，也可能丢失位置细节。选择哪个操作应由任务需要决定，而非因为示例总是这样排列。对细小目标或需要精确边界的任务，过早下采样会产生不可逆的信息损失。

随机失活的参数语义跨版本发生过变化

旧式接口常用保留概率表达每个元素留下的机会，较新的高层接口更常用丢弃比例。二者数值互补，迁移时若原样复制会得到完全不同的正则强度。随机失活只应在训练时启用，推理时必须关闭并使用确定性路径。若通过Keras层构建模型，训练标志通常由调用链传递；若手写底层函数，则需要显式验证。固定随机种子有助于复现实验，但不能把每一步都强制产生同一掩码，否则会改变预期随机性。

损失函数最怕把概率与logits混为一谈

1. 先决定任务是二分类、多标签还是互斥多分类。
2. 确认模型末层输出的是未归一化分数还是已经转换的概率。
3. 让标签形状、类型与损失函数契约一致。
4. 在极小批次上手工构造“正确很自信”和“错误很自信”两组输出。
5. 检查前者损失更低，并验证梯度不是全零或非数值。

带logits字样的交叉熵接口通常内部已经包含数值稳定的激活计算。若在输入前再做Sigmoid或Softmax，相当于重复转换，可能让梯度变差。二分类与多标签任务常逐类使用Sigmoid；互斥类别通常使用Softmax语义。损失默认如何聚合批次、是否按样本加权，也会影响训练尺度。不能只看函数能否执行，还要用构造样本验证排序关系符合直觉。

常量、变量与输入边界承担不同寿命

常量适合不会由优化器更新的小型固定值；变量保存可训练权重或需要持久化的状态；外部批数据应通过数据管道或函数输入进入模型。早期图执行代码常通过占位符和feed方式提供运行时值，并在会话中显式求值。当前的即时执行更像普通Python调用，而图函数负责把稳定计算封装为可优化图。迁移旧代码时，应先识别每个对象的寿命和职责，再替换接口，不能把所有占位符机械改成变量。

从会话式示例迁移时保留行为对照

旧代码中的会话、全局变量初始化和集合机制反映了当时的图执行模型。迁移到较新的接口，通常可以用Keras层管理变量，用模型调用表达前向计算，用梯度带或训练接口执行更新。每替换一段，应在固定输入上比较输出形状、数值范围和损失，而不是等到整套训练结束才看准确率。卷积参数的顺序、随机失活含义和保留维度参数尤其需要逐项核对。

若项目必须继续运行历史模型，兼容层可以作为过渡，但要把它限制在清楚的模块边界，并记录退出计划。兼容调用成功只证明接口可达，并不保证数值与原环境完全一致。保存一组黄金输入和容许误差，升级前后自动比较，能够把“似乎能跑”提升为可审计的行为一致性。

一页API地图应以排错问题收尾

真正实用的笔记不必收录所有函数，而应让读者在遇到症状时知道向哪里看：维度错误先查布局和广播；训练推理不一致先查随机层与训练标志；损失异常先查logits、标签和数值范围；保存后无法服务先查签名与预处理契约。每个条目都配一个最小可算样例、一个反例和一个输出断言，比复制长参数表更能抵抗版本变化。

当接口按数据流组织后，新的TensorFlow操作也容易归位。先问它消费什么张量、改变哪些轴、是否保存状态、在训练与推理时是否不同、梯度怎样通过、最终如何被保存。函数名字可能变化，高层封装也会演进，但形状、语义、状态和验证这四条主线长期稳定。形状账本的终点不是背熟API，而是让每一次张量变换都有理由、有预期、有失败信号。