ValueError: Shape mismatch 通常因模型结构不一致导致，需比对 model.summary() 的层名、shape、参数量；SavedModel 加载失败多因路径错误或目录结构缺失；子类模型必须预定义类并传 custom_objects；H5 兼容性问题建议改用 SavedModel 格式。
模型加载时报 ValueError: Shape mismatch 怎么快速定位
这通常不是权重文件损坏，而是模型定义和保存时的结构对不上。TensorFlow 会严格校验层名、层顺序、输入输出 shape，哪怕只是 tf.keras.layers.Dense(128) 和 tf.keras.layers.Dense(units=128) 这种等价写法，在某些保存方式下也可能因内部属性序列化差异导致 name 或 config 不一致。
实操建议：
- 用
model.summary()分别在「训练保存前」和「加载前重新构建的模型」上执行，逐行比对层名、output shape、param #；特别注意name字段是否完全一致（比如带不带_1后缀） - 检查是否混用了函数式 API 和子类模型：用
model.save('path', save_format='h5')保存的子类模型，不能用tf.keras.models.load_model()直接加载——必须传入custom_objects且模型类已定义 - 如果用
model.save_weights_only=True，加载时必须先用完全相同的 Python 代码重建模型结构，再调用model.load_weights('path')，顺序错一步就报 shape mismatch
加载 SavedModel 时提示 Failed to find any matching files
这不是路径写错那么简单，而是 SavedModel 目录结构被破坏或路径指向了错误层级。TensorFlow 要求该目录下必须存在 saved_model.pb（或 saved_model.pbtxt）和 variables/ 子目录，缺一不可。
实操建议：
- 确认路径是目录路径，不是文件路径：传给
tf.keras.models.load_model()的必须是包含saved_model.pb的文件夹路径，例如'./my_model'，而不是'./my_model/saved_model.pb' - Windows 用户注意反斜杠问题：用原始字符串或正斜杠，避免
'C:\models\m1'中的\m被解释为转义符；推荐写成r'C:\models\m1'或'C:/models/m1' - 检查权限：Linux/macOS 下若目录属主不是当前用户，或
variables/下文件无读权限，也会静默失败——用ls -l ./my_model/variables确认
子类模型（tf.keras.Model 子类）加载失败，报 NameError 或 TypeError
子类模型无法仅靠结构自动重建，因为它的前向逻辑藏在 call() 方法里，而该方法依赖外部定义的类。TensorFlow 加载时找不到对应类名，就会炸。
实操建议：
- 确保加载前，模型类定义已执行：把
class MyModel(tf.keras.Model): ...的代码块放在load_model()调用之前，不要放在函数内或条件分支里 - 传入
custom_objects参数：即使类名没变，也显式传入，例如tf.keras.models.load_model('./model', custom_objects={'MyModel': MyModel}) - 避免使用闭包或局部变量构造层：像在
__init__里写self.dense = Dense(64, activation=lambda x: tf.nn.gelu(x))会导致序列化失败——改用字符串名activation='gelu'
从 H5 文件加载时出现 AttributeError: 'NoneType' object has no attribute 'decode'
这是 TF 2.10+ 版本中一个已知兼容性问题，发生在用旧版 TensorFlow（≤2.8）保存的 H5 模型，被新版加载时解析自定义 layer 的 config 出错。本质是 H5 的 metadata 字段为空但新版解码逻辑未做空值防护。
实操建议：
- 优先转用 SavedModel 格式：新项目一律用
model.save('path/', save_format='tf')，它更稳定、可移植性更强 - 临时绕过：降级到 TF 2.8 或 2.9 加载，导出为 SavedModel 后再升回新版使用
- 若必须用 H5，检查是否含自定义层：没有的话，尝试加参数
compile=False加载，再手动编译——有时 compile 流程里的 optimizer 反序列化会触发该错误
最常被忽略的一点：模型保存和加载环境的 TensorFlow 版本最好一致，尤其跨大版本（如 2.7 → 2.12）时，底层序列化协议可能变更。不是“能跑就行”，而是“结构描述字节流”本身变了。
