TensorFlow Object Detection API需手动安装models仓库对应分支并编译protobuf；label_map.pbtxt类别id从1开始，TFRecord中class_text为bytes、class_label为int64；微调时须设fine_tune_checkpoint_type为"detection"且校验config路径与字段。

TensorFlow 官方的 tf.keras.applications 不支持直接做物体检测，你得用 TensorFlow Object Detection API —— 它是独立维护的仓库，不是 TensorFlow 核心库的一部分，装错包或版本不匹配，模型根本跑不起来。

怎么装对版本的 TensorFlow Object Detection API

最常踩的坑是 pip 直接 pip install tensorflow-object-detection-api —— 这个包不存在，纯属误导。正确路径是：

• 先确认 Python 版本（3.8–3.11 为稳妥区间），再查 官方 TF2 兼容表，锁定 tensorflow 和 models 仓库 commit 的对应关系
• 例如 TF 2.15 需要克隆 models 仓库的 r2.15 分支，不能用 main 分支
• protoc 必须安装（≥3.20），且要手动编译 research/object_detection/protos/*.proto 文件，生成 py 模块，否则 import 就报 ModuleNotFoundError: No module named 'object_detection.protos'
• setup.py 要在 models/research/ 下运行：python setup.py build & python setup.py install，否则本地路径不生效

训练自定义数据集时，label_map.pbtxt 和 TFRecord 怎么写才不报错

label_map.pbtxt 编号必须从 1 开始，0 是保留值；TFRecord 里每个 example 的 image/object/class/label 必须和它严格对齐，否则训练中会卡在 OutOfRangeError: RandomShuffleQueue 或静默跳过样本。

Python Testing

Python 测试速查：运行 pytest、使用 mock/patch、参数化、fixtures、异步、覆盖率测试。

下载

• label_map.pbtxt 示例（注意 id: 1，不是 0）：

  item {
    name: "person"
    id: 1
  }
  item {
    name: "car"
    id: 2
  }

• TFRecord 中的 class_text 字段必须是 bytes 类型（如 b"person"），不能是字符串；class_label 必须是 int64，且值 ∈ {1, 2, …}
• 推荐用 generate_tfrecord.py 脚本（官方提供）生成，别手写；若用自定义脚本，务必校验 tf.train.Example 的 feature 字段名是否与 config 中的 label_map_path 和 classes 配置一致

加载预训练模型后微调，config 文件里哪些参数动不得

直接改 num_classes 是不够的，fine_tune_checkpoint_type: "detection" 必须显式设置，否则权重加载失败但无提示；更隐蔽的问题是 learning_rate 和 batch_size 不匹配导致 loss 爆掉或不下降。

立即学习“Python免费学习笔记（深入）”；

• model.ssd.num_classes 或 model.faster_rcnn.num_classes 改为你自己的类别数（不含 background）
• train_config.fine_tune_checkpoint 指向下载解压后的 checkpoint 目录（含 ckpt-0.index 等文件），不是 .pb 或 .h5
• train_config.load_all_detection_checkpoint_vars: true 建议设为 true，避免 backbone 加载了、head 没加载
• train_input_reader.label_map_path 和 eval_input_reader.label_map_path 必须分别指向你的 label_map.pbtxt，路径错误只报 warning，但实际用默认空 map

真正难的不是跑通 demo，而是 debug 时分不清问题是出在 protobuf 编译、TFRecord 结构、config 字段拼写，还是 checkpoint 兼容性——它们报的错往往都一样：InvalidArgumentError 或直接 segfault。建议每次只改一个地方，用 model_lib_v2.validate_and_run_pipeline() 先做 config 校验，别一上来就 train。