 archived/Amazon_JumpStart_Text_Classification.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "773cbac1",
   "metadata": {},
   "source": [
    "# Introduction to JumpStart - Text Classification"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c0ad326f",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "This notebook's CI test result for us-west-2 is as follows. CI test results in other regions can be found at the end of the notebook. \n",
    "\n",
    "![This us-west-2 badge failed to load. Check your device's internet connectivity, otherwise the service is currently unavailable](https://prod.us-west-2.tcx-beacon.docs.aws.dev/sagemaker-nb/us-west-2/introduction_to_amazon_algorithms|jumpstart_text_classification|Amazon_JumpStart_Text_Classification.ipynb)\n",
    "\n",
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e8029d8a",
   "metadata": {},
   "source": [
    "---\n",
    "Welcome to Amazon [SageMaker JumpStart](https://docs.aws.amazon.com/sagemaker/latest/dg/studio-jumpstart.html)! You can use JumpStart to solve many Machine Learning tasks through one-click in SageMaker Studio, or through [SageMaker JumpStart API](https://sagemaker.readthedocs.io/en/stable/overview.html#use-prebuilt-models-with-sagemaker-jumpstart). \n",
    "\n",
    "In this demo notebook, we demonstrate how to use the JumpStart API for Text Classification. Text Classification refers to classifying an input sentence to one of the class labels of the training dataset.  We demonstrate following use cases of Text Classification models:\n",
    "\n",
    "* How to fine-tune a pre-trained Transformer model to a custom dataset, and then run inference on the fine-tuned model.\n",
    "\n",
    "Note: This notebook was tested on ml.t3.medium instance in Amazon SageMaker Studio with Python 3 (Data Science) kernel and in Amazon SageMaker Notebook instance with conda_python3 kernel.\n",
    "\n",
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e12d4028",
   "metadata": {},
   "source": [
    "1. [Set Up](#1.-Set-Up)\n",
    "2. [Select a pre-trained model](#2.-Select-a-pre-trained-model)\n",
    "3. [Finetune the pre-trained model on a custom dataset](#4.-Finetune-the-pre-trained-model-on-a-custom-dataset)\n",
    "    * [Retrieve JumpStart Training artifacts](#4.1.-Retrieve-JumpStart-Training-artifacts)\n",
    "    * [Set Training parameters](#4.2.-Set-Training-parameters)\n",
    "    * [Train with Automatic Model Tuning (HPO)](#AMT)\n",
    "    * [Start Training](#4.4.-Start-Training)\n",
    "    * [Deploy & run Inference on the fine-tuned model](#4.5.-Deploy-&-run-Inference-on-the-fine-tuned-model)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "664b058b",
   "metadata": {},
   "source": [
    "## 1. Set Up\n",
    "***\n",
    "Before executing the notebook, there are some initial steps required for setup. This notebook requires latest version of sagemaker and ipywidgets.\n",
    "***"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5a24ba2b",
   "metadata": {},
   "outputs": [],
   "source": [
    "!pip install sagemaker ipywidgets --upgrade --quiet"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5d03b914",
   "metadata": {},
   "outputs": [],
   "source": [
    "import sagemaker, boto3, json\n",
    "from sagemaker import get_execution_role\n",
    "\n",
    "aws_role = get_execution_role()\n",
    "aws_region = boto3.Session().region_name\n",
    "sess = sagemaker.Session()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bb8c4bbb",
   "metadata": {},
   "source": [
    "## 2. Select a pre-trained model\n",
    "***\n",
    "You can continue with the default model, or can choose a different model from the dropdown generated upon running the next cell. A complete list of JumpStart models can also be accessed at [JumpStart Models](https://sagemaker.readthedocs.io/en/stable/doc_utils/jumpstart.html#).\n",
    "***"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fc4016db",
   "metadata": {},
   "outputs": [],
   "source": [
    "model_id = \"tensorflow-tc-bert-en-uncased-L-12-H-768-A-12-2\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "422bcdec",
   "metadata": {},
   "outputs": [],
   "source": [
    "import IPython\n",
    "from ipywidgets import Dropdown\n",
    "\n",
    "# download JumpStart model_manifest file.\n",
    "boto3.client(\"s3\").download_file(\n",
    "    f\"jumpstart-cache-prod-{aws_region}\", \"models_manifest.json\", \"models_manifest.json\"\n",
    ")\n",
    "with open(\"models_manifest.json\", \"rb\") as json_file:\n",
    "    model_list = json.load(json_file)\n",
    "\n",
    "# filter-out all the Text Classification models from the manifest list.\n",
    "tc_models_all_versions, tc_models = [\n",
    "    model[\"model_id\"] for model in model_list if \"-tc-\" in model[\"model_id\"]\n",
    "], []\n",
    "[tc_models.append(model) for model in tc_models_all_versions if model not in tc_models]\n",
    "\n",
    "# display the model-ids in a dropdown, for user to select a model.\n",
    "dropdown = Dropdown(\n",
    "    value=model_id,\n",
    "    options=tc_models,\n",
    "    description=\"JumpStart Text Classification Models:\",\n",
    "    style={\"description_width\": \"initial\"},\n",
    "    layout={\"width\": \"max-content\"},\n",
    ")\n",
    "display(IPython.display.Markdown(\"## Select a JumpStart pre-trained model from the dropdown below\"))\n",
    "display(dropdown)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0e75c896",
   "metadata": {},
   "outputs": [],
   "source": [
    "model_id = dropdown.value"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "78b81eff",
   "metadata": {},
   "source": [
    "## 3. Finetune the pre-trained model on a custom dataset\n",
    "***\n",
    "We discuss how a model can be finetuned to a custom dataset with any number of classes. \n",
    "\n",
    "The Text Embedding model can be fine-tuned on any text classification dataset in the same way the \n",
    "model available for inference has been fine-tuned on the SST2 movie review dataset.\n",
    "\n",
    "The model available for fine-tuning attaches a classification layer to the Text Embedding model \n",
    "and initializes the layer parameters to random values. \n",
    "The output dimension of the classification layer is determined based on the number of classes \n",
    "detected in the input data. The fine-tuning step fine-tunes all the model \n",
    "parameters to minimize prediction error on the input data and returns the fine-tuned model. \n",
    "The model returned by fine-tuning can be further deployed for inference. \n",
    "Below are the instructions for how the training data should be formatted for input to the model.\n",
    "\n",
    "\n",
    "- **Input:** A directory containing a 'data.csv' file. \n",
    "    - Each row of the first column of 'data.csv' should have integer class labels between 0 to the number of classes.\n",
    "    - Each row of the second column should have the corresponding text. \n",
    "- **Output:** A trained model that can be deployed for inference. \n",
    " \n",
    "Below is an example of 'data.csv' file showing values in its first two columns. Note that the file should not have any header.\n",
    "\n",
    "|   |   |\n",
    "|---|---|\n",
    "|0\t|hide new secretions from the parental units| \n",
    "|0\t|contains no wit , only labored gags| \n",
    "|1\t|that loves its characters and communicates something rather beautiful about human nature| \n",
    "|...|...|\n",
    " \n",
    "source: [TensorFlow Hub](model_url). License:[Apache 2.0 License](https://jumpstart-cache-alpha-us-west-2.s3-us-west-2.amazonaws.com/licenses/Apache-License/LICENSE-2.0.txt).\n",
    " \n",
    "SST2 dataset is downloaded from [TensorFlow](https://www.tensorflow.org/datasets/catalog/glue#gluesst2).\n",
    " [Apache 2.0 License](https://jumpstart-cache-prod-us-west-2.s3-us-west-2.amazonaws.com/licenses/Apache-License/LICENSE-2.0.txt).\n",
    "  [Dataset Homepage](https://nlp.stanford.edu/sentiment/index.html). \n",
    "***"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "21d059ba",
   "metadata": {},
   "source": [
    "### Set Training parameters\n",
    "Now that we are done with all the setup that is needed, we are ready to fine-tune our model. To begin, let us create a [``sageMaker.estimator.Estimator``](https://sagemaker.readthedocs.io/en/stable/api/training/estimators.html) object. This estimator will launch the training job. \n",
    "\n",
    "There are two kinds of parameters that need to be set for training. \n",
    "\n",
    "The first one are the parameters for the training job. These include: Training data path. This is S3 folder in which the input data is stored \n",
    "***\n",
    "The second set of parameters are algorithm specific training hyper-parameters.\n",
    "***"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "59d8c279",
   "metadata": {},
   "outputs": [],
   "source": [
    "import json\n",
    "from sagemaker.jumpstart.estimator import JumpStartEstimator\n",
    "from sagemaker.jumpstart.utils import get_jumpstart_content_bucket\n",
    "\n",
    "\n",
    "# Sample training data is available in this bucket\n",
    "training_data_bucket = get_jumpstart_content_bucket()\n",
    "training_data_prefix = \"training-datasets/SST/\"\n",
    "\n",
    "training_dataset_s3_path = f\"s3://{training_data_bucket}/{training_data_prefix}\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "164ecdb6",
   "metadata": {},
   "source": [
    "### Start Training\n",
    "***\n",
    "We start by creating the estimator object with all the required assets and then launch the training job.  Since default hyperparameter values are model-specific, inspect estimator.hyperparameters() to view default values for your selected model.\n",
    "***"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b191e499",
   "metadata": {},
   "outputs": [],
   "source": [
    "estimator = JumpStartEstimator(\n",
    "    model_id=model_id,\n",
    "    hyperparameters={\"epochs\": \"1\", \"batch_size\": \"64\"},\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1a219e8e",
   "metadata": {},
   "outputs": [],
   "source": [
    "# You can now fit the estimator by providing training data to the train channel\n",
    "\n",
    "estimator.fit({\"training\": training_dataset_s3_path}, logs=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "74121803",
   "metadata": {},
   "source": [
    "## Deploy & run Inference on the fine-tuned model\n",
    "***\n",
    "A trained model does nothing on its own. We now want to use the model to perform inference. For this example, that means predicting the class label of an input sentence.\n",
    "***"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d6810ec7",
   "metadata": {},
   "outputs": [],
   "source": [
    "# You can deploy the fine-tuned model to an endpoint directly from the estimator.\n",
    "predictor = estimator.deploy()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9d7f7a0a",
   "metadata": {},
   "source": [
    "---\n",
    "Next, we input example sentences for running inference.\n",
    "These examples are taken from SST2 dataset downloaded from [TensorFlow](https://www.tensorflow.org/datasets/catalog/glue#gluesst2). [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0). [Dataset Homepage](https://nlp.stanford.edu/sentiment/index.html). \n",
    "\n",
    "---"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ce1baed7",
   "metadata": {},
   "outputs": [],
   "source": [
    "text1 = \"astonishing ... ( frames ) profound ethical and philosophical questions in the form of dazzling pop entertainment\"\n",
    "text2 = \"simply stupid , irrelevant and deeply , truly , bottomlessly cynical \""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "728ba891",
   "metadata": {},
   "outputs": [],
   "source": [
    "for text in [text1, text2]:\n",
    "    query_response = predictor.predict(text)\n",
    "    print(query_response)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "89667923",
   "metadata": {},
   "source": [
    "---\n",
    "Next, we clean up the deployed endpoint.\n",
    "\n",
    "---"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "32cdae4e",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Delete the SageMaker endpoint and the attached resources\n",
    "predictor.delete_predictor()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4488f8ef",
   "metadata": {},
   "source": [
    "## Notebook CI Test Results\n",
    "\n",
    "This notebook was tested in multiple regions. The test results are as follows, except for us-west-2 which is shown at the top of the notebook.\n",
    "\n",
    "![This us-east-1 badge failed to load. Check your device's internet connectivity, otherwise the service is currently unavailable](https://prod.us-west-2.tcx-beacon.docs.aws.dev/sagemaker-nb/us-east-1/introduction_to_amazon_algorithms|jumpstart_text_classification|Amazon_JumpStart_Text_Classification.ipynb)\n",
    "\n",
    "![This us-east-2 badge failed to load. Check your device's internet connectivity, otherwise the service is currently unavailable](https://prod.us-west-2.tcx-beacon.docs.aws.dev/sagemaker-nb/us-east-2/introduction_to_amazon_algorithms|jumpstart_text_classification|Amazon_JumpStart_Text_Classification.ipynb)\n",
    "\n",
    "![This us-west-1 badge failed to load. Check your device's internet connectivity, otherwise the service is currently unavailable](https://prod.us-west-2.tcx-beacon.docs.aws.dev/sagemaker-nb/us-west-1/introduction_to_amazon_algorithms|jumpstart_text_classification|Amazon_JumpStart_Text_Classification.ipynb)\n",
    "\n",
    "![This ca-central-1 badge failed to load. Check your device's internet connectivity, otherwise the service is currently unavailable](https://prod.us-west-2.tcx-beacon.docs.aws.dev/sagemaker-nb/ca-central-1/introduction_to_amazon_algorithms|jumpstart_text_classification|Amazon_JumpStart_Text_Classification.ipynb)\n",
    "\n",
    "![This sa-east-1 badge failed to load. Check your device's internet connectivity, otherwise the service is currently unavailable](https://prod.us-west-2.tcx-beacon.docs.aws.dev/sagemaker-nb/sa-east-1/introduction_to_amazon_algorithms|jumpstart_text_classification|Amazon_JumpStart_Text_Classification.ipynb)\n",
    "\n",
    "![This eu-west-1 badge failed to load. Check your device's internet connectivity, otherwise the service is currently unavailable](https://prod.us-west-2.tcx-beacon.docs.aws.dev/sagemaker-nb/eu-west-1/introduction_to_amazon_algorithms|jumpstart_text_classification|Amazon_JumpStart_Text_Classification.ipynb)\n",
    "\n",
    "![This eu-west-2 badge failed to load. Check your device's internet connectivity, otherwise the service is currently unavailable](https://prod.us-west-2.tcx-beacon.docs.aws.dev/sagemaker-nb/eu-west-2/introduction_to_amazon_algorithms|jumpstart_text_classification|Amazon_JumpStart_Text_Classification.ipynb)\n",
    "\n",
    "![This eu-west-3 badge failed to load. Check your device's internet connectivity, otherwise the service is currently unavailable](https://prod.us-west-2.tcx-beacon.docs.aws.dev/sagemaker-nb/eu-west-3/introduction_to_amazon_algorithms|jumpstart_text_classification|Amazon_JumpStart_Text_Classification.ipynb)\n",
    "\n",
    "![This eu-central-1 badge failed to load. Check your device's internet connectivity, otherwise the service is currently unavailable](https://prod.us-west-2.tcx-beacon.docs.aws.dev/sagemaker-nb/eu-central-1/introduction_to_amazon_algorithms|jumpstart_text_classification|Amazon_JumpStart_Text_Classification.ipynb)\n",
    "\n",
    "![This eu-north-1 badge failed to load. Check your device's internet connectivity, otherwise the service is currently unavailable](https://prod.us-west-2.tcx-beacon.docs.aws.dev/sagemaker-nb/eu-north-1/introduction_to_amazon_algorithms|jumpstart_text_classification|Amazon_JumpStart_Text_Classification.ipynb)\n",
    "\n",
    "![This ap-southeast-1 badge failed to load. Check your device's internet connectivity, otherwise the service is currently unavailable](https://prod.us-west-2.tcx-beacon.docs.aws.dev/sagemaker-nb/ap-southeast-1/introduction_to_amazon_algorithms|jumpstart_text_classification|Amazon_JumpStart_Text_Classification.ipynb)\n",
    "\n",
    "![This ap-southeast-2 badge failed to load. Check your device's internet connectivity, otherwise the service is currently unavailable](https://prod.us-west-2.tcx-beacon.docs.aws.dev/sagemaker-nb/ap-southeast-2/introduction_to_amazon_algorithms|jumpstart_text_classification|Amazon_JumpStart_Text_Classification.ipynb)\n",
    "\n",
    "![This ap-northeast-1 badge failed to load. Check your device's internet connectivity, otherwise the service is currently unavailable](https://prod.us-west-2.tcx-beacon.docs.aws.dev/sagemaker-nb/ap-northeast-1/introduction_to_amazon_algorithms|jumpstart_text_classification|Amazon_JumpStart_Text_Classification.ipynb)\n",
    "\n",
    "![This ap-northeast-2 badge failed to load. Check your device's internet connectivity, otherwise the service is currently unavailable](https://prod.us-west-2.tcx-beacon.docs.aws.dev/sagemaker-nb/ap-northeast-2/introduction_to_amazon_algorithms|jumpstart_text_classification|Amazon_JumpStart_Text_Classification.ipynb)\n",
    "\n",
    "![This ap-south-1 badge failed to load. Check your device's internet connectivity, otherwise the service is currently unavailable](https://prod.us-west-2.tcx-beacon.docs.aws.dev/sagemaker-nb/ap-south-1/introduction_to_amazon_algorithms|jumpstart_text_classification|Amazon_JumpStart_Text_Classification.ipynb)\n"
   ]
  }
 ],
 "metadata": {
  "instance_type": "ml.t3.medium",
  "kernelspec": {
   "display_name": "conda_python3",
   "language": "python",
   "name": "conda_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.10.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}