1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
|
EVERYTHING IN THIS DIRECTORY IS DEPRECATED.
Using functions or classes will result in warnings.
Instructions for converting to current alternatives are included in the
warnings. A high-level overview is below.
## Canned Estimators
Many canned estimators (subclasses of `Estimator`) have equivalents in core:
`DNNClassifier`, `DNNRegressor`, `DNNEstimator`, `LinearClassifier`,
`LinearRegressor`, `DNNLinearCombinedClassifier` and
`DNNLinearCombinedRegressor`. They are exposed under `tf.estimator`.
`DNNEstimator`, `LinearEstimator` and `DNNLinearCombinedEstimator`
are exposed under `tf.contrib.estimator`.
To migrate to the new api, users need to take the following steps:
* Replace `tf.contrib.learn` with `tf.estimator`.
* If you subclass any of the estimators, stop doing that. You should be able to
write a factory method that returns a canned estimator instead. If this is not
possible (if you override methods from the canned estimator), consider writing
a custom estimator instead. See `tf.estimator.Estimator`.
* Set `loss_reduction=tf.losses.Reduction.SUM_OVER_BATCH_SIZE` to preserve loss
reduction as the average over batch.
* Some optimizer-related arguments are no longer passed in the estimator
constructor. Instead, we provide methods that perform the same job by wrapping
an optimizer. Specifically:
* `gradient_clip_norm`: Use `tf.contrib.estimator.clip_gradients_by_norm`
* `embedding_lr_multipliers`: Not supported.
Other arguments:
* `input_layer_min_slice_size`: Replaced by `input_layer_partitioner`
* `enable_centered_bias`: Not supported. Dropping this argument is unlikely to
harm your model.
* `feature_engineering_fn`: Not supported. You can call your
`feature_engineering_fn` inside your input_fn:
```python
def new_input_fn():
features, labels = old_input_fn()
return feature_engineering_fn(features, labels)
```
* Use `tf.reshape` to reshape labels in your `input_fn`. `tf.estimator`
classifiers and regressors expect labels as a 2D Tensor of shape
`[batch_size, 1]`, or `[batch_size, n_labels]`. In contrast,
`tf.contrib.learn` classifiers and regressors supported labels with shape
`[batch_size]`.
* If you pass custom metrics from the `evaluate()` method call, use
`tf.contrib.estimator.add_metrics`.
* Replace your `serving_input_fn` with a `serving_input_receiver_fn`.
Note this should be entirely distinct from your training `input_fn`, so if you
previously had one `input_fn` with different "modes", you should now factor
that apart. Where the former returned either a simple `(features, labels)`
tuple or `InputFnOps`, you should now return a `ServingInputReceiver`.
If you were generating your `serving_input_fn` using the
`build_parsing_serving_input_fn` helper, you can simply drop in the
replacement `build_parsing_serving_input_receiver_fn`.
Some remaining estimators/classes:
* `DynamicRnnEstimator`: Consider a custom `model_fn`.
* `KMeansClustering`: Use `tf.contrib.factorization.KMeansClustering`.
* `LogisticRegressor`: Not supported. Instead, use `binary_classification_head`
with a custom `model_fn`, or with `DNNEstimator`.
* `StateSavingRnnEstimator`: Consider a custom `model_fn`.
* SVM: Consider a custom `model_fn`.
* `LinearComposableModel` and `DNNComposableModel`: Not supported.
Consider `tf.contrib.estimator.DNNEstimator`, or write a custom model_fn.
* `MetricSpec`: Deprecated. For adding custom metrics to canned Estimators, use
`tf.contrib.estimator.add_metrics`.
## Estimator
`tf.contrib.learn.Estimator` is migrated to `tf.estimator.Estimator`.
To migrate, users need to take the following steps:
* Replace `tf.contrib.learn.Estimator` with `tf.estimator.Estimator`.
* If you pass a `config` argument to `Estimator`, this must be
`tf.estimator.RunConfig`. You may need to edit your code accordingly.
* Edit your `model_fn` to return `tf.estimator.EstimatorSpec`. Refer to
`EstimatorSpec` for documentation of specific fields.
* If your `model_fn` uses the `mode` argument, use `tf.estimator.ModeKeys`.
Some related classes:
* `Evaluable`, `Trainable`: Not supported, merged into `tf.estimator.Estimator`.
* ExportStrategy: Replaced by `tf.estimator.Exporter`.
## Head/MultiHead
These classes are now supported under `tf.contrib.estimator`, e.g.
`tf.contrib.estimator.multi_class_head` and `tf.contrib.estimator.multi_head`.
Some differences:
* `multi_class_head`: If you use `tf.contrib.learn.multi_class_head` with
`n_classes=2`, switch to `tf.contrib.estimator.binary_classification_head`.
* `loss_only_head`: Not supported.
* `poisson_regression_head`: Not supported (yet).
* `binary_svm_head`: Not supported (yet).
* `no_op_train_fn`: Replace it with `tf.no_op`.
Some arguments are renamed, please refer to documentation. In addition:
* `loss_fn`: Supported for `multi_label_head`. If you need it for other heads,
please open an issue.
* `metric_class_ids`: Not supported (yet).
* `enable_centered_bias`: Not supported. Dropping this argument is unlikely to
harm your model.
* `label_name`: Not needed in `tf.estimator`. If you don’t use `multi_head`,
drop this argument. If you use `multi_head`, refer to
`tf.contrib.estimator.multi_head` documentation.
## Experiment Class - Distributed Training Tooling
Switch to `tf.estimator.train_and_evaluate`. Some differences:
* Most of the constructor arguments, like `train_input_fn`, `eval_input_fn`,
should be wrapped into `tf.estimator.TrainSpec` and `tf.estimator.EvalSpec`.
* Remove the `experiment_fn`. Instead, create the `Estimator`,
`train_spec` and `eval_spec`, then call `tf.estimator.train_and_evaluate`
directly.
* Inside `tf.estimator.EvalSpec`, the `exporter` field is the replacement
for `export_strategy`. To be precise, `tf.estimator.LatestExporter` is the
replacement for `tf.contrib.learn.make_export_strategy`. If you want to export
only at the end of training use `tf.estimator.FinalExporter`.
* If the `TF_CONFIG` environment variable is constructed manually, please read
the `train_and_evaluate` documentation for the new requirementds (in
particular, the chief node and evaluator node).
## Others Classes and Functions
* `tf.contrib.learn.datasets` is deprecated. We are adding ready to use datasets
to tensorflow/models. Many smaller datasets are available from other sources,
such as scikits.learn. Some Python processing may have to be written, but this
is straightforward to implement using the standard modules.
* `tf.contrib.learn.preprocessing`: Deprecated. The python-only preprocessing
functions are not a good fit for TensorFlow. Please use `tf.data`, and
consider tensorflow/transform for more complex use cases.
* `tf.contrib.learn.models`: Not supported, use canned estimators instead.
* `tf.contrib.learn.monitors`: Implement `SessionRunHook` instead. Hook
implementations are in `tf.train`.
* `tf.contrib.learn.learn_io`: Use the methods in `tf.estimator.inputs`, such as
`tf.estimator.inputs.numpy_input_fn`. Some utility functions have no
equivalent, we encourage the use of `tf.data`.
|
