TF-Vision Model Garden 实战指南：TensorFlow Models 仓库中图像分类、检测、分割与视频识别的模型架构与训练体系

TF-Vision（official/vision）是 TensorFlow Models 仓库中的视觉模型花园，提供图像分类、目标检测/实例分割、语义分割与视频分类四大任务的基线实现与预训练检查点。本文基于 官方 README 及仓库源码，完整梳理其 Backbones/Decoders/Heads 组件体系、各任务基线的训练设置与精度指标、YAML 实验配置的实际字段含义，以及通过 train.py 驱动一次完整训练或复现检查点的标准流程，帮助开发者既能直接复用检查点，也能理解其背后的架构与训练配方并从源码级深度进行定制。

一、组件化架构：Backbones、Decoders 与 Heads

TF-Vision 的核心设计理念是将视觉模型拆分为三类可独立替换的组件，再组合成完整任务模型。README 列出的组件清单与仓库源码目录一一对应：

Backbones（特征主干），实现位于 official/vision/modeling/backbones：

Backbone	源码文件
DilatedResNet（空洞卷积 ResNet，用于 DeepLab 分割）	resnet_deeplab.py
EfficientNet	efficientnet.py
MobileDet	mobiledet.py
MobileNet	mobilenet.py
ResNet / ResNet-RS	resnet.py
ResNet3D（视频任务 R3D）	resnet_3d.py
RevNet（可逆网络）	revnet.py
SpineNet（NAS 搜索得到的检测主干）	spinenet.py
SpineNetMobile	spinenet_mobile.py
VisionTransformer（ViT）	vit.py

Decoders（特征解码器），实现位于 official/vision/modeling/decoders：ASPP（aspp.py）、FPN（fpn.py）、NASFPN（nasfpn.py）。

Heads（任务头），实现位于 official/vision/modeling/heads：DetectionHead、MaskHead、MaskScoring、RPNHead、RetinaNetHead、SegmentationHead，分别定义在 dense_prediction_heads.py、instance_heads.py 与 segmentation_heads.py 中。

从源码结构看，组件如何被"组装"成任务模型可以清晰地在 工厂文件 factory.py 中看到：

• build_classification_model()：仅构建 backbone 并接上 ClassificationModel 分类头；
• build_retinanet()：backbone → decoder → RetinaNetHead → MultilevelDetectionGenerator（含 NMS 后处理），并注入 anchor 配置（min_level、max_level、num_scales、aspect_ratios、anchor_size）；
• build_maskrcnn()：backbone → decoder → RPNHead → MultilevelROIGenerator/ROISampler/MultilevelROIAligner → DetectionHead（cascade_iou_thresholds 非空时自动级联多组检测头，即 Cascade R-CNN）→ 可选 MaskHead；
• build_segmentation_model()：backbone → decoder（ASPP 等）→ SegmentationHead，可选接 MaskScoring 头（即 DeepLabV3+ 的低层特征融合路径）。

这一工厂模式意味着：任何 YAML 配置文件中 backbone.type、decoder.type、head 字段的组合，最终都会落到上述工厂函数中实例化对应的组件。

二、训练入口与命令行参数

所有基线的训练统一由 official/vision/train.py 驱动。该入口的调用链为：解析 gin 参数 → train_utils.parse_configuration(FLAGS) 生成实验参数 → 按 distribution_strategy 建立分布策略（TPU/GPU/单机）→ task_factory.get_task() 取注册的任务 → train_lib.run_experiment() 执行训练。三个必选命令行标志（由 flags.mark_flags_as_required(['experiment', 'mode', 'model_dir']) 指定）为：

• --experiment：注册表中的实验名（对应 official/vision/configs/experiments/ 下的 YAML 文件，例如 imagenet_resnet50_tpu）；
• --mode：运行模式，取值包括 train、eval、train_and_eval、continuous_eval、continuous_train_and_eval 等（定义于 official/common/flags.py）；
• --model_dir：检查点与摘要输出目录。

此外还支持 --config_file（多个 YAML/JSON 覆盖文件，按命令行顺序生效）与 --params_override（在 config_file 之后做最终覆盖，适合微调 global_batch_size 等少量参数）、--tpu（Cloud TPU 名称或 grpc://ip:8470 地址）等（详见 flags.py）。典型调用形如：

python official/vision/train.py \
  --experiment=imagenet_resnet50_tpu \
  --mode=train \
  --model_dir=./model_dir \
  --tpu=grpc://your-tpu-vm:8470

