TensorFlow 2 版 Object Detection API 快速上手指南：安装、微调训练、模型库与官方资源全梳理

本篇指南面向希望在本仓库中直接使用 TensorFlow 2 版 Object Detection API 的开发者，核心覆盖从环境安装、功能自检、Colab 快速体验，到本地/云端训练评估、预训练检测模型库（Model Zoo）与官方子指南检索的完整链路。读完后你将能够独立完成 TF2 目标检测环境搭建，并据此开启自定义数据集上的训练与评估流程。

本仓库整体为基于 TensorFlow 构建的模型与示例集合（Models and examples built with TensorFlow），其中 research/object_detection 即著名的 TensorFlow Object Detection API 代码库。本文对应的基础文档为 research/object_detection/g3doc/tf2.md，下面以其为核心骨架展开，并结合仓库内源码与配套文档给出更具操作性的细节。

环境要求

使用 TF2 版 Object Detection API 前，请先核对如下基础环境：

依赖	版本要求
Python	3.6 及以上
TensorFlow	2.2 及以上
Protobuf Compiler（protoc）	3.0 及以上

其中 Python 与 TensorFlow 的版本要求与本仓库 TF2 Dockerfile 中的基准镜像 tensorflow/tensorflow:2.2.0-gpu 保持一致；而 protoc 用于把 research/object_detection/protos/ 下的 .proto 描述文件编译为可被 Python 导入的模块，这是安装阶段的关键步骤。

获取仓库并选择安装方式

Object Detection API 的代码全部位于本仓库的 research/object_detection/ 目录。安装方式有两种：

• 本地/自建服务器运行：推荐使用 Docker 安装；
• Google Cloud 云上运行：推荐使用 Python 包安装（pip）。

首先获取仓库源码（若需在本地准备一份完整副本，可通过 git clone 拉取）：

git clone https://gitcode.com/GitHub_Trending/mode/models

两种安装方式会在仓库根目录下分别执行，具体差异如下。

方式一：Docker 安装

仓库已经为 TF2 环境预制了 Dockerfile，位于 research/object_detection/dockerfiles/tf2/Dockerfile。在仓库根目录执行：

# 在 git 仓库根目录执行
docker build -f research/object_detection/dockerfiles/tf2/Dockerfile -t od .
docker run -it od

从 Dockerfile 源码可以看出该镜像构建过程实际替你完成了全部环境准备工作：

