README.md 7.19 KB
Newer Older
A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
1
![Logo](https://storage.googleapis.com/model_garden_artifacts/TF_Model_Garden.png)
2

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
3
# TensorFlow Official Models
4

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
5
6
7
8
The TensorFlow official models are a collection of models
that use TensorFlow’s high-level APIs.
They are intended to be well-maintained, tested, and kept up to date
with the latest TensorFlow API.
A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
9

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
10
11
12
13
They should also be reasonably optimized for fast performance while still
being easy to read.
These models are used as end-to-end tests, ensuring that the models run
with the same or improved speed and performance with each new TensorFlow build.
14

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
15
## More models to come!
16

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
17
18
19
The team is actively developing new models.
In the near future, we will add:

20
21
* State-of-the-art language understanding models.
* State-of-the-art image classification models.
bhack's avatar
bhack committed
22
* State-of-the-art object detection and instance segmentation models.
A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
23
24

## Table of Contents
25

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
26
27
28
29
30
31
32
33
34
- [Models and Implementations](#models-and-implementations)
  * [Computer Vision](#computer-vision)
    + [Image Classification](#image-classification)
    + [Object Detection and Segmentation](#object-detection-and-segmentation)
  * [Natural Language Processing](#natural-language-processing)
  * [Recommendation](#recommendation)
- [How to get started with the official models](#how-to-get-started-with-the-official-models)

## Models and Implementations
Hongkun Yu's avatar
Hongkun Yu committed
35

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
36
### Computer Vision
Hongkun Yu's avatar
Hongkun Yu committed
37

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
38
39
40
41
42
#### Image Classification

| Model | Reference (Paper) |
|-------|-------------------|
| [MNIST](vision/image_classification) | A basic model to classify digits from the [MNIST dataset](http://yann.lecun.com/exdb/mnist/) |
43
| [ResNet](vision/beta/MODEL_GARDEN.md) | [Deep Residual Learning for Image Recognition](https://arxiv.org/abs/1512.03385) |
44
| [ResNet-RS](vision/beta/MODEL_GARDEN.md) | [Revisiting ResNets: Improved Training and Scaling Strategies](https://arxiv.org/abs/2103.07579) |
45
| [EfficientNet](vision/image_classification) | [EfficientNet: Rethinking Model Scaling for Convolutional Neural Networks](https://arxiv.org/abs/1905.11946) |
Xianzhi Du's avatar
Xianzhi Du committed
46
| [Vision Transformer](vision/beta/MODEL_GARDEN.md) | [An Image is Worth 16x16 Words: Transformers for Image Recognition at Scale](https://arxiv.org/abs/2010.11929) |
47

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
48
#### Object Detection and Segmentation
49

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
50
51
| Model | Reference (Paper) |
|-------|-------------------|
52
53
| [RetinaNet](vision/beta/MODEL_GARDEN.md) | [Focal Loss for Dense Object Detection](https://arxiv.org/abs/1708.02002) |
| [Mask R-CNN](vision/beta/MODEL_GARDEN.md) | [Mask R-CNN](https://arxiv.org/abs/1703.06870) |
54
| [ShapeMask](vision/detection) | [ShapeMask: Learning to Segment Novel Objects by Refining Shape Priors](https://arxiv.org/abs/1904.03239) |
55
| [SpineNet](vision/beta/MODEL_GARDEN.md) | [SpineNet: Learning Scale-Permuted Backbone for Recognition and Localization](https://arxiv.org/abs/1912.05027) |
Xianzhi Du's avatar
Xianzhi Du committed
56
| [Cascade RCNN-RS and RetinaNet-RS](vision/beta/MODEL_GARDEN.md) | [Simple Training Strategies and Model Scaling for Object Detection](https://arxiv.org/abs/2107.00057)|
A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
57
58

### Natural Language Processing
59

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
60
61
| Model | Reference (Paper) |
|-------|-------------------|
62
63
| [ALBERT (A Lite BERT)](nlp/MODEL_GARDEN.md#available-model-configs) | [ALBERT: A Lite BERT for Self-supervised Learning of Language Representations](https://arxiv.org/abs/1909.11942) |
| [BERT (Bidirectional Encoder Representations from Transformers)](nlp/MODEL_GARDEN.md#available-model-configs) | [BERT: Pre-training of Deep Bidirectional Transformers for Language Understanding](https://arxiv.org/abs/1810.04805) |
Yuexin Wu's avatar
Yuexin Wu committed
64
| [NHNet (News Headline generation model)](projects/nhnet) | [Generating Representative Headlines for News Stories](https://arxiv.org/abs/2001.09386) |
65
| [Transformer](nlp/MODEL_GARDEN.md#available-model-configs) | [Attention Is All You Need](https://arxiv.org/abs/1706.03762) |
A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
66
| [XLNet](nlp/xlnet) | [XLNet: Generalized Autoregressive Pretraining for Language Understanding](https://arxiv.org/abs/1906.08237) |
67
| [MobileBERT](projects/mobilebert) | [MobileBERT: a Compact Task-Agnostic BERT for Resource-Limited Devices](https://arxiv.org/abs/2004.02984) |
68

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
69
70
### Recommendation

71
72
73
74
75
Model                            | Reference (Paper)
-------------------------------- | -----------------
[DLRM](recommendation/ranking)   | [Deep Learning Recommendation Model for Personalization and Recommendation Systems](https://arxiv.org/abs/1906.00091)
[DCN v2](recommendation/ranking) | [Improved Deep & Cross Network and Practical Lessons for Web-scale Learning to Rank Systems](https://arxiv.org/abs/2008.13535)
[NCF](recommendation)            | [Neural Collaborative Filtering](https://arxiv.org/abs/1708.05031)
A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
76
77

## How to get started with the official models
Hongkun Yu's avatar
Hongkun Yu committed
78

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
79
80
81
82
83
84
85
86
* The models in the master branch are developed using TensorFlow 2,
and they target the TensorFlow [nightly binaries](https://github.com/tensorflow/tensorflow#installation)
built from the
[master branch of TensorFlow](https://github.com/tensorflow/tensorflow/tree/master).
* The stable versions targeting releases of TensorFlow are available
as tagged branches or [downloadable releases](https://github.com/tensorflow/models/releases).
* Model repository version numbers match the target TensorFlow release,
such that
Hongkun Yu's avatar
Hongkun Yu committed
87
[release v2.5.0](https://github.com/tensorflow/models/releases/tag/v2.5.0)
Vishnuvardhan Janapati's avatar
Vishnuvardhan Janapati committed
88
is compatible with
Hongkun Yu's avatar
Hongkun Yu committed
89
[TensorFlow v2.5.0](https://github.com/tensorflow/tensorflow/releases/tag/v2.5.0).
Hongkun Yu's avatar
Hongkun Yu committed
90

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
91
Please follow the below steps before running models in this repository.
92

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
93
### Requirements
94

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
95
* The latest TensorFlow Model Garden release and TensorFlow 2
Hongkun Yu's avatar
Hongkun Yu committed
96
  * If you are on a version of TensorFlow earlier than 2.2, please
A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
97
upgrade your TensorFlow to [the latest TensorFlow 2](https://www.tensorflow.org/install/).
Hongkun Yu's avatar
Hongkun Yu committed
98

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
99
100
101
```shell
pip3 install tf-nightly
```
Hongkun Yu's avatar
Hongkun Yu committed
102

Hongkun Yu's avatar
Hongkun Yu committed
103
104
105
106
107
* Python 3.7+

Our integration tests run with Python 3.7. Although Python 3.6 should work, we
don't recommend earlier versions.

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
108
### Installation
Hongkun Yu's avatar
Hongkun Yu committed
109

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
110
#### Method 1: Install the TensorFlow Model Garden pip package
Hongkun Yu's avatar
Hongkun Yu committed
111

112
113
**tf-models-official** is the stable Model Garden package.
pip will install all models and dependencies automatically.
114

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
115
```shell
116
pip install tf-models-official
A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
117
```
118

Chen Chen's avatar
Chen Chen committed
119
120
121
122
123
124
If you are using nlp packages, please also install **tensorflow-text**:

```shell
pip install tensorflow-text
```

125
Please check out our [example](https://github.com/tensorflow/text/blob/master/docs/tutorials/fine_tune_bert.ipynb)
A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
126
to learn how to use a PIP package.
127

128
129
130
131
132
133
134
135
Note that **tf-models-official** may not include the latest changes in this
github repo. To include latest changes, you may install **tf-models-nightly**,
which is the nightly Model Garden package created daily automatically.

```shell
pip install tf-models-nightly
```

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
136
#### Method 2: Clone the source
137

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
138
1. Clone the GitHub repository:
139

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
140
141
142
```shell
git clone https://github.com/tensorflow/models.git
```
143

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
144
2. Add the top-level ***/models*** folder to the Python path.
145

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
146
147
148
```shell
export PYTHONPATH=$PYTHONPATH:/path/to/models
```
149

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
150
If you are using a Colab notebook, please set the Python path with os.environ.
151

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
152
153
154
155
```python
import os
os.environ['PYTHONPATH'] += ":/path/to/models"
```
156

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
157
3. Install other dependencies
158

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
159
160
161
```shell
pip3 install --user -r official/requirements.txt
```
Hongkun Yu's avatar
Hongkun Yu committed
162

Chen Chen's avatar
Chen Chen committed
163
164
165
166
167
168
169
Finally, if you are using nlp packages, please also install
**tensorflow-text-nightly**:

```shell
pip3 install tensorflow-text-nightly
```

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
170
## Contributions
171

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
172
If you want to contribute, please review the [contribution guidelines](https://github.com/tensorflow/models/wiki/How-to-contribute).