The Canonical Keras Workflow

Training a Multi-Layer Perceptron on MNIST

Published

July 15, 2026

Almost every deep learning project — no matter how fancy — follows the same seven steps:

# Step Question it answers
1 Load the data What am I working with?
2 Explore & visualize What does it actually look like?
3 Preprocess What shape/scale does the network need?
4 Split train / validation How will I know if I’m overfitting?
5 Build & compile the model What function am I fitting, and how do I score it?
6 Train Turn the crank.
7 Evaluate Did it work? Where does it fail?

Our task: look at a 28×28 grayscale image of a handwritten digit and say which digit (0–9) it is.

Keep one idea in the back of your mind the whole time: a neural network is just a function. It takes 784 numbers in and produces 10 numbers out. Training is the process of nudging its internal knobs (weights) until that function is usually right.

0. Setup

import numpy as np
import matplotlib.pyplot as plt

import tensorflow as tf
from tensorflow import keras
from tensorflow.keras import layers

# Fix the random seeds so the notebook is reproducible run-to-run.
np.random.seed(42)
tf.random.set_seed(42)

print("TensorFlow:", tf.__version__)
TensorFlow: 2.13.0

1. Load the data

MNIST ships with Keras, so loading is a one-liner. It arrives already divided into a training set (60,000 images) and a test set (10,000 images).

The test set is a locked box. We will not look at it again until the very end.

(x_train_full, y_train_full), (x_test, y_test) = keras.datasets.mnist.load_data()

print("Training images:", x_train_full.shape, "| labels:", y_train_full.shape)
print("Test images:    ", x_test.shape, "| labels:", y_test.shape)
Training images: (60000, 28, 28) | labels: (60000,)
Test images:     (10000, 28, 28) | labels: (10000,)

2. Explore and visualize

Never train on data you haven’t looked at. Three quick questions:

  1. What type and range are the pixel values?
  2. Are the classes balanced?
  3. What do the images actually look like?
print("dtype:", x_train_full.dtype)
print("pixel min:", x_train_full.min(), " pixel max:", x_train_full.max())
print("labels present:", np.unique(y_train_full))
dtype: uint8
pixel min: 0  pixel max: 255
labels present: [0 1 2 3 4 5 6 7 8 9]

So each image is a 28 × 28 grid of integers from 0 to 255, where 0 = black (background) and 255 = white (ink).

That’s the key insight: an image is just a matrix of numbers. Let’s prove it by printing a corner of one.

img = x_train_full[0]
label = y_train_full[0]

fig, ax = plt.subplots(1, 2, figsize=(11, 5))

# Left: the image as we see it
ax[0].imshow(img, cmap="gray")
ax[0].set_title(f"Image #0 — label = {label}")
ax[0].axis("off")

# Right: the same image as the computer sees it (a 14x14 crop, values printed)
crop = img[7:21, 7:21]
ax[1].imshow(crop, cmap="gray")
for i in range(crop.shape[0]):
    for j in range(crop.shape[1]):
        v = crop[i, j]
        ax[1].text(j, i, str(v), ha="center", va="center", fontsize=6,
                   color="red" if v < 128 else "black")
ax[1].set_title("...the same thing, as numbers (center crop)")
ax[1].axis("off")

plt.tight_layout()
plt.show()

One example of each digit

fig, axes = plt.subplots(2, 5, figsize=(10, 4.5))

for digit, ax in enumerate(axes.flat):
    # find the first image whose label is this digit
    idx = np.where(y_train_full == digit)[0][0]
    ax.imshow(x_train_full[idx], cmap="gray")
    ax.set_title(f"{digit}")
    ax.axis("off")

plt.suptitle("One sample of each class")
plt.tight_layout()
plt.show()

Are the classes balanced?

counts = np.bincount(y_train_full)

plt.figure(figsize=(7, 3.5))
plt.bar(range(10), counts)
plt.xticks(range(10))
plt.xlabel("digit")
plt.ylabel("# of training images")
plt.title("Class balance")
plt.show()

print(counts)

[5923 6742 5958 6131 5842 5421 5918 6265 5851 5949]

Roughly 6,000 images per digit — close enough to balanced that we don’t need to do anything special. (If one class had 50× fewer examples, accuracy would become a misleading metric and we’d have to be more careful.)