1. 以 tensorflow/tensorflow:2.2.0-gpu 为基础镜像，并安装 git、protobuf-compiler、python3-lxml、python3-tk、wget 等系统依赖；
2. 安装 gcloud 与 gsutil，方便后续对接 Google Cloud Storage 数据；
3. 将本仓库代码复制进镜像并预编译全部 protos（执行 protoc object_detection/protos/*.proto --python_out=.）；
4. 复制 research/object_detection/packages/tf2/setup.py 到 research/ 根目录并执行 pip install .。

也就是说，走 Docker 路线时无需手动安装 protobuf-compiler，镜像构建阶段已经处理完毕，进入容器后即可直接进入「验证安装」环节。

方式二：Python 包安装（pip）

在 research 目录下手动执行三条命令：

cd research
# 1. 编译 protos，生成对应的 *_pb2.py 模块
protoc object_detection/protos/*.proto --python_out=.
# 2. 将 TF2 专用的 setup.py 复制到 research/ 根目录
cp object_detection/packages/tf2/setup.py .
# 3. 安装 Object Detection API
python -m pip install --use-feature=2020-resolver .

几点实操说明：

• 步骤 1 的编译产物（*_pb2.py）是后续所有 builder、config_definitions 正常导入的前置条件，不可省略；
• 步骤 2 之所以用 cp 复制 setup.py，是为了让 setuptools 能以 research/ 作为包搜索根目录，同时兼容仓库内 slim/ 子目录的 datasets、nets、preprocessing 等子包（参见 packages/tf2/setup.py 中的 packages 与 package_dir 配置）；
• 步骤 3 中 --use-feature=2020-resolver 用于指示 pip 使用新的依赖解析器，如果你的 pip 版本较新，该参数可省略；
• packages/tf2/setup.py 声明了一组重要运行依赖，包括 apache-beam、tf-slim、pycocotools、lvis、tf-models-official>=2.5.1、tensorflow_io、keras 等，其中 pyparsing==2.4.7 与 sacrebleu<=2.2.0 是特意锁定的版本（源码中带有 issue 注释），遇到依赖冲突时请优先核对这两项。

注意：pip 安装路线要求你的机器上已存在可用的 protoc（>= 3.0）。如果本机没有 protoc，请优先考虑 Docker 安装，或在系统中另行安装 protobuf 编译器后再继续。

验证安装是否成功

无论采用哪种安装方式，完成安装后都建议先跑一遍官方自检用例：

python object_detection/builders/model_builder_tf2_test.py

该测试对应仓库中的 research/object_detection/builders/model_builder_tf2_test.py，它通过 TF2 模型构建器（model builder）加载并实例化各类检测模型配置。测试全部通过即说明以下链路已经打通：

• protos 已正确编译为 Python 模块（model_builder 需要导入各配置 message）；
• TF2 相关 builder 模块（含 Keras 版 feature extractor 等）可以正常 import；
• 本机 TensorFlow 2.2+ 与 Object Detection API 代码版本匹配。

如果此步报出 ImportError 或 protobuf 相关错误，请回头检查编译 protos 与 pip 安装两步是否在正确的目录（research/）下执行。

快速开始：三份官方 Colab

仓库的 colab_tutorials 目录 提供了三份与 TF2 直接相关的官方 notebook，覆盖训练、推理与移动端三个典型场景：

场景	Colab Notebook	说明
训练	eager_few_shot_od_training_tf2_colab.ipynb	在 eager mode 下用自定义数据对预训练检测器做 few-shot 微调，是理解 TF2 训练入口（model_main_tf2.py + pipeline config）的起点
推理	inference_tf2_colab.ipynb	直接加载 Model Zoo 中的预训练模型运行推理，适合先跑通效果再做定制
移动端 Few-Shot 学习	eager_few_shot_od_training_tflite.ipynb	微调一个面向 TensorFlow Lite 的预训练检测器，目标产物可直接部署到移动端

三份 notebook 均位于仓库内，可直接在 Colab 中打开或本地用 Jupyter 执行。其中训练类 notebook 演示的正是「复用预训练 checkpoint + 少量自定义数据」这一 Object Detection API 最主流的用法；有关移动端推理的更多说明还可参考 running_on_mobile_tf2.md。

训练与评估：从配置到命令

完整的分步训练/评估指引（本地 CPU/GPU 以及 Google Cloud GPU/TPU VM、AI Platform 场景）记录在 tf2_training_and_evaluation.md 中。这里先提炼其中最关键的实战要素，便于你按图索骥：

推荐的目录结构

原文档推荐的工程目录如下，训练与评估产物严格分目录存放，便于 TensorBoard 汇总：

.
├── data/
│   ├── eval-00000-of-00001.tfrecord
│   ├── label_map.txt
│   ├── train-00000-of-00002.tfrecord
│   └── train-00001-of-00002.tfrecord
└── models/
    └── my_model_dir/
        ├── eval/                 # 由评估任务生成
        ├── my_model.config
        ├── model_ckpt-100-data@1   # 由训练任务生成
        ├── model_ckpt-100-index
        └── checkpoint

编写模型配置

训练前需要一份 pipeline 配置文件。仓库在 research/object_detection/configs/tf2 下提供了 39 份可直接套用的官方 TF2 示例配置，覆盖 CenterNet（HourGlass104/ResNet/MobileNetV2 等）、EfficientDet D0-D7、SSD MobileNet/ResNet 系列、Faster R-CNN ResNet 系列与 Mask R-CNN 等。以 ssd_mobilenet_v2_fpnlite_320x320_coco17_tpu-8.config 为例，可看到一份标准 pipeline config 的骨架：

• model { ssd { ... } }：定义骨干网络（feature extractor）、anchor 生成器、box predictor、loss 与 NMS 后处理等结构；
• train_config { ... }：指定 batch size、优化器与学习率（如 cosine decay + warmup）、数据增强与总步数；
• train_input_reader { ... } / eval_input_reader { ... }：分别指定训练/评估 TFRecord 输入路径与 label map 路径。

其中 label_map_path、input_path 等字段通常以 PATH_TO_BE_CONFIGURED 占位，复制到自己项目时需要替换为真实路径。

借助预训练 checkpoint 初始化模型参数

目标检测从零训练往往需要数天，因此强烈建议复用既有图像分类或目标检测 checkpoint 来初始化骨干网络。在 train_config 中通过两个字段控制（详见 tf2_training_and_evaluation.md）：

• fine_tune_checkpoint：预训练 checkpoint 的路径前缀（例如 .../model.ckpt-#####）；
• fine_tune_checkpoint_type：取值 classification 或 detection，取决于 checkpoint 是分类还是检测模型。

对应的可下载资源分别整理在两份列表中：分类模型（tf2_classification_zoo.md） 与 检测模型（tf2_detection_zoo.md）。

本地训练与评估

在 research/ 目录下使用统一的入口脚本 research/object_detection/model_main_tf2.py：

# —— 本地训练 ——
PIPELINE_CONFIG_PATH={path to pipeline config file}
MODEL_DIR={path to model directory}
python object_detection/model_main_tf2.py \
    --pipeline_config_path=${PIPELINE_CONFIG_PATH} \
    --model_dir=${MODEL_DIR} \
    --alsologtostderr

训练产出的 checkpoint 与 events 写入 ${MODEL_DIR}。评估任务则在训练进程外另起一个进程，额外传入 --checkpoint_dir：

# —— 本地评估 ——
PIPELINE_CONFIG_PATH={path to pipeline config file}
MODEL_DIR={path to model directory}
CHECKPOINT_DIR=${MODEL_DIR}
python object_detection/model_main_tf2.py \
    --pipeline_config_path=${PIPELINE_CONFIG_PATH} \
    --model_dir=${MODEL_DIR} \
    --checkpoint_dir=${CHECKPOINT_DIR} \
    --alsologtostderr

评估事件写入 ${MODEL_DIR}/eval。实践中通常让训练与评估任务并发运行，训练产出 checkpoint 后评估器会持续跟踪最新权重。

云上（Google Cloud）扩展

• GPU/TPU VM：训练命令与本地几乎一致，仅需追加 --use_tpu=true 与 --tpu_name=${TPU_NAME} 两个可选参数即可跑在 TPU 上；注意评估仅支持 GPU，不支持在 TPU 上执行评估；
• AI Platform（Cloud ML）：需要先基于 tf2_ai_platform/Dockerfile 构建并推送自定义容器镜像，再通过 gcloud ai-platform jobs submit training ... 提交多 GPU（如 8×V100）或 BASIC_TPU 等级的分布式训练任务；训练产物与配置均可直接使用 gs:// 路径；
• 云上路径可以是本地路径或 GCS bucket 路径，脚本内已天然兼容。

建议在上云之前，先在本地把训练与评估各跑若干步验证配置无误，再做大规模提交。

用 TensorBoard 观察进度

如果采用上文推荐的目录结构，一条命令即可同时汇总训练与评估指标：

tensorboard --logdir=${MODEL_DIR}

其中 ${MODEL_DIR} 指向同时包含 train 与 eval 两个子目录的父目录。TensorBoard 需要一到两分钟才能完成数据填充，属正常现象。

预训练模型库（TF2 Detection Model Zoo）

仓库官方提供了一大批在 COCO 2017 上预训练好的检测模型，完整清单与下载地址见 tf2_detection_zoo.md。这些模型的典型用途有两类：

1. 开箱即用的推理：当你要识别的类别已包含在 COCO 类别之内，可直接加载运行，配合 inference_tf2_colab.ipynb 快速体验；
2. 新数据集的初始化权重：作为微调起点以加速收敛，这正是上面 fine_tune_checkpoint / fine_tune_checkpoint_type 两个字段所指的对象，对应 eager_few_shot_od_training_tf2_colab.ipynb 的 few-shot 训练流程。

从 Model Zoo 清单（以及 configs/tf2 配置目录 中一一对应的 .config 文件）可以看到预训练模型按输出类型可分为以下几大家族：

模型家族	代表配置	输出	特点
SSD 系列	SSD MobileNet V2、SSD MobileNet V1 FPN、SSD MobileNet V2 FPNLite 320/640、SSD ResNet50/101/152 V1 FPN（RetinaNet 640/1024）	Boxes	覆盖移动端到服务端，速度快
EfficientDet	D0（512×512）至 D7（1536×1536）	Boxes	输入分辨率逐档增大，精度递增
Faster R-CNN 系列	ResNet50/101/152 V1 640、1024、800×1333 等	Boxes	两阶段，精度较高
Mask R-CNN	Mask R-CNN Inception ResNet V2 1024×1024	Boxes / Masks	目标检测 + 实例分割
CenterNet 系列	HourGlass104 512/1024、ResNet50/101 V1 FPN、ResNet50 V2、MobileNetV2 FPN，含 Keypoints 变体	Boxes / Keypoints	无 anchor 的中心点方法，支持人体关键点
ExtremeNet	ExtremeNet	Boxes	仓库中标注为 deprecated，可忽略

其中每份 tar.gz 内通常同时附带模型结构与训练用的 pipeline config。如果想自行从零复现训练，直接使用 research/object_detection/configs/tf2 下对应名称的配置文件即可；Model Zoo 各模型的具体速度（ms）与 COCO mAP 数值请以 tf2_detection_zoo.md 中完整表格为准。若目标是移动端部署，可进一步参考 running_on_mobile_tf2.md。

官方子指南速查

本文档同时是指向 Object Detection API 全系子指南的「路由页」，下面是这些指南在本仓库中的具体位置与定位，可按需深入：

• configuring_jobs.md：如何配置一条完整的 object detection pipeline（pipeline config 各字段详解）；
• preparing_inputs.md：如何为 PASCAL VOC / Oxford-IIIT Pet 等数据集生成 TFRecord 输入；
• defining_your_own_model.md：如何定义你自己的模型架构并接入 API；
• using_your_own_dataset.md：如何接入自有数据集（label map、TFRecord 转换）；
• evaluation_protocols.md：支持的检测评估协议（如 COCO 指标）说明；
• tpu_compatibility.md：哪些 pipeline 支持在 TPU 上训练；
• tf2_training_and_evaluation.md：训练与评估完整指南（CPU / GPU / TPU）。

上手路线建议：先用本文完成安装与自检 → 跑通 inference_tf2_colab.ipynb 感受推理效果 → 按 preparing_inputs.md 与 using_your_own_dataset.md 准备自有数据 → 参照 configs/tf2 示例配置 写好 pipeline config → 使用 model_main_tf2.py 启动训练与评估。这条路径也正是官方 few-shot 训练 Colab 背后的完整工作流。