Additional APIs for algorithms that need to be distribution-aware.
Some common use cases of functions on this page:
tf.distribute.DistributedValues can have the same locality as a distributed variable, which leads to a mirrored value residing on the same devices as the variable (as opposed to the compute devices). Such values may be passed to a call to tf.distribute.StrategyExtended.update to update the value of a variable. You may use tf.distribute.StrategyExtended.colocate_vars_with to give a variable the same locality as another variable. You may convert a "PerReplica" value to a variable's locality by using tf.distribute.StrategyExtended.reduce_to or tf.distribute.StrategyExtended.batch_reduce_to.
A distributed variable is variables created on multiple devices. As discussed in the glossary, mirrored variable and SyncOnRead variable are two examples. The standard pattern for updating distributed variables is to:
Steps 2 through 4 are done automatically by class tf.keras.optimizers.Optimizer if you call its tf.keras.optimizers.Optimizer.apply_gradients method in a replica context.
In fact, a higher-level solution to update a distributed variable is by calling assign on the variable as you would do to a regular tf.Variable. You can call the method in both replica context and cross-replica context. For a mirrored variable, calling assign in replica context requires you to specify the aggregation type in the variable constructor. In that case, the context switching and sync described in steps 2 through 4 are handled for you. If you call assign on mirrored variable in cross-replica context, you can only assign a single value or assign values from another mirrored variable or a mirrored tf.distribute.DistributedValues. For a SyncOnRead variable, in replica context, you can simply call assign on it and no aggregation happens under the hood. In cross-replica context, you can only assign a single value to a SyncOnRead variable. One example case is restoring from a checkpoint: if the aggregation type of the variable is tf.VariableAggregation.SUM, it is assumed that replica values were added before checkpointing, so at the time of restoring, the value is divided by the number of replicas and then assigned to each replica; if the aggregation type is tf.VariableAggregation.MEAN, the value is assigned to each replica directly.
View source
Combine multiple reduce_to calls into one for faster execution.
Similar to reduce_to, but accepts a list of (value, destinations) pairs. It's more efficient than reduce each value separately.
This API currently can only be called in cross-replica context. Other variants to reduce values across replicas are:
See reduce_to for more information.
View source
Scope that controls which devices variables will be created on.
No operations should be added to the graph inside this scope, it should only be used when creating variables (some implementations work by changing variable creation, others work by using a tf.compat.v1.colocate_with() scope).
This may only be used inside self.scope().
View source
Combine (via e.g. sum or mean) values across replicas.
reduce_to aggregates tf.distribute.DistributedValues and distributed variables. It supports both dense values and tf.IndexedSlices.
This API currently can only be called in cross-replica context. Other variants to reduce values across replicas are:
destinations specifies where to reduce the value to, e.g. "GPU:0". You can also pass in a Tensor, and the destinations will be the device of that tensor. For all-reduce, pass the same to value and destinations.
It can be used in tf.distribute.ReplicaContext.merge_call to write code that works for all tf.distribute.Strategy.
View source
Run fn to update var using inputs mirrored to the same devices.
tf.distribute.StrategyExtended.update takes a distributed variable var to be updated, an update function fn, and args and kwargs for fn. It applies fn to each component variable of var and passes corresponding values from args and kwargs. Neither args nor kwargs may contain per-replica values. If they contain mirrored values, they will be unwrapped before calling fn. For example, fn can be assign_add and args can be a mirrored DistributedValues where each component contains the value to be added to this mirrored variable var. Calling update will call assign_add on each component variable of var with the corresponding tensor value on that device.
If var is mirrored across multiple devices, then this method implements logic as following:
Otherwise, this method returns fn(var, *args, **kwargs) colocated with var.
View source
Returns the container that this per-replica value belongs to.
View source
Tests whether v was created while this strategy scope was active.
Variables created inside the strategy scope are "owned" by it:
Variables created outside the strategy are not owned by it:


Synchronous training on TPUs and TPU Pods.
Inherits From: Strategy
To construct a TPUStrategy object, you need to run the initialization code as below:
While using distribution strategies, the variables created within the strategy's scope will be replicated across all the replicas and can be kept in sync using all-reduce algorithms.
To run TF2 programs on TPUs, you can either use .compile and .fit APIs in tf.keras with TPUStrategy, or write your own customized training loop by calling strategy.run directly. Note that TPUStrategy doesn't support pure eager execution, so please make sure the function passed into strategy.run is a tf.function or strategy.run is called inside a tf.function if eager behavior is enabled. See more details in https://www.tensorflow.org/guide/tpu.
distribute_datasets_from_function and experimental_distribute_dataset APIs can be used to distribute the dataset across the TPU workers when writing your own training loop. If you are using fit and compile methods available in tf.keras.Model, then Keras will handle the distribution for you.
An example of writing customized training loop on TPUs:
For the advanced use cases like model parallelism, you can set experimental_device_assignment argument when creating TPUStrategy to specify number of replicas and number of logical devices. Below is an example to initialize TPU system with 2 logical devices and 1 replica.
Then you can run a tf.add operation only on logical device 0.
In general, when using a multi-worker tf.distribute strategy such as tf.distribute.experimental.MultiWorkerMirroredStrategy or tf.distribute.TPUStrategy(), there is a tf.distribute.cluster_resolver.ClusterResolver associated with the strategy used, and such an instance is returned by this property.
Strategies that intend to have an associated tf.distribute.cluster_resolver.ClusterResolver must set the relevant attribute, or override this property; otherwise, None is returned by default. Those strategies should also provide information regarding what is returned by this property.
Single-worker strategies usually do not have a tf.distribute.cluster_resolver.ClusterResolver, and in those cases this property will return None.
The tf.distribute.cluster_resolver.ClusterResolver may be useful when the user needs to access information such as the cluster spec, task type or task id. For example,
For more information, please see tf.distribute.cluster_resolver.ClusterResolver's API docstring.
View source
Distributes tf.data.Dataset instances created by calls to dataset_fn.
The argument dataset_fn that users pass in is an input function that has a tf.distribute.InputContext argument and returns a tf.data.Dataset instance. It is expected that the returned dataset from dataset_fn is already batched by per-replica batch size (i.e. global batch size divided by the number of replicas in sync) and sharded. tf.distribute.Strategy.distribute_datasets_from_function does not batch or shard the tf.data.Dataset instance returned from the input function. dataset_fn will be called on the CPU device of each of the workers and each generates a dataset where every replica on that worker will dequeue one batch of inputs (i.e. if a worker has two replicas, two batches will be dequeued from the Dataset every step).
This method can be used for several purposes. First, it allows you to specify your own batching and sharding logic. (In contrast, tf.distribute.experimental_distribute_dataset does batching and sharding for you.) For example, where experimental_distribute_dataset is unable to shard the input files, this method might be used to manually shard the dataset (avoiding the slow fallback behavior in experimental_distribute_dataset). In cases where the dataset is infinite, this sharding can be done by creating dataset replicas that differ only in their random seed.
The dataset_fn should take an tf.distribute.InputContext instance where information about batching and input replication can be accessed.
You can use element_spec property of the tf.distribute.DistributedDataset returned by this API to query the tf.TypeSpec of the elements returned by the iterator. This can be used to set the input_signature property of a tf.function. Follow tf.distribute.DistributedDataset.element_spec to see an example.
For a tutorial on more usage and properties of this method, refer to the tutorial on distributed input). If you are interested in last partial batch handling, read this section.
View source
Adds annotation that tensor will be assigned to a logical device.
This adds an annotation to tensor specifying that operations on tensor will be invoked on logical core device id logical_device_id. When model parallelism is used, the default behavior is that all ops are placed on zero-th logical device.
View source
Creates tf.distribute.DistributedDataset from tf.data.Dataset.
The returned tf.distribute.DistributedDataset can be iterated over similar to regular datasets. NOTE: The user cannot add any more transformations to a tf.distribute.DistributedDataset. You can only create an iterator or examine the tf.TypeSpec of the data generated by it. See API docs of tf.distribute.DistributedDataset to learn more.
The following is an example:
Three key actions happending under the hood of this method are batching, sharding, and prefetching.
In the code snippet above, dataset is batched by global_batch_size, and calling experimental_distribute_dataset on it rebatches dataset to a new batch size that is equal to the global batch size divided by the number of replicas in sync. We iterate through it using a Pythonic for loop. x is a tf.distribute.DistributedValues containing data for all replicas, and each replica gets data of the new batch size. tf.distribute.Strategy.run will take care of feeding the right per-replica data in x to the right replica_fn executed on each replica.
Sharding contains autosharding across multiple workers and within every worker. First, in multi-worker distributed training (i.e. when you use tf.distribute.experimental.MultiWorkerMirroredStrategy or tf.distribute.TPUStrategy), autosharding a dataset over a set of workers means that each worker is assigned a subset of the entire dataset (if the right tf.data.experimental.AutoShardPolicy is set). This is to ensure that at each step, a global batch size of non-overlapping dataset elements will be processed by each worker. Autosharding has a couple of different options that can be specified using tf.data.experimental.DistributeOptions. Then, sharding within each worker means the method will split the data among all the worker devices (if more than one a present). This will happen regardless of multi-worker autosharding.
By default, this method adds a prefetch transformation at the end of the user provided tf.data.Dataset instance. The argument to the prefetch transformation which is buffer_size is equal to the number of replicas in sync.
If the above batch splitting and dataset sharding logic is undesirable, please use tf.distribute.Strategy.distribute_datasets_from_function instead, which does not do any automatic batching or sharding for you.
For a tutorial on more usage and properties of this method, refer to the tutorial on distributed input. If you are interested in last partial batch handling, read this section.
View source
Generates tf.distribute.DistributedValues from value_fn.
This function is to generate tf.distribute.DistributedValues to pass into run, reduce, or other methods that take distributed values when not using datasets.
View source
Returns the list of all local per-replica values contained in value.
View source
Adds annotation that tensor will be replicated to all logical devices.
This adds an annotation to tensor tensor specifying that operations on tensor will be invoked on all logical devices.
Args: tensor: Input tensor to annotate.
View source
Adds annotation that tensor will be split across logical devices.
This adds an annotation to tensor tensor specifying that operations on tensor will be be split among multiple logical devices. Tensor tensor will be split across dimensions specified by partition_dimensions. The dimensions of tensor must be divisible by corresponding value in partition_dimensions.
For example, for system with 8 logical devices, if tensor is an image tensor with shape (batch_size, width, height, channel) and partition_dimensions is [1, 2, 4, 1], then tensor will be split 2 in width dimension and 4 way in height dimension and the split tensor values will be fed into 8 logical devices.
Args: tensor: Input tensor to annotate. partition_dimensions: An unnested list of integers with the size equal to rank of tensor specifying how tensor will be partitioned. The product of all elements in partition_dimensions must be equal to the total number of logical devices per replica.
1) If the size of partition_dimensions does not equal to rank of tensor or 2) if product of elements of partition_dimensions does not match the number of logical devices per replica defined by the implementing DistributionStrategy's device specification or 3) if a known size of tensor is not divisible by corresponding value in partition_dimensions.
View source
Gather value across replicas along axis to the current device.
Given a tf.distribute.DistributedValues or tf.Tensor-like object value, this API gathers and concatenates value across replicas along the axis-th dimension. The result is copied to the "current" device
This API can only be called in the cross-replica context. For a counterpart in the replica context, see tf.distribute.ReplicaContext.all_gather.
Consider the following example for more combinations:
View source
Reduce value across replicas and return result on current device.
To see how this would look with multiple replicas, consider the same example with MirroredStrategy with 2 GPUs:
This API is typically used for aggregating the results returned from different replicas, for reporting etc. For example, loss computed from different replicas can be averaged using this API before printing.
There are a number of different tf.distribute APIs for reducing values across replicas:
What should axis be?
Given a per-replica value returned by run, say a per-example loss, the batch will be divided across all the replicas. This function allows you to aggregate across replicas and optionally also across batch elements by specifying the axis parameter accordingly.
For example, if you have a global batch size of 8 and 2 replicas, values for examples [0, 1, 2, 3] will be on replica 0 and [4, 5, 6, 7] will be on replica 1. With axis=None, reduce will aggregate only across replicas, returning [0+4, 1+5, 2+6, 3+7]. This is useful when each replica is computing a scalar or some other value that doesn't have a "batch" dimension (like a gradient or loss).
Sometimes, you will want to aggregate across both the global batch and all replicas. You can get this behavior by specifying the batch dimension as the axis, typically axis=0. In this case it would return a scalar 0+1+2+3+4+5+6+7.
If there is a last partial batch, you will need to specify an axis so that the resulting shape is consistent across replicas. So if the last batch has size 6 and it is divided into [0, 1, 2, 3] and [4, 5], you would get a shape mismatch unless you specify axis=0. If you specify tf.distribute.ReduceOp.MEAN, using axis=0 will use the correct denominator of 6. Contrast this with computing reduce_mean to get a scalar value on each replica and this function to average those means, which will weigh some values 1/8 and others 1/4.
View source
Run the computation defined by fn on each TPU replica.
Executes ops specified by fn on each replica. If args or kwargs have tf.distribute.DistributedValues, such as those produced by a tf.distribute.DistributedDataset from tf.distribute.Strategy.experimental_distribute_dataset or tf.distribute.Strategy.distribute_datasets_from_function, when fn is executed on a particular replica, it will be executed with the component of tf.distribute.DistributedValues that correspond to that replica.
fn may call tf.distribute.get_replica_context() to access members such as all_reduce.
All arguments in args or kwargs should either be nest of tensors or tf.distribute.DistributedValues containing tensors or composite tensors.
View source
Context manager to make the strategy current and distribute variables.
This method returns a context manager, and is used as follows:
What happens when Strategy.scope is entered?
What should be in scope and what should be outside?
There are a number of requirements on what needs to happen inside the scope. However, in places where we have information about which strategy is in use, we often enter the scope for the user, so they don't have to do it explicitly (i.e. calling those either inside or outside the scope is OK).