值得注意的工程细节是 train.py 中的 _run_experiment_with_preemption_recovery()（train.py）：训练捕获 TPU 抢占导致的 OpError 后会自动从最近检查点恢复，这对长周期（350 epoch 级）的 TPU 实验很关键；同时 --enable_async_checkpointing 默认开启，以异步方式写检查点减少训练阻塞。

三、图像分类基线

3.1 常规设置训练的 ResNet

README 说明：模型从 scratch 训练，batch size 4096、初始学习率 1.6，前 5 个 epoch 线性 warmup，采用 L2 权重正则与 ReLU 激活。ImageNet-2012 基线指标如下（Top-1 / Top-5，%）：

| Model | Resolution | Epochs | Top-1 | Top-5 | 配置文件 | | --- | :-: | -: | :-: | --- | | ResNet-50 | 224x224 | 90 | 76.1 | 92.9 | imagenet_resnet50_tpu.yaml | | ResNet-50 | 224x224 | 200 | 77.1 | 93.5 | 同上 | | ResNet-101 | 224x224 | 200 | 78.3 | 94.2 | imagenet_resnet101_tpu.yaml | | ResNet-152 | 224x224 | 200 | 78.7 | 94.3 | imagenet_resnet152_tpu.yaml |

对照 imagenet_resnet50_tpu.yaml 可以看到上述设置如何落到具体字段：

runtime:
  distribution_strategy: 'tpu'
  mixed_precision_dtype: 'bfloat16'   # TPU 下使用 bfloat16 混合精度
task:
  model:
    num_classes: 1001                  # 1000 类 + 1 个无背景类占位
    input_size: [224, 224, 3]
    backbone:
      type: 'resnet'
      resnet:
        model_id: 50
  losses:
    l2_weight_decay: 0.0001
    one_hot: true
    label_smoothing: 0.1
  train_data:
    global_batch_size: 4096
    dtype: 'bfloat16'
trainer:
  train_steps: 28080                   # 90 epoch × 312 步/epoch
  optimizer_config:
    optimizer:
      type: 'sgd'
      sgd:
        momentum: 0.9
    learning_rate:
      type: 'stepwise'
      stepwise:
        boundaries: [9360, 18720, 24960]  # 30/60/80 epoch 处衰减
        values: [1.6, 0.16, 0.016, 0.0016]
    warmup:
      type: 'linear'
      linear:
        warmup_steps: 1560             # 5 epoch 线性 warmup

可见"1.6 初始学习率、5 epoch 线性 warmup、L2 正则"分别对应 stepwise.values 首值、warmup_steps（1560 = 5 × 312）与 l2_weight_decay 字段；steps_per_loop: 312 对应约 1 个 epoch 的步数，学习率边界恰好落在训练总量的 1/3、2/3、8/9 处。

3.2 ResNet-RS 及其训练配方

仓库支持 ResNet-RS（Revisiting ResNets）系列模型，并叠加了以下训练增强（README 原文列点）：

• ResNet-RS 的架构变更 + Swish 激活（注意：原论文采用 ReLU）；
• 正则化组合：RandomAugment、4e-5 权重衰减、Stochastic Depth、label smoothing、dropout；
• 350-epoch 训练调度、cosine 学习率、EMA（指数滑动平均）。

ImageNet 基线指标（Params 单位为 M）：

Model	Resolution	Params (M)	Top-1	Top-5	配置文件
ResNet-RS-50	160x160	35.7	79.1	94.5	imagenet_resnetrs50_i160.yaml
ResNet-RS-101	160x160	63.7	80.2	94.9	imagenet_resnetrs101_i160.yaml
ResNet-RS-101	192x192	63.7	81.3	95.6	imagenet_resnetrs101_i192.yaml
ResNet-RS-152	192x192	86.8	81.9	95.8	imagenet_resnetrs152_i192.yaml
ResNet-RS-152	224x224	86.8	82.5	96.1	imagenet_resnetrs152_i224.yaml
ResNet-RS-152	256x256	86.8	83.1	96.3	imagenet_resnetrs152_i256.yaml
ResNet-RS-200	256x256	93.4	83.5	96.6	imagenet_resnetrs200_i256.yaml
ResNet-RS-270	256x256	130.1	83.6	96.6	imagenet_resnetrs270_i256.yaml
ResNet-RS-350	256x256	164.3	83.7	96.7	imagenet_resnetrs350_i256.yaml
ResNet-RS-350	320x320	164.3	84.2	96.9	imagenet_resnetrs350_i320.yaml

