tf.keras.models.load_model()加载的模型不能直接转onnx，因tf2onnx.convert.from_keras仅接受keras模型对象，需确保为tf.keras.model实例、注册自定义层、固定输入shape、匹配input_signature、指定opset=15，并注意tf 2.16+兼容性问题。
tf.keras.models.load_model() 加载模型后直接转 ONNX 会失败
TensorFlow SavedModel 或 HDF5 格式模型不能直接喂给 tf2onnx.convert.from_keras —— 它只接受 Keras 模型对象，但常见错误是传入路径字符串或 tf.keras.Model 子类实例却未正确实例化。更隐蔽的问题是模型含自定义层、动态 shape（如 tf.shape(x)[0]）或非标准控制流（tf.cond、tf.while_loop），这些在转换时会被静默忽略或报 NotImplementedError。
实操建议：
- 先用
tf.keras.models.load_model("path/to/model")确保返回的是tf.keras.Model实例（检查type(model)） - 若模型含自定义层，必须提前注册：用
@tf.keras.utils.register_keras_serializable()装饰类，并确保get_config()和from_config()可用 - 对动态 batch size，显式指定输入 shape：用
model.input_shape替换为固定值（如(1, 224, 224, 3)），否则tf2onnx会推导出None导致 ONNX 推理失败
tf2onnx.convert.from_keras() 的 input_signature 参数必须匹配实际推理输入
很多用户卡在转换后 ONNX 模型运行时报 InvalidArgumentError: Input is not a vector 或 shape 不匹配——根源常是 input_signature 描述与模型实际 call 签名不一致。比如模型接受 (batch, h, w, c)，但 signature 写成 tf.TensorSpec((None, None, None, 3), tf.float32)，ONNX 就无法确定中间 tensor 的 rank。
实操建议：
- 用
model.inputs查看原始输入 spec：[<tf.tensor shape="(None," dtype="float32">]</tf.tensor>→ 对应input_signature=[tf.TensorSpec((1, 224, 224, 3), tf.float32)] - 多输入模型必须按
model.inputs顺序提供 list，不能靠名字匹配 - 避免用
None填充所有维度：至少固定 batch 维（如(1, ...)），否则 ONNX Runtime 无法分配内存
转换后 ONNX 模型在 onnxruntime 推理时输出 shape 异常
常见现象：ONNX 模型输出维度比原 TensorFlow 模型少一维（如 TF 输出 (1, 1000)，ONNX 输出 (1000,)），或 softmax 后概率全为 0。这通常不是转换 bug，而是 ONNX opset 版本与算子实现差异导致的——例如 opset=13 下 Softmax 默认 axis=-1，而某些 TF 版本导出时隐含 axis=1。
Python 3.14.2是Python编程语言在2025年12月5日发布的稳定版本，属于3.14系列的第二个维护更新。该版本包含了18项修复，重点解决了多进程、数据类及正则表达式等模块的回归问题，并修复了CVE-2025-12084等安全漏洞。此版本标志着自由线程模式（移除GIL）正式获得官方支持，是Python发展的重要里程碑。
实操建议：
- 强制指定
opset=15（当前最兼容）：tf2onnx.convert.from_keras(model, input_signature=..., opset=15) - 转换后用
onnx.checker.check_model(model_proto)验证结构，再用onnx.shape_inference.infer_shapes()补全 shape 信息 - 对比 TF 与 ORT 输出：用相同输入跑
model(tf_input)和ort_session.run(None, {"input": np_input})，逐层检查中间 tensor 是否一致
TensorFlow 2.16+ 与 tf2onnx 1.16+ 的兼容性陷阱
新版本 TF 默认启用 tf.function 图模式，但 tf2onnx 依赖旧版 graph 构建逻辑。典型表现：转换成功但 ONNX 模型加载时报 RuntimeError: No OpKernel was registered to support Op 'StatefulPartitionedCall' —— 这说明图里残留了 Eager-only op。
实操建议：
- 转换前加
tf.config.run_functions_eagerly(False)确保图模式导出 - 若模型含
@tf.function包装的预处理函数，必须单独提取并转换为 Keras Lambda 层，不能留在模型外 - 避坑组合：TF 2.13 + tf2onnx 1.14 最稳定；升级需同步验证
tf2onnx.convert.from_graph_def()是否替代from_keras()更可靠
真正麻烦的不是转换步骤本身，而是模型里那些没显式声明、却依赖 TF 内部状态的 ops——它们不会报错，但会让 ONNX Runtime 在不同设备上行为不一致。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
