Mxnet BYOM Verbosity matched with other datasets

Author: Venkatesan

sagemaker-python-sdk/mxnet_mnist_byom/mxnet_mnist.ipynb

@@ -4,16 +4,73 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Mxnet MNIST BYOM. Train locally and deploy on SageMaker."
+    "# Mxnet BYOM: Train locally and deploy on SageMaker.\n",
+    "\n",
+    "1. [Introduction](#Introduction)\n",
+    "2. [Prerequisites and Preprocessing](#Prequisites-and-Preprocessing)\n",
+    "    1. [Permissions and environment variables](#Permissions-and-environment-variables)\n",
+    "    2. [Data Setup](#Data-setup)\n",
+    "3. [Training the network locally](#Training)\n",
+    "4. [Set up hosting for the model](#Set-up-hosting-for-the-model)\n",
+    "    1. [Export from mxnet](#Export-the-model-from-mxnet)\n",
+    "    2. [Import model into SageMaker](#Import-model-into-SageMaker)\n",
+    "    3. [Create endpoint](#Create-endpoint) \n",
+    "5. [Validate the ebdpoint for use](#Validate-the-endpoint-for-use)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "In this notebook, we will train a model locally on the notebook instance and will deploy and predict from Sagemaker. This can easily be extended to a model trained anywhere else as well. All that is needed is the exported model file and the entry point file containing model definitions. \n",
+    "## Introduction\n",
+    "In this notebook, we will train a neural network locally on the location from where this notebook is run using MXNet. We will then see how to create an endpoint from the trained MXNet model and deploy it on SageMaker. We will then inference from the newly created SageMaker endpoint. \n",
+    "\n",
+    "The neural network that we will use is a simple fully-connected neural network. The definition of the neural network can be found in the accompanying [mnist.py](mnist.py) file. The ``build_graph`` method contains the model defnition (shown below).\n",
+    "\n",
+    "```python\n",
+    "def build_graph():\n",
+    "    data = mx.sym.var('data')\n",
+    "    data = mx.sym.flatten(data=data)\n",
+    "    fc1 = mx.sym.FullyConnected(data=data, num_hidden=128)\n",
+    "    act1 = mx.sym.Activation(data=fc1, act_type=\"relu\")\n",
+    "    fc2 = mx.sym.FullyConnected(data=act1, num_hidden=64)\n",
+    "    act2 = mx.sym.Activation(data=fc2, act_type=\"relu\")\n",
+    "    fc3 = mx.sym.FullyConnected(data=act2, num_hidden=10)\n",
+    "    return mx.sym.SoftmaxOutput(data=fc3, name='softmax')\n",
+    "```\n",
+    "\n",
+    "From this definitnion we can see that there are two fully-connected layers of 128 and 64 neurons each. The activations of the last fully-connected layer is then fed into a Softmax layer of 10 neurons. We use 10 neurons here because the datatset on which we are going to predict is the MNIST dataset of hand-written digit recognition which has 10 classes. More details can be found about the dataset on the [creator's webpage](http://yann.lecun.com/exdb/mnist/)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Prequisites and Preprocessing\n",
+    "\n",
+    "### Permissions and environment variables\n",
     "\n",
-    "First, let us begin by downloading the mnist data using the mxnet utilities."
+    "Here we set up the linkage and authentication to AWS services. In this notebook we only need the roles used to give learning and hosting access to your data. The Sagemaker SDK will use S3 defualt buckets when needed. Supply the role in the variable below."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    "role = '<your SageMaker execution role here>'"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Data setup\n",
+    "\n",
+    "Next, we need to pull the data from the author's site to our local box. Since we have ``mxnet`` utilities, we will use the utilities to download the dataset locally."
    ]
   },
   {
@@ -34,7 +91,34 @@
     "collapsed": true
    },
    "source": [
-    "Train a typical mxnet model for lenet."
+    "### Training\n",
+    "\n",
+    "It is time to train the network. Since we are training the network locally, we can make use of mxnet training tools. The training method is also in the accompanying [mnist.py](mnist.py) file. The method is shown below. \n",
+    "\n",
+    "```python \n",
+    "def train(data, hyperparameters= {'learning_rate': 0.11}, num_cpus=0, num_gpus =1 , **kwargs):\n",
+    "    train_labels = data['train_label']\n",
+    "    train_images = data['train_data']\n",
+    "    test_labels = data['test_label']\n",
+    "    test_images = data['test_data']\n",
+    "    batch_size = 100\n",
+    "    train_iter = mx.io.NDArrayIter(train_images, train_labels, batch_size, shuffle=True)\n",
+    "    val_iter = mx.io.NDArrayIter(test_images, test_labels, batch_size)\n",
+    "    logging.getLogger().setLevel(logging.DEBUG)\n",
+    "    mlp_model = mx.mod.Module(\n",
+    "        symbol=build_graph(),\n",
+    "        context=get_train_context(num_cpus, num_gpus))\n",
+    "    mlp_model.fit(train_iter,\n",
+    "                  eval_data=val_iter,\n",
+    "                  optimizer='sgd',\n",
+    "                  optimizer_params={'learning_rate': float(hyperparameters.get(\"learning_rate\", 0.1))},\n",
+    "                  eval_metric='acc',\n",
+    "                  batch_end_callback=mx.callback.Speedometer(batch_size, 100),\n",
+    "                  num_epoch=10)\n",
+    "    return mlp_model\n",
+    "```\n",
+    "\n",
+    "The method above collects the ``data`` variable that ``get_mnist`` method gives you (which is a dictionary of data arrays) along with a dictionary of ``hyperparameters`` which only contains learning rate, and other parameters. It creates a [``mxnet.mod.Module``](https://mxnet.incubator.apache.org/api/python/module.html) from the network graph we built in the ``build_graph`` method and trains the network using the ``mxnet.mod.Module.fit`` method. "
    ]
   },
   {
@@ -53,7 +137,11 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Export the model and save it down. Analogous to the tensorflow example, some structure needs to be followed, which is explained in the following code."
+    "## Set up hosting for the model\n",
+    "\n",
+    "### Export the model from mxnet\n",
+    "\n",
+    "In order to set up hosting, we have to import the model from training to hosting. We will begin by exporting the model from mxnet and saving it down. Analogous to the [tensorflow example](../tensorflow_iris_byom/tensorflow_BYOM_iris.ipynb), some structure needs to be followed. The exported model has to be converted into a form that is readable by ``sagemaker.mxnet.model.MXNetModel``. The following code describes exporting the model in a form that does the same:"
    ]
   },
   {
@@ -76,7 +164,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Open a sagemaker session and upload the model on to the default S3 bucket."
+    "### Import model into SageMaker\n",
+    "\n",
+    "Open a new sagemaker session and upload the model on to the default S3 bucket. We can use the ``sagemaker.Session.upload_data`` method to do this. We need the location of where we exported the model from MXNet and where in our default bucket we want to store the model(``/model``). The default S3 bucket can be found using the ``sagemaker.Session.default_bucket`` method."
    ]
   },
   {
@@ -97,7 +187,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Use the ``sagemaker.mxnet.model.MXNetModel`` to create a new model that can be deployed."
+    "Use the ``sagemaker.mxnet.model.MXNetModel`` to import the model into SageMaker that can be deployed. We need the location of the S3 bucket where we have the model, the role for authentication and the entry_point where the model defintion is stored (``mnist.py``). The import call is the following:"
    ]
   },
   {
@@ -118,7 +208,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Deploy the model"
+    "### Create endpoint\n",
+    "\n",
+    "Now the model is ready to be deployed at a SageMaker endpoint. We can use the ``sagemaker.mxnet.model.MXNetModel.deploy`` method to do this. Unless you have created or prefer other instances, we recommend using 1 ``'ml.c4.xlarge'`` instance for this training. These are supplied as arguments. "
    ]
   },
   {
@@ -137,7 +229,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "We can now use this predictor to classify hand-written digits."
+    "### Validate the endpoint for use\n",
+    "\n",
+    "We can now use this endpoint to classify hand-written digits."
    ]
   },
   {
@@ -187,6 +281,13 @@
     "sagemaker.Session().delete_endpoint(predictor.endpoint)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Clear all stored model data so that we don't overwrite them the next time. "
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,