以 imagenet_resnetrs152_i224.yaml 为例，"RS"配方在 YAML 中的落点非常明确：resnet.se_ratio: 0.25（SE 模块）、replace_stem_max_pool: true 与 resnetd_shortcut: true（架构变更）、norm_activation.activation: 'swish'、losses.l2_weight_decay: 0.00004（即 4e-5）、aug_type: randaug（magnitude 15）、learning_rate: cosine（initial 1.6、decay_steps 109200 = 350 epoch × 312）以及 optimizer_config.ema.average_decay: 0.9999。这些字段共同构成了 README 中列出的训练特性清单；stochastic_depth_drop_rate 同样在该配置中暴露，可按需开启。

3.3 Vision Transformer (ViT) / DEIT

仓库同时提供 ViT 与 DEIT 实现，以下检查点在 DEIT 训练设置下训练（224x224 输入，ImageNet-2012，Top-1 / Top-5，%）：

Model	Resolution	Top-1	Top-5
ViT-ti16	224x224	73.4	91.9
ViT-s16	224x224	79.4	94.7
ViT-b16	224x224	81.8	95.8
ViT-l16	224x224	82.2	95.8

对应的训练配置在 image_classification 目录 下均有同名 YAML，例如 imagenet_vitb16_i224_tpu.yaml（另含 i384 分辨率与 GPU 变体）。ViT 主干本身由 vit.py 与 vit_specs.py 定义。

四、目标检测与实例分割基线

4.1 通用训练设置

README 对该组基线的共性约定如下（后续各表均适用）：

• 采用 ResNet-FPN 与 SpineNet 两类 backbone，覆盖 RetinaNet、RetinaNet-RS、Mask R-CNN、Cascade RCNN 及其 -RS 变体等检测框架；
• 全部模型在 COCO train2017 上训练、COCO val2017 上评估。检查点基于 COCO Consortium 持有版权的标注（CC-BY 4.0 许可）；图片版权归 Flickr 用户所有，使用者自行承担责任；
• 从 ImageNet 预训练权重微调的模型采用 12/36 epoch 调度；从 scratch 训练的采用长周期调度（表中为 350~600 epoch）；
• 默认数据增强为水平翻转 + 随机缩放（scale 在 0.5~2.0 之间）；
• 默认 L2 权重正则与 ReLU 激活；
• batch size 256，stepwise 学习率，在最后 30 与 10 个 epoch 处衰减；
• 输入为方形图像：将长边缩放到目标尺寸，短边补零。

以 SpineNet-49 的 coco_spinenet49_tpu.yaml 为例验证上述约定：global_batch_size: 256、parser.aug_rand_hflip: true 与 aug_scale_min/max、l2_weight_decay: 4.0e-05、stepwise 学习率 values: [0.32, 0.032, 0.0032] 在 boundaries: [219450, 226380]（总步数 231000，即 500 epoch × 462 步）处衰减——恰好对应"最后 30 与 10 个 epoch"。该配置同时暴露了 anchor 设置（anchor_size: 3、aspect_ratios: [0.5, 1.0, 2.0]、num_scales: 3）、特征层级（min_level: 3、max_level: 7）与 spinenet.stochastic_depth_drop_rate: 0.2 等模型级参数。

4.2 COCO 检测：RetinaNet（ImageNet 预训练）

Backbone	Resolution	Epochs	FLOPs (B)	Params (M)	Box AP
R50-FPN	640x640	12	97.0	34.0	34.3
R50-FPN	640x640	72	97.0	34.0	36.8

对应配置可参考 resnet50fpn_coco_tfds_tpu.yaml。

4.3 COCO 检测：RetinaNet（从 scratch 训练）

README 注明该组额外启用了 Stochastic Depth（drop rate 0.2）与 Swish 激活：

Backbone	Resolution	Epochs	FLOPs (B)	Params (M)	Box AP
SpineNet-49	640x640	500	85.4	28.5	44.2
SpineNet-96	1024x1024	500	265.4	43.0	48.5
SpineNet-143	1280x1280	500	524.0	67.0	50.0

配置文件分别为 coco_spinenet49_tpu.yaml、coco_spinenet96_tpu.yaml、coco_spinenet143_tpu.yaml。