3. Preprocess

Two changes are needed to feed a plain MLP:

(a) Flatten. A dense layer takes a vector, not a grid. So we unroll each 28 × 28 image into a 784-long vector by reading it row by row.

Note what this throws away: the network no longer knows that pixel 5 and pixel 33 were vertical neighbors. An MLP has to rediscover spatial structure from scratch. This is exactly the weakness that convolutional networks fix — but it’s remarkable how far an MLP still gets.

(b) Rescale to [0, 1]. Divide by 255. Neural networks train much more stably when inputs are small and comparable in size; feeding in raw values up to 255 makes gradients large and erratic.

# (a) flatten: (N, 28, 28) -> (N, 784)
x_train_full_flat = x_train_full.reshape(-1, 28 * 28)
x_test_flat       = x_test.reshape(-1, 28 * 28)

# (b) rescale: 0..255 -> 0.0..1.0
x_train_full_flat = x_train_full_flat.astype("float32") / 255.0
x_test_flat       = x_test_flat.astype("float32") / 255.0

print("shape:", x_train_full_flat.shape)
print("range:", x_train_full_flat.min(), "to", x_train_full_flat.max())
shape: (60000, 784)
range: 0.0 to 1.0

4. Split into training and validation

We already have a test set — so why split again?

  • Training set → the model learns from this (weights are updated).
  • Validation set → the model never learns from this. We watch its score during training to detect overfitting and decide when to stop.
  • Test set → touched exactly once, at the end, for an honest final number.

If we tuned our choices by peeking at the test set, the test score would stop being an honest estimate of performance on new data. So we carve a validation set out of the training data.

from sklearn.model_selection import train_test_split

x_train, x_val, y_train, y_val = train_test_split(
    x_train_full_flat, y_train_full,
    test_size=0.2,          # 20% held out for validation
    stratify=y_train_full,  # keep the class balance in both halves
    random_state=42,
)

print("train:", x_train.shape[0], "images")
print("val:  ", x_val.shape[0], "images")
print("test: ", x_test_flat.shape[0], "images")
train: 48000 images
val:   12000 images
test:  10000 images

5. Build and compile the model

Here is the whole architecture:

784 inputs  →  Dense(128, relu)  →  Dense(64, relu)  →  Dense(10, softmax)

Reading it left to right:

  • Dense = “fully connected”: every neuron sees every value from the previous layer. Each neuron computes w · x + b — a weighted vote over its inputs.
  • relu = max(0, z). Without this nonlinearity, stacking layers would be pointless: a chain of linear maps collapses into a single linear map. ReLU is what lets the network build curved decision boundaries.
  • The layers get narrower (784 → 128 → 64 → 10). Think of it as a funnel: raw pixels → coarse strokes/edges → digit-ish features → a decision.
  • softmax on the last layer turns 10 arbitrary scores into 10 probabilities that sum to 1.
model = keras.Sequential([
    layers.Input(shape=(784,)),
    layers.Dense(128, activation="relu"),
    layers.Dense(64,  activation="relu"),
    layers.Dense(10,  activation="softmax"),
])

model.summary()
Model: "sequential"
_________________________________________________________________
 Layer (type)                Output Shape              Param #   
=================================================================
 dense (Dense)               (None, 128)               100480    
                                                                 
 dense_1 (Dense)             (None, 64)                8256      
                                                                 
 dense_2 (Dense)             (None, 10)                650       
                                                                 
=================================================================
Total params: 109386 (427.29 KB)
Trainable params: 109386 (427.29 KB)
Non-trainable params: 0 (0.00 Byte)
_________________________________________________________________

Sanity-check the parameter count. Layer 1 has 784 × 128 weights plus 128 biases = 100,480 knobs. Layer 2: 128 × 64 + 64 = 8,256. Layer 3: 64 × 10 + 10 = 650. Total ≈ 109,386 numbers that training will adjust.

Compile = choose the scoring rule and the search strategy

compile() doesn’t train anything. It just attaches three things to the model:

  • loss — the number we are trying to make small. sparse_categorical_crossentropy is essentially “how surprised was the model by the correct answer?” It’s near 0 when the model puts high probability on the true digit, and blows up when it is confidently wrong. “Sparse” just means our labels are plain integers (7) rather than one-hot vectors ([0,...,1,...,0]).
  • optimizer — the rule for updating weights from the gradient. adam is the reliable default.
  • metrics — numbers we want reported but that aren’t used for the update. Accuracy is for humans; the loss is for the optimizer.
