本文详解在 Keras CV 中微调 YOLOv8 检测器后，因模型结构自定义导致 load_model 失败的典型问题，并提供符合 Keras 3+ 规范的完整保存/加载方案，包括格式选择、自定义对象注册及常见错误规避。
本文详解在 keras cv 中微调 yolov8 检测器后，因模型结构自定义导致 `load_model` 失败的典型问题，并提供符合 keras 3+ 规范的完整保存/加载方案，包括格式选择、自定义对象注册及常见错误规避。
在使用 keras_cv.models.YOLOV8Detector 进行目标检测任务微调时，一个高频陷阱是：误将整个检测器模型（含自定义层）当作普通 Keras 模型直接保存为 .h5 或 .tf 格式，却未在加载时正确声明 custom_objects。这会导致 ValueError: Unknown layer: 'YOLOV8Detector' —— 因为 Keras 序列化机制无法自动识别 keras_cv 中非内置的类。
✅ 正确做法：统一使用 .keras 格式 + 显式注册自定义类
Keras 3+ 官方推荐且唯一完全支持自定义模型序列化的格式是 .keras（取代已弃用的 .h5 和不兼容的 SavedModel .tf）。必须配合 custom_objects 参数显式传入所需类的引用：
# ✅ 正确保存：调用模型实例的 .save() 方法（非 ModelCheckpoint 保存权重）
checkpoint_filepath = "E:/model.yolo_v8_s_ft.keras"
yolo.save(checkpoint_filepath) # 自动保存架构、权重、编译配置
# ✅ 正确加载：指定 custom_objects 并导入对应类
from keras_cv.models.object_detection.yolo_v8 import YOLOV8Detector
loaded_model = keras.models.load_model(
checkpoint_filepath,
custom_objects={"YOLOV8Detector": YOLOV8Detector}
)⚠️ 注意：
custom_objects中的键名（如"YOLOV8Detector"）必须与模型保存时序列化使用的类名完全一致（区分大小写），值为该类本身（非字符串或实例）。
❌ 常见错误与修正说明
错误1：混用
ModelCheckpoint保存权重 vs. 保存完整模型ModelCheckpoint默认仅保存权重（save_weights_only=True），而YOLOV8Detector的架构含不可序列化的动态层（如YOLOV8Backbone子类、FPN 构建逻辑）。若需保存完整可复用模型，必须调用model.save()，而非依赖回调。错误2：使用
.h5或.tf格式.h5不支持 Keras 3+ 的新序列化协议；.tf（SavedModel）对keras_cv自定义模型兼容性差，且报错明确提示：“filepath must end in.keras”。务必使用.keras后缀。错误3：错误注册
custom_objects
如尝试{'YOLOV8Detector': hub.YOLOV8Detector}（tensorflow_hub无此属性）或传入字符串"keras_cv.models.YOLOV8Detector"—— 均会失败。必须从keras_cv正确导入类并传入类对象本身。
? 补充：若只需保存/加载 backbone（轻量场景）
若仅需复用微调后的骨干网络（如用于其他检测器），应单独保存 backbone 实例：
# 微调后保存 backbone（非整个 detector）
backbone = yolo.backbone # 获取已训练的 backbone
backbone.save("E:/backbone_ft.keras") # 可直接 load，无需 custom_objects
# 加载 backbone（标准方式）
backbone_loaded = keras.models.load_model("E:/backbone_ft.keras")✅ 总结
| 场景 | 推荐方式 | 关键要点 |
|---|---|---|
| 保存完整 YOLOv8Detector | model.save("xxx.keras") |
必须用 .keras，避免 .h5/.tf
|
| 加载完整 YOLOv8Detector | load_model(..., custom_objects={...}) |
custom_objects 值为 keras_cv 中的类对象 |
| 仅复用 backbone | 单独 backbone.save() + load_model()
|
无需 custom_objects，更轻量可靠 |
遵循此规范，即可彻底解决 YOLOv8 模型保存加载中的序列化异常，确保实验可复现、部署可落地。