Public API for tf.dtypes namespace.
class DType: Represents the type of the elements in a Tensor.
as_dtype(...): Converts the given type_value to a DType.
cast(...): Casts a tensor to a new type.
complex(...): Converts two real numbers to a complex number.
saturate_cast(...): Performs a safe saturating cast of value to dtype.


Converts the given type_value to a DType.
Main aliases
tf.as_dtype
See Migration guide for more details.
tf.compat.v1.as_dtype, tf.compat.v1.dtypes.as_dtype


Converts two real numbers to a complex number.
Main aliases
tf.complex
See Migration guide for more details.
tf.compat.v1.complex, tf.compat.v1.dtypes.complex
Given a tensor real representing the real part of a complex number, and a tensor imag representing the imaginary part of a complex number, this operation returns complex numbers elementwise of the form \(a + bj\), where a represents the real part and b represents the imag part.
The input tensors real and imag must have the same shape.


Represents the type of the elements in a Tensor.
Main aliases
tf.DType
See Migration guide for more details.
tf.compat.v1.DType, tf.compat.v1.dtypes.DType
The following DType objects are defined:
The tf.as_dtype() function converts numpy types and string type names to a DType object.
Non-numeric, unordered, and quantized types are not considered unsigned, and this function returns False.
(min, max) tuple, of the dtype. Args: clip_negative : bool, optional If True, clip the negative range (i.e. return 0 for min intensity) even if the image dtype allows negative values. Returns min, max : tuple Lower and upper intensity limits.
View source
Returns True if the other DType will be converted to this DType.
The conversion rules are as follows:
View source
Returns True iff this DType refers to the same type as other.
View source
Returns True iff self != other.


Performs a safe saturating cast of value to dtype.
Main aliases
tf.saturate_cast
See Migration guide for more details.
tf.compat.v1.dtypes.saturate_cast, tf.compat.v1.saturate_cast
This function casts the input to dtype without applying any scaling. If there is a danger that values would over or underflow in the cast, this op applies the appropriate clamping before the cast.


Partitions data into num_partitions tensors using indices from partitions.
Compat aliases for migration
See Migration guide for more details.
tf.compat.v1.dynamic_partition
For each index tuple js of size partitions.ndim, the slice data[js, ...] becomes part of outputs[partitions[js]]. The slices with partitions[js] = i are placed in outputs[i] in lexicographic order of js, and the first dimension of outputs[i] is the number of entries in partitions equal to i. In detail,
data.shape must start with partitions.shape.
See dynamic_stitch for an example on how to merge partitions back.


Interleave the values from the data tensors into a single tensor.
Compat aliases for migration
See Migration guide for more details.
tf.compat.v1.dynamic_stitch
Builds a merged tensor such that
For example, if each indices[m] is scalar or vector, we have
Each data[i].shape must start with the corresponding indices[i].shape, and the rest of data[i].shape must be constant w.r.t. i. That is, we must have data[i].shape = indices[i].shape + constant. In terms of this constant, the output shape is
Values are merged in order, so if an index appears in both indices[m][i] and indices[n][j] for (m,i) < (n,j) the slice data[n][j] will appear in the merged result. If you do not need this guarantee, ParallelDynamicStitch might perform better on some devices.
This method can be used to merge partitions created by dynamic_partition as illustrated on the following example:


Computes the Levenshtein distance between sequences.
Compat aliases for migration
See Migration guide for more details.
tf.compat.v1.edit_distance
This operation takes variable-length sequences (hypothesis and truth), each provided as a SparseTensor, and computes the Levenshtein distance. You can normalize the edit distance by length of truth by setting normalize to true.
Given the following input,
The operaton returns a dense Tensor of shape [2, 2] with edit distances normalized by truth lengths.
For the following inputs,


Tensor contraction over specified indices and outer product.
Main aliases
tf.linalg.einsum
See Migration guide for more details.
tf.compat.v1.einsum, tf.compat.v1.linalg.einsum
Einsum allows defining Tensors by defining their element-wise computation. This computation is defined by equation, a shorthand form based on Einstein summation. As an example, consider multiplying two matrices A and B to form a matrix C. The elements of C are given by:
or
The corresponding einsum equation is:
In general, to convert the element-wise equation into the equation string, use the following procedure (intermediate strings for matrix multiplication example provided in parentheses):
Many common operations can be expressed in this way. For example:
Matrix multiplication
Repeated indices are summed if the output indices are not specified.
Dot product
Outer product
Transpose
Diag
Trace
Batch matrix multiplication
This method does not support broadcasting on named-axes. All axes with matching labels should have the same length. If you have length-1 axes, use tf.squeseze or tf.reshape to eliminate them.
To write code that is agnostic to the number of indices in the input use an ellipsis. The ellipsis is a placeholder for "whatever other indices fit here".
For example, to perform a NumPy-style broadcasting-batch-matrix multiplication where the matrix multiply acts on the last two axes of the input, use:
Einsum will broadcast over axes covered by the ellipsis.


Updates the shape of a tensor and checks at runtime that the shape holds.
Compat aliases for migration
See Migration guide for more details.
tf.compat.v1.ensure_shape
The above example raises tf.errors.InvalidArgumentError, because the shape (3,) is not compatible with the shape (None, 3, 3)
With eager execution this is a shape assertion, that returns the input:
Inside a tf.function or v1.Graph context it checks both the buildtime and runtime shapes. This is stricter than tf.Tensor.set_shape which only checks the buildtime shape.
For example, of loading images of a known size:
When tracing a function, no ops are being executed, shapes may be unknown. See the Concrete Functions Guide for details.