model.compile(
    optimizer="adam",
    loss="sparse_categorical_crossentropy",
    metrics=["accuracy"],
)

6. Train

fit() is the crank. In each epoch the model sees every training image once, in shuffled mini-batches of 128. For every batch it:

  1. predicts,
  2. measures the loss,
  3. computes the gradient of the loss w.r.t. all 109,386 weights (backpropagation),
  4. takes a small step downhill.

At the end of each epoch, Keras also scores the untouched validation set so we can watch for overfitting.

history = model.fit(
    x_train, y_train,
    validation_data=(x_val, y_val),
    epochs=20,
    batch_size=128,
    verbose=2,
)
Epoch 1/20
375/375 - 1s - loss: 0.3588 - accuracy: 0.8998 - val_loss: 0.2029 - val_accuracy: 0.9402 - 865ms/epoch - 2ms/step
Epoch 2/20
375/375 - 1s - loss: 0.1512 - accuracy: 0.9548 - val_loss: 0.1490 - val_accuracy: 0.9557 - 574ms/epoch - 2ms/step
Epoch 3/20
375/375 - 1s - loss: 0.1062 - accuracy: 0.9684 - val_loss: 0.1209 - val_accuracy: 0.9647 - 553ms/epoch - 1ms/step
Epoch 4/20
375/375 - 1s - loss: 0.0799 - accuracy: 0.9758 - val_loss: 0.0996 - val_accuracy: 0.9716 - 528ms/epoch - 1ms/step
Epoch 5/20
375/375 - 0s - loss: 0.0618 - accuracy: 0.9816 - val_loss: 0.0933 - val_accuracy: 0.9722 - 487ms/epoch - 1ms/step
Epoch 6/20
375/375 - 1s - loss: 0.0504 - accuracy: 0.9846 - val_loss: 0.0902 - val_accuracy: 0.9738 - 601ms/epoch - 2ms/step
Epoch 7/20
375/375 - 1s - loss: 0.0385 - accuracy: 0.9882 - val_loss: 0.0980 - val_accuracy: 0.9707 - 517ms/epoch - 1ms/step
Epoch 8/20
375/375 - 0s - loss: 0.0332 - accuracy: 0.9899 - val_loss: 0.0935 - val_accuracy: 0.9740 - 468ms/epoch - 1ms/step
Epoch 9/20
375/375 - 0s - loss: 0.0258 - accuracy: 0.9927 - val_loss: 0.1061 - val_accuracy: 0.9719 - 455ms/epoch - 1ms/step
Epoch 10/20
375/375 - 0s - loss: 0.0237 - accuracy: 0.9926 - val_loss: 0.0964 - val_accuracy: 0.9743 - 455ms/epoch - 1ms/step
Epoch 11/20
375/375 - 0s - loss: 0.0184 - accuracy: 0.9950 - val_loss: 0.1168 - val_accuracy: 0.9681 - 455ms/epoch - 1ms/step
Epoch 12/20
375/375 - 0s - loss: 0.0139 - accuracy: 0.9961 - val_loss: 0.0977 - val_accuracy: 0.9749 - 461ms/epoch - 1ms/step
Epoch 13/20
375/375 - 0s - loss: 0.0136 - accuracy: 0.9959 - val_loss: 0.0959 - val_accuracy: 0.9759 - 462ms/epoch - 1ms/step
Epoch 14/20
375/375 - 0s - loss: 0.0119 - accuracy: 0.9962 - val_loss: 0.1010 - val_accuracy: 0.9759 - 459ms/epoch - 1ms/step
Epoch 15/20
375/375 - 0s - loss: 0.0124 - accuracy: 0.9961 - val_loss: 0.1067 - val_accuracy: 0.9728 - 458ms/epoch - 1ms/step
Epoch 16/20
375/375 - 0s - loss: 0.0105 - accuracy: 0.9968 - val_loss: 0.0979 - val_accuracy: 0.9781 - 465ms/epoch - 1ms/step
Epoch 17/20
375/375 - 0s - loss: 0.0044 - accuracy: 0.9993 - val_loss: 0.0986 - val_accuracy: 0.9777 - 460ms/epoch - 1ms/step
Epoch 18/20
375/375 - 0s - loss: 0.0044 - accuracy: 0.9990 - val_loss: 0.1122 - val_accuracy: 0.9756 - 463ms/epoch - 1ms/step
Epoch 19/20
375/375 - 0s - loss: 0.0097 - accuracy: 0.9968 - val_loss: 0.1262 - val_accuracy: 0.9726 - 458ms/epoch - 1ms/step
Epoch 20/20
375/375 - 0s - loss: 0.0098 - accuracy: 0.9968 - val_loss: 0.1188 - val_accuracy: 0.9748 - 463ms/epoch - 1ms/step