4.4 移动端 RetinaNet（从 scratch 训练）

Backbone	Resolution	Epochs	FLOPs (B)	Params (M)	Box AP
MobileNetv2	256x256	600	-	2.27	23.5
Mobile SpineNet-49	384x384	600	1.0	2.32	28.1

配置见 coco_mobilenetv2_tpu.yaml 与 coco_spinenet49_mobile_tpu.yaml。

4.5 YOLOv7（从 scratch 训练）

Variant	Resolution	Epochs	FLOPs (B)	Params (M)	Box AP
YOLOv7	640x640	300	53.16	44.57	50.5

配置位于 YOLO 项目目录：yolov7.yaml。

4.6 实例分割：Mask R-CNN（从 scratch 训练）

Backbone	Resolution	Epochs	FLOPs (B)	Params (M)	Box AP	Mask AP
ResNet50-FPN	640x640	350	227.7	46.3	42.3	37.6
SpineNet-49	640x640	350	215.7	40.8	42.6	37.9
SpineNet-96	1024x1024	500	315.0	55.2	48.1	42.4
SpineNet-143	1280x1280	500	498.8	79.2	49.3	43.4

配置文件见 maskrcnn 目录，如 r50fpn_640_coco_scratch_tpu4x4.yaml、coco_spinenet49_mrcnn_tpu.yaml。

4.7 实例分割：Cascade RCNN-RS（从 scratch 训练）

Backbone	Resolution	Epochs	Params (M)	Box AP	Mask AP
SpineNet-49	640x640	500	56.4	46.4	40.0
SpineNet-96	1024x1024	500	70.8	50.9	43.8
SpineNet-143	1280x1280	500	94.9	51.9	45.0

配置文件见 coco_spinenet49_cascadercnn_tpu.yaml、coco_spinenet96_cascadercnn_tpu.yaml、coco_spinenet143_cascadercnn_tpu.yaml。从源码结构看，"Cascade"在实现层由 roi_sampler.cascade_iou_thresholds 触发：factory.py 的 build_maskrcnn 会为每个级联 IoU 阈值复制一组 DetectionHead 与 ROISampler，逐级收紧正样本标准，这正是 Cascade R-CNN 的核心机制。

五、语义分割：DeepLabV3 / DeepLabV3+

仓库支持 DeepLabV3 与 DeepLabV3+ 架构，backbone 为 Dilated ResNet（空洞 ResNet，resnet_deeplab.py），且 backbone 均在 ImageNet 上预训练。

PASCAL-VOC（输入 512x512，训练 30k steps）：

Model	Backbone	Resolution	Steps	mIoU
DeepLabV3	Dilated ResNet-101	512x512	30k	78.7
DeepLabV3+	Dilated ResNet-101	512x512	30k	79.2

CITYSCAPES：

Model	Backbone	Resolution	Steps	mIoU
DeepLabV3+	Dilated ResNet-101	1024x2048	90k	78.79

CITYSCAPES 对应配置为 deeplabv3plus_resnet101_cityscapes_gpu.yaml（另含 TPU 变体），ImageNet 预训练阶段配置可参考 imagenet_resnet101_deeplab_tpu.yaml。DeepLabV3 的空洞率（rate）设置与 ASPP 模块分别位于 layers/deeplab.py 与 decoders/aspp.py，DeepLabV3+ 的"低层特征融合"则通过 SegmentationHead 的 feature_fusion/low_level 参数开启。

六、视频分类：Kinetics-400 / 600 基线

6.1 支持的 backbone 与通用设置

README 列出四类视频 backbone 及其出处论文：

• SlowOnly（SlowFast Networks for Video Recognition）；
• ResNet-3D（R3D，Spatiotemporal Contrastive Video Representation Learning）；
• ResNet-3D-RS（R3D-RS，Revisiting 3D ResNets）；
• MoViNets（移动端视频网络）。

通用训练设置：所有模型从 scratch 用 RGB 视觉模态训练 200 epochs；batch size 1024，cosine 学习率衰减，前 5 个 epoch 线性 warmup；评估遵循 SlowFast 的 30-view 协议（10 crop × 3 采样位置）。

6.2 Kinetics-400 动作识别基线

输入格式为 帧数 x 帧间隔(stride)，Top-1 / Top-5（%）：

