{"id":18339936,"url":"https://github.com/mxagar/sentiment_rnn_aws_deployment","last_synced_at":"2026-04-24T16:05:00.270Z","repository":{"id":106857987,"uuid":"570118064","full_name":"mxagar/sentiment_rnn_aws_deployment","owner":"mxagar","description":"This project contains a Sentiment Analysis RNN based on LSTM cells which is deployed using AWS SageMaker.","archived":false,"fork":false,"pushed_at":"2022-12-02T10:20:32.000Z","size":1420,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-15T12:50:22.981Z","etag":null,"topics":["aws","deep-learning","deployment","lstm","natural-language-processing","nlp","rnn","sagemaker","sentiment-analysis"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mxagar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-11-24T11:32:07.000Z","updated_at":"2022-11-24T12:25:46.000Z","dependencies_parsed_at":null,"dependency_job_id":"25190860-d529-4f67-8c8a-107b8066dbe6","html_url":"https://github.com/mxagar/sentiment_rnn_aws_deployment","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxagar%2Fsentiment_rnn_aws_deployment","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxagar%2Fsentiment_rnn_aws_deployment/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxagar%2Fsentiment_rnn_aws_deployment/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxagar%2Fsentiment_rnn_aws_deployment/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mxagar","download_url":"https://codeload.github.com/mxagar/sentiment_rnn_aws_deployment/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248109301,"owners_count":21049286,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","deep-learning","deployment","lstm","natural-language-processing","nlp","rnn","sagemaker","sentiment-analysis"],"created_at":"2024-11-05T20:19:56.368Z","updated_at":"2026-04-24T16:05:00.202Z","avatar_url":"https://github.com/mxagar.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Sentiment Analysis RNN Deployed Using AWS SageMaker\n\nThis repository contains a Sentiment Analysis Recurrent Neural Network (RNN) based on Long Short-Term Memory (LSTM) units which is deployed using [AWS SageMaker](https://aws.amazon.com/pm/sagemaker/). The result is simple public web app which interacts with the deployed endpoint to determine whether a movie review written by the user is positive or negative. In its present form, the project is intended to be executed using Amazon's SageMaker, but it could be easily ported to other deployment platforms.\n\nThe model is implemented with [Pytorch](https://pytorch.org/) and it uses materials from the [Udacity Deep Learning Nanodegree](https://www.udacity.com/course/deep-learning-nanodegree--nd101), which can be obtained in their original (non-implemented) form in [sagemaker-deployment](https://github.com/mxagar/sagemaker-deployment). That original repository, as well as the current one, serve as templates for similar projects.\n\nThe dataset used for training is the [IMDB dataset](http://ai.stanford.edu/~amaas/data/sentiment/):\n\n\u003e Maas, Andrew L., et al. [Learning Word Vectors for Sentiment Analysis](http://ai.stanford.edu/~amaas/data/sentiment/). In _Proceedings of the 49th Annual Meeting of the Association for Computational Linguistics: Human Language Technologies_. Association for Computational Linguistics, 2011.\n\nPlease note that **the project focuses on the deployment process/techniques rather than the model efficiency.**\n\nTable of Contents:\n\n- [Sentiment Analysis RNN Deployed Using AWS SageMaker](#sentiment-analysis-rnn-deployed-using-aws-sagemaker)\n  - [How to Use This](#how-to-use-this)\n    - [Overview of Files and Contents](#overview-of-files-and-contents)\n    - [CLI and Git](#cli-and-git)\n    - [Dependencies](#dependencies)\n    - [Model Integration](#model-integration)\n    - [App Usage](#app-usage)\n  - [Brief Notes on the Web App Architecture](#brief-notes-on-the-web-app-architecture)\n  - [Brief Notes on AWS SageMaker](#brief-notes-on-aws-sagemaker)\n  - [Brief Notes on the Chosen Model](#brief-notes-on-the-chosen-model)\n  - [Preliminary Results](#preliminary-results)\n  - [Improvements, Next Steps](#improvements-next-steps)\n  - [Interesting Links](#interesting-links)\n  - [Authorship](#authorship)\n\n## How to Use This\n\nThe AWS SageMaker environment can be set up following these steps:\n\n- Log in to the AWS console and go to the SageMaker dashboard.\n- Click on 'Create notebook instance':\n    - Choose a name, e.g.: `sentiment-rnn-deployment`\n    - Instance type: `ml.t2.medium`; we can choose a more powerful one if we'd like to pay.\n    - Elastic inference: none; no GPU acceleration needed for the notebook.\n    - Platform identifier: Amazon Linux 2, Jupyter Lab 1.\n    - Create a new IAM role with the following properties, if not available:\n        - All SageMaker buckets should be accessible.\n        - BUT: S3 buckets you specify: None.\n        - Give/Enable root access to notebook.\n    - No VPC.\n    - Git repository: Clone a public repository: [https://github.com/mxagar/sentiment_rnn_aws_deployment.git](https://github.com/mxagar/sentiment_rnn_aws_deployment.git).\n    - Rest of options: Default values are okay.\n- Create the notebook.\n- Start the notebook from the list of notebook instances; open JupyterLab.\n\n:warning: AWS SageMaker charges the usage of it services if they're not in the free tier, thus, be careful to\n\n- track any expenses in the AWS Billing dashboard\n- and **turn off any unused services**.\n\nRefer to [SageMaker Cleanup](https://docs.aws.amazon.com/sagemaker/latest/dg/ex1-cleanup.html) for more information on how to remove resources related a a project.\n\n### Overview of Files and Contents\n\nThe project folder contains the following files:\n\n```\n.\n├── Instructions.md                                   # Original instructions\n├── LICENSE                                           # Original Udacity license\n├── README.md                                         # This file\n├── assets                                            # Images and auxiliary assets\n│   ├── sagemaker_examples.py                         # Exemplary code blocks for all step in SageMaker\n│   └── sagemaker_examples_workflow.png               # Workflow diagram for the exemplary code blocks\n└── src\n    ├── README.md\n    ├── SageMaker_Sentiment_Analysis_Project.ipynb    # Project notebook\n    ├── Web_App_Diagram.svg\n    ├── serve                                         # Files for deployment\n    │   ├── model.py                                  # Model definition, derived from nn.Module\n    │   ├── predict.py                                # Inference script, entry point for the container\n    │   ├── requirements.txt                          # Dependencies installed in the deployment container\n    │   └── utils.py\n    ├── train                                         # Files for model training\n    │   ├── model.py                                  # Same as in serve/\n    │   ├── requirements.txt                          # Dependencies installed in the training container\n    │   └── train.py                                  # Training script, entry point for the container\n    └── website                                       # Web app HTML file\n        ├── index.html\n        ├── review_1.png                              # Example result 1\n        ├── review_2.png\n        ├── review_3.png\n        └── review_4.png\n```\n\nThe notebook [`SageMaker_Sentiment_Analysis_Project.ipynb`](src/SageMaker_Sentiment_Analysis_Project) is the main file which guides the complete model creation and its deployment.\n\nWhen that main notebook is run, the folders `data` and `cache` appear in the root project directory; these folders contain the downloaded dataset and generated artifacts/object, such as the created word dictionary.\n\n### CLI and Git\n\nIn the notebook instance, we can open a Terminal with the launcher, which gives us access to the EC2 instance on which the notebook is running:\n\n```bash\npwd # /home/ec2-user\ncd SageMaker\nll\n# sentiment_rnn_aws_deployment # the repo cloned via the GUI\n# lost+found\n```\n\nThere are several ways to push/pull to repositories that were cloned with their HTTPS version; I use **Personal Access Tokens**. Steps to set up a token credential:\n\n- Create a token on Github: Github Settings \u003e Developer Settings \u003e Personal Access Token: Create.\n- In the notebook instance terminal, set user account and activate credential storing:\n\n```bash\n# Open Terminal and set user account\ngit config --global user.email \"my@email.com\"\ngit config --global user.name \"my_username\"\n\n# Activate credential storing to local file\n# If we use \n#   credendial.helper cache\n# instead of\n#   credendial.helper store\n# the credential (token) is saved to memory\ngit config --global credential.helper store\n\ngit pull\n\n# Edit something\ngit add .\ngit commit -m \"message\"\ngit push\n# Input\n# - username\n# - pw: token\n\n# Check that the credential is there!\n# If we chose 'store', it should be there\nless ~/.git-credentials\n```\n\nLater on, to push, either do it in the Terminal, or using the GUI: left menu panel, Git icon.\n\nNote that with the option `credendial.helper store` a file is stored with our credentials, without encryption!\n\nMore information:\n\n- [Pushing to HTTPS repositories](https://repost.aws/questions/QU-P1Hlk4OR6K6kAug-wHT_g/can-sagemaker-git-repositories-use-ssh-secrets-no-name-and-password)\n- [Git Credentials Storage](https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage)\n\n### Dependencies\n\nDependencies are resolved with the `requirements.txt` from [`src/train/`](src/train) and [`src/serve/`](src/serve). Additionally, SageMaker is already set up to use the main notebook.\n\n### Model Integration\n\nWhile AWS SageMaker has plenty of container images ready for specific models (e.g., XGBoost, Linear Learner, etc.), this project uses a Pytorch model which has custom scripts for its definition, training and inference. These scripts are located in the folders [`src/train/`](train) and [`src/serve/`](src/serve).\n\nIn particular:\n\n- The model definition is done is `model.py`, which is copied in both [`src/train/`](src/train) and [`src/serve/`](src/serve).\n- The folder [`src/train/`](src/train) contains the training script [`src/train/train.py`](src/train/train.py), which is the entry point for the training container.\n- The folder [`src/serve/`](src/src/serve) contains the training script [`src/serve/predict.py`](src/serve/predict.py), which is the entry point for the inference container that is deployed.\n\nAll the details are explained in the main notebook.\n\n### App Usage\n\nIn order to use the app, we need to have:\n\n- All the cells in the main notebook executed (except the deletion of the deployment endpoints, at the end).\n- A Lambda function deployed, as explained in the notebook.\n- An API Gateway created, as explained in the notebook.\n- The API Gateway URL correctly specified in the [`src/website/index.html`](src/website/index.html) file.\n\nOnce all is set up, we can locally open the [`src/website/index.html`](src/website/index.html) app with our local browser and we'll the following input field ready to use:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/web_app_gui.png\" alt=\"Web app GUI.\" width=500px\u003e\n\u003c/p\u003e\n\n\n## Brief Notes on the Web App Architecture\n\nAWS models are deployed as containers that have endpoints waiting for requests. We can even deploy several models behind the same endpoint and the container itself routes the requests to the different models. However, those endpoints are only accessible by AWS authenticated services, i.e., we cannot use them directly over the internet without additional layers of processing.\n\nTherefore, the usual solution, and the one adopted here, consists in using an **API Gateway** combined with a **Lambda function**. The resulting architecture is schematically depicted below, and the list of steps taken to  score a review are the following:\n\n- The user submits a review in plain text to the publicly reachable API Gateway, which is a REST API.\n- The API catches the request (i.e., the review to be evaluated) and triggers a Lambda function, passing to it the review.\n- The Lambda function connects to the model endpoint and requests a scoring; it waits for the inferred value, and sends it back to the API Gateway.\n- The API Gateway packs the score as an HTML response and delivers it to the user.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./src/Web_App_Diagram.svg\" alt=\"Web app architecture.\" width=500px\u003e\n\u003c/p\u003e\n\nNote that the user interacts with a simple GUI implemented in an HTML form; however, the API Gateway can be interfaced by any system that speaks HTTP methods, since it's in reality a REST API.\n\nLambda functions have become extremely popular in cloud computing, since they allow *serverless* simple processings or interactions with a backend. That means we don't need to spin up a container / VM / server to execute the code in the lambda function, it is executed for the user seamlessly \u0026mdash; of course, there's a server running behind, but we don't care about setting it up.\n\n## Brief Notes on AWS SageMaker\n\n[AWS SageMaker](https://aws.amazon.com/pm/sagemaker/) is a cloud service by Amazon which enables the execution of all the major steps in a machine learning application hosted at AWS: (1) exploration and data processing, (2) modeling and (3) deployment. SageMaker is composed by three major elements:\n\n- SageMaker Studio\n- Notebook instances\n- The SageMaker API\n\nThe SageMaker Studio is basically an IDE based on Jupyter Labs notebooks with additional Amazon extensions and plugins. However, this project still uses regular notebook instances.\n\nSageMaker works in such a way that dedicated containers are started via the API for training, testing and deploying models. The results or operation information (i.e., logs) of those containers can be consulted in the AWS console. Additionally, the datasets used for training as well as the generated artifacts are stored in S3 buckets. Depending on the degree of control we'd like for each container-task definition, we can use the so called *high level* or *low level* APIs.\n\nThe file [`assets/sagemaker_examples.py`](assets/sagemaker_examples.py) contains code blocks that can be re-used to build an application as the one defined and deployed in this repository; the following diagram shows how the different code blocks are related:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/sagemaker_examples_workflow.png\" alt=\"SageMaker Examples Workflow\" width=750px\u003e\n\u003c/p\u003e\n\nHowever, note that:\n\n- These code blocks are barely explained in the script, i.e., they're intended for the user who knows what's going on but in need for the correct API call with context; if you'd like to have a more detailed guide on AWS SageMaker, I suggest checking my notes in the file [`DLND_Deployment.md`](https://github.com/mxagar/deep_learning_udacity/blob/main/06_Deployment/DLND_Deployment.md).\n- The workflow and file constellation used in the present repository are somewhat different to the one used in the exemplary code blocks, because the project defines, trains and deploys a custom Pytorch model. That requires creating custom containers with manually defined entry points or executed scripts. The differences and the required approach are detailed in the project notebook.\n\n## Brief Notes on the Chosen Model\n\nSentiment analysis models have difficulties with irony and sarcasm, word ambiguity, or when previous sentences are negated, among other challenges. For these cases a model that works with sequences is probably better suited than one that scores bags of words, because decisive nuances often can be captured from the word sequence as a whole (i.e., the text), but not observing the individual scrambled words alone.\n\nThe model chosen for the sentiment classification is a Recurrent Neural Network (RNN) based on Long Short-Term Memory (LSTM) units. These networks are particularly efficient at modeling long sequences of vectors. More information on the text pre-processing which is necessary and how these models work is provided in my repository [text_sentiment](https://github.com/mxagar/text_sentiment).\n\nHowever, it is worth noting that gradient boosting models (e.g., XGBoost) or tree-based models (e.g., random forests) often outperform neural networks with tabular data. One could consider a text vectorized as a bag of words to be a tabular data point. Also, consider the fact that the majority of the reviews have a straightforward style, thus, observing the valence/sentiment value of the words used in them should lead to enough information on the overall sentiment of the text.\n\nFinally, we should take into account that neural networks require larger corpora than the one used in this project in order to become really efficient.\n\nAll in all, the focus of this project lies more on the techniques used for deployment on AWS SageMaker rather than defining an efficient model.\n\n## Preliminary Results\n\nThe model seems to work nicely with easy reviews where no irony or meaning changes are conveyed. In contrast, when those properties are introduced, it starts to fail. However, note that **the focus of the project lies on the AWS deployment**, rather than on the efficiency of the network.\n\nSome examples:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./src/website/review_3.png\" alt=\"Example review.\" width=500px\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./src/website/review_4.png\" alt=\"Example review.\" width=500px\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./src/website/review_1.png\" alt=\"Example review.\" width=500px\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./src/website/review_2.png\" alt=\"Example review.\" width=500px\u003e\n\u003c/p\u003e\n\n## Improvements, Next Steps\n\n- [ ] Improve the html web app.\n- [ ] Improve the model: try more layers; train longer; get a bigger dataset.\n- [ ] Test more thoroughly irony an sarcasm.\n- [ ] Use AWS SageMaker Studio instead of the notebook instances.\n- [ ] Upgrade the required SageMaker version (to V2).\n\n## Interesting Links\n\n- [My notes and code](https://github.com/mxagar/deep_learning_udacity) on the [Udacity Deep Learning Nanodegree](https://www.udacity.com/course/deep-learning-nanodegree--nd101). A more detailed guide on AWS SageMaker can be found in the file [`DLND_Deployment.md`](https://github.com/mxagar/deep_learning_udacity/blob/main/06_Deployment/DLND_Deployment.md) from that repository.\n- Tutorial on how to use AWS SageMaker: [sagemaker-deployment](https://github.com/mxagar/sagemaker-deployment).\n- My on-going compilation of resources for [text sentiment analysis](https://github.com/mxagar/text_sentiment), with related text pre-processing and model explanations.\n- More examples with RNNs using Pytorch: [Pytorch Guide](https://github.com/mxagar/deep_learning_udacity/blob/main/02_Pytorch_Guide/DL_Pytorch_Guide.md) (Section \"Recursive Neural Networks\").\n- My [NLP Guide](https://github.com/mxagar/nlp_guide).\n- [Understanding LSTM Networks, by Chris Olah](http://colah.github.io/posts/2015-08-Understanding-LSTMs/)\n- [Exploring LSTMs, by Edwin Chen](http://blog.echen.me/2017/05/30/exploring-lstms/)\n- [Karpathy's Lecture: Recurrent Neural Networks, Image Captioning, LSTM](https://www.youtube.com/watch?v=iX5V1WpxxkY)\n- [Using Docker containers with SageMaker](https://docs.aws.amazon.com/sagemaker/latest/dg/docker-containers.html).\n\n\n## Authorship\n\nMikel Sagardia, 2022.  \nNo guarantees.\n\nYou are free to use this project, but please link it back to the original source.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmxagar%2Fsentiment_rnn_aws_deployment","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmxagar%2Fsentiment_rnn_aws_deployment","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmxagar%2Fsentiment_rnn_aws_deployment/lists"}