7a. Training curves

history.history is just a dictionary of lists — one value per epoch. Plotting it is the single most informative diagnostic in deep learning.

How to read these plots: - Both curves still falling → keep training. - Training loss falls, validation loss turns back up → overfitting: the model is memorizing training images instead of learning digits. - Both curves flat and high → underfitting (too small a model, or too few epochs).

h = history.history
epochs = range(1, len(h["loss"]) + 1)

fig, ax = plt.subplots(1, 2, figsize=(12, 4))

ax[0].plot(epochs, h["loss"], "o-", label="train")
ax[0].plot(epochs, h["val_loss"], "o-", label="validation")
ax[0].set_xlabel("epoch"); ax[0].set_ylabel("loss")
ax[0].set_title("Loss")
ax[0].legend(); ax[0].grid(alpha=0.3)

ax[1].plot(epochs, h["accuracy"], "o-", label="train")
ax[1].plot(epochs, h["val_accuracy"], "o-", label="validation")
ax[1].set_xlabel("epoch"); ax[1].set_ylabel("accuracy")
ax[1].set_title("Accuracy")
ax[1].legend(); ax[1].grid(alpha=0.3)

plt.tight_layout()
plt.show()

Look at the gap between the two curves. The training accuracy climbs toward 100% while validation accuracy plateaus — that gap is overfitting, made visible. The model has enough capacity to start memorizing.

7b. Final evaluation on the test set

Now — and only now — we open the locked box.

test_loss, test_acc = model.evaluate(x_test_flat, y_test, verbose=0)

print(f"Test loss:     {test_loss:.4f}")
print(f"Test accuracy: {test_acc:.4f}   ({test_acc*100:.2f}%)")
print(f"That's about {int(round((1-test_acc)*len(y_test)))} mistakes out of {len(y_test)} images.")
Test loss:     0.1084
Test accuracy: 0.9760   (97.60%)
That's about 240 mistakes out of 10000 images.

What the model actually outputs

predict() returns 10 probabilities per image. To get a hard prediction we take the argmax — the index of the largest probability.

probs  = model.predict(x_test_flat, verbose=0)   # shape (10000, 10)
y_pred = probs.argmax(axis=1)                    # shape (10000,)

# Inspect a single test image and its full probability vector
i = 0
fig, ax = plt.subplots(1, 2, figsize=(10, 3.5))

ax[0].imshow(x_test[i], cmap="gray")
ax[0].set_title(f"true = {y_test[i]}   predicted = {y_pred[i]}")
ax[0].axis("off")

ax[1].bar(range(10), probs[i])
ax[1].set_xticks(range(10))
ax[1].set_xlabel("digit")
ax[1].set_ylabel("probability")
ax[1].set_title("Softmax output (sums to 1)")

plt.tight_layout()
plt.show()

print("probabilities sum to:", probs[i].sum())

probabilities sum to: 0.9999999

7c. Confusion matrix

Accuracy is one number, and one number hides everything interesting. The confusion matrix tells us which digits get mistaken for which.

Row = the true digit. Column = what the model guessed. The diagonal is correct; everything off-diagonal is a mistake.

from sklearn.metrics import confusion_matrix, ConfusionMatrixDisplay, classification_report

cm = confusion_matrix(y_test, y_pred)

fig, ax = plt.subplots(figsize=(7, 6))
ConfusionMatrixDisplay(cm, display_labels=range(10)).plot(
    ax=ax, cmap="Blues", colorbar=False, values_format="d"
)
ax.set_title("Confusion matrix (test set)")
plt.tight_layout()
plt.show()