Exception types for TensorFlow errors.
class AbortedError: The operation was aborted, typically due to a concurrent action.
class AlreadyExistsError: Raised when an entity that we attempted to create already exists.
class CancelledError: Raised when an operation or step is cancelled.
class DataLossError: Raised when unrecoverable data loss or corruption is encountered.
class DeadlineExceededError: Raised when a deadline expires before an operation could complete.
class FailedPreconditionError: Operation was rejected because the system is not in a state to execute it.
class InternalError: Raised when the system experiences an internal error.
class InvalidArgumentError: Raised when an operation receives an invalid argument.
class NotFoundError: Raised when a requested entity (e.g., a file or directory) was not found.
class OpError: A generic error that is raised when TensorFlow execution fails.
class OperatorNotAllowedInGraphError: An error is raised for unsupported operator in Graph execution.
class OutOfRangeError: Raised when an operation iterates past the valid input range.
class PermissionDeniedError: Raised when the caller does not have permission to run an operation.
class ResourceExhaustedError: Some resource has been exhausted.
class UnauthenticatedError: The request does not have valid authentication credentials.
class UnavailableError: Raised when the runtime is currently unavailable.
class UnimplementedError: Raised when an operation has not been implemented.
class UnknownError: Unknown error.


The operation was aborted, typically due to a concurrent action.
Inherits From: OpError
Compat aliases for migration
See Migration guide for more details.
tf.compat.v1.errors.AbortedError
For example, running a tf.QueueBase.enqueue operation may raise AbortedError if a tf.QueueBase.close operation previously ran.


Raised when an entity that we attempted to create already exists.
Inherits From: OpError
Compat aliases for migration
See Migration guide for more details.
tf.compat.v1.errors.AlreadyExistsError
For example, running an operation that saves a file (e.g. tf.train.Saver.save) could potentially raise this exception if an explicit filename for an existing file was passed.


