CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> <meta name="description" content="Keras documentation"> <meta name="author" content="Keras Team"> <link rel="shortcut icon" href="https://keras.io/img/favicon.ico"> <link rel="canonical" href="https://keras.io/guides/functional_api/" />  <meta property="og:title" content="Keras documentation: The Functional API"> <meta property="og:image" content="https://keras.io/img/logo-k-keras-wb.png"> <meta name="twitter:title" content="Keras documentation: The Functional API"> <meta name="twitter:image" content="https://keras.io/img/k-keras-social.png"> <meta name="twitter:card" content="summary"> <title>The Functional API</title>  <link href="/css/bootstrap.min.css" rel="stylesheet">  <link href="https://fonts.googleapis.com/css2?family=Open+Sans:wght@400;600;700;800&display=swap" rel="stylesheet">  <link href="/css/docs.css" rel="stylesheet"> <link href="/css/monokai.css" rel="stylesheet">  <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= 'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-5DNGF4N'); </script> <script> (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) })(window,document,'script','https://www.google-analytics.com/analytics.js','ga'); ga('create', 'UA-175165319-128', 'auto'); ga('send', 'pageview'); </script>  <script async defer src="https://buttons.github.io/buttons.js"></script> </head> <body>  <noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-5DNGF4N" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>  <div class='k-page'> <div class="k-nav" id="nav-menu"> <a href='/'><img src='/img/logo-small.png' class='logo-small' /></a> <div class="nav flex-column nav-pills" role="tablist" aria-orientation="vertical"> <a class="nav-link" href="/about/" role="tab" aria-selected="">About Keras</a> <a class="nav-link" href="/getting_started/" role="tab" aria-selected="">Getting started</a> <a class="nav-link active" href="/guides/" role="tab" aria-selected="">Developer guides</a> <a class="nav-sublink active" href="/guides/functional_api/">The Functional API</a> <a class="nav-sublink" href="/guides/sequential_model/">The Sequential model</a> <a class="nav-sublink" href="/guides/making_new_layers_and_models_via_subclassing/">Making new layers & models via subclassing</a> <a class="nav-sublink" href="/guides/training_with_built_in_methods/">Training & evaluation with the built-in methods</a> <a class="nav-sublink" href="/guides/custom_train_step_in_jax/">Customizing `fit()` with JAX</a> <a class="nav-sublink" href="/guides/custom_train_step_in_tensorflow/">Customizing `fit()` with TensorFlow</a> <a class="nav-sublink" href="/guides/custom_train_step_in_torch/">Customizing `fit()` with PyTorch</a> <a class="nav-sublink" href="/guides/writing_a_custom_training_loop_in_jax/">Writing a custom training loop in JAX</a> <a class="nav-sublink" href="/guides/writing_a_custom_training_loop_in_tensorflow/">Writing a custom training loop in TensorFlow</a> <a class="nav-sublink" href="/guides/writing_a_custom_training_loop_in_torch/">Writing a custom training loop in PyTorch</a> <a class="nav-sublink" href="/guides/serialization_and_saving/">Serialization & saving</a> <a class="nav-sublink" href="/guides/customizing_saving_and_serialization/">Customizing saving & serialization</a> <a class="nav-sublink" href="/guides/writing_your_own_callbacks/">Writing your own callbacks</a> <a class="nav-sublink" href="/guides/transfer_learning/">Transfer learning & fine-tuning</a> <a class="nav-sublink" href="/guides/distributed_training_with_jax/">Distributed training with JAX</a> <a class="nav-sublink" href="/guides/distributed_training_with_tensorflow/">Distributed training with TensorFlow</a> <a class="nav-sublink" href="/guides/distributed_training_with_torch/">Distributed training with PyTorch</a> <a class="nav-sublink" href="/guides/distribution/">Distributed training with Keras 3</a> <a class="nav-sublink" href="/guides/migrating_to_keras_3/">Migrating Keras 2 code to Keras 3</a> <a class="nav-link" href="/examples/" role="tab" aria-selected="">Code examples</a> <a class="nav-link" href="/api/" role="tab" aria-selected="">Keras 3 API documentation</a> <a class="nav-link" href="/2.18/api/" role="tab" aria-selected="">Keras 2 API documentation</a> <a class="nav-link" href="/keras_tuner/" role="tab" aria-selected="">KerasTuner: Hyperparam Tuning</a> <a class="nav-link" href="/keras_hub/" role="tab" aria-selected="">KerasHub: Pretrained Models</a> </div> </div> <div class='k-main'> <div class='k-main-top'> <script> function displayDropdownMenu() { e = document.getElementById("nav-menu"); if (e.style.display == "block") { e.style.display = "none"; } else { e.style.display = "block"; document.getElementById("dropdown-nav").style.display = "block"; } } function resetMobileUI() { if (window.innerWidth <= 840) { document.getElementById("nav-menu").style.display = "none"; document.getElementById("dropdown-nav").style.display = "block"; } else { document.getElementById("nav-menu").style.display = "block"; document.getElementById("dropdown-nav").style.display = "none"; } var navmenu = document.getElementById("nav-menu"); var menuheight = navmenu.clientHeight; var kmain = document.getElementById("k-main-id"); kmain.style.minHeight = (menuheight + 100) + 'px'; } window.onresize = resetMobileUI; window.addEventListener("load", (event) => { resetMobileUI() }); </script> <div id='dropdown-nav' onclick="displayDropdownMenu();"> <svg viewBox="-20 -20 120 120" width="60" height="60"> <rect width="100" height="20"></rect> <rect y="30" width="100" height="20"></rect> <rect y="60" width="100" height="20"></rect> </svg> </div> <form class="bd-search d-flex align-items-center k-search-form" id="search-form"> <input type="search" class="k-search-input" id="search-input" placeholder="Search Keras documentation..." aria-label="Search Keras documentation..." autocomplete="off"> <button class="k-search-btn"> <svg width="13" height="13" viewBox="0 0 13 13"><title>search</title><path d="m4.8495 7.8226c0.82666 0 1.5262-0.29146 2.0985-0.87438 0.57232-0.58292 0.86378-1.2877 0.87438-2.1144 0.010599-0.82666-0.28086-1.5262-0.87438-2.0985-0.59352-0.57232-1.293-0.86378-2.0985-0.87438-0.8055-0.010599-1.5103 0.28086-2.1144 0.87438-0.60414 0.59352-0.8956 1.293-0.87438 2.0985 0.021197 0.8055 0.31266 1.5103 0.87438 2.1144 0.56172 0.60414 1.2665 0.8956 2.1144 0.87438zm4.4695 0.2115 3.681 3.6819-1.259 1.284-3.6817-3.7 0.0019784-0.69479-0.090043-0.098846c-0.87973 0.76087-1.92 1.1413-3.1207 1.1413-1.3553 0-2.5025-0.46363-3.4417-1.3909s-1.4088-2.0686-1.4088-3.4239c0-1.3553 0.4696-2.4966 1.4088-3.4239 0.9392-0.92727 2.0864-1.3969 3.4417-1.4088 1.3553-0.011889 2.4906 0.45771 3.406 1.4088 0.9154 0.95107 1.379 2.0924 1.3909 3.4239 0 1.2126-0.38043 2.2588-1.1413 3.1385l0.098834 0.090049z"></path></svg> </button> </form> <script> var form = document.getElementById('search-form'); form.onsubmit = function(e) { e.preventDefault(); var query = document.getElementById('search-input').value; window.location.href = '/search.html?query=' + query; return False } </script> </div> <div class='k-main-inner' id='k-main-id'> <div class='k-location-slug'> ► <a href='/guides/'>Developer guides</a> / The Functional API </div> <div class='k-content'> <h1 id="the-functional-api">The Functional API</h1> Author: <a href="https://twitter.com/fchollet">fchollet</a> Date created: 2019/03/01 Last modified: 2023/06/25 Description: Complete guide to the functional API. <img class="k-inline-icon" src="https://colab.research.google.com/img/colab_favicon.ico"/> <a href="https://colab.research.google.com/github/keras-team/keras-io/blob/master/guides/ipynb/functional_api.ipynb">View in Colab</a> •<img class="k-inline-icon" src="https://github.com/favicon.ico"/> <a href="https://github.com/keras-team/keras-io/blob/master/guides/functional_api.py">GitHub source</a> <hr /> <h2 id="setup">Setup</h2> <div class="codehilite"><pre><code>import numpy as np import keras from keras import layers from keras import ops </code></pre></div> <hr /> <h2 id="introduction">Introduction</h2> The Keras functional API is a way to create models that are more flexible than the <a href="/api/models/sequential#sequential-class"><code>keras.Sequential</code></a> API. The functional API can handle models with non-linear topology, shared layers, and even multiple inputs or outputs. The main idea is that a deep learning model is usually a directed acyclic graph (DAG) of layers. So the functional API is a way to build graphs of layers. Consider the following model: <div class="k-default-codeblock"> <div class="codehilite"><pre><code>(input: 784-dimensional vectors) ↧ [Dense (64 units, relu activation)] ↧ [Dense (64 units, relu activation)] ↧ [Dense (10 units, softmax activation)] ↧ (output: logits of a probability distribution over 10 classes) </code></pre></div> </div> This is a basic graph with three layers. To build this model using the functional API, start by creating an input node: <div class="codehilite"><pre><code>inputs = keras.Input(shape=(784,)) </code></pre></div> The shape of the data is set as a 784-dimensional vector. The batch size is always omitted since only the shape of each sample is specified. If, for example, you have an image input with a shape of <code>(32, 32, 3)</code>, you would use: <div class="codehilite"><pre><code># Just for demonstration purposes. img_inputs = keras.Input(shape=(32, 32, 3)) </code></pre></div> The <code>inputs</code> that is returned contains information about the shape and <code>dtype</code> of the input data that you feed to your model. Here's the shape: <div class="codehilite"><pre><code>inputs.shape </code></pre></div> <div class="k-default-codeblock"> <div class="codehilite"><pre><code>(None, 784) </code></pre></div> </div> Here's the dtype: <div class="codehilite"><pre><code>inputs.dtype </code></pre></div> <div class="k-default-codeblock"> <div class="codehilite"><pre><code>'float32' </code></pre></div> </div> You create a new node in the graph of layers by calling a layer on this <code>inputs</code> object: <div class="codehilite"><pre><code>dense = layers.Dense(64, activation="relu") x = dense(inputs) </code></pre></div> The "layer call" action is like drawing an arrow from "inputs" to this layer you created. You're "passing" the inputs to the <code>dense</code> layer, and you get <code>x</code> as the output. Let's add a few more layers to the graph of layers: <div class="codehilite"><pre><code>x = layers.Dense(64, activation="relu")(x) outputs = layers.Dense(10)(x) </code></pre></div> At this point, you can create a <code>Model</code> by specifying its inputs and outputs in the graph of layers: <div class="codehilite"><pre><code>model = keras.Model(inputs=inputs, outputs=outputs, name="mnist_model") </code></pre></div> Let's check out what the model summary looks like: <div class="codehilite"><pre><code>model.summary() </code></pre></div> <pre style="white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace">Model: "mnist_model" </pre> <pre style="white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace">┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓ ┃ Layer (type) ┃ Output Shape ┃ Param # ┃ ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩ │ input_layer (InputLayer) │ (None, 784) │ 0 │ ├─────────────────────────────────┼────────────────────────┼───────────────┤ │ dense (Dense) │ (None, 64) │ 50,240 │ ├─────────────────────────────────┼────────────────────────┼───────────────┤ │ dense_1 (Dense) │ (None, 64) │ 4,160 │ ├─────────────────────────────────┼────────────────────────┼───────────────┤ │ dense_2 (Dense) │ (None, 10) │ 650 │ └─────────────────────────────────┴────────────────────────┴───────────────┘ </pre> <pre style="white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace"> Total params: 55,050 (215.04 KB) </pre> <pre style="white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace"> Trainable params: 55,050 (215.04 KB) </pre> <pre style="white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace"> Non-trainable params: 0 (0.00 B) </pre> You can also plot the model as a graph: <div class="codehilite"><pre><code>keras.utils.plot_model(model, "my_first_model.png") </code></pre></div> <img alt="png" src="/img/guides/functional_api/functional_api_20_0.png" /> And, optionally, display the input and output shapes of each layer in the plotted graph: <div class="codehilite"><pre><code>keras.utils.plot_model(model, "my_first_model_with_shape_info.png", show_shapes=True) </code></pre></div> <img alt="png" src="/img/guides/functional_api/functional_api_22_0.png" /> This figure and the code are almost identical. In the code version, the connection arrows are replaced by the call operation. A "graph of layers" is an intuitive mental image for a deep learning model, and the functional API is a way to create models that closely mirrors this. <hr /> <h2 id="training-evaluation-and-inference">Training, evaluation, and inference</h2> Training, evaluation, and inference work exactly in the same way for models built using the functional API as for <code>Sequential</code> models. The <code>Model</code> class offers a built-in training loop (the <code>fit()</code> method) and a built-in evaluation loop (the <code>evaluate()</code> method). Note that you can easily customize these loops to implement your own training routines. See also the guides on customizing what happens in <code>fit()</code>: <ul> <li><a href="/guides/custom_train_step_in_tensorflow/">Writing a custom train step with TensorFlow</a></li> <li><a href="/guides/custom_train_step_in_jax/">Writing a custom train step with JAX</a></li> <li><a href="/guides/custom_train_step_in_torch/">Writing a custom train step with PyTorch</a></li> </ul> Here, load the MNIST image data, reshape it into vectors, fit the model on the data (while monitoring performance on a validation split), then evaluate the model on the test data: <div class="codehilite"><pre><code>(x_train, y_train), (x_test, y_test) = keras.datasets.mnist.load_data() x_train = x_train.reshape(60000, 784).astype("float32") / 255 x_test = x_test.reshape(10000, 784).astype("float32") / 255 model.compile( loss=keras.losses.SparseCategoricalCrossentropy(from_logits=True), optimizer=keras.optimizers.RMSprop(), metrics=["accuracy"], ) history = model.fit(x_train, y_train, batch_size=64, epochs=2, validation_split=0.2) test_scores = model.evaluate(x_test, y_test, verbose=2) print("Test loss:", test_scores[0]) print("Test accuracy:", test_scores[1]) </code></pre></div> <div class="k-default-codeblock"> <div class="codehilite"><pre><code>Epoch 1/2 750/750 ━━━━━━━━━━━━━━━━━━━━ 1s 863us/step - accuracy: 0.8425 - loss: 0.5733 - val_accuracy: 0.9496 - val_loss: 0.1711 Epoch 2/2 750/750 ━━━━━━━━━━━━━━━━━━━━ 1s 859us/step - accuracy: 0.9509 - loss: 0.1641 - val_accuracy: 0.9578 - val_loss: 0.1396 313/313 - 0s - 341us/step - accuracy: 0.9613 - loss: 0.1288 Test loss: 0.12876172363758087 Test accuracy: 0.9613000154495239 </code></pre></div> </div> For further reading, see the <a href="/guides/training_with_built_in_methods/">training and evaluation</a> guide. <hr /> <h2 id="save-and-serialize">Save and serialize</h2> Saving the model and serialization work the same way for models built using the functional API as they do for <code>Sequential</code> models. The standard way to save a functional model is to call <code>model.save()</code> to save the entire model as a single file. You can later recreate the same model from this file, even if the code that built the model is no longer available. This saved file includes the: - model architecture - model weight values (that were learned during training) - model training config, if any (as passed to <code>compile()</code>) - optimizer and its state, if any (to restart training where you left off) <div class="codehilite"><pre><code>model.save("my_model.keras") del model # Recreate the exact same model purely from the file: model = keras.models.load_model("my_model.keras") </code></pre></div> For details, read the model <a href="/guides/serialization_and_saving/">serialization & saving</a> guide. <hr /> <h2 id="use-the-same-graph-of-layers-to-define-multiple-models">Use the same graph of layers to define multiple models</h2> In the functional API, models are created by specifying their inputs and outputs in a graph of layers. That means that a single graph of layers can be used to generate multiple models. In the example below, you use the same stack of layers to instantiate two models: an <code>encoder</code> model that turns image inputs into 16-dimensional vectors, and an end-to-end <code>autoencoder</code> model for training. <div class="codehilite"><pre><code>encoder_input = keras.Input(shape=(28, 28, 1), name="img") x = layers.Conv2D(16, 3, activation="relu")(encoder_input) x = layers.Conv2D(32, 3, activation="relu")(x) x = layers.MaxPooling2D(3)(x) x = layers.Conv2D(32, 3, activation="relu")(x) x = layers.Conv2D(16, 3, activation="relu")(x) encoder_output = layers.GlobalMaxPooling2D()(x) encoder = keras.Model(encoder_input, encoder_output, name="encoder") encoder.summary() x = layers.Reshape((4, 4, 1))(encoder_output) x = layers.Conv2DTranspose(16, 3, activation="relu")(x) x = layers.Conv2DTranspose(32, 3, activation="relu")(x) x = layers.UpSampling2D(3)(x) x = layers.Conv2DTranspose(16, 3, activation="relu")(x) decoder_output = layers.Conv2DTranspose(1, 3, activation="relu")(x) autoencoder = keras.Model(encoder_input, decoder_output, name="autoencoder") autoencoder.summary() </code></pre></div> <pre style="white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace">Model: "encoder" </pre> <pre style="white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace">┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓ ┃ Layer (type) ┃ Output Shape ┃ Param # ┃ ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩ │ img (InputLayer) │ (None, 28, 28, 1) │ 0 │ ├─────────────────────────────────┼────────────────────────┼───────────────┤ │ conv2d (Conv2D) │ (None, 26, 26, 16) │ 160 │ ├─────────────────────────────────┼────────────────────────┼───────────────┤ │ conv2d_1 (Conv2D) │ (None, 24, 24, 32) │ 4,640 │ ├─────────────────────────────────┼────────────────────────┼───────────────┤ │ max_pooling2d (MaxPooling2D) │ (None, 8, 8, 32) │ 0 │ ├─────────────────────────────────┼────────────────────────┼───────────────┤ │ conv2d_2 (Conv2D) │ (None, 6, 6, 32) │ 9,248 │ ├─────────────────────────────────┼────────────────────────┼───────────────┤ │ conv2d_3 (Conv2D) │ (None, 4, 4, 16) │ 4,624 │ ├─────────────────────────────────┼────────────────────────┼───────────────┤ │ global_max_pooling2d │ (None, 16) │ 0 │ │ (GlobalMaxPooling2D) │ │ │ └─────────────────────────────────┴────────────────────────┴───────────────┘ </pre> <pre style="white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace"> Total params: 18,672 (72.94 KB) </pre> <pre style="white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace"> Trainable params: 18,672 (72.94 KB) </pre> <pre style="white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace"> Non-trainable params: 0 (0.00 B) </pre> <pre style="white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace">Model: "autoencoder" </pre> <pre style="white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace">┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓ ┃ Layer (type) ┃ Output Shape ┃ Param # ┃ ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩ │ img (InputLayer) │ (None, 28, 28, 1) │ 0 │ ├─────────────────────────────────┼────────────────────────┼───────────────┤ │ conv2d (Conv2D) │ (None, 26, 26, 16) │ 160 │ ├─────────────────────────────────┼────────────────────────┼───────────────┤ │ conv2d_1 (Conv2D) │ (None, 24, 24, 32) │ 4,640 │ ├─────────────────────────────────┼────────────────────────┼───────────────┤ │ max_pooling2d (MaxPooling2D) │ (None, 8, 8, 32) │ 0 │ ├─────────────────────────────────┼────────────────────────┼───────────────┤ │ conv2d_2 (Conv2D) │ (None, 6, 6, 32) │ 9,248 │ ├─────────────────────────────────┼────────────────────────┼───────────────┤ │ conv2d_3 (Conv2D) │ (None, 4, 4, 16) │ 4,624 │ ├─────────────────────────────────┼────────────────────────┼───────────────┤ │ global_max_pooling2d │ (None, 16) │ 0 │ │ (GlobalMaxPooling2D) │ │ │ ├─────────────────────────────────┼────────────────────────┼───────────────┤ │ reshape (Reshape) │ (None, 4, 4, 1) │ 0 │ ├─────────────────────────────────┼────────────────────────┼───────────────┤ │ conv2d_transpose │ (None, 6, 6, 16) │ 160 │ │ (Conv2DTranspose) │ │ │ ├─────────────────────────────────┼────────────────────────┼───────────────┤ │ conv2d_transpose_1 │ (None, 8, 8, 32) │ 4,640 │ │ (Conv2DTranspose) │ │ │ ├─────────────────────────────────┼────────────────────────┼───────────────┤ │ up_sampling2d (UpSampling2D) │ (None, 24, 24, 32) │ 0 │ ├─────────────────────────────────┼────────────────────────┼───────────────┤ │ conv2d_transpose_2 │ (None, 26, 26, 16) │ 4,624 │ │ (Conv2DTranspose) │ │ │ ├─────────────────────────────────┼────────────────────────┼───────────────┤ │ conv2d_transpose_3 │ (None, 28, 28, 1) │ 145 │ │ (Conv2DTranspose) │ │ │ └─────────────────────────────────┴────────────────────────┴───────────────┘ </pre> <pre style="white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace"> Total params: 28,241 (110.32 KB) </pre> <pre style="white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace"> Trainable params: 28,241 (110.32 KB) </pre> <pre style="white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace"> Non-trainable params: 0 (0.00 B) </pre> Here, the decoding architecture is strictly symmetrical to the encoding architecture, so the output shape is the same as the input shape <code>(28, 28, 1)</code>. The reverse of a <code>Conv2D</code> layer is a <code>Conv2DTranspose</code> layer, and the reverse of a <code>MaxPooling2D</code> layer is an <code>UpSampling2D</code> layer. <hr /> <h2 id="all-models-are-callable-just-like-layers">All models are callable, just like layers</h2> You can treat any model as if it were a layer by invoking it on an <code>Input</code> or on the output of another layer. By calling a model you aren't just reusing the architecture of the model, you're also reusing its weights. To see this in action, here's a different take on the autoencoder example that creates an encoder model, a decoder model, and chains them in two calls to obtain the autoencoder model: <div class="codehilite"><pre><code>encoder_input = keras.Input(shape=(28, 28, 1), name="original_img") x = layers.Conv2D(16, 3, activation="relu")(encoder_input) x = layers.Conv2D(32, 3, activation="relu")(x) x = layers.MaxPooling2D(3)(x) x = layers.Conv2D(32, 3, activation="relu")(x) x = layers.Conv2D(16, 3, activation="relu")(x) encoder_output = layers.GlobalMaxPooling2D()(x) encoder = keras.Model(encoder_input, encoder_output, name="encoder") encoder.summary() decoder_input = keras.Input(shape=(16,), name="encoded_img") x = layers.Reshape((4, 4, 1))(decoder_input) x = layers.Conv2DTranspose(16, 3, activation="relu")(x) x = layers.Conv2DTranspose(32, 3, activation="relu")(x) x = layers.UpSampling2D(3)(x) x = layers.Conv2DTranspose(16, 3, activation="relu")(x) decoder_output = layers.Conv2DTranspose(1, 3, activation="relu")(x) decoder = keras.Model(decoder_input, decoder_output, name="decoder") decoder.summary() autoencoder_input = keras.Input(shape=(28, 28, 1), name="img") encoded_img = encoder(autoencoder_input) decoded_img = decoder(encoded_img) autoencoder = keras.Model(autoencoder_input, decoded_img, name="autoencoder") autoencoder.summary() </code></pre></div> <pre style="white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace">Model: "encoder" </pre> <pre style="white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace">┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓ ┃ Layer (type) ┃ Output Shape ┃ Param # ┃ ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩ │ original_img (InputLayer) │ (None, 28, 28, 1) │ 0 │ ├─────────────────────────────────┼────────────────────────┼───────────────┤ │ conv2d_4 (Conv2D) │ (None, 26, 26, 16) │ 160 │ ├─────────────────────────────────┼────────────────────────┼───────────────┤ │ conv2d_5 (Conv2D) │ (None, 24, 24, 32) │ 4,640 │ ├─────────────────────────────────┼────────────────────────┼───────────────┤ │ max_pooling2d_1 (MaxPooling2D) │ (None, 8, 8, 32) │ 0 │ ├─────────────────────────────────┼────────────────────────┼───────────────┤ │ conv2d_6 (Conv2D) │ (None, 6, 6, 32) │ 9,248 │ ├─────────────────────────────────┼────────────────────────┼───────────────┤ │ conv2d_7 (Conv2D) │ (None, 4, 4, 16) │ 4,624 │ ├─────────────────────────────────┼────────────────────────┼───────────────┤ │ global_max_pooling2d_1 │ (None, 16) │ 0 │ │ (GlobalMaxPooling2D) │ │ │ └─────────────────────────────────┴────────────────────────┴───────────────┘ </pre> <pre style="white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace"> Total params: 18,672 (72.94 KB) </pre> <pre style="white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace"> Trainable params: 18,672 (72.94 KB) </pre> <pre style="white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace"> Non-trainable params: 0 (0.00 B) </pre> <pre style="white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace">Model: "decoder" </pre> <pre style="white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace">┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓ ┃ Layer (type) ┃ Output Shape ┃ Param # ┃ ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩ │ encoded_img (InputLayer) │ (None, 16) │ 0 │ ├─────────────────────────────────┼────────────────────────┼───────────────┤ │ reshape_1 (Reshape) │ (None, 4, 4, 1) │ 0 │ ├─────────────────────────────────┼────────────────────────┼───────────────┤ │ conv2d_transpose_4 │ (None, 6, 6, 16) │ 160 │ │ (Conv2DTranspose) │ │ │ ├─────────────────────────────────┼────────────────────────┼───────────────┤ │ conv2d_transpose_5 │ (None, 8, 8, 32) │ 4,640 │ │ (Conv2DTranspose) │ │ │ ├─────────────────────────────────┼────────────────────────┼───────────────┤ │ up_sampling2d_1 (UpSampling2D) │ (None, 24, 24, 32) │ 0 │ ├─────────────────────────────────┼────────────────────────┼───────────────┤ │ conv2d_transpose_6 │ (None, 26, 26, 16) │ 4,624 │ │ (Conv2DTranspose) │ │ │ ├─────────────────────────────────┼────────────────────────┼───────────────┤ │ conv2d_transpose_7 │ (None, 28, 28, 1) │ 145 │ │ (Conv2DTranspose) │ │ │ └─────────────────────────────────┴────────────────────────┴───────────────┘ </pre> <pre style="white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace"> Total params: 9,569 (37.38 KB) </pre> <pre style="white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace"> Trainable params: 9,569 (37.38 KB) </pre> <pre style="white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace"> Non-trainable params: 0 (0.00 B) </pre> <pre style="white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace">Model: "autoencoder" </pre> <pre style="white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace">┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓ ┃ Layer (type) ┃ Output Shape ┃ Param # ┃ ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩ │ img (InputLayer) │ (None, 28, 28, 1) │ 0 │ ├─────────────────────────────────┼────────────────────────┼───────────────┤ │ encoder (Functional) │ (None, 16) │ 18,672 │ ├─────────────────────────────────┼────────────────────────┼───────────────┤ │ decoder (Functional) │ (None, 28, 28, 1) │ 9,569 │ └─────────────────────────────────┴────────────────────────┴───────────────┘ </pre> <pre style="white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace"> Total params: 28,241 (110.32 KB) </pre> <pre style="white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace"> Trainable params: 28,241 (110.32 KB) </pre> <pre style="white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace"> Non-trainable params: 0 (0.00 B) </pre> As you can see, the model can be nested: a model can contain sub-models (since a model is just like a layer). A common use case for model nesting is ensembling. For example, here's how to ensemble a set of models into a single model that averages their predictions: <div class="codehilite"><pre><code>def get_model(): inputs = keras.Input(shape=(128,)) outputs = layers.Dense(1)(inputs) return keras.Model(inputs, outputs) model1 = get_model() model2 = get_model() model3 = get_model() inputs = keras.Input(shape=(128,)) y1 = model1(inputs) y2 = model2(inputs) y3 = model3(inputs) outputs = layers.average([y1, y2, y3]) ensemble_model = keras.Model(inputs=inputs, outputs=outputs) </code></pre></div> <hr /> <h2 id="manipulate-complex-graph-topologies">Manipulate complex graph topologies</h2> <h3 id="models-with-multiple-inputs-and-outputs">Models with multiple inputs and outputs</h3> The functional API makes it easy to manipulate multiple inputs and outputs. This cannot be handled with the <code>Sequential</code> API. For example, if you're building a system for ranking customer issue tickets by priority and routing them to the correct department, then the model will have three inputs: <ul> <li>the title of the ticket (text input),</li> <li>the text body of the ticket (text input), and</li> <li>any tags added by the user (categorical input)</li> </ul> This model will have two outputs: <ul> <li>the priority score between 0 and 1 (scalar sigmoid output), and</li> <li>the department that should handle the ticket (softmax output over the set of departments).</li> </ul> You can build this model in a few lines with the functional API: <div class="codehilite"><pre><code>num_tags = 12 # Number of unique issue tags num_words = 10000 # Size of vocabulary obtained when preprocessing text data num_departments = 4 # Number of departments for predictions title_input = keras.Input( shape=(None,), name="title" ) # Variable-length sequence of ints body_input = keras.Input(shape=(None,), name="body") # Variable-length sequence of ints tags_input = keras.Input( shape=(num_tags,), name="tags" ) # Binary vectors of size `num_tags` # Embed each word in the title into a 64-dimensional vector title_features = layers.Embedding(num_words, 64)(title_input) # Embed each word in the text into a 64-dimensional vector body_features = layers.Embedding(num_words, 64)(body_input) # Reduce sequence of embedded words in the title into a single 128-dimensional vector title_features = layers.LSTM(128)(title_features) # Reduce sequence of embedded words in the body into a single 32-dimensional vector body_features = layers.LSTM(32)(body_features) # Merge all available features into a single large vector via concatenation x = layers.concatenate([title_features, body_features, tags_input]) # Stick a logistic regression for priority prediction on top of the features priority_pred = layers.Dense(1, name="priority")(x) # Stick a department classifier on top of the features department_pred = layers.Dense(num_departments, name="department")(x) # Instantiate an end-to-end model predicting both priority and department model = keras.Model( inputs=[title_input, body_input, tags_input], outputs={"priority": priority_pred, "department": department_pred}, ) </code></pre></div> Now plot the model: <div class="codehilite"><pre><code>keras.utils.plot_model(model, "multi_input_and_output_model.png", show_shapes=True) </code></pre></div> <img alt="png" src="/img/guides/functional_api/functional_api_40_0.png" /> When compiling this model, you can assign different losses to each output. You can even assign different weights to each loss – to modulate their contribution to the total training loss. <div class="codehilite"><pre><code>model.compile( optimizer=keras.optimizers.RMSprop(1e-3), loss=[ keras.losses.BinaryCrossentropy(from_logits=True), keras.losses.CategoricalCrossentropy(from_logits=True), ], loss_weights=[1.0, 0.2], ) </code></pre></div> Since the output layers have different names, you could also specify the losses and loss weights with the corresponding layer names: <div class="codehilite"><pre><code>model.compile( optimizer=keras.optimizers.RMSprop(1e-3), loss={ "priority": keras.losses.BinaryCrossentropy(from_logits=True), "department": keras.losses.CategoricalCrossentropy(from_logits=True), }, loss_weights={"priority": 1.0, "department": 0.2}, ) </code></pre></div> Train the model by passing lists of NumPy arrays of inputs and targets: <div class="codehilite"><pre><code># Dummy input data title_data = np.random.randint(num_words, size=(1280, 12)) body_data = np.random.randint(num_words, size=(1280, 100)) tags_data = np.random.randint(2, size=(1280, num_tags)).astype("float32") # Dummy target data priority_targets = np.random.random(size=(1280, 1)) dept_targets = np.random.randint(2, size=(1280, num_departments)) model.fit( {"title": title_data, "body": body_data, "tags": tags_data}, {"priority": priority_targets, "department": dept_targets}, epochs=2, batch_size=32, ) </code></pre></div> <div class="k-default-codeblock"> <div class="codehilite"><pre><code>Epoch 1/2 40/40 ━━━━━━━━━━━━━━━━━━━━ 3s 57ms/step - loss: 1108.3792 Epoch 2/2 40/40 ━━━━━━━━━━━━━━━━━━━━ 2s 54ms/step - loss: 621.3049 <keras.src.callbacks.history.History at 0x34afc3d90> </code></pre></div> </div> When calling fit with a <code>Dataset</code> object, it should yield either a tuple of lists like <code>([title_data, body_data, tags_data], [priority_targets, dept_targets])</code> or a tuple of dictionaries like <code>({'title': title_data, 'body': body_data, 'tags': tags_data}, {'priority': priority_targets, 'department': dept_targets})</code>. For more detailed explanation, refer to the <a href="/guides/training_with_built_in_methods/">training and evaluation</a> guide. <h3 id="a-toy-resnet-model">A toy ResNet model</h3> In addition to models with multiple inputs and outputs, the functional API makes it easy to manipulate non-linear connectivity topologies – these are models with layers that are not connected sequentially, which the <code>Sequential</code> API cannot handle. A common use case for this is residual connections. Let's build a toy ResNet model for CIFAR10 to demonstrate this: <div class="codehilite"><pre><code>inputs = keras.Input(shape=(32, 32, 3), name="img") x = layers.Conv2D(32, 3, activation="relu")(inputs) x = layers.Conv2D(64, 3, activation="relu")(x) block_1_output = layers.MaxPooling2D(3)(x) x = layers.Conv2D(64, 3, activation="relu", padding="same")(block_1_output) x = layers.Conv2D(64, 3, activation="relu", padding="same")(x) block_2_output = layers.add([x, block_1_output]) x = layers.Conv2D(64, 3, activation="relu", padding="same")(block_2_output) x = layers.Conv2D(64, 3, activation="relu", padding="same")(x) block_3_output = layers.add([x, block_2_output]) x = layers.Conv2D(64, 3, activation="relu")(block_3_output) x = layers.GlobalAveragePooling2D()(x) x = layers.Dense(256, activation="relu")(x) x = layers.Dropout(0.5)(x) outputs = layers.Dense(10)(x) model = keras.Model(inputs, outputs, name="toy_resnet") model.summary() </code></pre></div> <pre style="white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace">Model: "toy_resnet" </pre> <pre style="white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace">┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┓ ┃ Layer (type) ┃ Output Shape ┃ Param # ┃ Connected to ┃ ┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━┩ │ img (InputLayer) │ (None, 32, 32, 3) │ 0 │ - │ ├─────────────────────┼───────────────────┼────────────┼───────────────────┤ │ conv2d_8 (Conv2D) │ (None, 30, 30, │ 896 │ img[0][0] │ │ │ 32) │ │ │ ├─────────────────────┼───────────────────┼────────────┼───────────────────┤ │ conv2d_9 (Conv2D) │ (None, 28, 28, │ 18,496 │ conv2d_8[0][0] │ │ │ 64) │ │ │ ├─────────────────────┼───────────────────┼────────────┼───────────────────┤ │ max_pooling2d_2 │ (None, 9, 9, 64) │ 0 │ conv2d_9[0][0] │ │ (MaxPooling2D) │ │ │ │ ├─────────────────────┼───────────────────┼────────────┼───────────────────┤ │ conv2d_10 (Conv2D) │ (None, 9, 9, 64) │ 36,928 │ max_pooling2d_2[… │ ├─────────────────────┼───────────────────┼────────────┼───────────────────┤ │ conv2d_11 (Conv2D) │ (None, 9, 9, 64) │ 36,928 │ conv2d_10[0][0] │ ├─────────────────────┼───────────────────┼────────────┼───────────────────┤ │ add (Add) │ (None, 9, 9, 64) │ 0 │ conv2d_11[0][0], │ │ │ │ │ max_pooling2d_2[… │ ├─────────────────────┼───────────────────┼────────────┼───────────────────┤ │ conv2d_12 (Conv2D) │ (None, 9, 9, 64) │ 36,928 │ add[0][0] │ ├─────────────────────┼───────────────────┼────────────┼───────────────────┤ │ conv2d_13 (Conv2D) │ (None, 9, 9, 64) │ 36,928 │ conv2d_12[0][0] │ ├─────────────────────┼───────────────────┼────────────┼───────────────────┤ │ add_1 (Add) │ (None, 9, 9, 64) │ 0 │ conv2d_13[0][0], │ │ │ │ │ add[0][0] │ ├─────────────────────┼───────────────────┼────────────┼───────────────────┤ │ conv2d_14 (Conv2D) │ (None, 7, 7, 64) │ 36,928 │ add_1[0][0] │ ├─────────────────────┼───────────────────┼────────────┼───────────────────┤ │ global_average_poo… │ (None, 64) │ 0 │ conv2d_14[0][0] │ │ (GlobalAveragePool… │ │ │ │ ├─────────────────────┼───────────────────┼────────────┼───────────────────┤ │ dense_6 (Dense) │ (None, 256) │ 16,640 │ global_average_p… │ ├─────────────────────┼───────────────────┼────────────┼───────────────────┤ │ dropout (Dropout) │ (None, 256) │ 0 │ dense_6[0][0] │ ├─────────────────────┼───────────────────┼────────────┼───────────────────┤ │ dense_7 (Dense) │ (None, 10) │ 2,570 │ dropout[0][0] │ └─────────────────────┴───────────────────┴────────────┴───────────────────┘ </pre> <pre style="white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace"> Total params: 223,242 (872.04 KB) </pre> <pre style="white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace"> Trainable params: 223,242 (872.04 KB) </pre> <pre style="white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace"> Non-trainable params: 0 (0.00 B) </pre> Plot the model: <div class="codehilite"><pre><code>keras.utils.plot_model(model, "mini_resnet.png", show_shapes=True) </code></pre></div> <img alt="png" src="/img/guides/functional_api/functional_api_51_0.png" /> Now train the model: <div class="codehilite"><pre><code>(x_train, y_train), (x_test, y_test) = keras.datasets.cifar10.load_data() x_train = x_train.astype("float32") / 255.0 x_test = x_test.astype("float32") / 255.0 y_train = keras.utils.to_categorical(y_train, 10) y_test = keras.utils.to_categorical(y_test, 10) model.compile( optimizer=keras.optimizers.RMSprop(1e-3), loss=keras.losses.CategoricalCrossentropy(from_logits=True), metrics=["acc"], ) # We restrict the data to the first 1000 samples so as to limit execution time # on Colab. Try to train on the entire dataset until convergence! model.fit( x_train[:1000], y_train[:1000], batch_size=64, epochs=1, validation_split=0.2, ) </code></pre></div> <div class="k-default-codeblock"> <div class="codehilite"><pre><code> 13/13 ━━━━━━━━━━━━━━━━━━━━ 1s 60ms/step - acc: 0.1096 - loss: 2.3053 - val_acc: 0.1150 - val_loss: 2.2973 <keras.src.callbacks.history.History at 0x1758bed40> </code></pre></div> </div> <hr /> <h2 id="shared-layers">Shared layers</h2> Another good use for the functional API are models that use shared layers. Shared layers are layer instances that are reused multiple times in the same model – they learn features that correspond to multiple paths in the graph-of-layers. Shared layers are often used to encode inputs from similar spaces (say, two different pieces of text that feature similar vocabulary). They enable sharing of information across these different inputs, and they make it possible to train such a model on less data. If a given word is seen in one of the inputs, that will benefit the processing of all inputs that pass through the shared layer. To share a layer in the functional API, call the same layer instance multiple times. For instance, here's an <code>Embedding</code> layer shared across two different text inputs: <div class="codehilite"><pre><code># Embedding for 1000 unique words mapped to 128-dimensional vectors shared_embedding = layers.Embedding(1000, 128) # Variable-length sequence of integers text_input_a = keras.Input(shape=(None,), dtype="int32") # Variable-length sequence of integers text_input_b = keras.Input(shape=(None,), dtype="int32") # Reuse the same layer to encode both inputs encoded_input_a = shared_embedding(text_input_a) encoded_input_b = shared_embedding(text_input_b) </code></pre></div> <hr /> <h2 id="extract-and-reuse-nodes-in-the-graph-of-layers">Extract and reuse nodes in the graph of layers</h2> Because the graph of layers you are manipulating is a static data structure, it can be accessed and inspected. And this is how you are able to plot functional models as images. This also means that you can access the activations of intermediate layers ("nodes" in the graph) and reuse them elsewhere – which is very useful for something like feature extraction. Let's look at an example. This is a VGG19 model with weights pretrained on ImageNet: <div class="codehilite"><pre><code>vgg19 = keras.applications.VGG19() </code></pre></div> And these are the intermediate activations of the model, obtained by querying the graph data structure: <div class="codehilite"><pre><code>features_list = [layer.output for layer in vgg19.layers] </code></pre></div> Use these features to create a new feature-extraction model that returns the values of the intermediate layer activations: <div class="codehilite"><pre><code>feat_extraction_model = keras.Model(inputs=vgg19.input, outputs=features_list) img = np.random.random((1, 224, 224, 3)).astype("float32") extracted_features = feat_extraction_model(img) </code></pre></div> This comes in handy for tasks like <a href="https://keras.io/examples/generative/neural_style_transfer/">neural style transfer</a>, among other things. <hr /> <h2 id="extend-the-api-using-custom-layers">Extend the API using custom layers</h2> <code>keras</code> includes a wide range of built-in layers, for example: <ul> <li>Convolutional layers: <code>Conv1D</code>, <code>Conv2D</code>, <code>Conv3D</code>, <code>Conv2DTranspose</code></li> <li>Pooling layers: <code>MaxPooling1D</code>, <code>MaxPooling2D</code>, <code>MaxPooling3D</code>, <code>AveragePooling1D</code></li> <li>RNN layers: <code>GRU</code>, <code>LSTM</code>, <code>ConvLSTM2D</code></li> <li><code>BatchNormalization</code>, <code>Dropout</code>, <code>Embedding</code>, etc.</li> </ul> But if you don't find what you need, it's easy to extend the API by creating your own layers. All layers subclass the <code>Layer</code> class and implement: <ul> <li><code>call</code> method, that specifies the computation done by the layer.</li> <li><code>build</code> method, that creates the weights of the layer (this is just a style convention since you can create weights in <code>__init__</code>, as well).</li> </ul> To learn more about creating layers from scratch, read <a href="/guides/making_new_layers_and_models_via_subclassing">custom layers and models</a> guide. The following is a basic implementation of <a href="/api/layers/core_layers/dense#dense-class"><code>keras.layers.Dense</code></a>: <div class="codehilite"><pre><code>class CustomDense(layers.Layer): def __init__(self, units=32): super().__init__() self.units = units def build(self, input_shape): self.w = self.add_weight( shape=(input_shape[-1], self.units), initializer="random_normal", trainable=True, ) self.b = self.add_weight( shape=(self.units,), initializer="random_normal", trainable=True ) def call(self, inputs): return ops.matmul(inputs, self.w) + self.b inputs = keras.Input((4,)) outputs = CustomDense(10)(inputs) model = keras.Model(inputs, outputs) </code></pre></div> For serialization support in your custom layer, define a <code>get_config()</code> method that returns the constructor arguments of the layer instance: <div class="codehilite"><pre><code>class CustomDense(layers.Layer): def __init__(self, units=32): super().__init__() self.units = units def build(self, input_shape): self.w = self.add_weight( shape=(input_shape[-1], self.units), initializer="random_normal", trainable=True, ) self.b = self.add_weight( shape=(self.units,), initializer="random_normal", trainable=True ) def call(self, inputs): return ops.matmul(inputs, self.w) + self.b def get_config(self): return {"units": self.units} inputs = keras.Input((4,)) outputs = CustomDense(10)(inputs) model = keras.Model(inputs, outputs) config = model.get_config() new_model = keras.Model.from_config(config, custom_objects={"CustomDense": CustomDense}) </code></pre></div> Optionally, implement the class method <code>from_config(cls, config)</code> which is used when recreating a layer instance given its config dictionary. The default implementation of <code>from_config</code> is: <div class="codehilite"><pre><code>def from_config(cls, config): return cls(**config) </code></pre></div> <hr /> <h2 id="when-to-use-the-functional-api">When to use the functional API</h2> Should you use the Keras functional API to create a new model, or just subclass the <code>Model</code> class directly? In general, the functional API is higher-level, easier and safer, and has a number of features that subclassed models do not support. However, model subclassing provides greater flexibility when building models that are not easily expressible as directed acyclic graphs of layers. For example, you could not implement a Tree-RNN with the functional API and would have to subclass <code>Model</code> directly. For an in-depth look at the differences between the functional API and model subclassing, read <a href="https://blog.tensorflow.org/2019/01/what-are-symbolic-and-imperative-apis.html">What are Symbolic and Imperative APIs in TensorFlow 2.0?</a>. <h3 id="functional-api-strengths">Functional API strengths:</h3> The following properties are also true for Sequential models (which are also data structures), but are not true for subclassed models (which are Python bytecode, not data structures). <h4 id="less-verbose">Less verbose</h4> There is no <code>super().__init__(...)</code>, no <code>def call(self, ...):</code>, etc. Compare: <div class="codehilite"><pre><code>inputs = keras.Input(shape=(32,)) x = layers.Dense(64, activation='relu')(inputs) outputs = layers.Dense(10)(x) mlp = keras.Model(inputs, outputs) </code></pre></div> With the subclassed version: <div class="codehilite"><pre><code>class MLP(keras.Model): def __init__(self, **kwargs): super().__init__(**kwargs) self.dense_1 = layers.Dense(64, activation='relu') self.dense_2 = layers.Dense(10) def call(self, inputs): x = self.dense_1(inputs) return self.dense_2(x) # Instantiate the model. mlp = MLP() # Necessary to create the model's state. # The model doesn't have a state until it's called at least once. _ = mlp(ops.zeros((1, 32))) </code></pre></div> <h4 id="model-validation-while-defining-its-connectivity-graph">Model validation while defining its connectivity graph</h4> In the functional API, the input specification (shape and dtype) is created in advance (using <code>Input</code>). Every time you call a layer, the layer checks that the specification passed to it matches its assumptions, and it will raise a helpful error message if not. This guarantees that any model you can build with the functional API will run. All debugging – other than convergence-related debugging – happens statically during the model construction and not at execution time. This is similar to type checking in a compiler. <h4 id="a-functional-model-is-plottable-and-inspectable">A functional model is plottable and inspectable</h4> You can plot the model as a graph, and you can easily access intermediate nodes in this graph. For example, to extract and reuse the activations of intermediate layers (as seen in a previous example): <div class="codehilite"><pre><code>features_list = [layer.output for layer in vgg19.layers] feat_extraction_model = keras.Model(inputs=vgg19.input, outputs=features_list) </code></pre></div> <h4 id="a-functional-model-can-be-serialized-or-cloned">A functional model can be serialized or cloned</h4> Because a functional model is a data structure rather than a piece of code, it is safely serializable and can be saved as a single file that allows you to recreate the exact same model without having access to any of the original code. See the <a href="/guides/serialization_and_saving/">serialization & saving guide</a>. To serialize a subclassed model, it is necessary for the implementer to specify a <code>get_config()</code> and <code>from_config()</code> method at the model level. <h3 id="functional-api-weakness">Functional API weakness:</h3> <h4 id="it-does-not-support-dynamic-architectures">It does not support dynamic architectures</h4> The functional API treats models as DAGs of layers. This is true for most deep learning architectures, but not all – for example, recursive networks or Tree RNNs do not follow this assumption and cannot be implemented in the functional API. <hr /> <h2 id="mixandmatch-api-styles">Mix-and-match API styles</h2> Choosing between the functional API or Model subclassing isn't a binary decision that restricts you into one category of models. All models in the <code>keras</code> API can interact with each other, whether they're <code>Sequential</code> models, functional models, or subclassed models that are written from scratch. You can always use a functional model or <code>Sequential</code> model as part of a subclassed model or layer: <div class="codehilite"><pre><code>units = 32 timesteps = 10 input_dim = 5 # Define a Functional model inputs = keras.Input((None, units)) x = layers.GlobalAveragePooling1D()(inputs) outputs = layers.Dense(1)(x) model = keras.Model(inputs, outputs) class CustomRNN(layers.Layer): def __init__(self): super().__init__() self.units = units self.projection_1 = layers.Dense(units=units, activation="tanh") self.projection_2 = layers.Dense(units=units, activation="tanh") # Our previously-defined Functional model self.classifier = model def call(self, inputs): outputs = [] state = ops.zeros(shape=(inputs.shape[0], self.units)) for t in range(inputs.shape[1]): x = inputs[:, t, :] h = self.projection_1(x) y = h + self.projection_2(state) state = y outputs.append(y) features = ops.stack(outputs, axis=1) print(features.shape) return self.classifier(features) rnn_model = CustomRNN() _ = rnn_model(ops.zeros((1, timesteps, input_dim))) </code></pre></div> <div class="k-default-codeblock"> <div class="codehilite"><pre><code>(1, 10, 32) (1, 10, 32) </code></pre></div> </div> You can use any subclassed layer or model in the functional API as long as it implements a <code>call</code> method that follows one of the following patterns: <ul> <li><code>call(self, inputs, **kwargs)</code> – Where <code>inputs</code> is a tensor or a nested structure of tensors (e.g. a list of tensors), and where <code>**kwargs</code> are non-tensor arguments (non-inputs).</li> <li><code>call(self, inputs, training=None, **kwargs)</code> – Where <code>training</code> is a boolean indicating whether the layer should behave in training mode and inference mode.</li> <li><code>call(self, inputs, mask=None, **kwargs)</code> – Where <code>mask</code> is a boolean mask tensor (useful for RNNs, for instance).</li> <li><code>call(self, inputs, training=None, mask=None, **kwargs)</code> – Of course, you can have both masking and training-specific behavior at the same time.</li> </ul> Additionally, if you implement the <code>get_config</code> method on your custom Layer or model, the functional models you create will still be serializable and cloneable. Here's a quick example of a custom RNN, written from scratch, being used in a functional model: <div class="codehilite"><pre><code>units = 32 timesteps = 10 input_dim = 5 batch_size = 16 class CustomRNN(layers.Layer): def __init__(self): super().__init__() self.units = units self.projection_1 = layers.Dense(units=units, activation="tanh") self.projection_2 = layers.Dense(units=units, activation="tanh") self.classifier = layers.Dense(1) def call(self, inputs): outputs = [] state = ops.zeros(shape=(inputs.shape[0], self.units)) for t in range(inputs.shape[1]): x = inputs[:, t, :] h = self.projection_1(x) y = h + self.projection_2(state) state = y outputs.append(y) features = ops.stack(outputs, axis=1) return self.classifier(features) # Note that you specify a static batch size for the inputs with the `batch_shape` # arg, because the inner computation of `CustomRNN` requires a static batch size # (when you create the `state` zeros tensor). inputs = keras.Input(batch_shape=(batch_size, timesteps, input_dim)) x = layers.Conv1D(32, 3)(inputs) outputs = CustomRNN()(x) model = keras.Model(inputs, outputs) rnn_model = CustomRNN() _ = rnn_model(ops.zeros((1, 10, 5))) </code></pre></div> </div> <div class='k-outline'> <div class='k-outline-depth-1'> <a href='#the-functional-api'>The Functional API</a> </div> <div class='k-outline-depth-2'> ◆ <a href='#setup'>Setup</a> </div> <div class='k-outline-depth-2'> ◆ <a href='#introduction'>Introduction</a> </div> <div class='k-outline-depth-2'> ◆ <a href='#training-evaluation-and-inference'>Training, evaluation, and inference</a> </div> <div class='k-outline-depth-2'> ◆ <a href='#save-and-serialize'>Save and serialize</a> </div> <div class='k-outline-depth-2'> ◆ <a href='#use-the-same-graph-of-layers-to-define-multiple-models'>Use the same graph of layers to define multiple models</a> </div> <div class='k-outline-depth-2'> ◆ <a href='#all-models-are-callable-just-like-layers'>All models are callable, just like layers</a> </div> <div class='k-outline-depth-2'> ◆ <a href='#manipulate-complex-graph-topologies'>Manipulate complex graph topologies</a> </div> <div class='k-outline-depth-3'> <a href='#models-with-multiple-inputs-and-outputs'>Models with multiple inputs and outputs</a> </div> <div class='k-outline-depth-3'> <a href='#a-toy-resnet-model'>A toy ResNet model</a> </div> <div class='k-outline-depth-2'> ◆ <a href='#shared-layers'>Shared layers</a> </div> <div class='k-outline-depth-2'> ◆ <a href='#extract-and-reuse-nodes-in-the-graph-of-layers'>Extract and reuse nodes in the graph of layers</a> </div> <div class='k-outline-depth-2'> ◆ <a href='#extend-the-api-using-custom-layers'>Extend the API using custom layers</a> </div> <div class='k-outline-depth-2'> ◆ <a href='#when-to-use-the-functional-api'>When to use the functional API</a> </div> <div class='k-outline-depth-3'> <a href='#functional-api-strengths'>Functional API strengths:</a> </div> <div class='k-outline-depth-3'> <a href='#functional-api-weakness'>Functional API weakness:</a> </div> <div class='k-outline-depth-2'> ◆ <a href='#mixandmatch-api-styles'>Mix-and-match API styles</a> </div> </div> </div> </div> </div> </body> <footer style="float: left; width: 100%; padding: 1em; border-top: solid 1px #bbb;"> <a href="https://policies.google.com/terms">Terms</a> | <a href="https://policies.google.com/privacy">Privacy</a> </footer> </html>