README.md 7.51 KB
Newer Older
Hongkun Yu's avatar
Hongkun Yu committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
# Copyright 2021 The TensorFlow Authors. All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
15
![Logo](https://storage.googleapis.com/model_garden_artifacts/TF_Model_Garden.png)
16

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
17
# TensorFlow Official Models
18

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
19
20
21
22
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
23

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
24
25
26
27
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.
28

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
29
## More models to come!
30

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

34
35
* State-of-the-art language understanding models.
* State-of-the-art image classification models.
bhack's avatar
bhack committed
36
* State-of-the-art object detection and instance segmentation models.
A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
37
38

## Table of Contents
39

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
40
41
42
43
44
45
46
47
48
- [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
49

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
50
### Computer Vision
Hongkun Yu's avatar
Hongkun Yu committed
51

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
52
53
54
55
56
57
#### 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/) |
| [ResNet](vision/image_classification) | [Deep Residual Learning for Image Recognition](https://arxiv.org/abs/1512.03385) |
58
| [ResNet-RS](vision/beta/MODEL_GARDEN.md) | [Revisiting ResNets: Improved Training and Scaling Strategies](https://arxiv.org/abs/2103.07579) |
59
| [EfficientNet](vision/image_classification) | [EfficientNet: Rethinking Model Scaling for Convolutional Neural Networks](https://arxiv.org/abs/1905.11946) |
60

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
61
#### Object Detection and Segmentation
62

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
63
64
65
66
| Model | Reference (Paper) |
|-------|-------------------|
| [RetinaNet](vision/detection) | [Focal Loss for Dense Object Detection](https://arxiv.org/abs/1708.02002) |
| [Mask R-CNN](vision/detection) | [Mask R-CNN](https://arxiv.org/abs/1703.06870) |
67
| [ShapeMask](vision/detection) | [ShapeMask: Learning to Segment Novel Objects by Refining Shape Priors](https://arxiv.org/abs/1904.03239) |
68
| [SpineNet](vision/detection) | [SpineNet: Learning Scale-Permuted Backbone for Recognition and Localization](https://arxiv.org/abs/1912.05027) |
A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
69
70

### Natural Language Processing
71

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
72
73
74
75
76
77
78
| Model | Reference (Paper) |
|-------|-------------------|
| [ALBERT (A Lite BERT)](nlp/albert) | [ALBERT: A Lite BERT for Self-supervised Learning of Language Representations](https://arxiv.org/abs/1909.11942) |
| [BERT (Bidirectional Encoder Representations from Transformers)](nlp/bert) | [BERT: Pre-training of Deep Bidirectional Transformers for Language Understanding](https://arxiv.org/abs/1810.04805) |
| [NHNet (News Headline generation model)](nlp/nhnet) | [Generating Representative Headlines for News Stories](https://arxiv.org/abs/2001.09386) |
| [Transformer](nlp/transformer) | [Attention Is All You Need](https://arxiv.org/abs/1706.03762) |
| [XLNet](nlp/xlnet) | [XLNet: Generalized Autoregressive Pretraining for Language Understanding](https://arxiv.org/abs/1906.08237) |
79
| [MobileBERT](nlp/projects/mobilebert) | [MobileBERT: a Compact Task-Agnostic BERT for Resource-Limited Devices](https://arxiv.org/abs/2004.02984) |
80

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
81
82
### Recommendation

83
84
85
86
87
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
88
89

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

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
91
92
93
94
95
96
97
98
* 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
99
[release v2.2.0](https://github.com/tensorflow/models/releases/tag/v2.2.0)
A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
100
are compatible with
Hongkun Yu's avatar
Hongkun Yu committed
101
[TensorFlow v2.2.0](https://github.com/tensorflow/tensorflow/releases/tag/v2.2.0).
Hongkun Yu's avatar
Hongkun Yu committed
102

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

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
105
### Requirements
106

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

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
111
112
113
```shell
pip3 install tf-nightly
```
Hongkun Yu's avatar
Hongkun Yu committed
114

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
115
### Installation
Hongkun Yu's avatar
Hongkun Yu committed
116

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

119
120
**tf-models-official** is the stable Model Garden package.
pip will install all models and dependencies automatically.
121

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
122
```shell
123
pip install tf-models-official
A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
124
```
125

Chen Chen's avatar
Chen Chen committed
126
127
128
129
130
131
If you are using nlp packages, please also install **tensorflow-text**:

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

Jared T Nielsen's avatar
Jared T Nielsen committed
132
Please check out our [example](colab/fine_tuning_bert.ipynb)
A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
133
to learn how to use a PIP package.
134

135
136
137
138
139
140
141
142
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
143
#### Method 2: Clone the source
144

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
145
1. Clone the GitHub repository:
146

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
147
148
149
```shell
git clone https://github.com/tensorflow/models.git
```
150

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

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
153
154
155
```shell
export PYTHONPATH=$PYTHONPATH:/path/to/models
```
156

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

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
159
160
161
162
```python
import os
os.environ['PYTHONPATH'] += ":/path/to/models"
```
163

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
164
3. Install other dependencies
165

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
166
167
168
```shell
pip3 install --user -r official/requirements.txt
```
Hongkun Yu's avatar
Hongkun Yu committed
169

Chen Chen's avatar
Chen Chen committed
170
171
172
173
174
175
176
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
177
## Contributions
178

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
179
If you want to contribute, please review the [contribution guidelines](https://github.com/tensorflow/models/wiki/How-to-contribute).
Hongkun Yu's avatar
Hongkun Yu committed
180
181
182
183
184
185
186

## Citing TF Official Model Garden

To cite this repository:

```
@software{tfmodels2020github,
A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
187
188
  author = {Chen Chen and Xianzhi Du and Le Hou and Jaeyoun Kim and Jing Li and
  Yeqing Li and Abdullah Rashwan and Fan Yang and Hongkun Yu},
Hongkun Yu's avatar
Hongkun Yu committed
189
190
191
192
193
  title = {TensorFlow Official Model Garden},
  url = {https://github.com/tensorflow/models/tree/master/official},
  year = {2020},
}
```