README.md 5.6 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
9
10
11
12
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.
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.
13

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
14
## Model Implementations
15

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
16
### Natural Language Processing
17

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
18
19
20
21
| Model | Description | Reference |
| ----- | ----------- | --------- |
| [ALBERT](nlp/albert) | A Lite BERT for Self-supervised Learning of Language Representations | [arXiv:1909.11942](https://arxiv.org/abs/1909.11942) |
| [BERT](nlp/bert) | A powerful pre-trained language representation model: BERT (Bidirectional Encoder Representations from Transformers) | [arXiv:1810.04805](https://arxiv.org/abs/1810.04805) |
22
| [NHNet](nlp/nhnet) | A transformer-based multi-sequence to sequence model: Generating Representative Headlines for News Stories | [arXiv:2001.09386](https://arxiv.org/abs/2001.09386) |
A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
23
24
| [Transformer](nlp/transformer) | A transformer model to translate the WMT English to German dataset | [arXiv:1706.03762](https://arxiv.org/abs/1706.03762) |
| [XLNet](nlp/xlnet) | XLNet: Generalized Autoregressive Pretraining for Language Understanding | [arXiv:1906.08237](https://arxiv.org/abs/1906.08237) |
Hongkun Yu's avatar
Hongkun Yu committed
25

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
26
### Computer Vision
Hongkun Yu's avatar
Hongkun Yu committed
27

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
28
29
30
31
32
| Model | Description | Reference |
| ----- | ----------- | --------- |
| [MNIST](vision/image_classification) | A basic model to classify digits from the MNIST dataset | [Link](http://yann.lecun.com/exdb/mnist/) |
| [ResNet](vision/image_classification) | A deep residual network for image recognition | [arXiv:1512.03385](https://arxiv.org/abs/1512.03385) |
| [RetinaNet](vision/detection) | A fast and powerful object detector | [arXiv:1708.02002](https://arxiv.org/abs/1708.02002) |
A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
33
| [Mask R-CNN](vision/detection) | An object detection and instance segmentation model | [arXiv:1703.06870](https://arxiv.org/abs/1703.06870) |
34

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
35
### Other models
36

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
37
38
39
| Model | Description | Reference |
| ----- | ----------- | --------- |
| [NCF](recommendation) | Neural Collaborative Filtering model for recommendation tasks | [arXiv:1708.05031](https://arxiv.org/abs/1708.05031) |
40

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
41
---
42

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
43
## How to get started with the Model Garden official models
Hongkun Yu's avatar
Hongkun Yu committed
44

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
45
46
47
48
49
50
51
52
53
54
55
* 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
[release v2.1.0](https://github.com/tensorflow/models/releases/tag/v2.1.0)
are compatible with
[TensorFlow v2.1.0](https://github.com/tensorflow/tensorflow/releases/tag/v2.1.0).
Hongkun Yu's avatar
Hongkun Yu committed
56

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

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
59
### Requirements
60

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

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
65
66
67
```shell
pip3 install tf-nightly
```
Hongkun Yu's avatar
Hongkun Yu committed
68

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
69
### Installation
Hongkun Yu's avatar
Hongkun Yu committed
70

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

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
73
74
75
**tf-models-nightly** is the nightly Model Garden package
created daily automatically. pip will install all models
and dependencies automatically.
76

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
77
78
79
```shell
pip install tf-models-nightly
```
80

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
81
82
Please check out our [example](colab/bert.ipynb)
to learn how to use a PIP package.
83

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
84
#### Method 2: Clone the source
85

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
86
1. Clone the GitHub repository:
87

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
88
89
90
```shell
git clone https://github.com/tensorflow/models.git
```
91

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

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
94
95
96
```shell
export PYTHONPATH=$PYTHONPATH:/path/to/models
```
97

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

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
100
101
102
103
```python
import os
os.environ['PYTHONPATH'] += ":/path/to/models"
```
104

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
105
3. Install other dependencies
106

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
107
108
109
```shell
pip3 install --user -r official/requirements.txt
```
Hongkun Yu's avatar
Hongkun Yu committed
110

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
111
---
Hongkun Yu's avatar
Hongkun Yu committed
112
113
114

## More models to come!

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
115
116
The team is actively developing new models.
In the near future, we will add:
Hongkun Yu's avatar
Hongkun Yu committed
117

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
118
119
120
121
122
- State-of-the-art language understanding models:
  More members in Transformer family
- Start-of-the-art image classification models:
  EfficientNet, MnasNet and variants.
- A set of excellent objection detection models.
Hongkun Yu's avatar
Hongkun Yu committed
123

Hongkun Yu's avatar
Hongkun Yu committed
124
125
If you would like to make any fixes or improvements to the models, please
[submit a pull request](https://github.com/tensorflow/models/compare).
126

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
127
128
129
---

## Contributions
130

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
131
132
Every model should follow our guidelines to uphold our objectives of readable,
usable, and maintainable code.
133

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
134
### General Guidelines
Rajagopal Ananthanarayanan's avatar
Rajagopal Ananthanarayanan committed
135

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
136
137
138
139
140
141
142
- Code should be well documented and tested.
- Runnable from a blank environment with ease.
- Trainable on: single GPU/CPU (baseline), multiple GPUs & TPUs
- Compatible with Python 3 (using [six](https://pythonhosted.org/six/)
when being compatible with Python 2 is necessary)
- Conform to
  [Google Python Style Guide](https://github.com/google/styleguide/blob/gh-pages/pyguide.md)
143

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
144
### Implementation Guidelines
145

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
146
147
These guidelines are to ensure consistent model implementations for
better readability and maintainability.
148

A. Unique TensorFlower's avatar
A. Unique TensorFlower committed
149
150
151
- Use [common utility functions](utils)
- Export SavedModel at the end of the training.
- Consistent flags and flag-parsing library ([read more here](utils/flags/guidelines.md))