Raised when an operation or step is cancelled.
Inherits From: OpError
Compat aliases for migration
See Migration guide for more details.
tf.compat.v1.errors.CancelledError
For example, a long-running operation (e.g. tf.QueueBase.enqueue may be cancelled by running another operation (e.g. tf.QueueBase.close, or by tf.Session.close. A step that is running such a long-running operation will fail by raising CancelledError.


Raised when unrecoverable data loss or corruption is encountered.
Inherits From: OpError
Compat aliases for migration
See Migration guide for more details.
tf.compat.v1.errors.DataLossError
For example, this may be raised by running a tf.WholeFileReader.read operation, if the file is truncated while it is being read.


Raised when a deadline expires before an operation could complete.
Inherits From: OpError
Compat aliases for migration
See Migration guide for more details.
tf.compat.v1.errors.DeadlineExceededError
This exception is not currently used.


Operation was rejected because the system is not in a state to execute it.
Inherits From: OpError
Compat aliases for migration
See Migration guide for more details.
tf.compat.v1.errors.FailedPreconditionError
This exception is most commonly raised when running an operation that reads a tf.Variable before it has been initialized.


Raised when the system experiences an internal error.
Inherits From: OpError
Compat aliases for migration
See Migration guide for more details.
tf.compat.v1.errors.InternalError
This exception is raised when some invariant expected by the runtime has been broken. Catching this exception is not recommended.


Raised when an operation receives an invalid argument.
Inherits From: OpError
Compat aliases for migration
See Migration guide for more details.
tf.compat.v1.errors.InvalidArgumentError
This may occur, for example, if an operation receives an input tensor that has an invalid value or shape. For example, the tf.matmul op will raise this error if it receives an input that is not a matrix, and the tf.reshape op will raise this error if the new shape does not match the number of elements in the input tensor.


Raised when a requested entity (e.g., a file or directory) was not found.
Inherits From: OpError
Compat aliases for migration
See Migration guide for more details.
tf.compat.v1.errors.NotFoundError
For example, running the tf.WholeFileReader.read operation could raise NotFoundError if it receives the name of a file that does not exist.


An error is raised for unsupported operator in Graph execution.
For example, using a tf.Tensor as a Python bool in Graph execution is not allowed.


A generic error that is raised when TensorFlow execution fails.
Compat aliases for migration
See Migration guide for more details.
tf.compat.v1.OpError, tf.compat.v1.errors.OpError
Whenever possible, the session will raise a more specific subclass of OpError from the tf.errors module.


Raised when an operation iterates past the valid input range.
Inherits From: OpError
Compat aliases for migration
See Migration guide for more details.
tf.compat.v1.errors.OutOfRangeError
This exception is raised in "end-of-file" conditions, such as when a tf.QueueBase.dequeue operation is blocked on an empty queue, and a tf.QueueBase.close operation executes.


Raised when the caller does not have permission to run an operation.
Inherits From: OpError
Compat aliases for migration
See Migration guide for more details.
tf.compat.v1.errors.PermissionDeniedError
For example, running the tf.WholeFileReader.read operation could raise PermissionDeniedError if it receives the name of a file for which the user does not have the read file permission.


Some resource has been exhausted.
Inherits From: OpError
Compat aliases for migration
See Migration guide for more details.
tf.compat.v1.errors.ResourceExhaustedError
For example, this error might be raised if a per-user quota is exhausted, or perhaps the entire file system is out of space.


The request does not have valid authentication credentials.
Inherits From: OpError
Compat aliases for migration
See Migration guide for more details.
tf.compat.v1.errors.UnauthenticatedError
This exception is not currently used.


Raised when the runtime is currently unavailable.
Inherits From: OpError
Compat aliases for migration
See Migration guide for more details.
tf.compat.v1.errors.UnavailableError
This exception is not currently used.


Raised when an operation has not been implemented.
Inherits From: OpError
Compat aliases for migration
See Migration guide for more details.
tf.compat.v1.errors.UnimplementedError
Some operations may raise this error when passed otherwise-valid arguments that it does not currently support. For example, running the tf.nn.max_pool2d operation would raise this error if pooling was requested on the batch dimension, because this is not yet supported.


Unknown error.
Inherits From: OpError
Compat aliases for migration
See Migration guide for more details.
tf.compat.v1.errors.UnknownError
An example of where this error may be returned is if a Status value received from another address space belongs to an error-space that is not known to this address space. Also, errors raised by APIs that do not return enough error information may be converted to this error.


Estimator: High level tools for working with models.
experimental module: Public API for tf.estimator.experimental namespace.
export module: All public utility methods for exporting Estimator to SavedModel.
class BaselineClassifier: A classifier that can establish a simple baseline.
class BaselineEstimator: An estimator that can establish a simple baseline.
class BaselineRegressor: A regressor that can establish a simple baseline.
class BestExporter: This class exports the serving graph and checkpoints of the best models.
class BinaryClassHead: Creates a Head for single label binary classification.
class BoostedTreesClassifier: A Classifier for Tensorflow Boosted Trees models.
class BoostedTreesEstimator: An Estimator for Tensorflow Boosted Trees models.
class BoostedTreesRegressor: A Regressor for Tensorflow Boosted Trees models.
class CheckpointSaverHook: Saves checkpoints every N steps or seconds.
class CheckpointSaverListener: Interface for listeners that take action before or after checkpoint save.
class DNNClassifier: A classifier for TensorFlow DNN models.
class DNNEstimator: An estimator for TensorFlow DNN models with user-specified head.
class DNNLinearCombinedClassifier: An estimator for TensorFlow Linear and DNN joined classification models.
class DNNLinearCombinedEstimator: An estimator for TensorFlow Linear and DNN joined models with custom head.
class DNNLinearCombinedRegressor: An estimator for TensorFlow Linear and DNN joined models for regression.
class DNNRegressor: A regressor for TensorFlow DNN models.
class Estimator: Estimator class to train and evaluate TensorFlow models.
class EstimatorSpec: Ops and objects returned from a model_fn and passed to an Estimator.
class EvalSpec: Configuration for the "eval" part for the train_and_evaluate call.
class Exporter: A class representing a type of model export.
class FeedFnHook: Runs feed_fn and sets the feed_dict accordingly.
class FinalExporter: This class exports the serving graph and checkpoints at the end.
class FinalOpsHook: A hook which evaluates Tensors at the end of a session.
class GlobalStepWaiterHook: Delays execution until global step reaches wait_until_step.
class Head: Interface for the head/top of a model.
class LatestExporter: This class regularly exports the serving graph and checkpoints.
class LinearClassifier: Linear classifier model.
class LinearEstimator: An estimator for TensorFlow linear models with user-specified head.
class LinearRegressor: An estimator for TensorFlow Linear regression problems.
class LoggingTensorHook: Prints the given tensors every N local steps, every N seconds, or at end.
class LogisticRegressionHead: Creates a Head for logistic regression.
class ModeKeys: Standard names for Estimator model modes.
class MultiClassHead: Creates a Head for multi class classification.
class MultiHead: Creates a Head for multi-objective learning.
class MultiLabelHead: Creates a Head for multi-label classification.
class NanLossDuringTrainingError: Unspecified run-time error.
class NanTensorHook: Monitors the loss tensor and stops training if loss is NaN.
class PoissonRegressionHead: Creates a Head for poisson regression using tf.nn.log_poisson_loss.
class ProfilerHook: Captures CPU/GPU profiling information every N steps or seconds.
class RegressionHead: Creates a Head for regression using the mean_squared_error loss.
class RunConfig: This class specifies the configurations for an Estimator run.
class SecondOrStepTimer: Timer that triggers at most once every N seconds or once every N steps.
class SessionRunArgs: Represents arguments to be added to a Session.run() call.
class SessionRunContext: Provides information about the session.run() call being made.
class SessionRunHook: Hook to extend calls to MonitoredSession.run().
class SessionRunValues: Contains the results of Session.run().
class StepCounterHook: Hook that counts steps per second.
class StopAtStepHook: Hook that requests stop at a specified step.
class SummarySaverHook: Saves summaries every N steps.
class TrainSpec: Configuration for the "train" part for the train_and_evaluate call.
class VocabInfo: Vocabulary information for warm-starting.
class WarmStartSettings: Settings for warm-starting in tf.estimator.Estimators.
add_metrics(...): Creates a new tf.estimator.Estimator which has given metrics.
classifier_parse_example_spec(...): Generates parsing spec for tf.parse_example to be used with classifiers.
regressor_parse_example_spec(...): Generates parsing spec for tf.parse_example to be used with regressors.
train_and_evaluate(...): Train and evaluate the estimator.


Creates a new tf.estimator.Estimator which has given metrics.
Compat aliases for migration
See Migration guide for more details.
tf.compat.v1.estimator.add_metrics
Example usage of custom metric which uses features:


A classifier that can establish a simple baseline.
Inherits From: Estimator, Estimator
This classifier ignores feature values and will learn to predict the average value of each label. For single-label problems, this will predict the probability distribution of the classes as seen in the labels. For multi-label problems, this will predict the fraction of examples that are positive for each class.
Input of train and evaluate should have following features, otherwise there will be a KeyError:
Estimators can be used while eager execution is enabled. Note that input_fn and all hooks are executed inside a graph context, so they have to be written to be compatible with graph mode. Note that input_fn code using tf.data generally works in both graph and eager modes.
View source
Shows the directory name where evaluation metrics are dumped.
View source
Evaluates the model given evaluation data input_fn.
For each step, calls input_fn, which returns one batch of data. Evaluates until:
View source
Exports a SavedModel with tf.MetaGraphDefs for each requested mode.
For each mode passed in via the input_receiver_fn_map, this method builds a new graph by calling the input_receiver_fn to obtain feature and label Tensors. Next, this method calls the Estimator's model_fn in the passed mode to generate the model graph based on those features and labels, and restores the given checkpoint (or, lacking that, the most recent checkpoint) into the graph. Only one of the modes is used for saving variables to the SavedModel (order of preference: tf.estimator.ModeKeys.TRAIN, tf.estimator.ModeKeys.EVAL, then tf.estimator.ModeKeys.PREDICT), such that up to three tf.MetaGraphDefs are saved with a single set of variables in a single SavedModel directory.
For the variables and tf.MetaGraphDefs, a timestamped export directory below export_dir_base, and writes a SavedModel into it containing the tf.MetaGraphDef for the given mode and its associated signatures.
For prediction, the exported MetaGraphDef will provide one SignatureDef for each element of the export_outputs dict returned from the model_fn, named using the same keys. One of these keys is always tf.saved_model.signature_constants.DEFAULT_SERVING_SIGNATURE_DEF_KEY, indicating which signature will be served when a serving request does not specify one. For each signature, the outputs are provided by the corresponding tf.estimator.export.ExportOutputs, and the inputs are always the input receivers provided by the serving_input_receiver_fn.
For training and evaluation, the train_op is stored in an extra collection, and loss, metrics, and predictions are included in a SignatureDef for the mode in question.
Extra assets may be written into the SavedModel via the assets_extra argument. This should be a dict, where each key gives a destination path (including the filename) relative to the assets.extra directory. The corresponding value gives the full path of the source file to be copied. For example, the simple case of copying a single file without renaming it is specified as {'my_asset_file.txt': '/path/to/my_asset_file.txt'}.
View source
Exports inference graph as a SavedModel into the given dir.
For a detailed guide, see SavedModel from Estimators.
This method builds a new graph by first calling the serving_input_receiver_fn to obtain feature Tensors, and then calling this Estimator's model_fn to generate the model graph based on those features. It restores the given checkpoint (or, lacking that, the most recent checkpoint) into this graph in a fresh session. Finally it creates a timestamped export directory below the given export_dir_base, and writes a SavedModel into it containing a single tf.MetaGraphDef saved from this session.
The exported MetaGraphDef will provide one SignatureDef for each element of the export_outputs dict returned from the model_fn, named using the same keys. One of these keys is always tf.saved_model.signature_constants.DEFAULT_SERVING_SIGNATURE_DEF_KEY, indicating which signature will be served when a serving request does not specify one. For each signature, the outputs are provided by the corresponding tf.estimator.export.ExportOutputs, and the inputs are always the input receivers provided by the serving_input_receiver_fn.
Extra assets may be written into the SavedModel via the assets_extra argument. This should be a dict, where each key gives a destination path (including the filename) relative to the assets.extra directory. The corresponding value gives the full path of the source file to be copied. For example, the simple case of copying a single file without renaming it is specified as {'my_asset_file.txt': '/path/to/my_asset_file.txt'}.
The experimental_mode parameter can be used to export a single train/eval/predict graph as a SavedModel. See experimental_export_all_saved_models for full docs.
View source
Returns list of all variable names in this model.
View source
Returns value of the variable given by name.
View source
Finds the filename of the latest saved checkpoint file in model_dir.
View source
Yields predictions for given features.
Please note that interleaving two predict outputs does not work. See: issue/20506
View source
Trains a model given training data input_fn.


An estimator that can establish a simple baseline.
Inherits From: Estimator, Estimator
The estimator uses a user-specified head.
This estimator ignores feature values and will learn to predict the average value of each label. E.g. for single-label classification problems, this will predict the probability distribution of the classes as seen in the labels. For multi-label classification problems, it will predict the ratio of examples that contain each class.
Input of train and evaluate should have following features, otherwise there will be a KeyError:
View source
Shows the directory name where evaluation metrics are dumped.
View source
Evaluates the model given evaluation data input_fn.
For each step, calls input_fn, which returns one batch of data. Evaluates until:
View source
Exports a SavedModel with tf.MetaGraphDefs for each requested mode.
For each mode passed in via the input_receiver_fn_map, this method builds a new graph by calling the input_receiver_fn to obtain feature and label Tensors. Next, this method calls the Estimator's model_fn in the passed mode to generate the model graph based on those features and labels, and restores the given checkpoint (or, lacking that, the most recent checkpoint) into the graph. Only one of the modes is used for saving variables to the SavedModel (order of preference: tf.estimator.ModeKeys.TRAIN, tf.estimator.ModeKeys.EVAL, then tf.estimator.ModeKeys.PREDICT), such that up to three tf.MetaGraphDefs are saved with a single set of variables in a single SavedModel directory.
For the variables and tf.MetaGraphDefs, a timestamped export directory below export_dir_base, and writes a SavedModel into it containing the tf.MetaGraphDef for the given mode and its associated signatures.
For prediction, the exported MetaGraphDef will provide one SignatureDef for each element of the export_outputs dict returned from the model_fn, named using the same keys. One of these keys is always tf.saved_model.signature_constants.DEFAULT_SERVING_SIGNATURE_DEF_KEY, indicating which signature will be served when a serving request does not specify one. For each signature, the outputs are provided by the corresponding tf.estimator.export.ExportOutputs, and the inputs are always the input receivers provided by the serving_input_receiver_fn.
For training and evaluation, the train_op is stored in an extra collection, and loss, metrics, and predictions are included in a SignatureDef for the mode in question.
Extra assets may be written into the SavedModel via the assets_extra argument. This should be a dict, where each key gives a destination path (including the filename) relative to the assets.extra directory. The corresponding value gives the full path of the source file to be copied. For example, the simple case of copying a single file without renaming it is specified as {'my_asset_file.txt': '/path/to/my_asset_file.txt'}.
View source
Exports inference graph as a SavedModel into the given dir.
For a detailed guide, see SavedModel from Estimators.
This method builds a new graph by first calling the serving_input_receiver_fn to obtain feature Tensors, and then calling this Estimator's model_fn to generate the model graph based on those features. It restores the given checkpoint (or, lacking that, the most recent checkpoint) into this graph in a fresh session. Finally it creates a timestamped export directory below the given export_dir_base, and writes a SavedModel into it containing a single tf.MetaGraphDef saved from this session.
The exported MetaGraphDef will provide one SignatureDef for each element of the export_outputs dict returned from the model_fn, named using the same keys. One of these keys is always tf.saved_model.signature_constants.DEFAULT_SERVING_SIGNATURE_DEF_KEY, indicating which signature will be served when a serving request does not specify one. For each signature, the outputs are provided by the corresponding tf.estimator.export.ExportOutputs, and the inputs are always the input receivers provided by the serving_input_receiver_fn.
Extra assets may be written into the SavedModel via the assets_extra argument. This should be a dict, where each key gives a destination path (including the filename) relative to the assets.extra directory. The corresponding value gives the full path of the source file to be copied. For example, the simple case of copying a single file without renaming it is specified as {'my_asset_file.txt': '/path/to/my_asset_file.txt'}.
The experimental_mode parameter can be used to export a single train/eval/predict graph as a SavedModel. See experimental_export_all_saved_models for full docs.
View source
Returns list of all variable names in this model.
View source
Returns value of the variable given by name.
View source
Finds the filename of the latest saved checkpoint file in model_dir.
View source
Yields predictions for given features.
Please note that interleaving two predict outputs does not work. See: issue/20506
View source
Trains a model given training data input_fn.


A regressor that can establish a simple baseline.
Inherits From: Estimator, Estimator
This regressor ignores feature values and will learn to predict the average value of each label.
Input of train and evaluate should have following features, otherwise there will be a KeyError:
Estimators can be used while eager execution is enabled. Note that input_fn and all hooks are executed inside a graph context, so they have to be written to be compatible with graph mode. Note that input_fn code using tf.data generally works in both graph and eager modes.
View source
Shows the directory name where evaluation metrics are dumped.
View source
Evaluates the model given evaluation data input_fn.
For each step, calls input_fn, which returns one batch of data. Evaluates until:
View source
Exports a SavedModel with tf.MetaGraphDefs for each requested mode.
For each mode passed in via the input_receiver_fn_map, this method builds a new graph by calling the input_receiver_fn to obtain feature and label Tensors. Next, this method calls the Estimator's model_fn in the passed mode to generate the model graph based on those features and labels, and restores the given checkpoint (or, lacking that, the most recent checkpoint) into the graph. Only one of the modes is used for saving variables to the SavedModel (order of preference: tf.estimator.ModeKeys.TRAIN, tf.estimator.ModeKeys.EVAL, then tf.estimator.ModeKeys.PREDICT), such that up to three tf.MetaGraphDefs are saved with a single set of variables in a single SavedModel directory.
For the variables and tf.MetaGraphDefs, a timestamped export directory below export_dir_base, and writes a SavedModel into it containing the tf.MetaGraphDef for the given mode and its associated signatures.
For prediction, the exported MetaGraphDef will provide one SignatureDef for each element of the export_outputs dict returned from the model_fn, named using the same keys. One of these keys is always tf.saved_model.signature_constants.DEFAULT_SERVING_SIGNATURE_DEF_KEY, indicating which signature will be served when a serving request does not specify one. For each signature, the outputs are provided by the corresponding tf.estimator.export.ExportOutputs, and the inputs are always the input receivers provided by the serving_input_receiver_fn.
For training and evaluation, the train_op is stored in an extra collection, and loss, metrics, and predictions are included in a SignatureDef for the mode in question.
Extra assets may be written into the SavedModel via the assets_extra argument. This should be a dict, where each key gives a destination path (including the filename) relative to the assets.extra directory. The corresponding value gives the full path of the source file to be copied. For example, the simple case of copying a single file without renaming it is specified as {'my_asset_file.txt': '/path/to/my_asset_file.txt'}.
View source
Exports inference graph as a SavedModel into the given dir.
For a detailed guide, see SavedModel from Estimators.
This method builds a new graph by first calling the serving_input_receiver_fn to obtain feature Tensors, and then calling this Estimator's model_fn to generate the model graph based on those features. It restores the given checkpoint (or, lacking that, the most recent checkpoint) into this graph in a fresh session. Finally it creates a timestamped export directory below the given export_dir_base, and writes a SavedModel into it containing a single tf.MetaGraphDef saved from this session.
The exported MetaGraphDef will provide one SignatureDef for each element of the export_outputs dict returned from the model_fn, named using the same keys. One of these keys is always tf.saved_model.signature_constants.DEFAULT_SERVING_SIGNATURE_DEF_KEY, indicating which signature will be served when a serving request does not specify one. For each signature, the outputs are provided by the corresponding tf.estimator.export.ExportOutputs, and the inputs are always the input receivers provided by the serving_input_receiver_fn.
Extra assets may be written into the SavedModel via the assets_extra argument. This should be a dict, where each key gives a destination path (including the filename) relative to the assets.extra directory. The corresponding value gives the full path of the source file to be copied. For example, the simple case of copying a single file without renaming it is specified as {'my_asset_file.txt': '/path/to/my_asset_file.txt'}.
The experimental_mode parameter can be used to export a single train/eval/predict graph as a SavedModel. See experimental_export_all_saved_models for full docs.
View source
Returns list of all variable names in this model.
View source
Returns value of the variable given by name.
View source
Finds the filename of the latest saved checkpoint file in model_dir.
View source
Yields predictions for given features.
Please note that interleaving two predict outputs does not work. See: issue/20506
View source
Trains a model given training data input_fn.


This class exports the serving graph and checkpoints of the best models.
Inherits From: Exporter
Compat aliases for migration
See Migration guide for more details.
tf.compat.v1.estimator.BestExporter
This class performs a model export everytime the new model is better than any existing model.
A directory name under the export base directory where exports of this type are written. Should not be None nor empty.
View source
Exports the given Estimator to a specific format.


Creates a Head for single label binary classification.
Inherits From: Head
Compat aliases for migration
See Migration guide for more details.
tf.compat.v1.estimator.BinaryClassHead
Uses sigmoid_cross_entropy_with_logits loss.
The head expects logits with shape [D0, D1, ... DN, 1]. In many applications, the shape is [batch_size, 1].
labels must be a dense Tensor with shape matching logits, namely [D0, D1, ... DN, 1]. If label_vocabulary given, labels must be a string Tensor with values from the vocabulary. If label_vocabulary is not given, labels must be float Tensor with values in the interval [0, 1].
If weight_column is specified, weights must be of shape [D0, D1, ... DN], or [D0, D1, ... DN, 1].
The loss is the weighted sum over the input dimensions. Namely, if the input labels have shape [batch_size, 1], the loss is the weighted sum over batch_size.
Also supports custom loss_fn. loss_fn takes (labels, logits) or (labels, logits, features, loss_reduction) as arguments and returns loss with shape [D0, D1, ... DN, 1]. loss_fn must support float labels with shape [D0, D1, ... DN, 1]. Namely, the head applies label_vocabulary to the input labels before passing them to loss_fn.
Usage with a canned estimator:
It can also be used with a custom model_fn. Example:
View source
Returns EstimatorSpec that a model_fn can return.
It is recommended to pass all args via name.
View source
Returns regularized training loss. See base_head.Head for details.
View source
Creates metrics. See base_head.Head for details.
View source
Return predictions based on keys.
See base_head.Head for details.
View source
Updates eval metrics. See base_head.Head for details.


A Classifier for Tensorflow Boosted Trees models.
Inherits From: Estimator
Compat aliases for migration
See Migration guide for more details.
tf.compat.v1.estimator.BoostedTreesClassifier
Estimators can be used while eager execution is enabled. Note that input_fn and all hooks are executed inside a graph context, so they have to be written to be compatible with graph mode. Note that input_fn code using tf.data generally works in both graph and eager modes.
View source
Shows the directory name where evaluation metrics are dumped.
View source
Evaluates the model given evaluation data input_fn.
For each step, calls input_fn, which returns one batch of data. Evaluates until:
View source
Exports a SavedModel with tf.MetaGraphDefs for each requested mode.
For each mode passed in via the input_receiver_fn_map, this method builds a new graph by calling the input_receiver_fn to obtain feature and label Tensors. Next, this method calls the Estimator's model_fn in the passed mode to generate the model graph based on those features and labels, and restores the given checkpoint (or, lacking that, the most recent checkpoint) into the graph. Only one of the modes is used for saving variables to the SavedModel (order of preference: tf.estimator.ModeKeys.TRAIN, tf.estimator.ModeKeys.EVAL, then tf.estimator.ModeKeys.PREDICT), such that up to three tf.MetaGraphDefs are saved with a single set of variables in a single SavedModel directory.
For the variables and tf.MetaGraphDefs, a timestamped export directory below export_dir_base, and writes a SavedModel into it containing the tf.MetaGraphDef for the given mode and its associated signatures.
For prediction, the exported MetaGraphDef will provide one SignatureDef for each element of the export_outputs dict returned from the model_fn, named using the same keys. One of these keys is always tf.saved_model.signature_constants.DEFAULT_SERVING_SIGNATURE_DEF_KEY, indicating which signature will be served when a serving request does not specify one. For each signature, the outputs are provided by the corresponding tf.estimator.export.ExportOutputs, and the inputs are always the input receivers provided by the serving_input_receiver_fn.
For training and evaluation, the train_op is stored in an extra collection, and loss, metrics, and predictions are included in a SignatureDef for the mode in question.
Extra assets may be written into the SavedModel via the assets_extra argument. This should be a dict, where each key gives a destination path (including the filename) relative to the assets.extra directory. The corresponding value gives the full path of the source file to be copied. For example, the simple case of copying a single file without renaming it is specified as {'my_asset_file.txt': '/path/to/my_asset_file.txt'}.
View source
Computes gain-based feature importances.
The higher the value, the more important the corresponding feature.
View source
Computes model explainability outputs per example along with predictions.
Currently supports directional feature contributions (DFCs). For each instance, DFCs indicate the aggregate contribution of each feature. See https://arxiv.org/abs/1312.1121 and http://blog.datadive.net/interpreting-random-forests/ for more details.
View source
Exports inference graph as a SavedModel into the given dir.
For a detailed guide, see SavedModel from Estimators.
This method builds a new graph by first calling the serving_input_receiver_fn to obtain feature Tensors, and then calling this Estimator's model_fn to generate the model graph based on those features. It restores the given checkpoint (or, lacking that, the most recent checkpoint) into this graph in a fresh session. Finally it creates a timestamped export directory below the given export_dir_base, and writes a SavedModel into it containing a single tf.MetaGraphDef saved from this session.
The exported MetaGraphDef will provide one SignatureDef for each element of the export_outputs dict returned from the model_fn, named using the same keys. One of these keys is always tf.saved_model.signature_constants.DEFAULT_SERVING_SIGNATURE_DEF_KEY, indicating which signature will be served when a serving request does not specify one. For each signature, the outputs are provided by the corresponding tf.estimator.export.ExportOutputs, and the inputs are always the input receivers provided by the serving_input_receiver_fn.
Extra assets may be written into the SavedModel via the assets_extra argument. This should be a dict, where each key gives a destination path (including the filename) relative to the assets.extra directory. The corresponding value gives the full path of the source file to be copied. For example, the simple case of copying a single file without renaming it is specified as {'my_asset_file.txt': '/path/to/my_asset_file.txt'}.
The experimental_mode parameter can be used to export a single train/eval/predict graph as a SavedModel. See experimental_export_all_saved_models for full docs.
View source
Exports inference graph as a SavedModel into the given dir. (deprecated)
For a detailed guide, see SavedModel from Estimators.
This method builds a new graph by first calling the serving_input_receiver_fn to obtain feature Tensors, and then calling this Estimator's model_fn to generate the model graph based on those features. It restores the given checkpoint (or, lacking that, the most recent checkpoint) into this graph in a fresh session. Finally it creates a timestamped export directory below the given export_dir_base, and writes a SavedModel into it containing a single tf.MetaGraphDef saved from this session.
The exported MetaGraphDef will provide one SignatureDef for each element of the export_outputs dict returned from the model_fn, named using the same keys. One of these keys is always tf.saved_model.signature_constants.DEFAULT_SERVING_SIGNATURE_DEF_KEY, indicating which signature will be served when a serving request does not specify one. For each signature, the outputs are provided by the corresponding tf.estimator.export.ExportOutputs, and the inputs are always the input receivers provided by the serving_input_receiver_fn.
Extra assets may be written into the SavedModel via the assets_extra argument. This should be a dict, where each key gives a destination path (including the filename) relative to the assets.extra directory. The corresponding value gives the full path of the source file to be copied. For example, the simple case of copying a single file without renaming it is specified as {'my_asset_file.txt': '/path/to/my_asset_file.txt'}.
View source
Returns list of all variable names in this model.
View source
Returns value of the variable given by name.
View source
Finds the filename of the latest saved checkpoint file in model_dir.
View source
Yields predictions for given features.
Please note that interleaving two predict outputs does not work. See: issue/20506
View source
Trains a model given training data input_fn.


An Estimator for Tensorflow Boosted Trees models.
Inherits From: Estimator
Compat aliases for migration
See Migration guide for more details.
tf.compat.v1.estimator.BoostedTreesEstimator
View source
Shows the directory name where evaluation metrics are dumped.
View source
Evaluates the model given evaluation data input_fn.
For each step, calls input_fn, which returns one batch of data. Evaluates until:
View source
Exports a SavedModel with tf.MetaGraphDefs for each requested mode.
For each mode passed in via the input_receiver_fn_map, this method builds a new graph by calling the input_receiver_fn to obtain feature and label Tensors. Next, this method calls the Estimator's model_fn in the passed mode to generate the model graph based on those features and labels, and restores the given checkpoint (or, lacking that, the most recent checkpoint) into the graph. Only one of the modes is used for saving variables to the SavedModel (order of preference: tf.estimator.ModeKeys.TRAIN, tf.estimator.ModeKeys.EVAL, then tf.estimator.ModeKeys.PREDICT), such that up to three tf.MetaGraphDefs are saved with a single set of variables in a single SavedModel directory.
For the variables and tf.MetaGraphDefs, a timestamped export directory below export_dir_base, and writes a SavedModel into it containing the tf.MetaGraphDef for the given mode and its associated signatures.
For prediction, the exported MetaGraphDef will provide one SignatureDef for each element of the export_outputs dict returned from the model_fn, named using the same keys. One of these keys is always tf.saved_model.signature_constants.DEFAULT_SERVING_SIGNATURE_DEF_KEY, indicating which signature will be served when a serving request does not specify one. For each signature, the outputs are provided by the corresponding tf.estimator.export.ExportOutputs, and the inputs are always the input receivers provided by the serving_input_receiver_fn.
For training and evaluation, the train_op is stored in an extra collection, and loss, metrics, and predictions are included in a SignatureDef for the mode in question.
Extra assets may be written into the SavedModel via the assets_extra argument. This should be a dict, where each key gives a destination path (including the filename) relative to the assets.extra directory. The corresponding value gives the full path of the source file to be copied. For example, the simple case of copying a single file without renaming it is specified as {'my_asset_file.txt': '/path/to/my_asset_file.txt'}.
View source
Computes gain-based feature importances.
The higher the value, the more important the corresponding feature.
View source
Computes model explainability outputs per example along with predictions.
Currently supports directional feature contributions (DFCs). For each instance, DFCs indicate the aggregate contribution of each feature. See https://arxiv.org/abs/1312.1121 and http://blog.datadive.net/interpreting-random-forests/ for more details.
View source
Exports inference graph as a SavedModel into the given dir.
For a detailed guide, see SavedModel from Estimators.
This method builds a new graph by first calling the serving_input_receiver_fn to obtain feature Tensors, and then calling this Estimator's model_fn to generate the model graph based on those features. It restores the given checkpoint (or, lacking that, the most recent checkpoint) into this graph in a fresh session. Finally it creates a timestamped export directory below the given export_dir_base, and writes a SavedModel into it containing a single tf.MetaGraphDef saved from this session.
The exported MetaGraphDef will provide one SignatureDef for each element of the export_outputs dict returned from the model_fn, named using the same keys. One of these keys is always tf.saved_model.signature_constants.DEFAULT_SERVING_SIGNATURE_DEF_KEY, indicating which signature will be served when a serving request does not specify one. For each signature, the outputs are provided by the corresponding tf.estimator.export.ExportOutputs, and the inputs are always the input receivers provided by the serving_input_receiver_fn.
Extra assets may be written into the SavedModel via the assets_extra argument. This should be a dict, where each key gives a destination path (including the filename) relative to the assets.extra directory. The corresponding value gives the full path of the source file to be copied. For example, the simple case of copying a single file without renaming it is specified as {'my_asset_file.txt': '/path/to/my_asset_file.txt'}.
The experimental_mode parameter can be used to export a single train/eval/predict graph as a SavedModel. See experimental_export_all_saved_models for full docs.
View source
Exports inference graph as a SavedModel into the given dir. (deprecated)
For a detailed guide, see SavedModel from Estimators.
This method builds a new graph by first calling the serving_input_receiver_fn to obtain feature Tensors, and then calling this Estimator's model_fn to generate the model graph based on those features. It restores the given checkpoint (or, lacking that, the most recent checkpoint) into this graph in a fresh session. Finally it creates a timestamped export directory below the given export_dir_base, and writes a SavedModel into it containing a single tf.MetaGraphDef saved from this session.
The exported MetaGraphDef will provide one SignatureDef for each element of the export_outputs dict returned from the model_fn, named using the same keys. One of these keys is always tf.saved_model.signature_constants.DEFAULT_SERVING_SIGNATURE_DEF_KEY, indicating which signature will be served when a serving request does not specify one. For each signature, the outputs are provided by the corresponding tf.estimator.export.ExportOutputs, and the inputs are always the input receivers provided by the serving_input_receiver_fn.
Extra assets may be written into the SavedModel via the assets_extra argument. This should be a dict, where each key gives a destination path (including the filename) relative to the assets.extra directory. The corresponding value gives the full path of the source file to be copied. For example, the simple case of copying a single file without renaming it is specified as {'my_asset_file.txt': '/path/to/my_asset_file.txt'}.
View source
Returns list of all variable names in this model.
View source
Returns value of the variable given by name.
View source
Finds the filename of the latest saved checkpoint file in model_dir.
View source
Yields predictions for given features.
Please note that interleaving two predict outputs does not work. See: issue/20506
View source
Trains a model given training data input_fn.


A Regressor for Tensorflow Boosted Trees models.
Inherits From: Estimator
Compat aliases for migration
See Migration guide for more details.
tf.compat.v1.estimator.BoostedTreesRegressor
Estimators can be used while eager execution is enabled. Note that input_fn and all hooks are executed inside a graph context, so they have to be written to be compatible with graph mode. Note that input_fn code using tf.data generally works in both graph and eager modes.
View source
Shows the directory name where evaluation metrics are dumped.
View source
Evaluates the model given evaluation data input_fn.
For each step, calls input_fn, which returns one batch of data. Evaluates until:
View source
Exports a SavedModel with tf.MetaGraphDefs for each requested mode.
For each mode passed in via the input_receiver_fn_map, this method builds a new graph by calling the input_receiver_fn to obtain feature and label Tensors. Next, this method calls the Estimator's model_fn in the passed mode to generate the model graph based on those features and labels, and restores the given checkpoint (or, lacking that, the most recent checkpoint) into the graph. Only one of the modes is used for saving variables to the SavedModel (order of preference: tf.estimator.ModeKeys.TRAIN, tf.estimator.ModeKeys.EVAL, then tf.estimator.ModeKeys.PREDICT), such that up to three tf.MetaGraphDefs are saved with a single set of variables in a single SavedModel directory.
For the variables and tf.MetaGraphDefs, a timestamped export directory below export_dir_base, and writes a SavedModel into it containing the tf.MetaGraphDef for the given mode and its associated signatures.
For prediction, the exported MetaGraphDef will provide one SignatureDef for each element of the export_outputs dict returned from the model_fn, named using the same keys. One of these keys is always tf.saved_model.signature_constants.DEFAULT_SERVING_SIGNATURE_DEF_KEY, indicating which signature will be served when a serving request does not specify one. For each signature, the outputs are provided by the corresponding tf.estimator.export.ExportOutputs, and the inputs are always the input receivers provided by the serving_input_receiver_fn.
For training and evaluation, the train_op is stored in an extra collection, and loss, metrics, and predictions are included in a SignatureDef for the mode in question.
Extra assets may be written into the SavedModel via the assets_extra argument. This should be a dict, where each key gives a destination path (including the filename) relative to the assets.extra directory. The corresponding value gives the full path of the source file to be copied. For example, the simple case of copying a single file without renaming it is specified as {'my_asset_file.txt': '/path/to/my_asset_file.txt'}.
View source
Computes gain-based feature importances.
The higher the value, the more important the corresponding feature.
View source
Computes model explainability outputs per example along with predictions.
Currently supports directional feature contributions (DFCs). For each instance, DFCs indicate the aggregate contribution of each feature. See https://arxiv.org/abs/1312.1121 and http://blog.datadive.net/interpreting-random-forests/ for more details.
View source
Exports inference graph as a SavedModel into the given dir.
For a detailed guide, see SavedModel from Estimators.
This method builds a new graph by first calling the serving_input_receiver_fn to obtain feature Tensors, and then calling this Estimator's model_fn to generate the model graph based on those features. It restores the given checkpoint (or, lacking that, the most recent checkpoint) into this graph in a fresh session. Finally it creates a timestamped export directory below the given export_dir_base, and writes a SavedModel into it containing a single tf.MetaGraphDef saved from this session.
The exported MetaGraphDef will provide one SignatureDef for each element of the export_outputs dict returned from the model_fn, named using the same keys. One of these keys is always tf.saved_model.signature_constants.DEFAULT_SERVING_SIGNATURE_DEF_KEY, indicating which signature will be served when a serving request does not specify one. For each signature, the outputs are provided by the corresponding tf.estimator.export.ExportOutputs, and the inputs are always the input receivers provided by the serving_input_receiver_fn.
Extra assets may be written into the SavedModel via the assets_extra argument. This should be a dict, where each key gives a destination path (including the filename) relative to the assets.extra directory. The corresponding value gives the full path of the source file to be copied. For example, the simple case of copying a single file without renaming it is specified as {'my_asset_file.txt': '/path/to/my_asset_file.txt'}.
The experimental_mode parameter can be used to export a single train/eval/predict graph as a SavedModel. See experimental_export_all_saved_models for full docs.
View source
Exports inference graph as a SavedModel into the given dir. (deprecated)
For a detailed guide, see SavedModel from Estimators.
This method builds a new graph by first calling the serving_input_receiver_fn to obtain feature Tensors, and then calling this Estimator's model_fn to generate the model graph based on those features. It restores the given checkpoint (or, lacking that, the most recent checkpoint) into this graph in a fresh session. Finally it creates a timestamped export directory below the given export_dir_base, and writes a SavedModel into it containing a single tf.MetaGraphDef saved from this session.
The exported MetaGraphDef will provide one SignatureDef for each element of the export_outputs dict returned from the model_fn, named using the same keys. One of these keys is always tf.saved_model.signature_constants.DEFAULT_SERVING_SIGNATURE_DEF_KEY, indicating which signature will be served when a serving request does not specify one. For each signature, the outputs are provided by the corresponding tf.estimator.export.ExportOutputs, and the inputs are always the input receivers provided by the serving_input_receiver_fn.
Extra assets may be written into the SavedModel via the assets_extra argument. This should be a dict, where each key gives a destination path (including the filename) relative to the assets.extra directory. The corresponding value gives the full path of the source file to be copied. For example, the simple case of copying a single file without renaming it is specified as {'my_asset_file.txt': '/path/to/my_asset_file.txt'}.
View source
Returns list of all variable names in this model.
View source
Returns value of the variable given by name.
View source
Finds the filename of the latest saved checkpoint file in model_dir.
View source
Yields predictions for given features.
Please note that interleaving two predict outputs does not work. See: issue/20506
View source
Trains a model given training data input_fn.


Saves checkpoints every N steps or seconds.
Inherits From: SessionRunHook
Compat aliases for migration
See Migration guide for more details.
tf.compat.v1.estimator.CheckpointSaverHook, tf.compat.v1.train.CheckpointSaverHook
View source
Called when new TensorFlow session is created.
This is called to signal the hooks that a new session has been created. This has two essential differences with the situation in which begin is called:
View source
Called after each call to run().
The run_values argument contains results of requested ops/tensors by before_run().
The run_context argument is the same one send to before_run call. run_context.request_stop() can be called to stop the iteration.
If session.run() raises any exceptions then after_run() is not called.
View source
Called before each call to run().
You can return from this call a SessionRunArgs object indicating ops or tensors to add to the upcoming run() call. These ops/tensors will be run together with the ops/tensors originally passed to the original run() call. The run args you return can also contain feeds to be added to the run() call.
The run_context argument is a SessionRunContext that provides information about the upcoming run() call: the originally requested op/tensors, the TensorFlow Session.
At this point graph is finalized and you can not add ops.
View source
Called once before using the session.
When called, the default graph is the one that will be launched in the session. The hook can modify the graph by adding new operations to it. After the begin() call the graph will be finalized and the other callbacks can not modify the graph anymore. Second call of begin() on the same graph, should not change the graph.
View source
Called at the end of session.
The session argument can be used in case the hook wants to run final ops, such as saving a last checkpoint.
If session.run() raises exception other than OutOfRangeError or StopIteration then end() is not called. Note the difference between end() and after_run() behavior when session.run() raises OutOfRangeError or StopIteration. In that case end() is called but after_run() is not called.


Interface for listeners that take action before or after checkpoint save.
Compat aliases for migration
See Migration guide for more details.
tf.compat.v1.estimator.CheckpointSaverListener, tf.compat.v1.train.CheckpointSaverListener
CheckpointSaverListener triggers only in steps when CheckpointSaverHook is triggered, and provides callbacks at the following points:
To use a listener, implement a class and pass the listener to a CheckpointSaverHook, as in this example:
A CheckpointSaverListener may simply take some action after every checkpoint save. It is also possible for the listener to use its own schedule to act less frequently, e.g. based on global_step_value. In this case, implementors should implement the end() method to handle actions related to the last checkpoint save. But the listener should not act twice if after_save() already handled this last checkpoint save.
A CheckpointSaverListener can request training to be stopped, by returning True in after_save. Please note that, in replicated distributed training setting, only chief should use this behavior. Otherwise each worker will do their own evaluation, which may be wasteful of resources.
View source
View source
View source
View source


Generates parsing spec for tf.parse_example to be used with classifiers.
If users keep data in tf.Example format, they need to call tf.parse_example with a proper feature spec. There are two main things that this utility helps:
Example output of parsing spec:
Example usage with a classifier:


A classifier for TensorFlow DNN models.
Inherits From: Estimator, Estimator
Input of train and evaluate should have following features, otherwise there will be a KeyError:
Loss is calculated by using softmax cross entropy.
Estimators can be used while eager execution is enabled. Note that input_fn and all hooks are executed inside a graph context, so they have to be written to be compatible with graph mode. Note that input_fn code using tf.data generally works in both graph and eager modes.
View source
Shows the directory name where evaluation metrics are dumped.
View source
Evaluates the model given evaluation data input_fn.
For each step, calls input_fn, which returns one batch of data. Evaluates until:
View source
Exports a SavedModel with tf.MetaGraphDefs for each requested mode.
For each mode passed in via the input_receiver_fn_map, this method builds a new graph by calling the input_receiver_fn to obtain feature and label Tensors. Next, this method calls the Estimator's model_fn in the passed mode to generate the model graph based on those features and labels, and restores the given checkpoint (or, lacking that, the most recent checkpoint) into the graph. Only one of the modes is used for saving variables to the SavedModel (order of preference: tf.estimator.ModeKeys.TRAIN, tf.estimator.ModeKeys.EVAL, then tf.estimator.ModeKeys.PREDICT), such that up to three tf.MetaGraphDefs are saved with a single set of variables in a single SavedModel directory.
For the variables and tf.MetaGraphDefs, a timestamped export directory below export_dir_base, and writes a SavedModel into it containing the tf.MetaGraphDef for the given mode and its associated signatures.
For prediction, the exported MetaGraphDef will provide one SignatureDef for each element of the export_outputs dict returned from the model_fn, named using the same keys. One of these keys is always tf.saved_model.signature_constants.DEFAULT_SERVING_SIGNATURE_DEF_KEY, indicating which signature will be served when a serving request does not specify one. For each signature, the outputs are provided by the corresponding tf.estimator.export.ExportOutputs, and the inputs are always the input receivers provided by the serving_input_receiver_fn.
For training and evaluation, the train_op is stored in an extra collection, and loss, metrics, and predictions are included in a SignatureDef for the mode in question.
Extra assets may be written into the SavedModel via the assets_extra argument. This should be a dict, where each key gives a destination path (including the filename) relative to the assets.extra directory. The corresponding value gives the full path of the source file to be copied. For example, the simple case of copying a single file without renaming it is specified as {'my_asset_file.txt': '/path/to/my_asset_file.txt'}.
View source
Exports inference graph as a SavedModel into the given dir.
For a detailed guide, see SavedModel from Estimators.
This method builds a new graph by first calling the serving_input_receiver_fn to obtain feature Tensors, and then calling this Estimator's model_fn to generate the model graph based on those features. It restores the given checkpoint (or, lacking that, the most recent checkpoint) into this graph in a fresh session. Finally it creates a timestamped export directory below the given export_dir_base, and writes a SavedModel into it containing a single tf.MetaGraphDef saved from this session.
The exported MetaGraphDef will provide one SignatureDef for each element of the export_outputs dict returned from the model_fn, named using the same keys. One of these keys is always tf.saved_model.signature_constants.DEFAULT_SERVING_SIGNATURE_DEF_KEY, indicating which signature will be served when a serving request does not specify one. For each signature, the outputs are provided by the corresponding tf.estimator.export.ExportOutputs, and the inputs are always the input receivers provided by the serving_input_receiver_fn.
Extra assets may be written into the SavedModel via the assets_extra argument. This should be a dict, where each key gives a destination path (including the filename) relative to the assets.extra directory. The corresponding value gives the full path of the source file to be copied. For example, the simple case of copying a single file without renaming it is specified as {'my_asset_file.txt': '/path/to/my_asset_file.txt'}.
The experimental_mode parameter can be used to export a single train/eval/predict graph as a SavedModel. See experimental_export_all_saved_models for full docs.
View source
Returns list of all variable names in this model.
View source
Returns value of the variable given by name.
View source
Finds the filename of the latest saved checkpoint file in model_dir.
View source
Yields predictions for given features.
Please note that interleaving two predict outputs does not work. See: issue/20506
View source
Trains a model given training data input_fn.


An estimator for TensorFlow DNN models with user-specified head.
Inherits From: Estimator, Estimator
Input of train and evaluate should have following features, otherwise there will be a KeyError:
Loss and predicted output are determined by the specified head.
Estimators can be used while eager execution is enabled. Note that input_fn and all hooks are executed inside a graph context, so they have to be written to be compatible with graph mode. Note that input_fn code using tf.data generally works in both graph and eager modes.
View source
Shows the directory name where evaluation metrics are dumped.
View source
Evaluates the model given evaluation data input_fn.
For each step, calls input_fn, which returns one batch of data. Evaluates until:
View source
Exports a SavedModel with tf.MetaGraphDefs for each requested mode.
For each mode passed in via the input_receiver_fn_map, this method builds a new graph by calling the input_receiver_fn to obtain feature and label Tensors. Next, this method calls the Estimator's model_fn in the passed mode to generate the model graph based on those features and labels, and restores the given checkpoint (or, lacking that, the most recent checkpoint) into the graph. Only one of the modes is used for saving variables to the SavedModel (order of preference: tf.estimator.ModeKeys.TRAIN, tf.estimator.ModeKeys.EVAL, then tf.estimator.ModeKeys.PREDICT), such that up to three tf.MetaGraphDefs are saved with a single set of variables in a single SavedModel directory.
For the variables and tf.MetaGraphDefs, a timestamped export directory below export_dir_base, and writes a SavedModel into it containing the tf.MetaGraphDef for the given mode and its associated signatures.
For prediction, the exported MetaGraphDef will provide one SignatureDef for each element of the export_outputs dict returned from the model_fn, named using the same keys. One of these keys is always tf.saved_model.signature_constants.DEFAULT_SERVING_SIGNATURE_DEF_KEY, indicating which signature will be served when a serving request does not specify one. For each signature, the outputs are provided by the corresponding tf.estimator.export.ExportOutputs, and the inputs are always the input receivers provided by the serving_input_receiver_fn.
For training and evaluation, the train_op is stored in an extra collection, and loss, metrics, and predictions are included in a SignatureDef for the mode in question.
Extra assets may be written into the SavedModel via the assets_extra argument. This should be a dict, where each key gives a destination path (including the filename) relative to the assets.extra directory. The corresponding value gives the full path of the source file to be copied. For example, the simple case of copying a single file without renaming it is specified as {'my_asset_file.txt': '/path/to/my_asset_file.txt'}.
View source
Exports inference graph as a SavedModel into the given dir.
For a detailed guide, see SavedModel from Estimators.
This method builds a new graph by first calling the serving_input_receiver_fn to obtain feature Tensors, and then calling this Estimator's model_fn to generate the model graph based on those features. It restores the given checkpoint (or, lacking that, the most recent checkpoint) into this graph in a fresh session. Finally it creates a timestamped export directory below the given export_dir_base, and writes a SavedModel into it containing a single tf.MetaGraphDef saved from this session.
The exported MetaGraphDef will provide one SignatureDef for each element of the export_outputs dict returned from the model_fn, named using the same keys. One of these keys is always tf.saved_model.signature_constants.DEFAULT_SERVING_SIGNATURE_DEF_KEY, indicating which signature will be served when a serving request does not specify one. For each signature, the outputs are provided by the corresponding tf.estimator.export.ExportOutputs, and the inputs are always the input receivers provided by the serving_input_receiver_fn.
Extra assets may be written into the SavedModel via the assets_extra argument. This should be a dict, where each key gives a destination path (including the filename) relative to the assets.extra directory. The corresponding value gives the full path of the source file to be copied. For example, the simple case of copying a single file without renaming it is specified as {'my_asset_file.txt': '/path/to/my_asset_file.txt'}.
The experimental_mode parameter can be used to export a single train/eval/predict graph as a SavedModel. See experimental_export_all_saved_models for full docs.
View source
Returns list of all variable names in this model.
View source
Returns value of the variable given by name.
View source
Finds the filename of the latest saved checkpoint file in model_dir.
View source
Yields predictions for given features.
Please note that interleaving two predict outputs does not work. See: issue/20506
View source
Trains a model given training data input_fn.


An estimator for TensorFlow Linear and DNN joined classification models.
Inherits From: Estimator, Estimator
Input of train and evaluate should have following features, otherwise there will be a KeyError:
Loss is calculated by using softmax cross entropy.
Estimators can be used while eager execution is enabled. Note that input_fn and all hooks are executed inside a graph context, so they have to be written to be compatible with graph mode. Note that input_fn code using tf.data generally works in both graph and eager modes.
View source
Shows the directory name where evaluation metrics are dumped.
View source
Evaluates the model given evaluation data input_fn.
For each step, calls input_fn, which returns one batch of data. Evaluates until:
View source
Exports a SavedModel with tf.MetaGraphDefs for each requested mode.
For each mode passed in via the input_receiver_fn_map, this method builds a new graph by calling the input_receiver_fn to obtain feature and label Tensors. Next, this method calls the Estimator's model_fn in the passed mode to generate the model graph based on those features and labels, and restores the given checkpoint (or, lacking that, the most recent checkpoint) into the graph. Only one of the modes is used for saving variables to the SavedModel (order of preference: tf.estimator.ModeKeys.TRAIN, tf.estimator.ModeKeys.EVAL, then tf.estimator.ModeKeys.PREDICT), such that up to three tf.MetaGraphDefs are saved with a single set of variables in a single SavedModel directory.
For the variables and tf.MetaGraphDefs, a timestamped export directory below export_dir_base, and writes a SavedModel into it containing the tf.MetaGraphDef for the given mode and its associated signatures.
For prediction, the exported MetaGraphDef will provide one SignatureDef for each element of the export_outputs dict returned from the model_fn, named using the same keys. One of these keys is always tf.saved_model.signature_constants.DEFAULT_SERVING_SIGNATURE_DEF_KEY, indicating which signature will be served when a serving request does not specify one. For each signature, the outputs are provided by the corresponding tf.estimator.export.ExportOutputs, and the inputs are always the input receivers provided by the serving_input_receiver_fn.
For training and evaluation, the train_op is stored in an extra collection, and loss, metrics, and predictions are included in a SignatureDef for the mode in question.
Extra assets may be written into the SavedModel via the assets_extra argument. This should be a dict, where each key gives a destination path (including the filename) relative to the assets.extra directory. The corresponding value gives the full path of the source file to be copied. For example, the simple case of copying a single file without renaming it is specified as {'my_asset_file.txt': '/path/to/my_asset_file.txt'}.
View source
Exports inference graph as a SavedModel into the given dir.
For a detailed guide, see SavedModel from Estimators.
This method builds a new graph by first calling the serving_input_receiver_fn to obtain feature Tensors, and then calling this Estimator's model_fn to generate the model graph based on those features. It restores the given checkpoint (or, lacking that, the most recent checkpoint) into this graph in a fresh session. Finally it creates a timestamped export directory below the given export_dir_base, and writes a SavedModel into it containing a single tf.MetaGraphDef saved from this session.
The exported MetaGraphDef will provide one SignatureDef for each element of the export_outputs dict returned from the model_fn, named using the same keys. One of these keys is always tf.saved_model.signature_constants.DEFAULT_SERVING_SIGNATURE_DEF_KEY, indicating which signature will be served when a serving request does not specify one. For each signature, the outputs are provided by the corresponding tf.estimator.export.ExportOutputs, and the inputs are always the input receivers provided by the serving_input_receiver_fn.
Extra assets may be written into the SavedModel via the assets_extra argument. This should be a dict, where each key gives a destination path (including the filename) relative to the assets.extra directory. The corresponding value gives the full path of the source file to be copied. For example, the simple case of copying a single file without renaming it is specified as {'my_asset_file.txt': '/path/to/my_asset_file.txt'}.
The experimental_mode parameter can be used to export a single train/eval/predict graph as a SavedModel. See experimental_export_all_saved_models for full docs.
View source
Returns list of all variable names in this model.
View source
Returns value of the variable given by name.
View source
Finds the filename of the latest saved checkpoint file in model_dir.
View source
Yields predictions for given features.
Please note that interleaving two predict outputs does not work. See: issue/20506
View source
Trains a model given training data input_fn.


An estimator for TensorFlow Linear and DNN joined models with custom head.
Inherits From: Estimator, Estimator
Input of train and evaluate should have following features, otherwise there will be a KeyError:
Loss is calculated by using mean squared error.
Estimators can be used while eager execution is enabled. Note that input_fn and all hooks are executed inside a graph context, so they have to be written to be compatible with graph mode. Note that input_fn code using tf.data generally works in both graph and eager modes.
View source
Shows the directory name where evaluation metrics are dumped.
View source
Evaluates the model given evaluation data input_fn.
For each step, calls input_fn, which returns one batch of data. Evaluates until:
View source
Exports a SavedModel with tf.MetaGraphDefs for each requested mode.
For each mode passed in via the input_receiver_fn_map, this method builds a new graph by calling the input_receiver_fn to obtain feature and label Tensors. Next, this method calls the Estimator's model_fn in the passed mode to generate the model graph based on those features and labels, and restores the given checkpoint (or, lacking that, the most recent checkpoint) into the graph. Only one of the modes is used for saving variables to the SavedModel (order of preference: tf.estimator.ModeKeys.TRAIN, tf.estimator.ModeKeys.EVAL, then tf.estimator.ModeKeys.PREDICT), such that up to three tf.MetaGraphDefs are saved with a single set of variables in a single SavedModel directory.
For the variables and tf.MetaGraphDefs, a timestamped export directory below export_dir_base, and writes a SavedModel into it containing the tf.MetaGraphDef for the given mode and its associated signatures.
For prediction, the exported MetaGraphDef will provide one SignatureDef for each element of the export_outputs dict returned from the model_fn, named using the same keys. One of these keys is always tf.saved_model.signature_constants.DEFAULT_SERVING_SIGNATURE_DEF_KEY, indicating which signature will be served when a serving request does not specify one. For each signature, the outputs are provided by the corresponding tf.estimator.export.ExportOutputs, and the inputs are always the input receivers provided by the serving_input_receiver_fn.
For training and evaluation, the train_op is stored in an extra collection, and loss, metrics, and predictions are included in a SignatureDef for the mode in question.
Extra assets may be written into the SavedModel via the assets_extra argument. This should be a dict, where each key gives a destination path (including the filename) relative to the assets.extra directory. The corresponding value gives the full path of the source file to be copied. For example, the simple case of copying a single file without renaming it is specified as {'my_asset_file.txt': '/path/to/my_asset_file.txt'}.
View source
Exports inference graph as a SavedModel into the given dir.
For a detailed guide, see SavedModel from Estimators.
This method builds a new graph by first calling the serving_input_receiver_fn to obtain feature Tensors, and then calling this Estimator's model_fn to generate the model graph based on those features. It restores the given checkpoint (or, lacking that, the most recent checkpoint) into this graph in a fresh session. Finally it creates a timestamped export directory below the given export_dir_base, and writes a SavedModel into it containing a single tf.MetaGraphDef saved from this session.
The exported MetaGraphDef will provide one SignatureDef for each element of the export_outputs dict returned from the model_fn, named using the same keys. One of these keys is always tf.saved_model.signature_constants.DEFAULT_SERVING_SIGNATURE_DEF_KEY, indicating which signature will be served when a serving request does not specify one. For each signature, the outputs are provided by the corresponding tf.estimator.export.ExportOutputs, and the inputs are always the input receivers provided by the serving_input_receiver_fn.
Extra assets may be written into the SavedModel via the assets_extra argument. This should be a dict, where each key gives a destination path (including the filename) relative to the assets.extra directory. The corresponding value gives the full path of the source file to be copied. For example, the simple case of copying a single file without renaming it is specified as {'my_asset_file.txt': '/path/to/my_asset_file.txt'}.
The experimental_mode parameter can be used to export a single train/eval/predict graph as a SavedModel. See experimental_export_all_saved_models for full docs.
View source
Returns list of all variable names in this model.
View source
Returns value of the variable given by name.
View source
Finds the filename of the latest saved checkpoint file in model_dir.
View source
Yields predictions for given features.
Please note that interleaving two predict outputs does not work. See: issue/20506
View source
Trains a model given training data input_fn.