tf.function 重追踪（Retracing）

• 输入形状（shape）或数据类型（dtype）发生变化会触发重追踪——开销大，且会打印警告信息
• 使用 input_signature 固定输入形状——@tf.function(input_signature=[tf.TensorSpec(...)])
• Python 值会导致重追踪——应传入 tensor，而非 Python int/float
• 避免在 tf.function 中使用 Python 边侧效应（side effects）——仅在图构建（tracing）阶段执行一次

GPU 内存

• TensorFlow 默认占用全部 GPU 显存——需在任何算子执行前设置 memory_growth=True
• tf.config.experimental.set_memory_growth(gpu, True) —— 必须在 GPU 初始化前调用
• 大模型易发生显存溢出（OOM）——可减小 batch size 或启用梯度检查点（gradient checkpointing）
• CUDA_VISIBLE_DEVICES="" 强制使用 CPU——适用于无 GPU 环境下的测试

数据流水线（Data Pipeline）

• tf.data.Dataset 未使用 .prefetch() —— 导致 batch 间出现 CPU/GPU 空闲时间
• .cache() 应置于高开销操作之后、随机数据增强（random augmentation）之前
• 为提升向量化操作效率，应先调用 .batch() 再调用 .map() —— 比逐元素处理更快
• num_parallel_calls=tf.data.AUTOTUNE —— 启用并行预处理
• eager 模式下遍历 Dataset 效率低——应在 tf.function 或 model.fit 中使用

形状（Shape）相关问题

• 第一维为 batch 维度——Input 层中使用 None 表示可变 batch size
• 若未使用 Input 层，需显式调用 model.build(input_shape) —— 否则首次调用可能报错
• reshape 错误提示不明确——可使用 tf.debugging.assert_shapes() 辅助调试
• 广播（broadcasting）静默成功——可能掩盖 shape 相关缺陷

梯度记录器（Gradient Tape）

• Variable 默认被自动追踪——tensor 需显式调用 tape.watch(tensor)
• 如需计算多次梯度，请设置 persistent=True —— 否则 tape 在首次调用 tape.gradient 后即被释放
• tape.gradient 在无梯度路径时返回 None —— 请检查是否存在图断连（disconnected graph）
• 使用 @tf.custom_gradient 实现自定义反向传播——并非所有算子都内置梯度实现

训练常见陷阱（Training Gotchas）

• model.trainable = False 在 compile 后设置无效——必须在 compile 前设置
• BatchNorm 在训练与推理模式下行为不同——务必注意 training=True/False 参数
• model.fit 默认启用 shuffle——时序数据等场景应设 shuffle=False
• validation_split 从数据末尾划分验证集——若顺序敏感，请先 shuffle 数据

模型保存

• model.save() 保存全部内容——包括网络结构、权重及优化器状态
• model.save_weights() 仅保存权重——恢复时需提供原始模型代码
• SavedModel 格式适用于部署（serving）——tf.saved_model.save(model, path)
• H5 格式功能受限——对自定义对象支持不佳，推荐优先使用 SavedModel

常见错误

• 错误混用 Keras 层与原生 tf ops——在 Sequential 模型中应使用 layers.Lambda 封装 tf ops
• tf.print 与 Python print 的区别——后者在 tf.function 中仅于 trace 阶段执行一次
• 图模式中不应使用 NumPy ops——应改用 tf ops；NumPy 仅在 eager 模式下执行
• 损失函数应返回每个样本的标量 loss——Keras 会自动取均值；自定义训练循环中可能需要显式调用 tf.reduce_mean