TensorFlow Official Models：tf-models 官方模型集的定位、模型版图与上手训练指南

本文基于 models 仓库中的 official/README.md 展开，系统梳理 TensorFlow 官方模型集（official models）的设计定位、已覆盖的计算机视觉 / 自然语言处理 / 推荐系统三大方向模型版图，以及版本号与 TensorFlow 发布的对应关系、依赖安装与训练入口，帮助你在当前仓库中正确安装 tf-models-official、定位各方向的训练驱动脚本，并理解其作为 TensorFlow 端到端基准的角色。

一、official models 是什么

official/README.md 对官方模型集给出了四条核心定位：

1. 基于 TensorFlow 高层 API 构建：所有模型都使用 TensorFlow 的高层 API（主要是 tf.keras 体系）编写；
2. 维护质量与 API 时效性：目标是 well-maintained、tested，并始终跟上最新的 TensorFlow API；
3. 性能与可读性兼顾：在保持代码易读的前提下做合理的性能优化；
4. 充当端到端测试基准：这些模型被用作 end-to-end tests，确保每一个新的 TensorFlow 构建都能以相同或更优的速度和性能跑通这些模型。

第 4 条决定了这个仓库的独特价值：它不只是一个"模型下载站"，而是 TensorFlow 自身的性能回归基准池。仓库内大量 *_test.py 文件（如 official/core/base_trainer_test.py、official/vision/README.md 所描述的各类模型配置）正是这一思路的落地。

README 同时声明团队持续扩充模型版图，规划方向包括最先进的语言理解模型、图像分类模型、目标检测与实例分割模型、视频分类模型——从仓库当前结构看，这些方向都已实际落地（见下文模型版图）。

二、模型与实现版图

官方 README 将模型版图组织为三大板块：Computer Vision、NLP 与 Recommendation，每一行都给出模型名与其参考论文。下面按原文档骨架完整继承该版图，并把原 README 中的相对链接转换为以仓库根目录为起点的可点击路径。

2.1 计算机视觉

子库入口为 official/vision/README.md，完整基线与检查点见 official/vision/MODEL_GARDEN.md。

图像分类

模型	参考论文
ResNet	Deep Residual Learning for Image Recognition
ResNet-RS	Revisiting ResNets: Improved Training and Scaling Strategies
EfficientNet	EfficientNet: Rethinking Model Scaling for Convolutional Neural Networks
Vision Transformer	An Image is Worth 16x16 Words: Transformers for Image Recognition at Scale

目标检测与分割

模型	参考论文
RetinaNet	Focal Loss for Dense Object Detection
Mask R-CNN	Mask R-CNN
YOLO	YOLOv7: Trainable bag-of-freebies sets new state-of-the-art for real-time object detectors
SpineNet	SpineNet: Learning Scale-Permuted Backbone for Recognition and Localization
Cascade RCNN-RS 与 RetinaNet-RS	Simple Training Strategies and Model Scaling for Object Detection

其中 YOLO 位于项目扩展区 official/projects/yolo/README.md。

视频分类

模型	参考论文
Mobile Video Networks (MoViNets)	MoViNets: Mobile Video Networks for Efficient Video Recognition

实现位于 official/projects/movinet/。

视觉子库的组件化设计可以在 official/vision/README.md 中进一步看到：它把模型拆成三层积木——Backbones（DilatedResNet、EfficientNet、MobileDet、MobileNet、ResNet、ResNet3D、RevNet、SpineNet、SpineNetMobile、VisionTransformer）、Decoders（ASPP、FPN、NASFPN）和 Heads（DetectionHead、MaskHead、MaskScoring、RPNHead、RetinaNetHead、SegmentationHead）。"骨干 + 解码器 + 头"的正交组合正是 RetinaNet、Mask R-CNN、语义分割模型能共享同一套训练代码的原因。

2.2 自然语言处理

子库入口为 official/nlp/README.md，预训练基线配置见 official/nlp/MODEL_GARDEN.md。

预训练语言模型

模型	参考论文
ALBERT	ALBERT: A Lite BERT for Self-supervised Learning of Language Representations
BERT	BERT: Pre-training of Deep Bidirectional Transformers for Language Understanding
ELECTRA	ELECTRA: Pre-training Text Encoders as Discriminators Rather Than Generators（任务实现入口：official/nlp/tasks/electra_task.py）

神经机器翻译

模型	参考论文
Transformer	Attention Is All You Need

自然语言生成

模型	参考论文
NHNet（新闻标题生成）	Generating Representative Headlines for News Stories，实现见 official/projects/nhnet/README.md

知识蒸馏

模型	参考论文
MobileBERT	MobileBERT: a Compact Task-Agnostic BERT for Resource-Limited Devices，实现见 official/projects/mobilebert/README.md

