Defined in tensorflow/contrib/estimator/python/estimator/

Creates a _Head for multi class classification.

Uses sparse_softmax_cross_entropy loss.

The head expects logits with shape [D0, D1, ... DN, n_classes]. In many applications, the shape is [batch_size, n_classes].

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 an integer Tensor with values specifying the class index.

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) as arguments and returns unreduced loss with shape [D0, D1, ... DN, 1]. loss_fn must support integer labels with shape [D0, D1, ... DN, 1]. Namely, the head applies label_vocabulary to the input labels before passing them to loss_fn.

The head can be used with a canned estimator. Example:

my_head = tf.contrib.estimator.multi_class_head(n_classes=3)
my_estimator = tf.contrib.estimator.DNNEstimator(

It can also be used with a custom model_fn. Example:

def _my_model_fn(features, labels, mode):
  my_head = tf.contrib.estimator.multi_class_head(n_classes=3)
  logits = tf.keras.Model(...)(features)

  return my_head.create_estimator_spec(

my_estimator = tf.estimator.Estimator(model_fn=_my_model_fn)


  • n_classes: Number of classes, must be greater than 2 (for 2 classes, use binary_classification_head).
  • weight_column: A string or a _NumericColumn created by tf.feature_column.numeric_column defining feature column representing weights. It is used to down weight or boost examples during training. It will be multiplied by the loss of the example.
  • label_vocabulary: A list or tuple of strings representing possible label values. If it is not given, that means labels are already encoded as an integer within [0, n_classes). If given, labels must be of string type and have any value in label_vocabulary. Note that errors will be raised if label_vocabulary is not provided but labels are strings.
  • loss_reduction: One of tf.losses.Reduction except NONE. Describes how to reduce training loss over batch. Defaults to SUM_OVER_BATCH_SIZE, namely weighted sum of losses divided by batch size. See tf.losses.Reduction.
  • loss_fn: Optional loss function.
  • name: name of the head. If provided, summary and metrics keys will be suffixed by "/" + name. Also used as name_scope when creating ops.


An instance of _Head for multi class classification.


  • ValueError: if n_classes, label_vocabulary or loss_reduction is invalid.