1 # Copyright 2017 The TensorFlow Authors. All Rights Reserved. 2 # 3 # Licensed under the Apache License, Version 2.0 (the "License"); 4 # you may not use this file except in compliance with the License. 5 # You may obtain a copy of the License at 6 # 7 # http://www.apache.org/licenses/LICENSE-2.0 8 # 9 # Unless required by applicable law or agreed to in writing, software 10 # distributed under the License is distributed on an "AS IS" BASIS, 11 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 # See the License for the specific language governing permissions and 13 # limitations under the License. 14 # ============================================================================== 15 """Deep Neural Network estimators.""" 16 17 from __future__ import absolute_import 18 from __future__ import division 19 from __future__ import print_function 20 21 from tensorflow.python.estimator import estimator 22 from tensorflow.python.estimator.canned import dnn as dnn_lib 23 from tensorflow.python.ops import nn 24 25 26 class DNNEstimator(estimator.Estimator): 27 """An estimator for TensorFlow DNN models with user-specified head. 28 29 Example: 30 31 ```python 32 sparse_feature_a = sparse_column_with_hash_bucket(...) 33 sparse_feature_b = sparse_column_with_hash_bucket(...) 34 35 sparse_feature_a_emb = embedding_column(sparse_id_column=sparse_feature_a, 36 ...) 37 sparse_feature_b_emb = embedding_column(sparse_id_column=sparse_feature_b, 38 ...) 39 40 estimator = DNNEstimator( 41 head=tf.contrib.estimator.multi_label_head(n_classes=3), 42 feature_columns=[sparse_feature_a_emb, sparse_feature_b_emb], 43 hidden_units=[1024, 512, 256]) 44 45 # Or estimator using the ProximalAdagradOptimizer optimizer with 46 # regularization. 47 estimator = DNNEstimator( 48 head=tf.contrib.estimator.multi_label_head(n_classes=3), 49 feature_columns=[sparse_feature_a_emb, sparse_feature_b_emb], 50 hidden_units=[1024, 512, 256], 51 optimizer=tf.train.ProximalAdagradOptimizer( 52 learning_rate=0.1, 53 l1_regularization_strength=0.001 54 )) 55 56 # Input builders 57 def input_fn_train: # returns x, y 58 pass 59 estimator.train(input_fn=input_fn_train, steps=100) 60 61 def input_fn_eval: # returns x, y 62 pass 63 metrics = estimator.evaluate(input_fn=input_fn_eval, steps=10) 64 def input_fn_predict: # returns x, None 65 pass 66 predictions = estimator.predict(input_fn=input_fn_predict) 67 ``` 68 69 Input of `train` and `evaluate` should have following features, 70 otherwise there will be a `KeyError`: 71 72 * if `weight_column` is not `None`, a feature with 73 `key=weight_column` whose value is a `Tensor`. 74 * for each `column` in `feature_columns`: 75 - if `column` is a `_CategoricalColumn`, a feature with `key=column.name` 76 whose `value` is a `SparseTensor`. 77 - if `column` is a `_WeightedCategoricalColumn`, two features: the first 78 with `key` the id column name, the second with `key` the weight column 79 name. Both features' `value` must be a `SparseTensor`. 80 - if `column` is a `_DenseColumn`, a feature with `key=column.name` 81 whose `value` is a `Tensor`. 82 83 Loss and predicted output are determined by the specified head. 84 """ 85 86 def __init__(self, 87 head, 88 hidden_units, 89 feature_columns, 90 model_dir=None, 91 optimizer='Adagrad', 92 activation_fn=nn.relu, 93 dropout=None, 94 input_layer_partitioner=None, 95 config=None): 96 """Initializes a `DNNClassifier` instance. 97 98 Args: 99 head: A `_Head` instance constructed with a method such as 100 `tf.contrib.estimator.multi_label_head`. 101 hidden_units: Iterable of number hidden units per layer. All layers are 102 fully connected. Ex. `[64, 32]` means first layer has 64 nodes and 103 second one has 32. 104 feature_columns: An iterable containing all the feature columns used by 105 the model. All items in the set should be instances of classes derived 106 from `_FeatureColumn`. 107 model_dir: Directory to save model parameters, graph and etc. This can 108 also be used to load checkpoints from the directory into a estimator to 109 continue training a previously saved model. 110 optimizer: An instance of `tf.Optimizer` used to train the model. Defaults 111 to Adagrad optimizer. 112 activation_fn: Activation function applied to each layer. If `None`, will 113 use `tf.nn.relu`. 114 dropout: When not `None`, the probability we will drop out a given 115 coordinate. 116 input_layer_partitioner: Optional. Partitioner for input layer. Defaults 117 to `min_max_variable_partitioner` with `min_slice_size` 64 << 20. 118 config: `RunConfig` object to configure the runtime settings. 119 """ 120 def _model_fn(features, labels, mode, config): 121 return dnn_lib._dnn_model_fn( # pylint: disable=protected-access 122 features=features, 123 labels=labels, 124 mode=mode, 125 head=head, 126 hidden_units=hidden_units, 127 feature_columns=tuple(feature_columns or []), 128 optimizer=optimizer, 129 activation_fn=activation_fn, 130 dropout=dropout, 131 input_layer_partitioner=input_layer_partitioner, 132 config=config) 133 super(DNNEstimator, self).__init__( 134 model_fn=_model_fn, model_dir=model_dir, config=config) 135
