├── screenshots ├── s3.png ├── task.png ├── dynamodb.png ├── insights.png └── cloudwatchlogs.png ├── serving ├── build-image.sh ├── run-container.sh ├── Dockerfile └── serve.py ├── serve ├── test.sh ├── variables.tf ├── app.json └── main.tf ├── training ├── build-image.sh ├── run-container.sh ├── install-nvidia-runtime.sh ├── Dockerfile └── train.py ├── dynamodb.tf ├── scripts └── get-ecs-ami.sh ├── queue-training.sh ├── lambda-handler ├── src │ ├── test │ │ ├── resources │ │ │ └── log4j2.xml │ │ └── java │ │ │ └── example │ │ │ └── HandlerTest.java │ └── main │ │ └── java │ │ └── example │ │ ├── model │ │ ├── ModelTrainingRequest.java │ │ └── Model.java │ │ └── Handler.java └── pom.xml ├── resources.tf ├── main.tf ├── cloudwatch.tf ├── variables.tf ├── outputs.tf ├── lambda.tf ├── ecs.tf ├── .gitignore ├── README.md └── LICENSE /screenshots/s3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jzonthemtn/hashitalks2021-terraform-nlp/HEAD/screenshots/s3.png -------------------------------------------------------------------------------- /screenshots/task.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jzonthemtn/hashitalks2021-terraform-nlp/HEAD/screenshots/task.png -------------------------------------------------------------------------------- /screenshots/dynamodb.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jzonthemtn/hashitalks2021-terraform-nlp/HEAD/screenshots/dynamodb.png -------------------------------------------------------------------------------- /screenshots/insights.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jzonthemtn/hashitalks2021-terraform-nlp/HEAD/screenshots/insights.png -------------------------------------------------------------------------------- /screenshots/cloudwatchlogs.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jzonthemtn/hashitalks2021-terraform-nlp/HEAD/screenshots/cloudwatchlogs.png -------------------------------------------------------------------------------- /serving/build-image.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | set -e 3 | 4 | GIT_COMMIT=`git rev-parse --short HEAD` 5 | 6 | docker build --label gitcommit="$GIT_COMMIT" -t $DOCKERHUB_USERNAME/ner-serving:latest . 7 | -------------------------------------------------------------------------------- /serve/test.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | HOSTNAME=${1:-localhost:8080} 3 | curl -vvvv -X POST http://$HOSTNAME/ner --data "George Washington was president of the United States." -H "Content-type: text/plain" 4 | -------------------------------------------------------------------------------- /training/build-image.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | set -e 3 | 4 | GIT_COMMIT=`git rev-parse --short HEAD` 5 | FLAIR_VERSION="0.7" 6 | 7 | docker build --build-arg FLAIR_VERSION=$FLAIR_VERSION --label gitcommit="$GIT_COMMIT" -t $DOCKERHUB_USERNAME/ner-training:latest . 8 | -------------------------------------------------------------------------------- /dynamodb.tf: -------------------------------------------------------------------------------- 1 | resource "aws_dynamodb_table" "models_dynamodb_table" { 2 | name = "${var.name_prefix}-models" 3 | billing_mode = "PAY_PER_REQUEST" 4 | hash_key = "modelId" 5 | 6 | attribute { 7 | name = "modelId" 8 | type = "S" 9 | } 10 | 11 | } 12 | -------------------------------------------------------------------------------- /scripts/get-ecs-ami.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | # Amazon Linux 2 4 | aws ssm get-parameters --names /aws/service/ecs/optimized-ami/amazon-linux-2/recommended 5 | 6 | # Amazon Linux 2 (GPU) 7 | aws ssm get-parameters --names /aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended 8 | -------------------------------------------------------------------------------- /serve/variables.tf: -------------------------------------------------------------------------------- 1 | variable "region" { 2 | default = "us-east-1" 3 | } 4 | 5 | variable "name_prefix" { 6 | default = "nlp-ner" 7 | } 8 | 9 | variable "model_key" { 10 | default = "my-model" 11 | } 12 | 13 | variable "desired_count" { 14 | description = "desired number of tasks to run" 15 | default = "1" 16 | } 17 | -------------------------------------------------------------------------------- /serving/run-container.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | VERSION=${1:-latest} 4 | S3_BUCKET=${2:-my-bucket} 5 | 6 | docker run \ 7 | --env "AWS_ACCESS_KEY_ID=***" \ 8 | --env "AWS_SECRET_ACCESS_KEY=***" \ 9 | --env "AWS_DEFAULT_REGION=us-east-1" \ 10 | --env "MODEL_BUCKET=$S3_BUCKET" \ 11 | -p 8080:8080 \ 12 | -it \ 13 | --rm \ 14 | $DOCKERHUB_USERNAME/ner-serving:$VERSION 15 | -------------------------------------------------------------------------------- /queue-training.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | set -e 3 | 4 | QUEUE_URL=`terraform output -raw queue_url` 5 | MODEL_NAME=${1:-"my-model"} 6 | 7 | echo "Publishing message to SQS queue $QUEUE_URL" 8 | aws sqs send-message \ 9 | --queue-url $QUEUE_URL \ 10 | --message-body "{\"name\": \"$MODEL_NAME\", \"image\": \"$DOCKERHUB_USERNAME/ner-training:latest\", \"embeddings\": \"distilbert-base-cased\"}" 11 | -------------------------------------------------------------------------------- /lambda-handler/src/test/resources/log4j2.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | -------------------------------------------------------------------------------- /training/run-container.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | set -e 3 | 4 | CONTAINER_VERSION=${1:-"latest"} 5 | MODEL_NAME_VERSION=${2:-"test-0.1"} 6 | EPOCHS=${3:-"1"} 7 | S3_BUCKET=`terraform output -raw s3_bucket` 8 | 9 | docker run \ 10 | --env "MODEL=$MODEL_NAME_VERSION" \ 11 | --env "EPOCHS=1" \ 12 | --env "EMBEDDINGS=distilbert-base-cased" \ 13 | --env "S3_BUCKET=$S3_BUCKET" \ 14 | --rm \ 15 | $DOCKERHUB_USERNAME/ner-training:$CONTAINER_VERSION 16 | 17 | # --runtime=nvidia \ 18 | -------------------------------------------------------------------------------- /training/install-nvidia-runtime.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | # This script needs executed on the host. 4 | # The ndivia runtime will then be available to the containers. 5 | 6 | distribution=$(. /etc/os-release;echo $ID$VERSION_ID) 7 | curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add - 8 | curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list 9 | 10 | sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit 11 | sudo systemctl restart docker 12 | -------------------------------------------------------------------------------- /serve/app.json: -------------------------------------------------------------------------------- 1 | [{ 2 | "essential": true, 3 | "image": "jzemerick/ner-serving:latest", 4 | "memory": 4096, 5 | "memoryReservation": 4096, 6 | "name": "${name}", 7 | "portMappings": [{ 8 | "containerPort": 8080, 9 | "hostPort": 0 10 | }], 11 | "logConfiguration": { 12 | "logDriver": "awslogs", 13 | "options": { 14 | "awslogs-group": "${log_group}", 15 | "awslogs-region": "us-east-1", 16 | "awslogs-stream-prefix": "my-model/final-model.pt" 17 | } 18 | }, 19 | "environment": [{ 20 | "name": "MODEL_BUCKET", 21 | "value": "${bucket}" 22 | }, 23 | { 24 | "name": "MODEL_KEY", 25 | "value": "${key}" 26 | } 27 | ] 28 | }] 29 | -------------------------------------------------------------------------------- /serving/Dockerfile: -------------------------------------------------------------------------------- 1 | # The version of the base container must 2 | # match the driver installed on the local system. 3 | # Download the driver from: https://developer.nvidia.com/cuda-downloads 4 | 5 | FROM nvidia/cuda:11.1-devel-ubi8 6 | 7 | RUN yum upgrade -y \ 8 | && yum install -y python38 \ 9 | && yum install -y python38-devel 10 | 11 | # Note: These RUN lines could be combined into a single RUN command to reduce layers 12 | RUN python3.8 -m pip install wheel flair==0.7 awscli 13 | RUN python3.8 -m pip install nltk textblob cherrypy awscli boto3 14 | RUN python3.8 -c "import nltk; nltk.download('punkt')" 15 | RUN python3.8 -m pip freeze 16 | RUN python3.8 --version 17 | 18 | COPY serve.py /tmp/serve.py 19 | 20 | ENV MODEL_BUCKET="" 21 | ENV MODEL_KEY="" 22 | 23 | EXPOSE 8080 24 | 25 | CMD python3.8 /tmp/serve.py --b ${MODEL_BUCKET} --k ${MODEL_KEY} 26 | -------------------------------------------------------------------------------- /lambda-handler/src/main/java/example/model/ModelTrainingRequest.java: -------------------------------------------------------------------------------- 1 | package example.model; 2 | 3 | public class ModelTrainingRequest { 4 | 5 | private String name; 6 | private int epochs = 1; 7 | private String embeddings; 8 | private String image; 9 | 10 | public String getName() { 11 | return name; 12 | } 13 | 14 | public void setName(String name) { 15 | this.name = name; 16 | } 17 | 18 | public int getEpochs() { 19 | return epochs; 20 | } 21 | 22 | public void setEpochs(int epochs) { 23 | this.epochs = epochs; 24 | } 25 | 26 | public String getEmbeddings() { 27 | return embeddings; 28 | } 29 | 30 | public void setEmbeddings(String embeddings) { 31 | this.embeddings = embeddings; 32 | } 33 | 34 | public String getImage() { 35 | return image; 36 | } 37 | 38 | public void setImage(String image) { 39 | this.image = image; 40 | } 41 | } 42 | -------------------------------------------------------------------------------- /resources.tf: -------------------------------------------------------------------------------- 1 | resource "aws_sqs_queue" "queue" { 2 | name = "${var.name_prefix}-queue" 3 | delay_seconds = 10 4 | max_message_size = 2048 5 | message_retention_seconds = 1209600 6 | receive_wait_time_seconds = 10 7 | visibility_timeout_seconds = 60 8 | } 9 | 10 | resource "aws_s3_bucket" "bucket" { 11 | acl = "private" 12 | force_destroy = true 13 | } 14 | 15 | # Upload a sample model to S3 to illustrate serving without having to 16 | # spend time training a model. 17 | 18 | #resource "aws_s3_bucket_object" "object-model" { 19 | # bucket = aws_s3_bucket.bucket.id 20 | # key = "models/my-model/final-model.pt" 21 | # source = "my-model/final-model.pt" 22 | # etag = filemd5("my-model/final-model.pt") 23 | #} 24 | 25 | #resource "aws_s3_bucket_object" "object-weights" { 26 | # bucket = aws_s3_bucket.bucket.id 27 | # key = "models/my-model/weights.txt" 28 | # source = "my-model/weights.txt" 29 | # etag = filemd5("my-model/weights.txt") 30 | #} 31 | -------------------------------------------------------------------------------- /main.tf: -------------------------------------------------------------------------------- 1 | terraform { 2 | required_providers { 3 | aws = { 4 | source = "hashicorp/aws" 5 | version = "~> 3.0" 6 | } 7 | } 8 | } 9 | 10 | provider "aws" { 11 | region = var.region 12 | } 13 | 14 | resource "aws_vpc" "ml_vpc" { 15 | cidr_block = var.vpc_cidr_block 16 | enable_dns_hostnames = true 17 | tags = { 18 | Name = "${var.name_prefix}-vpc" 19 | } 20 | } 21 | 22 | resource "aws_subnet" "ml_vpc_subnet" { 23 | vpc_id = aws_vpc.ml_vpc.id 24 | cidr_block = var.subnet_1_cidr_block 25 | map_public_ip_on_launch = true 26 | availability_zone = var.availability_zone_1 27 | tags = { 28 | Name = "${var.name_prefix}-subnet-1" 29 | } 30 | } 31 | 32 | resource "aws_subnet" "ml_vpc_subnet_2" { 33 | vpc_id = aws_vpc.ml_vpc.id 34 | cidr_block = var.subnet_2_cidr_block 35 | map_public_ip_on_launch = true 36 | availability_zone = var.availability_zone_2 37 | tags = { 38 | Name = "${var.name_prefix}-subnet-2" 39 | } 40 | } 41 | -------------------------------------------------------------------------------- /training/Dockerfile: -------------------------------------------------------------------------------- 1 | # The version of the base container must 2 | # match the driver installed on the local system. 3 | # Download the driver from: https://developer.nvidia.com/cuda-downloads 4 | 5 | FROM nvidia/cuda:11.1-devel-ubi8 6 | 7 | ARG FLAIR_VERSION 8 | 9 | LABEL flair="${FLAIR_VERSION}" 10 | LABEL python="3.8" 11 | 12 | RUN yum upgrade -y \ 13 | && yum install -y python38 \ 14 | && yum install -y python38-devel 15 | 16 | # Note: These RUN lines could be combined into a single RUN command to reduce layers 17 | RUN python3.8 -m pip install --upgrade pip 18 | RUN python3.8 -m pip install --upgrade setuptools wheel 19 | RUN python3.8 -m pip install flair==${FLAIR_VERSION} 20 | RUN python3.8 -m pip install awscli boto3 21 | RUN python3.8 -m pip freeze 22 | RUN python3.8 --version 23 | 24 | ENV MODEL="ner-model" 25 | ENV EPOCHS="20" 26 | ENV EMBEDDINGS="distilbert-base-cased" 27 | ENV S3_BUCKET="my-models" 28 | ENV MODEL_ID="" 29 | ENV REGION="us-east-1" 30 | ENV TABLE_NAME="" 31 | 32 | COPY train.py /tmp/train.py 33 | 34 | CMD python3.8 /tmp/train.py --m ${MODEL} --e ${EPOCHS} --v ${EMBEDDINGS} --i ${MODEL_ID} --r ${REGION} --t ${TABLE_NAME} && aws s3 sync /tmp/$MODEL/ s3://${S3_BUCKET}/$MODEL/ 35 | -------------------------------------------------------------------------------- /lambda-handler/src/test/java/example/HandlerTest.java: -------------------------------------------------------------------------------- 1 | package example; 2 | 3 | import com.amazonaws.services.lambda.runtime.Context; 4 | import com.amazonaws.services.lambda.runtime.LambdaLogger; 5 | import com.amazonaws.services.lambda.runtime.events.ScheduledEvent; 6 | import org.junit.Test; 7 | import org.mockito.Mockito; 8 | import org.slf4j.Logger; 9 | import org.slf4j.LoggerFactory; 10 | 11 | import static org.mockito.Mockito.when; 12 | 13 | public class HandlerTest { 14 | 15 | @Test 16 | public void invokeTest() { 17 | 18 | final ScheduledEvent event = Mockito.mock(ScheduledEvent.class); 19 | 20 | final Context context = Mockito.mock(Context.class); 21 | when(context.getLogger()).thenReturn(new MockLogger()); 22 | 23 | final Handler handler = new Handler(); 24 | handler.handleRequest(event, context); 25 | 26 | } 27 | 28 | public static class MockLogger implements LambdaLogger { 29 | 30 | private static final Logger LOGGER = LoggerFactory.getLogger(MockLogger.class); 31 | 32 | @Override 33 | public void log(String message) { 34 | LOGGER.info(message); 35 | } 36 | 37 | @Override 38 | public void log(byte[] message) { 39 | LOGGER.info(new String(message)); 40 | } 41 | 42 | } 43 | 44 | } 45 | -------------------------------------------------------------------------------- /cloudwatch.tf: -------------------------------------------------------------------------------- 1 | resource "aws_cloudwatch_log_group" "log_group" { 2 | name = "/aws/lambda/java_lambda_function" 3 | } 4 | 5 | resource "aws_cloudwatch_log_group" "nlp-training" { 6 | name = "nlp-training" 7 | } 8 | 9 | data "aws_iam_policy_document" "cloudwatch_log_group_access_document" { 10 | statement { 11 | actions = [ 12 | "logs:CreateLogGroup", 13 | "logs:CreateLogStream", 14 | "logs:PutLogEvents" 15 | ] 16 | 17 | resources = [ 18 | "arn:aws:logs:::*", 19 | ] 20 | } 21 | } 22 | 23 | resource "aws_cloudwatch_event_rule" "every_one_minute" { 24 | name = "consume-nlp-training-queue" 25 | description = "Fires every one minutes" 26 | schedule_expression = "rate(1 minute)" 27 | } 28 | 29 | resource "aws_cloudwatch_event_target" "run_lambda_every_one_minute" { 30 | rule = aws_cloudwatch_event_rule.every_one_minute.name 31 | target_id = "lambda" 32 | arn = aws_lambda_function.aws_lambda_test.arn 33 | } 34 | 35 | resource "aws_lambda_permission" "allow_cloudwatch_to_call_lambda" { 36 | statement_id = "AllowExecutionFromCloudWatch" 37 | action = "lambda:InvokeFunction" 38 | function_name = aws_lambda_function.aws_lambda_test.function_name 39 | principal = "events.amazonaws.com" 40 | source_arn = aws_cloudwatch_event_rule.every_one_minute.arn 41 | } 42 | -------------------------------------------------------------------------------- /variables.tf: -------------------------------------------------------------------------------- 1 | variable "name_prefix" { 2 | default = "nlp-ner" 3 | } 4 | 5 | variable "region" { 6 | default = "us-east-1" 7 | } 8 | 9 | variable "availability_zone_1" { 10 | default = "us-east-1a" 11 | } 12 | 13 | variable "availability_zone_2" { 14 | default = "us-east-1b" 15 | } 16 | 17 | variable "vpc_cidr_block" { 18 | default = "10.0.0.0/16" 19 | } 20 | 21 | variable "subnet_1_cidr_block" { 22 | default = "10.0.1.0/24" 23 | } 24 | 25 | variable "subnet_2_cidr_block" { 26 | default = "10.0.2.0/24" 27 | } 28 | 29 | variable "destination_cidr_block" { 30 | default = "0.0.0.0/0" 31 | } 32 | 33 | variable "ingress_cidr_block" { 34 | type = list(any) 35 | default = ["0.0.0.0/0"] 36 | } 37 | 38 | variable "ec2_instance_type" { 39 | description = "ECS cluster instance type" 40 | default = "t3.large" 41 | } 42 | 43 | variable "max_cluster_size" { 44 | description = "Maximum number of instances in the cluster" 45 | default = 1 46 | } 47 | 48 | variable "min_cluster_size" { 49 | description = "Minimum number of instances in the cluster" 50 | default = 1 51 | } 52 | 53 | variable "desired_capacity" { 54 | description = "Desired number of instances in the cluster" 55 | default = 1 56 | } 57 | 58 | variable "lambda_payload_filename" { 59 | default = "lambda-handler/target/java-events-1.0-SNAPSHOT.jar" 60 | } 61 | -------------------------------------------------------------------------------- /lambda-handler/src/main/java/example/model/Model.java: -------------------------------------------------------------------------------- 1 | package example.model; 2 | 3 | public class Model { 4 | 5 | private String modelID; 6 | private String image; 7 | private String progress; 8 | private String serviceArn; 9 | private String serviceName; 10 | private long startTime; 11 | 12 | public String getModelID() { 13 | return modelID; 14 | } 15 | 16 | public void setModelID(String modelID) { 17 | this.modelID = modelID; 18 | } 19 | 20 | public String getImage() { 21 | return image; 22 | } 23 | 24 | public void setImage(String image) { 25 | this.image = image; 26 | } 27 | 28 | public String getProgress() { 29 | return progress; 30 | } 31 | 32 | public void setProgress(String progress) { 33 | this.progress = progress; 34 | } 35 | 36 | public String getServiceArn() { 37 | return serviceArn; 38 | } 39 | 40 | public void setServiceArn(String serviceArn) { 41 | this.serviceArn = serviceArn; 42 | } 43 | 44 | public String getServiceName() { 45 | return serviceName; 46 | } 47 | 48 | public void setServiceName(String serviceName) { 49 | this.serviceName = serviceName; 50 | } 51 | 52 | public long getStartTime() { 53 | return startTime; 54 | } 55 | 56 | public void setStartTime(long startTime) { 57 | this.startTime = startTime; 58 | } 59 | 60 | } 61 | -------------------------------------------------------------------------------- /outputs.tf: -------------------------------------------------------------------------------- 1 | output "queue_url" { 2 | value = aws_sqs_queue.queue.id 3 | } 4 | 5 | output "s3_bucket" { 6 | value = aws_s3_bucket.bucket.id 7 | } 8 | 9 | output "ml_vpc_subnet_id" { 10 | value = aws_subnet.ml_vpc_subnet.id 11 | } 12 | 13 | resource "aws_ssm_parameter" "param_subnet1" { 14 | name = "${var.name_prefix}-subnet1" 15 | type = "String" 16 | value = aws_subnet.ml_vpc_subnet.id 17 | } 18 | 19 | output "ml_vpc_subnet2_id" { 20 | value = aws_subnet.ml_vpc_subnet_2.id 21 | } 22 | 23 | resource "aws_ssm_parameter" "param_subnet2" { 24 | name = "${var.name_prefix}-subnet2" 25 | type = "String" 26 | value = aws_subnet.ml_vpc_subnet_2.id 27 | } 28 | 29 | output "ecs_cluster_name" { 30 | value = "${var.name_prefix}-ecs" 31 | } 32 | 33 | output "task_role_arn" { 34 | value = aws_iam_role.task_role.arn 35 | } 36 | 37 | resource "aws_ssm_parameter" "param_ecs_cluster_name" { 38 | name = "${var.name_prefix}-ecs-cluster-name" 39 | type = "String" 40 | value = "${var.name_prefix}-ecs" 41 | } 42 | 43 | resource "aws_ssm_parameter" "param_s3_bucket" { 44 | name = "${var.name_prefix}-s3-bucket" 45 | type = "String" 46 | value = aws_s3_bucket.bucket.id 47 | } 48 | 49 | resource "aws_ssm_parameter" "param_ecs_sg" { 50 | name = "${var.name_prefix}-ecs-sg" 51 | type = "String" 52 | value = aws_security_group.ecs_sg.id 53 | } 54 | 55 | resource "aws_ssm_parameter" "param_vpc" { 56 | name = "${var.name_prefix}-vpc" 57 | type = "String" 58 | value = aws_vpc.ml_vpc.id 59 | } 60 | -------------------------------------------------------------------------------- /serving/serve.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/python3 2 | 3 | import argparse 4 | from flair.models import SequenceTagger 5 | from flair.data import Sentence 6 | import cherrypy 7 | import json 8 | import boto3 9 | from textblob import TextBlob 10 | import os 11 | 12 | 13 | class Span: 14 | def __init__(self, text, tag, score, start, end): 15 | self.text = text 16 | self.tag = tag 17 | self.score = score 18 | self.start = start 19 | self.end = end 20 | 21 | 22 | def obj_dict(obj): 23 | return obj.__dict__ 24 | 25 | 26 | parser = argparse.ArgumentParser(description='Model Serving') 27 | parser.add_argument('--b', action="store", dest='bucket', default="") 28 | parser.add_argument('--k', action="store", dest='key', default=20) 29 | args = parser.parse_args() 30 | 31 | # Download the model. 32 | #s3 = boto3.resource('s3') 33 | #s3.Bucket(args.bucket).download_file(args.key, '/tmp/final-model.pt') 34 | 35 | print("Downloading model s3://" + args.bucket + "/" + args.key) 36 | s3 = boto3.client('s3') 37 | s3.download_file(args.bucket, args.key + '/final-model.pt', '/tmp/final-model.pt') 38 | print("Model downloaded.") 39 | 40 | model = SequenceTagger.load('/tmp/final-model.pt') 41 | 42 | class NerModelService(object): 43 | 44 | @cherrypy.expose 45 | def ner(self): 46 | 47 | input = cherrypy.request.body.read().decode('utf-8') 48 | 49 | sentences = [] 50 | 51 | blob = TextBlob(input) 52 | for s in blob.sentences: 53 | sentences.append(Sentence(s.raw)) 54 | 55 | model.predict(sentences) 56 | 57 | spans = [] 58 | index = 0 59 | 60 | for i in sentences: 61 | 62 | start_pos = blob.sentences[index].start_index 63 | 64 | for entity in i.get_spans('ner'): 65 | p1 = Span(entity.text, entity.tag, entity.score, (entity.start_pos + start_pos), 66 | (entity.end_pos + start_pos)) 67 | spans.append(p1) 68 | 69 | index = index + 1 70 | 71 | s = json.dumps(spans, default=obj_dict) 72 | 73 | return s 74 | 75 | @cherrypy.expose 76 | def health(self): 77 | return "healthy" 78 | 79 | 80 | if __name__ == '__main__': 81 | cherrypy.config.update({'server.socket_host': '0.0.0.0', 'server.socket_port': 8080}) 82 | cherrypy.quickstart(NerModelService()) 83 | -------------------------------------------------------------------------------- /training/train.py: -------------------------------------------------------------------------------- 1 | import argparse 2 | import os 3 | import sys 4 | import boto3 5 | from typing import List 6 | from pathlib import Path 7 | 8 | from flair.data import Corpus 9 | from flair.datasets import WIKINER_ENGLISH 10 | from flair.embeddings import BertEmbeddings, TokenEmbeddings, StackedEmbeddings, TransformerWordEmbeddings 11 | from flair.models import SequenceTagger 12 | from flair.trainers import ModelTrainer 13 | 14 | parser = argparse.ArgumentParser(description='Model Training') 15 | parser.add_argument('--m', action="store", dest='model', default="") 16 | parser.add_argument('--e', action="store", dest='epochs', default=20) 17 | parser.add_argument('--v', action="store", dest='embeddings', default="distilbert-base-cased") 18 | parser.add_argument('--i', action="store", dest='model_id', default="") 19 | parser.add_argument('--r', action="store", dest='region', default="us-east-1") 20 | parser.add_argument('--t', action="store", dest='table', default="") 21 | parser.add_argument('--c', action="store", dest='cluster', default="") 22 | parser.add_argument('--s', action="store", dest='service', default="") 23 | 24 | args = parser.parse_args() 25 | 26 | corpus: Corpus = WIKINER_ENGLISH().downsample(0.1) 27 | 28 | dynamodb = boto3.resource('dynamodb', region_name=args.region) 29 | 30 | table = dynamodb.Table(args.table) 31 | table.update_item( 32 | Key={ 33 | 'modelId': args.model_id 34 | }, 35 | UpdateExpression="set progress=:s", 36 | ExpressionAttributeValues={ 37 | ':s': 'In Progress' 38 | } 39 | ) 40 | 41 | 42 | tag_type = 'ner' 43 | tag_dictionary = corpus.make_tag_dictionary(tag_type=tag_type) 44 | embeddings = TransformerWordEmbeddings(model=args.embeddings) 45 | 46 | tagger: SequenceTagger = SequenceTagger(hidden_size=256, 47 | embeddings=embeddings, 48 | tag_dictionary=tag_dictionary, 49 | tag_type=tag_type, 50 | use_crf=True) 51 | 52 | trainer: ModelTrainer = ModelTrainer(tagger, corpus, use_tensorboard=True) 53 | 54 | os.mkdir('/tmp/' + args.model) 55 | print('Saving model to ' + '/tmp/' + args.model) 56 | 57 | trainer.train('/tmp/' + args.model, 58 | learning_rate=0.1, 59 | mini_batch_size=32, 60 | max_epochs=int(args.epochs), 61 | num_workers=12, 62 | checkpoint=True, 63 | save_final_model=True, 64 | shuffle=True, 65 | embeddings_storage_mode='cpu') 66 | 67 | 68 | table.update_item( 69 | Key={ 70 | 'modelId': args.model_id 71 | }, 72 | UpdateExpression="set progress=:s", 73 | ExpressionAttributeValues={ 74 | ':s': 'Completed' 75 | } 76 | ) 77 | -------------------------------------------------------------------------------- /lambda.tf: -------------------------------------------------------------------------------- 1 | resource "aws_lambda_function" "aws_lambda_test" { 2 | runtime = "java11" 3 | filename = var.lambda_payload_filename 4 | source_code_hash = filebase64sha256(var.lambda_payload_filename) 5 | function_name = "${var.name_prefix}-consumer-function" 6 | handler = "example.Handler" 7 | timeout = 60 8 | memory_size = 256 9 | role = aws_iam_role.iam_role_for_lambda.arn 10 | environment { 11 | variables = { 12 | s3_bucket = aws_s3_bucket.bucket.id 13 | aws_logs_group = aws_cloudwatch_log_group.nlp-training.name 14 | queue_url = aws_sqs_queue.queue.id 15 | ecs_cluster_name = "${var.name_prefix}-ecs" 16 | region = var.region 17 | max_tasks = "1" 18 | debug = "false" 19 | table_name = aws_dynamodb_table.models_dynamodb_table.id 20 | task_role_arn = aws_iam_role.task_role.arn 21 | } 22 | } 23 | } 24 | 25 | resource "aws_iam_role" "iam_role_for_lambda" { 26 | name = "${var.name_prefix}-lambda-invoke-role" 27 | assume_role_policy = < 3 | 4.0.0 4 | com.example 5 | java-events 6 | jar 7 | 1.0-SNAPSHOT 8 | java-events-function 9 | 10 | UTF-8 11 | 1.11.949 12 | 13 | 14 | 15 | 16 | maven-surefire-plugin 17 | 2.22.2 18 | 19 | 20 | org.apache.maven.plugins 21 | maven-shade-plugin 22 | 3.2.2 23 | 24 | false 25 | 26 | 27 | 28 | package 29 | 30 | shade 31 | 32 | 33 | 34 | 35 | 36 | org.apache.maven.plugins 37 | maven-compiler-plugin 38 | 3.8.0 39 | 40 | 11 41 | 42 | 43 | 44 | 45 | 46 | 47 | com.amazonaws 48 | aws-java-sdk-sqs 49 | ${aws.sdk.version} 50 | 51 | 52 | com.amazonaws 53 | aws-java-sdk-ecs 54 | ${aws.sdk.version} 55 | 56 | 57 | com.amazonaws 58 | aws-java-sdk-dynamodb 59 | ${aws.sdk.version} 60 | 61 | 62 | com.amazonaws 63 | aws-lambda-java-core 64 | 1.2.1 65 | 66 | 67 | com.amazonaws 68 | aws-lambda-java-events 69 | 2.2.9 70 | 71 | 72 | com.google.code.gson 73 | gson 74 | 2.8.9 75 | 76 | 77 | org.apache.commons 78 | commons-lang3 79 | 3.11 80 | 81 | 82 | org.apache.logging.log4j 83 | log4j-api 84 | 2.17.1 85 | 86 | 87 | org.apache.logging.log4j 88 | log4j-core 89 | 2.17.1 90 | 91 | 92 | org.apache.logging.log4j 93 | log4j-slf4j18-impl 94 | 2.13.0 95 | 96 | 97 | org.mockito 98 | mockito-all 99 | 1.10.19 100 | test 101 | 102 | 103 | junit 104 | junit 105 | 4.13.1 106 | test 107 | 108 | 109 | 110 | -------------------------------------------------------------------------------- /serve/main.tf: -------------------------------------------------------------------------------- 1 | terraform { 2 | required_providers { 3 | aws = { 4 | source = "hashicorp/aws" 5 | version = "~> 3.0" 6 | } 7 | } 8 | } 9 | 10 | provider "aws" { 11 | region = var.region 12 | } 13 | 14 | data "aws_ssm_parameter" "cluster" { 15 | name = "${var.name_prefix}-ecs-cluster-name" 16 | } 17 | 18 | data "aws_ssm_parameter" "bucket_name" { 19 | name = "${var.name_prefix}-s3-bucket" 20 | } 21 | 22 | data "aws_ssm_parameter" "subnet1" { 23 | name = "${var.name_prefix}-subnet1" 24 | } 25 | 26 | data "aws_ssm_parameter" "subnet2" { 27 | name = "${var.name_prefix}-subnet2" 28 | } 29 | 30 | data "aws_ssm_parameter" "vpc" { 31 | name = "${var.name_prefix}-vpc" 32 | } 33 | 34 | resource "aws_ecs_service" "service" { 35 | name = "${var.name_prefix}-${var.model_key}-serving" 36 | cluster = data.aws_ssm_parameter.cluster.value 37 | desired_count = var.desired_count 38 | task_definition = aws_ecs_task_definition.app.arn 39 | scheduling_strategy = "REPLICA" 40 | 41 | # 50 percent must be healthy during deploys 42 | deployment_minimum_healthy_percent = 50 43 | deployment_maximum_percent = 100 44 | 45 | load_balancer { 46 | target_group_arn = aws_alb_target_group.target_group.arn 47 | container_name = "${var.name_prefix}-${var.model_key}-serving" 48 | container_port = 8080 49 | } 50 | } 51 | 52 | data "template_file" "task_definition" { 53 | template = file("${path.module}/app.json") 54 | 55 | vars = { 56 | bucket = data.aws_ssm_parameter.bucket_name.value 57 | key = var.model_key 58 | name = "${var.name_prefix}-${var.model_key}-serving" 59 | log_group = "${var.name_prefix}-${var.model_key}-serving" 60 | } 61 | } 62 | 63 | resource "aws_ecs_task_definition" "app" { 64 | family = "${var.name_prefix}-${var.model_key}-serving" 65 | container_definitions = data.template_file.task_definition.rendered 66 | task_role_arn = aws_iam_role.task_role.arn 67 | } 68 | 69 | resource "aws_cloudwatch_log_group" "nlp-serving" { 70 | name = "${var.name_prefix}-${var.model_key}-serving" 71 | } 72 | 73 | resource "aws_iam_role_policy_attachment" "test-attach" { 74 | role = aws_iam_role.task_role.name 75 | policy_arn = aws_iam_policy.task_policy.arn 76 | } 77 | 78 | resource "aws_iam_role" "task_role" { 79 | name = "${var.name_prefix}-serving-task-role" 80 | 81 | assume_role_policy = < **Note: this project will create resources outside the AWS free tier. You are responsible for all associated costs/charges.** 25 | 26 | ### Building the Containers 27 | 28 | This project uses Docker containers for model training and serving. One container is used for training an NLP NER model and another container is used to serve a model via a simple REST API. Refer to each container's Dockerfile for details on the training and serving. The NLP is handled by [Flair](https://github.com/flairNLP/flair). 29 | 30 | **Important First Steps** 31 | 32 | * You will need a DockerHub account. 33 | * You will need to log the Docker CLI into your account `docker login` 34 | * Export your DockerHub username to the shell you'll be using `export DOCKERHUB_USERNAME=` 35 | 36 | Now you can build and push the NLP NER training container: 37 | 38 | ``` 39 | cd training 40 | ./build-image.sh 41 | docker push $DOCKERHUB_USERNAME/ner-training:latest 42 | ``` 43 | 44 | Now build and push the serving container: 45 | 46 | ``` 47 | cd serving 48 | ./build-image.sh 49 | docker push $DOCKERHUB_USERNAME/ner-serving:latest 50 | ``` 51 | 52 | ### Building the Lambda Function 53 | 54 | The Lambda function is implemented in Java. The Lambda function controls the creation of ECS tasks. 55 | 56 | To build the Lambda function, run `build.sh` or the command: 57 | 58 | ``` 59 | mvn clean package -f ./lambda-handler/pom.xml -DskipTests=true 60 | ``` 61 | 62 | ### Creating the infrastructure using Terraform 63 | 64 | With the Docker images built and pushed we can now create the infrastructure using Terraform. In `variables.tf` there is a `name_prefix` variable that you can set in order to instantiate multiple copies of the infrastructure. 65 | 66 | ``` 67 | terraform init 68 | terraform apply 69 | ``` 70 | 71 | This step creates: 72 | 73 | * An SQS queue that holds the model training definitions (the models we want to train). 74 | * An ECS cluster on which the model training and model serving containers will be run. 75 | * An EventsBridge rule to trigger the Lambda function. 76 | * A Lambda function that consumes from the SQS queue and initiates model training by creating the ECS service and task. 77 | * An S3 bucket that will contain the trained models and their associated files. 78 | * A DynamoDB table that will contain metadata about the models. 79 | 80 | To delete the resources and clean up run `terraform destroy`. 81 | 82 | #### Lambda Function 83 | 84 | The Lambda function is deployed via Terraform. It is a Java 11 function that is triggered by an Amazon EventBridge (CloudWatch Events) Rule. The function consumes messages from the SQS queue. The function is parameterized through environment variables set by the terraform script. 85 | 86 | ### Training a Model 87 | 88 | To train a model, publish a message to the SQS queue. Using the `queue-training.sh` scripts. Look at the contents of this script to change things such as the number of epochs and embeddings. The only required argument is the name of the model to train, shown below as `my-model`. 89 | 90 | `./queue-training.sh my-model` 91 | 92 | This publishes a message to the SQS queue which describes a desired model training. The Lambda function will be triggered by a Cloud Watch EventBridge (Events) rule. The function will consume the message(s) from the queue and launch a model training container on the ECS cluster if the cluster's number of running tasks is below a set threshold. The function will also insert a row into the DynamoDB table indicating the model's training is in progress. A `modelId` will be generated by the function that is the concatenation of the given model's name and a random UUID. 93 | 94 | When model training is complete, the model and its associated files will be uploaded to the S3 bucket by the container prior to exiting. The model's metadata in the DynamoDB table will be updated to reflect that training is complete. 95 | 96 | ### Serving a Model 97 | 98 | To serve a model, change to the `serve` directory. Edit `variables.tf` to set the name of the model to serve and then run `terraform init` and `terraform apply`. 99 | 100 | This will launch a service and task on the ECS cluster to serve the given given model. The model can then be used by referencing the output DNS name of the load balancer: 101 | 102 | ``` 103 | curl -X POST http://$ALB:8080/ner --data "George Washington was president of the United States." -H "Content-type: text/plain" 104 | ``` 105 | 106 | The response will be a JSON-encoded list of JSON entities (`George Washington` and `United States`) from the text. (The actual output will vary based on the model's training and input text.) 107 | 108 | > Note: if you receive a `503 Service Temporarily Unavailable` response, be patient and try again in a few moments. 109 | 110 | ## GPU 111 | 112 | For training and serving on a GPU: 113 | 114 | 1. Use a GPU-capable EC2 instance type for the ECS cluster. 115 | 1. Install the appropriate CUDA runtime on the EC2 instance(s). 116 | 117 | ## License 118 | 119 | This project is licensed under the Apache License, version 2.0. 120 | -------------------------------------------------------------------------------- /lambda-handler/src/main/java/example/Handler.java: -------------------------------------------------------------------------------- 1 | package example; 2 | 3 | import com.amazonaws.regions.Regions; 4 | import com.amazonaws.services.dynamodbv2.AmazonDynamoDB; 5 | import com.amazonaws.services.dynamodbv2.AmazonDynamoDBClientBuilder; 6 | import com.amazonaws.services.dynamodbv2.model.AttributeValue; 7 | import com.amazonaws.services.ecs.AmazonECS; 8 | import com.amazonaws.services.ecs.AmazonECSClientBuilder; 9 | import com.amazonaws.services.ecs.model.*; 10 | import com.amazonaws.services.lambda.runtime.Context; 11 | import com.amazonaws.services.lambda.runtime.LambdaLogger; 12 | import com.amazonaws.services.lambda.runtime.RequestHandler; 13 | import com.amazonaws.services.lambda.runtime.events.ScheduledEvent; 14 | import com.amazonaws.services.sqs.AmazonSQS; 15 | import com.amazonaws.services.sqs.AmazonSQSClientBuilder; 16 | import com.amazonaws.services.sqs.model.Message; 17 | import com.amazonaws.util.CollectionUtils; 18 | import com.google.gson.Gson; 19 | import com.google.gson.GsonBuilder; 20 | import example.model.ModelTrainingRequest; 21 | import org.apache.commons.lang3.StringUtils; 22 | 23 | import java.util.*; 24 | 25 | public class Handler implements RequestHandler { 26 | 27 | private final Gson gson = new GsonBuilder().setPrettyPrinting().create(); 28 | 29 | @Override 30 | public String handleRequest(ScheduledEvent event, Context context) { 31 | 32 | final LambdaLogger logger = context.getLogger(); 33 | 34 | final String ecsClusterName = System.getenv("ecs_cluster_name"); 35 | logger.log("Using ECS cluster " + ecsClusterName); 36 | 37 | final String queueUrl = System.getenv("queue_url"); 38 | logger.log("Using SQS queue " + queueUrl); 39 | 40 | final String region = System.getenv("region"); 41 | logger.log("Using region " + region); 42 | 43 | final String debug = System.getenv("debug"); 44 | logger.log("Using debug " + debug); 45 | 46 | final String tableName = System.getenv("table_name"); 47 | logger.log("Using table name " + tableName); 48 | 49 | final String taskRoleArn = System.getenv("task_role_arn"); 50 | logger.log("Using task role arn " + taskRoleArn); 51 | 52 | final AmazonECS ecs = AmazonECSClientBuilder.standard().withRegion(region).build(); 53 | final AmazonSQS sqs = AmazonSQSClientBuilder.standard().withRegion(region).build(); 54 | final AmazonDynamoDB ddb = AmazonDynamoDBClientBuilder.standard().withRegion(region).build(); 55 | 56 | final List messages = sqs.receiveMessage(queueUrl).getMessages(); 57 | 58 | if(messages.isEmpty()) { 59 | 60 | logger.log("No messages were consumed."); 61 | 62 | } else { 63 | 64 | for (final Message message : messages) { 65 | 66 | final ModelTrainingRequest modelTrainingRequest = gson.fromJson(message.getBody(), ModelTrainingRequest.class); 67 | final String modelId = modelTrainingRequest.getName() + "-" + UUID.randomUUID().toString(); 68 | 69 | logger.log("Received training request for model " + modelTrainingRequest.getName() + " (" + modelId + ")"); 70 | 71 | final ContainerDefinition containerDefinition = new ContainerDefinition(); 72 | containerDefinition.setName(modelTrainingRequest.getName()); 73 | containerDefinition.setMemoryReservation(1024); 74 | containerDefinition.setMemory(4096); 75 | containerDefinition.setImage(modelTrainingRequest.getImage()); 76 | 77 | final LogConfiguration logConfiguration = new LogConfiguration(); 78 | logConfiguration.setLogDriver("awslogs"); 79 | 80 | // See https://aws.amazon.com/blogs/compute/centralized-container-logs-with-amazon-ecs-and-amazon-cloudwatch-logs/ 81 | final Map options = new LinkedHashMap<>(); 82 | options.put("awslogs-group", System.getenv("aws_logs_group")); 83 | options.put("awslogs-region", Regions.US_EAST_1.getName()); 84 | options.put("awslogs-stream-prefix", modelId); 85 | logConfiguration.setOptions(options); 86 | containerDefinition.setLogConfiguration(logConfiguration); 87 | 88 | final String s3Bucket = System.getenv("s3_bucket"); 89 | logger.log("Using s3 bucket " + s3Bucket); 90 | 91 | final Collection environmentVariables = new LinkedList<>(); 92 | environmentVariables.add(new KeyValuePair().withName("MODEL").withValue(modelTrainingRequest.getName())); 93 | environmentVariables.add(new KeyValuePair().withName("MODEL_ID").withValue(modelId)); 94 | environmentVariables.add(new KeyValuePair().withName("EPOCHS").withValue(String.valueOf(modelTrainingRequest.getEpochs()))); 95 | environmentVariables.add(new KeyValuePair().withName("EMBEDDINGS").withValue(modelTrainingRequest.getEmbeddings())); 96 | environmentVariables.add(new KeyValuePair().withName("S3_BUCKET").withValue(s3Bucket)); 97 | environmentVariables.add(new KeyValuePair().withName("TABLE_NAME").withValue(tableName)); 98 | environmentVariables.add(new KeyValuePair().withName("REGION").withValue(region)); 99 | containerDefinition.setEnvironment(environmentVariables); 100 | 101 | final RegisterTaskDefinitionRequest registerTaskDefinitionRequest = new RegisterTaskDefinitionRequest(); 102 | registerTaskDefinitionRequest.setNetworkMode(NetworkMode.Host); 103 | registerTaskDefinitionRequest.setContainerDefinitions(Arrays.asList(containerDefinition)); 104 | registerTaskDefinitionRequest.setFamily(modelTrainingRequest.getName()); 105 | registerTaskDefinitionRequest.setTaskRoleArn(taskRoleArn); 106 | 107 | final RegisterTaskDefinitionResult registerTaskDefinitionResult = ecs.registerTaskDefinition(registerTaskDefinitionRequest); 108 | 109 | final RunTaskRequest runTaskRequest = new RunTaskRequest(); 110 | runTaskRequest.setCluster(ecsClusterName); 111 | runTaskRequest.setCount(1); 112 | runTaskRequest.setTaskDefinition(registerTaskDefinitionResult.getTaskDefinition().getTaskDefinitionArn()); 113 | runTaskRequest.setLaunchType("EC2"); 114 | 115 | logger.log("Running task for model " + modelId); 116 | final RunTaskResult runTaskResult = ecs.runTask(runTaskRequest); 117 | 118 | if(!CollectionUtils.isNullOrEmpty(runTaskResult.getTasks())) { 119 | 120 | final HashMap itemValues = new HashMap<>(); 121 | itemValues.put("modelId", new AttributeValue(modelId)); 122 | itemValues.put("image", new AttributeValue(modelTrainingRequest.getImage())); 123 | itemValues.put("startTime", new AttributeValue(String.valueOf(System.currentTimeMillis()))); 124 | itemValues.put("progress", new AttributeValue("Pending")); 125 | 126 | try { 127 | 128 | // Store in the table. 129 | ddb.putItem(tableName, itemValues); 130 | 131 | // Delete this message from the queue. 132 | sqs.deleteMessage(queueUrl, message.getReceiptHandle()); 133 | 134 | } catch (Exception ex) { 135 | 136 | System.err.println(ex.getMessage()); 137 | 138 | } 139 | 140 | } 141 | 142 | } 143 | 144 | if(StringUtils.equalsIgnoreCase(debug, "true")) { 145 | logger.log("ENVIRONMENT VARIABLES: " + gson.toJson(System.getenv())); 146 | logger.log("CONTEXT: " + gson.toJson(context)); 147 | logger.log("EVENT: " + gson.toJson(event)); 148 | logger.log("EVENT TYPE: " + event.getClass().toString()); 149 | } 150 | 151 | } 152 | 153 | return "done"; 154 | 155 | } 156 | 157 | } -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "[]" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright [yyyy] [name of copyright owner] 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | --------------------------------------------------------------------------------