NLP 子库 README 还说明了它的分层结构：official/nlp/modeling/ 提供可组装 Transformer 架构的 Layer / Network / Model 三级构建块（如 BertEncoder、AlbertEncoder、T5Transformer、BertClassifier 等），official/nlp/data/ 提供分词与输入预处理工具，并配有一个统一训练驱动 official/nlp/train.py（用法详见 official/nlp/docs/train.md）与预训练检查点文档 official/nlp/docs/pretrained_models.md。

2.3 推荐系统

模型	参考论文
DLRM	Deep Learning Recommendation Model for Personalization and Recommendation Systems，位于 official/recommendation/ranking/
DCN v2	Improved Deep & Cross Network and Practical Lessons for Web-scale Learning to Rank Systems，位于 official/recommendation/ranking/
NCF	Neural Collaborative Filtering，位于 official/recommendation/README.md

推荐子库包含两条线：

• NCF / NeuMF：基于 official/recommendation/neumf_model.py 的架构定义。其思路是用神经网络建模用户-物品交互，而非传统矩阵分解的内积：GMF 用线性核，MLP 用非线性核，NeuMF 将两者融合——允许 GMF 与 MLP 学习各自独立的 embedding，并通过拼接两者最后一层隐层来统一线性 MF 与非线性 MLP 的优势。支持在 MovieLens 数据集（ml-1m / ml-20m）上训练评估，数据下载预处理由 official/recommendation/movielens.py 完成（--data_dir 默认 /tmp/movielens-data/，--dataset 默认 ml-1m），训练与评估由 official/recommendation/ncf_keras_main.py 驱动（--model_dir、--data_dir、--dataset、--num_gpus 等参数，--num_gpus=0 时回退到 CPU）。
• DLRM / DCN v2：面向 CTR 预估等排序任务，输入为数值特征 + 类别特征，输出标量（如点击概率）。official/recommendation/ranking/README.md 说明其可在 GPU、TPU、CPU 上训练评估；TPU 路径上使用 TPU embedding 层承载大规模类别特征 embedding 表；训练支持合成数据（use_synthetic_data=True）或 Criteo Terabyte / Criteo Kaggle 真实数据集。

三、版本策略：nightly 与 stable 如何对应 TensorFlow

官方 README 的 "How to get started" 一节给出了两条安装路径，这一节直接决定你能用哪个版本的依赖，值得完整展开。

3.1 master 分支 → nightly

official 目录下的 master 分支代码是基于 TensorFlow 2 的 master 分支开发的。克隆仓库或直接 pip 安装 master 分支时，会以依赖形式拉取 TensorFlow 的 master 版本，等价于：

pip3 install tf-models-nightly
pip3 install tensorflow-text-nightly # 当模型使用 `nlp` 相关包时需要

这一机制在打包脚本 official/pip_package/setup.py 中可以找到直接证据：当 project_name 为 tf-models-nightly 时，脚本会把版本号改写为 x.(minor+1).0.dev<当日日期>，并向依赖列表追加 tf-nightly 与 tensorflow-text-nightly（见 setup.py）；nightly 的依赖清单读取自 official/nightly_requirements.txt，而 stable 版本读取 official/requirements.txt。

3.2 稳定版 → 与 TensorFlow 发布版本一一对应

对于针对特定发布的稳定版本，tf-models 仓库的版本号与目标 TensorFlow 的发布版本保持一致。例如 TensorFlow-models v2.8.x 对应 TensorFlow v2.8.x，等价于：

pip3 install tf-models-official==2.8.0
pip3 install tensorflow-text==2.8.0 # 当模型使用 `nlp` 相关包时需要

setup.py 中同样能印证这一设计：稳定分支在 install_requires 中写入 tensorflow~=2.20.0 与 tensorflow-text~=2.20.0（当前仓库中 version = '2.20.0'、tf_version = '2.20.0'，见 setup.py 与 setup.py），即该仓库快照与 TensorFlow 2.20.x 系列对齐。

3.3 2.9.x 之后的包名变化

从 2.9.x 发布开始，模型建模库以 tensorflow_models 包的形式发布，用户可以直接 import tensorflow_models 访问导出符号。当前仓库根目录下的 tensorflow_models/ 正是该包的源码：tensorflow_models/init.py 依次导出 nlp、uplift、vision 三个子模块。如果你在本地跑 master 分支代码或 nightly 包，README 建议以 GitHub 代码中的 docstring 为准。

四、环境要求与安装

4.1 运行前提

官方 README 的 Requirements 一节要求：

• 最新的 TensorFlow Model Garden 发布版 + 最新的 TensorFlow 2：如果你的 TensorFlow 低于 2.2，需要先升级；
• Python 3.7+：集成测试基于 Python 3.7 运行；Python 3.6 理论上可用但不推荐更早版本。

Python 下限在打包脚本中同样被固化：python_requires='>=3.7'（setup.py）。

4.2 三个可选的 PyPI 包

包	说明
tf-models-official	稳定发布版，版本号与 TensorFlow 发布对齐
tf-models-nightly	包含最新变更的每日构建，依赖 tf-nightly
tf-models-no-deps	依赖列表中不含 tensorflow 与 tensorflow-text，适合自行管控 TF 版本的用户

安装完成后，实际可用的第三方依赖以 official/requirements.txt 为准，关键条目包括：tf-keras、gin-config（配置系统）、tensorflow-hub、tensorflow-datasets、tensorflow-model-optimization、numpy>=1.20、pandas、CV 方向的 opencv-python-headless / Pillow / pycocotools，以及 NLP 方向的 seqeval、sentencepiece、sacrebleu 等。

五、统一训练框架：所有方向共享的底座

官方 README 虽然没有展开讲训练框架，但从源码结构看，各方向"统一的高层 API + 可复用底座"正是其定位的实现方式。

视觉方向的统一驱动为 official/vision/train.py，其 main 函数展示了标准调用链：

1. gin.parse_config_files_and_bindings(FLAGS.gin_file, FLAGS.gin_params) 解析 gin 配置（模型实验参数均以 YAML 组织，见 official/vision/configs/ 下大量 *.yaml）；
2. train_utils.parse_configuration(FLAGS) 把命令行标志合并为运行时参数；
3. distribute_utils.get_distribution_strategy(...) 依据 runtime.distribution_strategy、num_gpus、tpu 地址选择分布式策略（CPU / GPU / TPU）；
4. task_factory.get_task(params.task) 按注册表实例化任务，交由 official/core/train_lib.py 的 run_experiment 统一跑训练/评估循环。

此外该驱动还支持 TPU 抢占恢复（_run_experiment_with_preemption_recovery 在捕获到抢占 OpError 时从最近 checkpoint 续训）与混合精度（params.runtime.mixed_precision_dtype 可设为 mixed_float16 / mixed_bfloat16，GPU 用 float16、TPU 用 bfloat16，见 train.py）。

NLP 方向的 official/nlp/train.py 采用同一套 official.core 底座（task_factory + train_lib），配合 official/core/registry.py 的注册机制让新任务只需注册即可获得统一 CLI。通用训练逻辑位于 official/core/（base_task.py、base_trainer.py、exp_factory.py、train_lib.py 等），这正是 README 所说"每个新 TensorFlow 构建都能以相同或更优性能跑通这些模型"的测试基础设施。

Orbit 框架（仓库根目录 orbit/）则提供了另一条路径：orbit/README.md 与 orbit/standard_runner.py 面向"只需自定义模型构建与输入管道"的用户，用 tf.function 训练循环 + 可插拔 Action（checkpoint 保存、最佳指标导出 SavedModel 等）封装训练生命周期，示例见 orbit/examples/single_task/。

六、从示例与教程开始

官方 README 建议通过仓库自带的示例和教程入门，对应到本仓库即 docs/ 目录下的 Notebook 教程：

• NLP：docs/nlp/index.ipynb 及 fine_tune_bert.ipynb、customize_encoder.ipynb、decoding_api.ipynb 等，配套目录索引见 docs/nlp/_guide_toc.yaml；
• 视觉：docs/vision/image_classification.ipynb、object_detection.ipynb、semantic_segmentation.ipynb、instance_segmentation.ipynb，目录索引见 docs/vision/_toc.yaml；
• Orbit：docs/orbit/index.ipynb。

各子库 README 还指向各自更细化的文档，例如 NLP 的 official/nlp/docs/（train.md、pretrain.md、pretrained_models.md、optimization.md 等）与视觉的 official/vision/docs/，可作为深入阅读的入口。

七、小结

回到 official/README.md 的主线：official models 是 TensorFlow 仓库生态中"高层 API + 持续测试 + 性能与可读性兼顾"的官方模型集，覆盖 ResNet/ResNet-RS/EfficientNet/ViT、RetinaNet/Mask R-CNN/YOLOv7/SpineNet、MoViNets、BERT/ALBERT/ELECTRA/Transformer/NHNet/MobileBERT 以及 DLRM/DCN v2/NCF 等版图；安装上遵循"nightly 对 TF master、stable 版本号与 TF 发布一一对应（当前为 2.20.x）、2.9.x 起可直接 import tensorflow_models"的规则；训练上通过 gin 配置 + official.core 统一底座实现 CV / NLP 各方向的标准化调用。掌握这些，你既可以按模型版图定位目标模型的源码与配置，也能基于统一训练框架与教程 Notebook 快速开展复现或二次开发。