ML Community Day is November 9! Join us for updates from TensorFlow, JAX, and more Learn more


An Estimator for TensorFlow RNN models with user-specified head.

Inherits From: Estimator


token_sequence = sequence_categorical_column_with_hash_bucket(...)
token_emb = embedding_column(categorical_column=token_sequence, ...)

estimator = RNNEstimator(
    units=[32, 16], cell_type='lstm')

# Or with custom RNN cell:
def rnn_cell_fn(_):
  cells = [ tf.keras.layers.LSTMCell(size) for size in [32, 16] ]
  return tf.keras.layers.StackedRNNCells(cells)

estimator = RNNEstimator(

# Input builders
def input_fn_train: # returns x, y
estimator.train(input_fn=input_fn_train, steps=100)

def input_fn_eval: # returns x, y
metrics = estimator.evaluate(input_fn=input_fn_eval, steps=10)
def input_fn_predict: # returns x, None
predictions = estimator.predict(input_fn=input_fn_predict)

Input of train and evaluate should have following features, otherwise there will be a KeyError:

  • if the head's weight_column is not None, a feature with key=weight_column whose value is a Tensor.
  • for each column in sequence_feature_columns:
    • a feature with whose value is a SparseTensor.
  • for each column in context_feature_columns:
    • if column is a CategoricalColumn, a feature with whose value is a SparseTensor.
    • if column is a WeightedCategoricalColumn, two features: the first with key the id column name, the second with key the weight column name. Both features' value must be a SparseTensor.
    • if column is a DenseColumn, a feature with whose value is a Tensor.

Loss and predicted output are determined by the specified head.

head A Head instance. This specifies the model's output and loss function to be optimized.
sequence_feature_columns An iterable containing the FeatureColumns that represent sequential input. All items in the set should either be sequence columns (e.g. sequence_numeric_column) or constructed from one (e.g. embedding_column with sequence_categorical_column_* as input).
context_feature_columns An iterable containing the FeatureColumns for contextual input. The data represented by these columns will be replicated and given to the RNN at each timestep. These columns must be instances of classes derived from DenseColumn such as numeric_column, not the sequential variants.
units Iterable of integer number of hidden units per RNN layer. If set, cell_type must also be specified and rnn_cell_fn must be None.
cell_type A class producing a RNN cell or a string specifying the cell type. Supported strings are: 'simple_rnn', 'lstm', and 'gru'. If set, units must also be specified and rnn_cell_fn must be None.
rnn_cell_fn A function that returns a RNN cell instance that will be used to construct the RNN. If set, units and cell_type cannot be set. This is for advanced users who need additional customization beyond units and cell_type. Note that tf.keras.layers.StackedRNNCells is needed for stacked RNNs.
return_sequences A boolean indicating whether to return the last output in the output sequence, or the full sequence.
model_dir Directory to save model parameters, graph and etc. This can also be used to load checkpoints from the directory into a estimator to continue training a previo