examples/keras-fashion-mnist/keras-fashion-mnist-classification.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# BentoML Example: fashion-mnist with Keras\n",
    "\n",
    "[BentoML](http://bentoml.ai) is an open source framework for building, shipping and running machine learning services. It provides high-level APIs for defining an ML service and packaging its artifacts, source code, dependencies, and configurations into a production-system-friendly format that is ready for deployment.\n",
    "\n",
    "This notebook demonstrates how to use BentoML to turn a Keras model into a docker image containing a REST API server serving this model, how to use your ML service built with BentoML as a CLI tool, and how to distribute it a pypi package.\n",
    "\n",
    "![Impression](https://www.google-analytics.com/collect?v=1&tid=UA-112879361-3&cid=555&t=event&ec=nb&ea=open&el=official-example&dt=keras-fashion-mnist-classification)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!pip install bentoml\n",
    "!pip install tensorflow numpy matplotlib"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from __future__ import absolute_import, division, print_function\n",
    "\n",
    "import numpy as np\n",
    "import matplotlib.pyplot as plt\n",
    "\n",
    "import tensorflow as tf\n",
    "from tensorflow import keras\n",
    "print(\"Tensorflow Version: %s\" % tf.__version__)\n",
    "\n",
    "import bentoml\n",
    "print(\"BentoML Version: %s\" % bentoml.__version__)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "colab_type": "text",
    "id": "yR0EdgrLCaWR"
   },
   "source": [
    "## Load Fashion MNIST dataset"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "colab": {},
    "colab_type": "code",
    "id": "7MqDQO0KCaWS"
   },
   "outputs": [],
   "source": [
    "fashion_mnist = keras.datasets.fashion_mnist\n",
    "\n",
    "(train_images, train_labels), (test_images, test_labels) = fashion_mnist.load_data()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Each image is mapped to a single label. Since the class names are not included with the dataset, store them here to use later when plotting the images:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "colab": {},
    "colab_type": "code",
    "id": "IjnLH5S2CaWx"
   },
   "outputs": [],
   "source": [
    "class_names = ['T-shirt/top', 'Trouser', 'Pullover', 'Dress', 'Coat',\n",
    "               'Sandal', 'Shirt', 'Sneaker', 'Bag', 'Ankle boot']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "colab_type": "text",
    "id": "ES6uQoLKCaWr"
   },
   "source": [
    "## Preprocess the data\n",
    "\n",
    "The data must be preprocessed before training the network. If you inspect the first image in the training set, you will see that the pixel values fall in the range of 0 to 255:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "colab": {},
    "colab_type": "code",
    "id": "m4VEw8Ud9Quh",
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "plt.figure()\n",
    "plt.imshow(train_images[0], cmap=plt.cm.binary)\n",
    "plt.colorbar()\n",
    "plt.grid(False)\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "colab_type": "text",
    "id": "Wz7l27Lz9S1P"
   },
   "source": [
    "We should scale these values to a range of 0 to 1 before feeding to the neural network model. For this, we divide the values by 255. It's important that the *training set* and the *testing set* are preprocessed in the same way:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "colab": {},
    "colab_type": "code",
    "id": "bW5WzIPlCaWv"
   },
   "outputs": [],
   "source": [
    "train_images = train_images / 255.0\n",
    "test_images = test_images / 255.0"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "colab_type": "text",
    "id": "Ee638AlnCaWz"
   },
   "source": [
    "Display the first 25 images from the training set and display the class name below each image. Verify that the data is in the correct format and we're ready to build and train the network."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "colab": {},
    "colab_type": "code",
    "id": "oZTImqg_CaW1"
   },
   "outputs": [],
   "source": [
    "plt.figure(figsize=(10,10))\n",
    "for i in range(25):\n",
    "    plt.subplot(5,5,i+1)\n",
    "    plt.xticks([])\n",
    "    plt.yticks([])\n",
    "    plt.grid(False)\n",
    "    plt.imshow(train_images[i], cmap=plt.cm.binary)\n",
    "    plt.xlabel(class_names[train_labels[i]])\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "colab": {},
    "colab_type": "code",
    "id": "9ODch-OFCaW4"
   },
   "outputs": [],
   "source": [
    "# Reshaping the images so that our model can accept it\n",
    "train_images  = train_images.reshape((60000, 28, 28, 1))\n",
    "test_images = test_images.reshape((10000, 28, 28, 1))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Build the model"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "model = keras.Sequential()\n",
    "# Must define the input shape in the first layer of the neural network\n",
    "model.add(keras.layers.Conv2D(filters=64, kernel_size=2, padding='same', activation='relu', input_shape=(28,28,1))) \n",
    "model.add(keras.layers.MaxPooling2D(pool_size=2))\n",
    "model.add(keras.layers.Dropout(0.3))\n",
    "model.add(keras.layers.Conv2D(filters=32, kernel_size=2, padding='same', activation='relu'))\n",
    "model.add(keras.layers.MaxPooling2D(pool_size=2))\n",
    "model.add(keras.layers.Dropout(0.3))\n",
    "model.add(keras.layers.Flatten())\n",
    "model.add(keras.layers.Dense(256, activation='relu'))\n",
    "model.add(keras.layers.Dropout(0.5))\n",
    "model.add(keras.layers.Dense(10, activation='softmax'))\n",
    "# Take a look at the model summary\n",
    "model.summary()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Compile the model"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "colab": {},
    "colab_type": "code",
    "id": "Lhan11blCaW7"
   },
   "outputs": [],
   "source": [
    "model.compile(optimizer='adam',\n",
    "              loss='sparse_categorical_crossentropy',\n",
    "              metrics=['accuracy'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "colab_type": "text",
    "id": "qKF6uW-BCaW-"
   },
   "source": [
    "## Train the model"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "colab": {},
    "colab_type": "code",
    "id": "xvwvpA64CaW_"
   },
   "outputs": [],
   "source": [
    "model.fit(train_images, train_labels, batch_size=64, epochs=1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "colab_type": "text",
    "id": "oEw4bZgGCaXB"
   },
   "source": [
    "## Evaluate model accuracy"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "colab": {},
    "colab_type": "code",
    "id": "VflXLEeECaXC"
   },
   "outputs": [],
   "source": [
    "test_loss, test_acc = model.evaluate(test_images, test_labels)\n",
    "\n",
    "print('Test accuracy:', test_acc)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "y_hat = model.predict_classes(test_images)\n",
    "\n",
    "# Plot a random sample of 10 test images, their predicted labels and ground truth\n",
    "figure = plt.figure(figsize=(20, 8))\n",
    "for i, index in enumerate(np.random.choice(test_images.shape[0], size=15, replace=False)):\n",
    "    ax = figure.add_subplot(3, 5, i + 1, xticks=[], yticks=[])\n",
    "    # Display each image\n",
    "    ax.imshow(np.squeeze(test_images[index]))\n",
    "    predict_index = y_hat[index]\n",
    "    true_index = test_labels[index]\n",
    "    # Set the title for each image\n",
    "    ax.set_title(\"{} ({})\".format(class_names[predict_index], \n",
    "                                  class_names[true_index]),\n",
    "                                  color=(\"green\" if predict_index == true_index else \"red\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "colab_type": "text",
    "id": "xsoS7CPDCaXH"
   },
   "source": [
    "## Predict on a single image"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's first see the test image and and its label:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plt.imshow(test_images[0].squeeze(-1), cmap=plt.cm.binary)\n",
    "plt.show()\n",
    "print('Class:', class_names[test_labels[0]])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "colab": {},
    "colab_type": "code",
    "id": "Gl91RPhdCaXI",
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "pred_idx = model.predict_classes(np.expand_dims(test_images[0], 0))[0]\n",
    "print('Prediction:', class_names[pred_idx])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Create new BentoML service"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%writefile keras_fashion_mnist.py\n",
    "\n",
    "import numpy as np\n",
    "from PIL import Image\n",
    "from bentoml import api, artifacts, env, BentoService\n",
    "from bentoml.artifact import KerasModelArtifact\n",
    "from bentoml.handlers import ImageHandler\n",
    "\n",
    "class_names = ['T-shirt/top', 'Trouser', 'Pullover', 'Dress', 'Coat',\n",
    "               'Sandal', 'Shirt', 'Sneaker', 'Bag', 'Ankle boot']\n",
    "\n",
    "@env(pip_dependencies=['tensorflow==1.13.1', 'Pillow', 'numpy'])\n",
    "@artifacts([KerasModelArtifact('classifier')])\n",
    "class KerasFashionMnistService(BentoService):\n",
    "        \n",
    "    @api(ImageHandler, pilmode='L')\n",
    "    def predict(self, img):\n",
    "        img = Image.fromarray(img).resize((28, 28))\n",
    "        img = np.array(img.getdata()).reshape((1,28,28,1))\n",
    "        class_idx = self.artifacts.classifier.predict_classes(img)[0]\n",
    "        return class_names[class_idx]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Save BentoML service archive"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from keras_fashion_mnist import KerasFashionMnistService\n",
    "\n",
    "mnist_svc = KerasFashionMnistService.pack(classifier=model)\n",
    "saved_path = mnist_svc.save('/tmp/bento')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Load from BentoML service archive"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "svc = bentoml.load(saved_path)\n",
    "svc.predict(test_images[0].squeeze(-1))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# \"pip install\" a BentoML archive\n",
    "\n",
    "BentoML user can directly pip install saved BentoML archive with `pip install $SAVED_PATH`,  and use it as a regular python package."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!pip install {saved_path}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Your bentoML model class name will become packaged name\n",
    "import KerasFashionMnistService\n",
    "\n",
    "ms = KerasFashionMnistService.load()\n",
    "ms.predict(test_images[0].squeeze(-1))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "the installed pip package also comes with a CLI tool:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!KerasFashionMnistService predict --input=sample_image.png"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Serving via REST API"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!bentoml serve {saved_path}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Test sending request to API Server from terminal:\n",
    "\n",
    "```curl -X POST \"http://127.0.0.1:5000/predict\" -F image=@sample_image.png```\n",
    "\n",
    "or:\n",
    "\n",
    "```curl -X POST \"http://127.0.0.1:5000/predict\" -H \"Content-Type: image/png\" --data-binary @sample_image.png```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Run REST API server with Docker (Optional)\n",
    "\n",
    "** _Make sure you have `docker` installed, note that it is not available when running in Google Colaboratory_"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!cd {saved_path} && docker build -t keras-fashion-mnist ."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!docker run -p 5000:5000 keras-fashion-mnist"
   ]
  }
 ],
 "metadata": {
  "colab": {
   "collapsed_sections": [],
   "name": "basic_classification.ipynb",
   "private_outputs": true,
   "provenance": [],
   "toc_visible": true,
   "version": "0.3.2"
  },
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}