必须确认模型支持目标检测任务；仅ssd、faster r-cnn、efficientdet等明确标注“object_detection”的tf2 detection zoo预训练模型可微调，resnet50/mobilenetv2等分类模型因头结构不匹配会报权重形状错误。
微调前必须确认模型是否支持目标检测任务
TensorFlow官方提供的预训练模型中，只有SSD、Faster R-CNN、EfficientDet等系列明确标注为“object_detection”用途的检查点才能用于目标检测微调。直接拿ResNet50或MobileNetV2这类图像分类模型的.h5权重去加载到检测模型里会报ValueError: Layer weight shape (1000, 2048) not compatible with provided weight shape (91, 2048)——因为分类头和检测头结构完全不匹配。
正确做法是：从TF2 Detection Zoo下载带pipeline.config和checkpoint的完整压缩包（如ssd_mobilenet_v2_320x320_coco17_tpu-8），解压后保留checkpoint、saved_model、pipeline.config三个核心部分。
修改pipeline.config时最常踩的三个坑
pipeline.config是微调成败的关键配置文件，用文本编辑器打开后重点改以下几处，其他字段尽量不动：
-
num_classes：必须设为你数据集的实际类别数（不含背景），比如只有“car”和“person”，就填2，不是3；填错会导致训练时loss爆炸或NaN -
fine_tune_checkpoint：路径要写绝对路径，且指向解压后目录里的checkpoint文件（不含后缀），例如/path/to/model/checkpoint；相对路径或写成checkpoint.index都会静默失败 -
label_map_path：必须指向你自己的label_map.pbtxt，内容格式严格为：item { id: 1 name: 'car' } item { id: 2 name: 'person' }注意id从1开始，不能为0，且顺序要和训练数据标注一致
训练命令必须用model_main_tf2.py而非train.py
TensorFlow 2.x 官方已弃用train.py，现在统一用model_main_tf2.py启动训练。常见错误是复制旧教程命令，漏掉--use_tpu=False参数，导致在GPU环境报InvalidArgumentError: Cannot assign a device for operation...。
标准命令示例（Linux/macOS）：
python model_main_tf2.py \ --model_dir=/path/to/train_dir \ --pipeline_config_path=/path/to/pipeline.config \ --checkpoint_every_n=1000 \ --use_tpu=False其中
--checkpoint_every_n控制保存频率，建议设为1000~5000，太小会拖慢训练；--model_dir必须是空目录，否则可能复用旧检查点导致收敛异常。
验证微调结果时别只看eval日志里的mAP
model_lib_v2.py跑评估时输出的mAP@0.50IOU只是整体指标，容易掩盖具体问题。真正要查的是TensorBoard里的Precision/Recall曲线和Images面板下的预测图——如果某类别的Recall始终低于0.3，大概率是label_map.pbtxt和标注文件中的类别名不一致（比如写了'Car'但标注里是'car'），或者该类别样本数太少（少于50张）导致模型学不会。
更直接的办法是用exporter_main_v2.py导出SavedModel后，写几行代码做单图推理：
import tensorflow as tf
detect_fn = tf.saved_model.load('/path/to/exported/saved_model')
result = detect_fn(input_tensor)观察result['detection_classes']是否输出预期ID，比看日志快得多。
微调最难的不是跑通流程，而是让pipeline.config、label_map.pbtxt、标注XML/JSON、训练脚本四者ID和名称严格对齐——差一个字母或大小写，模型就学不会那一类。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
