Sync OSS keras to head.

PiperOrigin-RevId: 364644711

keras/activations.py

@@ -44,7 +44,7 @@
 @keras_export('keras.activations.softmax')
 @tf.__internal__.dispatch.add_dispatch_support
 def softmax(x, axis=-1):
-  """Softmax converts a real vector to a vector of categorical probabilities.
+  """Softmax converts a vector of values to a probability distribution.
 
   The elements of the output vector are in range (0, 1) and sum to 1.
 
@@ -61,23 +61,34 @@ def softmax(x, axis=-1):
   The input values in are the log-odds of the resulting probability.
 
   Args:
-      x : Input tensor.
-      axis: Integer, axis along which the softmax normalization is applied.
+    x : Input tensor.
+    axis: Integer, axis along which the softmax normalization is applied.
 
   Returns:
-      Tensor, output of softmax transformation (all values are non-negative
-        and sum to 1).
+    Tensor, output of softmax transformation (all values are non-negative
+      and sum to 1).
 
-  Raises:
-      ValueError: In case `dim(x) == 1`.
+  Examples:
+
+  **Example 1: standalone usage**
+
+  >>> inputs = tf.random.normal(shape=(32, 10))
+  >>> outputs = tf.keras.activations.softmax(inputs)
+  >>> tf.reduce_sum(outputs[0, :])  # Each sample in the batch now sums to 1
+  <tf.Tensor: shape=(), dtype=float32, numpy=1.0000001>
+
+  **Example 2: usage in a `Dense` layer**
+
+  >>> layer = tf.keras.layers.Dense(32, activation=tf.keras.activations.softmax)
   """
-  rank = x.shape.rank
-  if rank == 2:
-    output = tf.compat.v1.math.softmax(x)
-  elif rank > 2:
-    e = tf.exp(x - tf.reduce_max(x, axis=axis, keepdims=True))
-    s = tf.reduce_sum(e, axis=axis, keepdims=True)
-    output = e / s
+  if x.shape.rank > 1:
+    if isinstance(axis, int):
+      output = tf.compat.v1.math.softmax(x, axis=axis)
+    else:
+      # nn.softmax does not support tuple axis.
+      e = tf.exp(x - tf.reduce_max(x, axis=axis, keepdims=True))
+      s = tf.reduce_sum(e, axis=axis, keepdims=True)
+      output = e / s
   else:
     raise ValueError('Cannot apply softmax to a tensor that is 1D. '
                      'Received input: %s' % (x,))

keras/activations_test.py

@@ -92,6 +92,26 @@ def test_softmax(self):
     with self.assertRaises(ValueError):
       activations.softmax(x)
 
+  def test_softmax_2d_axis_0(self):
+    x = backend.placeholder(ndim=2)
+    f = backend.function([x], [activations.softmax(x, axis=0)])
+    test_values = np.random.random((2, 5))
+    result = f([test_values])[0]
+    expected = np.zeros((2, 5))
+    for i in range(5):
+      expected[:, i] = _ref_softmax(test_values[:, i])
+    self.assertAllClose(result, expected, rtol=1e-05)
+
+  def test_softmax_3d_axis_tuple(self):
+    x = backend.placeholder(ndim=3)
+    f = backend.function([x], [activations.softmax(x, axis=(1, 2))])
+    test_values = np.random.random((2, 3, 5))
+    result = f([test_values])[0]
+    expected = np.zeros((2, 3, 5))
+    for i in range(2):
+      expected[i, :, :] = _ref_softmax(test_values[i, :, :])
+    self.assertAllClose(result, expected, rtol=1e-05)
+
   def test_temporal_softmax(self):
     x = backend.placeholder(shape=(2, 2, 3))
     f = backend.function([x], [activations.softmax(x)])

keras/applications/densenet.py

@@ -142,13 +142,22 @@ def DenseNet(
   - [Densely Connected Convolutional Networks](
       https://arxiv.org/abs/1608.06993) (CVPR 2017)
 
-  Optionally loads weights pre-trained on ImageNet.
-  Note that the data format convention used by the model is
-  the one specified in your Keras config at `~/.keras/keras.json`.
+  This function returns a Keras image classification model,
+  optionally loaded with weights pre-trained on ImageNet.
+
+  For image classification use cases, see
+  [this page for detailed examples](
+    https://keras.io/api/applications/#usage-examples-for-image-classification-models).
+
+  For transfer learning use cases, make sure to read the
+  [guide to transfer learning & fine-tuning](
+    https://keras.io/guides/transfer_learning/).
 
   Note: each Keras Application expects a specific kind of input preprocessing.
   For DenseNet, call `tf.keras.applications.densenet.preprocess_input` on your
   inputs before passing them to the model.
+  `densenet.preprocess_input` will scale pixels between 0 and 1 and then
+  will normalize each channel with respect to the ImageNet dataset statistics.
 
   Args:
     blocks: numbers of building blocks for the four dense layers.
@@ -184,15 +193,11 @@ def DenseNet(
     classifier_activation: A `str` or callable. The activation function to use
       on the "top" layer. Ignored unless `include_top=True`. Set
       `classifier_activation=None` to return the logits of the "top" layer.
+      When loading pretrained weights, `classifier_activation` can only
+      be `None` or `"softmax"`.
 
   Returns:
     A `keras.Model` instance.
-
-  Raises:
-    ValueError: in case of invalid argument for `weights`,
-      or invalid input shape.
-    ValueError: if `classifier_activation` is not `softmax` or `None` when
-      using a pretrained top layer.
   """
   if not (weights in {'imagenet', None} or tf.io.gfile.exists(weights)):
     raise ValueError('The `weights` argument should be either '

keras/applications/efficientnet.py

@@ -150,10 +150,23 @@
   - [EfficientNet: Rethinking Model Scaling for Convolutional Neural Networks](
       https://arxiv.org/abs/1905.11946) (ICML 2019)
 
-  Optionally loads weights pre-trained on ImageNet.
-  Note that the data format convention used by the model is
-  the one specified in your Keras config at `~/.keras/keras.json`.
-  If you have never configured it, it defaults to `"channels_last"`.
+  This function returns a Keras image classification model,
+  optionally loaded with weights pre-trained on ImageNet.
+
+  For image classification use cases, see
+  [this page for detailed examples](
+    https://keras.io/api/applications/#usage-examples-for-image-classification-models).
+
+  For transfer learning use cases, make sure to read the
+  [guide to transfer learning & fine-tuning](
+    https://keras.io/guides/transfer_learning/).
+
+  Note: each Keras Application expects a specific kind of input preprocessing.
+  For EfficientNet, input preprocessing is included as part of the model
+  (as a `Rescaling` layer), and thus
+  `tf.keras.applications.efficientnet.preprocess_input` is actually a
+  pass-through function. EfficientNet models expect their inputs to be float
+  tensors of pixels with values in the [0-255] range.
 
   Args:
     include_top: Whether to include the fully-connected
@@ -186,6 +199,8 @@
         on the "top" layer. Ignored unless `include_top=True`. Set
         `classifier_activation=None` to return the logits of the "top" layer.
         Defaults to 'softmax'.
+        When loading pretrained weights, `classifier_activation` can only
+        be `None` or `"softmax"`.
 
   Returns:
     A `keras.Model` instance.
@@ -211,14 +226,6 @@ def EfficientNet(
     classifier_activation='softmax'):
   """Instantiates the EfficientNet architecture using given scaling coefficients.
 
-  Reference:
-  - [EfficientNet: Rethinking Model Scaling for Convolutional Neural Networks](
-      https://arxiv.org/abs/1905.11946) (ICML 2019)
-
-  Optionally loads weights pre-trained on ImageNet.
-  Note that the data format convention used by the model is
-  the one specified in your Keras config at `~/.keras/keras.json`.
-
   Args:
     width_coefficient: float, scaling coefficient for network width.
     depth_coefficient: float, scaling coefficient for network depth.

keras/applications/inception_resnet_v2.py

@@ -58,14 +58,23 @@ def InceptionResNetV2(include_top=True,
      Residual Connections on Learning](https://arxiv.org/abs/1602.07261)
     (AAAI 2017)
 
-  Optionally loads weights pre-trained on ImageNet.
-  Note that the data format convention used by the model is
-  the one specified in your Keras config at `~/.keras/keras.json`.
+  This function returns a Keras image classification model,
+  optionally loaded with weights pre-trained on ImageNet.
+
+  For image classification use cases, see
+  [this page for detailed examples](
+    https://keras.io/api/applications/#usage-examples-for-image-classification-models).
+
+  For transfer learning use cases, make sure to read the
+  [guide to transfer learning & fine-tuning](
+    https://keras.io/guides/transfer_learning/).
 
   Note: each Keras Application expects a specific kind of input preprocessing.
   For InceptionResNetV2, call
   `tf.keras.applications.inception_resnet_v2.preprocess_input`
   on your inputs before passing them to the model.
+  `inception_resnet_v2.preprocess_input`
+  will scale input pixels between -1 and 1.
 
   Args:
     include_top: whether to include the fully-connected
@@ -97,16 +106,12 @@ def InceptionResNetV2(include_top=True,
     classifier_activation: A `str` or callable. The activation function to use
       on the "top" layer. Ignored unless `include_top=True`. Set
       `classifier_activation=None` to return the logits of the "top" layer.
+      When loading pretrained weights, `classifier_activation` can only
+      be `None` or `"softmax"`.
     **kwargs: For backwards compatibility only.
 
   Returns:
     A `keras.Model` instance.
-
-  Raises:
-    ValueError: in case of invalid argument for `weights`,
-      or invalid input shape.
-    ValueError: if `classifier_activation` is not `softmax` or `None` when
-      using a pretrained top layer.
   """
   global layers
   if 'layers' in kwargs:

keras/applications/inception_v3.py

@@ -60,13 +60,21 @@ def InceptionV3(
   - [Rethinking the Inception Architecture for Computer Vision](
       http://arxiv.org/abs/1512.00567) (CVPR 2016)
 
-  Optionally loads weights pre-trained on ImageNet.
-  Note that the data format convention used by the model is
-  the one specified in the `tf.keras.backend.image_data_format()`.
+  This function returns a Keras image classification model,
+  optionally loaded with weights pre-trained on ImageNet.
+
+  For image classification use cases, see
+  [this page for detailed examples](
+    https://keras.io/api/applications/#usage-examples-for-image-classification-models).
+
+  For transfer learning use cases, make sure to read the
+  [guide to transfer learning & fine-tuning](
+    https://keras.io/guides/transfer_learning/).
 
   Note: each Keras Application expects a specific kind of input preprocessing.
-  For InceptionV3, call `tf.keras.applications.inception_v3.preprocess_input`
+  For `InceptionV3`, call `tf.keras.applications.inception_v3.preprocess_input`
   on your inputs before passing them to the model.
+  `inception_v3.preprocess_input` will scale input pixels between -1 and 1.
 
   Args:
     include_top: Boolean, whether to include the fully-connected
@@ -100,15 +108,11 @@ def InceptionV3(
     classifier_activation: A `str` or callable. The activation function to use
       on the "top" layer. Ignored unless `include_top=True`. Set
       `classifier_activation=None` to return the logits of the "top" layer.
+      When loading pretrained weights, `classifier_activation` can only
+      be `None` or `"softmax"`.
 
   Returns:
     A `keras.Model` instance.
-
-  Raises:
-    ValueError: in case of invalid argument for `weights`,
-      or invalid input shape.
-    ValueError: if `classifier_activation` is not `softmax` or `None` when
-      using a pretrained top layer.
   """
   if not (weights in {'imagenet', None} or tf.io.gfile.exists(weights)):
     raise ValueError('The `weights` argument should be either '

keras/applications/mobilenet.py

@@ -101,13 +101,21 @@ def MobileNet(input_shape=None,
      for Mobile Vision Applications](
       https://arxiv.org/abs/1704.04861)
 
-  Optionally loads weights pre-trained on ImageNet.
-  Note that the data format convention used by the model is
-  the one specified in the `tf.keras.backend.image_data_format()`.
+  This function returns a Keras image classification model,
+  optionally loaded with weights pre-trained on ImageNet.
+
+  For image classification use cases, see
+  [this page for detailed examples](
+    https://keras.io/api/applications/#usage-examples-for-image-classification-models).
+
+  For transfer learning use cases, make sure to read the
+  [guide to transfer learning & fine-tuning](
+    https://keras.io/guides/transfer_learning/).
 
   Note: each Keras Application expects a specific kind of input preprocessing.
   For MobileNet, call `tf.keras.applications.mobilenet.preprocess_input`
   on your inputs before passing them to the model.
+  `mobilenet.preprocess_input` will scale input pixels between -1 and 1.
 
   Args:
     input_shape: Optional shape tuple, only to be specified if `include_top`
@@ -149,15 +157,11 @@ def MobileNet(input_shape=None,
     classifier_activation: A `str` or callable. The activation function to use
       on the "top" layer. Ignored unless `include_top=True`. Set
       `classifier_activation=None` to return the logits of the "top" layer.
+      When loading pretrained weights, `classifier_activation` can only
+      be `None` or `"softmax"`.
     **kwargs: For backwards compatibility only.
   Returns:
     A `keras.Model` instance.
-
-  Raises:
-    ValueError: in case of invalid argument for `weights`,
-      or invalid input shape.
-    ValueError: if `classifier_activation` is not `softmax` or `None` when
-      using a pretrained top layer.
   """
   global layers
   if 'layers' in kwargs:

keras/applications/mobilenet_v2.py

@@ -106,15 +106,33 @@ def MobileNetV2(input_shape=None,
                 **kwargs):
   """Instantiates the MobileNetV2 architecture.
 
+  MobileNetV2 is very similar to the original MobileNet,
+  except that it uses inverted residual blocks with
+  bottlenecking features. It has a drastically lower
+  parameter count than the original MobileNet.
+  MobileNets support any input size greater
+  than 32 x 32, with larger image sizes
+  offering better performance.
+
   Reference:
   - [MobileNetV2: Inverted Residuals and Linear Bottlenecks](
       https://arxiv.org/abs/1801.04381) (CVPR 2018)
 
-  Optionally loads weights pre-trained on ImageNet.
+  This function returns a Keras image classification model,
+  optionally loaded with weights pre-trained on ImageNet.
+
+  For image classification use cases, see
+  [this page for detailed examples](
+    https://keras.io/api/applications/#usage-examples-for-image-classification-models).
+
+  For transfer learning use cases, make sure to read the
+  [guide to transfer learning & fine-tuning](
+    https://keras.io/guides/transfer_learning/).
 
   Note: each Keras Application expects a specific kind of input preprocessing.
   For MobileNetV2, call `tf.keras.applications.mobilenet_v2.preprocess_input`
   on your inputs before passing them to the model.
+  `mobilenet_v2.preprocess_input` will scale input pixels between -1 and 1.
 
   Args:
     input_shape: Optional shape tuple, to be specified if you would
@@ -163,17 +181,12 @@ def MobileNetV2(input_shape=None,
     classifier_activation: A `str` or callable. The activation function to use
       on the "top" layer. Ignored unless `include_top=True`. Set
       `classifier_activation=None` to return the logits of the "top" layer.
+      When loading pretrained weights, `classifier_activation` can only
+      be `None` or `"softmax"`.
     **kwargs: For backwards compatibility only.
 
   Returns:
     A `keras.Model` instance.
-
-  Raises:
-    ValueError: in case of invalid argument for `weights`,
-      or invalid input shape or invalid alpha, rows when
-      weights='imagenet'
-    ValueError: if `classifier_activation` is not `softmax` or `None` when
-      using a pretrained top layer.
   """
   global layers
   if 'layers' in kwargs: