Merge branch 'main' into atqy-correct-rtd-rst-2

Author: atqy

frameworks/pytorch/get_started_mnist_train.ipynb

@@ -4,10 +4,24 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# MNIST training with PyTorch\n",
+    "# Train an MNIST model with PyTorch\n",
     "\n",
-    "MNIST is a widely used dataset for handwritten digit classification. It consists of 70,000 labeled 28x28 pixel grayscale images of hand-written digits. The dataset is split into 60,000 training images and 10,000 test images. There are 10 classes (one for each of the 10 digits). This tutorial will show how to train and test an MNIST model on SageMaker using PyTorch. \n",
-    "\n"
+    "MNIST is a widely used dataset for handwritten digit classification. It consists of 70,000 labeled 28x28 pixel grayscale images of hand-written digits. The dataset is split into 60,000 training images and 10,000 test images. There are 10 classes (one for each of the 10 digits). This tutorial shows how to train and test an MNIST model on SageMaker using PyTorch. \n",
+    "\n",
+    "## Runtime\n",
+    "\n",
+    "This notebook takes approximately 5 minutes to run.\n",
+    "\n",
+    "## Contents\n",
+    "\n",
+    "1. [PyTorch Estimator](#PyTorch-Estimator)\n",
+    "1. [Implement the entry point for training](#Implement-the-entry-point-for-training)\n",
+    "1. [Set hyperparameters](#Set-hyperparameters)\n",
+    "1. [Set up channels for the training and testing data](#Set-up-channels-for-the-training-and-testing-data)\n",
+    "1. [Run the training script on SageMaker](#Run-the-training-script-on-SageMaker)\n",
+    "1. [Inspect and store model data](#Inspect-and-store-model-data)\n",
+    "1. [Test and debug the entry point before executing the training container](#Test-and-debug-the-entry-point-before-executing-the-training-container)\n",
+    "1. [Conclusion](#Conclusion)"
    ]
   },
   {
@@ -28,7 +42,7 @@
     "\n",
     "role = get_execution_role()\n",
     "\n",
-    "output_path = \"s3://\" + sess.default_bucket() + \"/mnist\""
+    "output_path = \"s3://\" + sess.default_bucket() + \"/DEMO-mnist\""
    ]
   },
   {
@@ -44,26 +58,26 @@
     "You need to configure\n",
     "it with the following parameters to set up the environment:\n",
     "\n",
-    "- entry_point: A user defined python file to be used by the training container as the \n",
+    "- `entry_point`: A user-defined Python file used by the training container as the \n",
     "instructions for training. We further discuss this file in the next subsection.\n",
     "\n",
-    "- role: An IAM role to make AWS service requests\n",
+    "- `role`: An IAM role to make AWS service requests\n",
     "\n",
-    "- instance_type: The type of SageMaker instance to run your training script. \n",
+    "- `instance_type`: The type of SageMaker instance to run your training script. \n",
     "Set it to `local` if you want to run the training job on \n",
     "the SageMaker instance you are using to run this notebook\n",
     "\n",
-    "- instance count: The number of instances you need to run your training job. \n",
+    "- `instance_count`: The number of instances to run your training job on. \n",
     "Multiple instances are needed for distributed training.\n",
     "\n",
-    "- output_path: \n",
+    "- `output_path`: \n",
     "S3 bucket URI to save training output (model artifacts and output files)\n",
     "\n",
-    "- framework_version: The version of PyTorch you need to use.\n",
+    "- `framework_version`: The version of PyTorch to use\n",
     "\n",
-    "- py_version: The python version you need to use\n",
+    "- `py_version`: The Python version to use\n",
     "\n",
-    "For more information, see [the API reference](https://sagemaker.readthedocs.io/en/stable/api/training/estimators.html#sagemaker.estimator.EstimatorBase)\n",
+    "For more information, see the [EstimatorBase API reference](https://sagemaker.readthedocs.io/en/stable/api/training/estimators.html#sagemaker.estimator.EstimatorBase)\n",
     "\n"
    ]
   },
@@ -73,26 +87,25 @@
    "source": [
     "## Implement the entry point for training\n",
     "\n",
-    "The entry point for training is a python script that provides all \n",
+    "The entry point for training is a Python script that provides all \n",
     "the code for training a PyTorch model. It is used by the SageMaker \n",
     "PyTorch Estimator (`PyTorch` class above) as the entry point for running the training job.\n",
     "\n",
     "Under the hood, SageMaker PyTorch Estimator creates a docker image\n",
     "with runtime environemnts \n",
-    "specified by the parameters you used to initiated the\n",
-    "estimator class and it injects the training script into the \n",
-    "docker image to be used as the entry point to run the container.\n",
+    "specified by the parameters you provide to initiate the\n",
+    "estimator class, and it injects the training script into the \n",
+    "docker image as the entry point to run the container.\n",
     "\n",
     "In the rest of the notebook, we use *training image* to refer to the \n",
     "docker image specified by the PyTorch Estimator and *training container*\n",
     "to refer to the container that runs the training image. \n",
     "\n",
     "This means your training script is very similar to a training script\n",
     "you might run outside Amazon SageMaker, but it can access the useful environment \n",
-    "variables provided by the training image. Checkout [the short list of environment variables provided by the SageMaker service](https://sagemaker.readthedocs.io/en/stable/frameworks/mxnet/using_mxnet.html?highlight=entry%20point) to see some common environment \n",
-    "variables you might used. Checkout [the complete list of environment variables](https://github.com/aws/sagemaker-training-toolkit/blob/master/ENVIRONMENT_VARIABLES.md) for a complete \n",
+    "variables provided by the training image. See [the complete list of environment variables](https://github.com/aws/sagemaker-training-toolkit/blob/master/ENVIRONMENT_VARIABLES.md) for a complete \n",
     "description of all environment variables your training script\n",
-    "can access to. \n",
+    "can access. \n",
     "\n",
     "In this example, we use the training script `code/train.py`\n",
     "as the entry point for our PyTorch Estimator.\n"
@@ -111,12 +124,12 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Set hyperparameters\n",
+    "## Set hyperparameters\n",
     "\n",
-    "In addition, PyTorch estimator allows you to parse command line arguments\n",
+    "In addition, the PyTorch estimator allows you to parse command line arguments\n",
     "to your training script via `hyperparameters`.\n",
     "\n",
-    "<span style=\"color:red\"> Note: local mode is not supported in SageMaker Studio </span>"
+    "Note: local mode is not supported in SageMaker Studio. "
    ]
   },
   {
@@ -125,8 +138,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# set local_mode to be True if you want to run the training script\n",
-    "# on the machine that runs this notebook\n",
+    "# Set local_mode to True to run the training script on the machine that runs this notebook\n",
     "\n",
     "local_mode = False\n",
     "\n",
@@ -153,22 +165,21 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The training container executes your training script like\n",
+    "The training container executes your training script like:\n",
     "\n",
     "```\n",
-    "python train.py --batch-size 100 --epochs 1 --learning-rate 1e-3 \\\n",
-    "    --log-interval 100\n",
+    "python train.py --batch-size 100 --epochs 1 --learning-rate 1e-3 --log-interval 100\n",
     "```"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Set up channels for training and testing data\n",
+    "## Set up channels for the training and testing data\n",
     "\n",
-    "You need to tell `PyTorch` estimator where to find your training and \n",
-    "testing data. It can be a link to an S3 bucket or it can be a path\n",
+    "Tell the `PyTorch` estimator where to find the training and \n",
+    "testing data. It can be a path to an S3 bucket, or a path\n",
     "in your local file system if you use local mode. In this example,\n",
     "we download the MNIST data from a public S3 bucket and upload it \n",
     "to your default bucket. "
@@ -184,11 +195,10 @@
     "import boto3\n",
     "from botocore.exceptions import ClientError\n",
     "\n",
-    "\n",
     "# Download training and testing data from a public S3 bucket\n",
     "\n",
     "\n",
-    "def download_from_s3(data_dir=\"/tmp/data\", train=True):\n",
+    "def download_from_s3(data_dir=\"./data\", train=True):\n",
     "    \"\"\"Download MNIST dataset and convert it to numpy array\n",
     "\n",
     "    Args:\n",
@@ -220,8 +230,8 @@
     "    return\n",
     "\n",
     "\n",
-    "download_from_s3(\"/tmp/data\", True)\n",
-    "download_from_s3(\"/tmp/data\", False)"
+    "download_from_s3(\"./data\", True)\n",
+    "download_from_s3(\"./data\", False)"
    ]
   },
   {
@@ -230,11 +240,11 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# upload to the default bucket\n",
+    "# Upload to the default bucket\n",
     "\n",
-    "prefix = \"mnist\"\n",
+    "prefix = \"DEMO-mnist\"\n",
     "bucket = sess.default_bucket()\n",
-    "loc = sess.upload_data(path=\"/tmp/data\", bucket=bucket, key_prefix=prefix)\n",
+    "loc = sess.upload_data(path=\"./data\", bucket=bucket, key_prefix=prefix)\n",
     "\n",
     "channels = {\"training\": loc, \"testing\": loc}"
    ]
@@ -243,23 +253,23 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The keys of the dictionary `channels` are parsed to the training image\n",
+    "The keys of the `channels` dictionary are passed to the training image,\n",
     "and it creates the environment variable `SM_CHANNEL_<key name>`. \n",
     "\n",
-    "In this example, `SM_CHANNEL_TRAINING` and `SM_CHANNEL_TESTING` are created in the training image (checkout \n",
-    "how `code/train.py` access these variables). For more information,\n",
-    "see: [SM_CHANNEL_{channel_name}](https://github.com/aws/sagemaker-training-toolkit/blob/master/ENVIRONMENT_VARIABLES.md#sm_channel_channel_name)\n",
+    "In this example, `SM_CHANNEL_TRAINING` and `SM_CHANNEL_TESTING` are created in the training image (see \n",
+    "how `code/train.py` accesses these variables). For more information,\n",
+    "see: [SM_CHANNEL_{channel_name}](https://github.com/aws/sagemaker-training-toolkit/blob/master/ENVIRONMENT_VARIABLES.md#sm_channel_channel_name).\n",
     "\n",
     "If you want, you can create a channel for validation:\n",
     "```\n",
     "channels = {\n",
     "    'training': train_data_loc,\n",
     "    'validation': val_data_loc,\n",
     "    'test': test_data_loc\n",
-    "    }\n",
+    "}\n",
     "```\n",
     "You can then access this channel within your training script via\n",
-    "`SM_CHANNEL_VALIDATION`\n"
+    "`SM_CHANNEL_VALIDATION`.\n"
    ]
   },
   {
@@ -268,7 +278,7 @@
    "source": [
     "## Run the training script on SageMaker\n",
     "Now, the training container has everything to execute your training\n",
-    "script. You can start the container by calling `fit` method."
+    "script. Start the container by calling the `fit()` method."
    ]
   },
   {
@@ -288,8 +298,8 @@
    "source": [
     "## Inspect and store model data\n",
     "\n",
-    "Now, the training is finished, the model artifact has been saved in \n",
-    "the `output_path`. We "
+    "Now, the training is finished, and the model artifact has been saved in \n",
+    "the `output_path`."
    ]
   },
   {
@@ -306,9 +316,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "We store the variable `model_data` in the current notebook kernel. \n",
-    "In the [next notebook](get_started_with_mnist_deploy.ipynb), you will learn how to retrieve the model artifact and deploy to a SageMaker\n",
-    "endpoint."
+    "We store the variable `pt_mnist_model_data` in the current notebook kernel."
    ]
   },
   {
@@ -326,8 +334,8 @@
    "source": [
     "## Test and debug the entry point before executing the training container\n",
     "\n",
-    "The entry point `code/train.py` provided here has been tested and it can be executed in the training container. \n",
-    "When you do develop your own training script, it is a good practice to simulate the container environment \n",
+    "The entry point `code/train.py` can be executed in the training container. \n",
+    "When you develop your own training script, it is a good practice to simulate the container environment \n",
     "in the local shell and test it before sending it to SageMaker, because debugging in a containerized environment\n",
     "is rather cumbersome. The following script shows how you can test your training script:"
    ]
@@ -340,11 +348,20 @@
    "source": [
     "!pygmentize code/test_train.py"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Conclusion\n",
+    "\n",
+    "In this notebook, we trained a PyTorch model on the MNIST dataset by fitting a SageMaker estimator. For next steps on how to deploy the trained model and perform inference, see [Deploy a Trained PyTorch Model](https://sagemaker-examples.readthedocs.io/en/latest/frameworks/pytorch/get_started_mnist_deploy.html)."
+   ]
   }
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Environment (conda_pytorch_p36)",
+   "display_name": "conda_pytorch_p36",
    "language": "python",
    "name": "conda_pytorch_p36"
   },
@@ -358,7 +375,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.6.10"
+   "version": "3.6.13"
   },
   "notice": "Copyright 2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.  Licensed under the Apache License, Version 2.0 (the \"License\"). You may not use this file except in compliance with the License. A copy of the License is located at http://aws.amazon.com/apache2.0/ or in the \"license\" file accompanying this file. This file is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License."
  },