Model	Input	Top-1	Top-5	配置文件
SlowOnly	8 x 8	74.1	91.4	k400_slowonly8x8_tpu.yaml
SlowOnly	16 x 4	75.6	92.1	k400_slowonly16x4_tpu.yaml
R3D-50	32 x 2	77.0	93.0	k400_3d-resnet50_tpu.yaml
R3D-RS-50	32 x 2	78.2	93.7	k400_resnet3drs_50_tpu.yaml
R3D-RS-101	32 x 2	79.5	94.2	-
R3D-RS-152	32 x 2	79.9	94.3	-
R3D-RS-200	32 x 2	80.4	94.4	-
R3D-RS-200	48 x 2	81.0	-	-
MoViNet-A0-Base	50 x 5	69.40	89.18	-
MoViNet-A1-Base	50 x 5	74.57	92.03	-
MoViNet-A2-Base	50 x 5	75.91	92.63	-
MoViNet-A3-Base	120 x 2	79.34	94.52	-
MoViNet-A4-Base	80 x 3	80.64	94.93	-
MoViNet-A5-Base	120 x 2	81.39	95.06	-

6.3 Kinetics-600 动作识别基线

Model	Input	Top-1	Top-5	配置文件
SlowOnly	8 x 8	77.3	93.6	k600_slowonly8x8_tpu.yaml
R3D-50	32 x 2	79.5	94.8	k600_3d-resnet50_tpu.yaml
R3D-RS-200	32 x 2	83.1	-	-
R3D-RS-200	48 x 2	83.8	-	-
MoViNet-A0-Base	50 x 5	72.05	90.92	movinet_a0_k600_8x8.yaml
MoViNet-A1-Base	50 x 5	76.69	93.40	movinet_a1_k600_8x8.yaml
MoViNet-A2-Base	50 x 5	78.62	94.17	movinet_a2_k600_8x8.yaml
MoViNet-A3-Base	120 x 2	81.79	95.67	movinet_a3_k600_8x8.yaml
MoViNet-A4-Base	80 x 3	83.48	96.16	movinet_a4_k600_8x8.yaml
MoViNet-A5-Base	120 x 2	84.27	96.39	movinet_a5_k600_8x8.yaml

视频任务模型由 video_classification_model.py 与 factory_3d.py 组装，R3D 主干见 resnet_3d.py，MoViNet 系列独立位于 official/projects/movinet 项目下。

七、检查点获取与许可注意事项

README 明确了两条许可声明，使用者务必知悉：

• 所有检查点基于公开数据集训练得到。部分数据集带有使用限制（包括非商业用途限制），使用前应审阅第三方提供的条款；检查点本身以 Apache 2.0 许可发布；
• README 中链接的数据集并非由 Google 拥有或分发，均由第三方提供，数据集使用者需自行遵守相应条款。COCO 检查点的标注版权归 COCO Consortium 所有（CC-BY 4.0），而图片版权归 Flickr 用户所有。

各表中列出的检查点以 tar.gz 压缩包形式托管在官方 Google Cloud Storage 上（README 的 Download 列给出了具体下载地址）；训练任何基线时，只需使用上文对应的 YAML 配置文件与 official/vision/train.py 入口，即可完全复现 README 声明的训练设置。

八、扩展阅读：从零搭建一个新的视觉项目

README 末尾指引读者参考 examples/starter 示例。该示例以分类任务为例，演示如何基于 TF Model Garden 的构件搭建新视觉项目，包含五个可运行的参考文件：

• example_model.py：定义 tf.keras.Model 子类与 build_example_model 工厂函数；
• example_input.py：自定义 Decoder（声明 tf.Example 字段，如 image/encoded、image/class/label）与 Parser（实现 _parse_train_data / _parse_eval_data，完成解码、增强与缩放）；
• example_config.py：以 dataclass 定义数据配置、模型配置（继承 hyperparams.Config）、Loss/Evaluation 配置并聚合为 Task 配置；
• example_config_local.yaml / example_config_tpu.yaml：本地 GPU 与 TPU 两套实验配置；
• train.py：复用 official.vision.train.main 作为驱动，仅通过 registry_imports.py 注册自定义构件。

其整体流程与主线一致：YAML 配置 → train.py 解析 → 工厂函数按配置实例化 backbone/decoder/head → 分布式训练循环。理解了 starter 与 factory.py 的对应关系，即可将仓库中任一直线配置（如 configs 目录 下的实验文件）当作可执行的训练说明书来阅读和改造。