The diagonal dominates, so let’s zero it out and look only at the errors — that’s where the story is.

cm_errors = cm.copy()
np.fill_diagonal(cm_errors, 0)

fig, ax = plt.subplots(figsize=(7, 6))
im = ax.imshow(cm_errors, cmap="Reds")
ax.set_xticks(range(10)); ax.set_yticks(range(10))
ax.set_xlabel("predicted"); ax.set_ylabel("true")
ax.set_title("Errors only (diagonal removed)")

for i in range(10):
    for j in range(10):
        if cm_errors[i, j] > 0:
            ax.text(j, i, cm_errors[i, j], ha="center", va="center", fontsize=8)

plt.colorbar(im)
plt.tight_layout()
plt.show()

# The single worst confusion:
i, j = np.unravel_index(cm_errors.argmax(), cm_errors.shape)
print(f"Most common mistake: true {i} predicted as {j}  ({cm_errors[i, j]} times)")

Most common mistake: true 2 predicted as 8  (16 times)

The mistakes are not random — they cluster where humans would also hesitate (4↔︎9, 3↔︎5, 7↔︎2). That’s reassuring: the model has learned something about shape, not noise.

Per-class scores

print(classification_report(y_test, y_pred, digits=3))
              precision    recall  f1-score   support

           0      0.982     0.986     0.984       980
           1      0.993     0.985     0.989      1135
           2      0.988     0.961     0.974      1032
           3      0.961     0.983     0.972      1010
           4      0.993     0.975     0.984       982
           5      0.972     0.979     0.975       892
           6      0.975     0.981     0.978       958
           7      0.983     0.970     0.976      1028
           8      0.941     0.976     0.958       974
           9      0.971     0.964     0.968      1009

    accuracy                          0.976     10000
   macro avg      0.976     0.976     0.976     10000
weighted avg      0.976     0.976     0.976     10000

Quick glossary for the columns: - precision — of everything the model called a 9, what fraction really was a 9? - recall — of all the actual 9s, what fraction did it catch? - f1-score — the harmonic mean of the two, a single balanced summary.

7d. Look at the failures

Always look at the images the model got wrong. It is the fastest way to build intuition about what the model is (and isn’t) doing.

wrong = np.where(y_pred != y_test)[0]
print(f"{len(wrong)} misclassified test images")

fig, axes = plt.subplots(2, 6, figsize=(12, 4.5))
for ax, idx in zip(axes.flat, wrong[:12]):
    ax.imshow(x_test[idx], cmap="gray")
    confidence = probs[idx].max()
    ax.set_title(f"true {y_test[idx]} → pred {y_pred[idx]}\n({confidence:.0%} sure)", fontsize=9)
    ax.axis("off")

plt.suptitle("Where the model went wrong")
plt.tight_layout()
plt.show()
240 misclassified test images

Many of these are genuinely ambiguous — sloppy handwriting that you might get wrong too. Notice also that the model is sometimes confidently wrong. A softmax probability is not a measure of how much the model actually knows.

Recap

You just executed the entire canonical workflow:

  1. Load — keras.datasets.mnist.load_data()
  2. Explore — shapes, ranges, class balance, sample images
  3. Preprocess — flatten to 784, rescale to [0, 1]
  4. Split — train / validation / (locked) test
  5. Build & compile — Sequential + Dense layers; loss, optimizer, metrics
  6. Train — fit(), watching validation each epoch
  7. Evaluate — training curves, test accuracy, confusion matrix, error inspection

This exact skeleton scales up. Swap MNIST for satellite images and the Dense stack for convolutions, and the seven steps do not change — only the contents of step 5.

Things to try

  • Remove the two hidden layers (leave only Dense(10, softmax)). You now have plain logistic regression — how much accuracy do you lose? That difference is what “deep” bought you.
  • Delete the activation="relu" arguments. Accuracy should collapse toward the linear model. Why?
  • Add layers.Dropout(0.2) after each hidden layer and re-look at the train/validation gap.
  • Skip the /255.0 rescaling and watch training struggle.
  • Train for 100 epochs and watch the validation loss curve turn upward — overfitting in the wild.