Posts in category: Amazon AWS

We’re pleased to announce enhancements to recommendation filters in Amazon Personalize, which provide you greater control on recommendations your users receive by allowing you to exclude or include items to recommend based on criteria that you define. For example, when recommending products for your e-retail store, you can exclude unavailable items from recommendations. If you’re recommending videos to users, you can choose to only recommend premium content if the user is in a particular subscription tier. You typically address this by writing custom code to implement their business rules, but you can now save time and streamline your architectures by using recommendation filters in Amazon Personalize.

Based on over 20 years of personalization experience, Amazon Personalize enables you to improve customer engagement by powering personalized product and content recommendations and targeted marketing promotions. Amazon Personalize uses machine learning (ML) to create high-quality recommendations for your websites and applications. You can get started without any prior ML experience using simple APIs to easily build sophisticated personalization capabilities in just a few clicks. Amazon Personalize processes and examines your data, identifies what is meaningful, automatically picks the right ML algorithm, and trains and optimizes a custom model based on your data. All of your data is encrypted to be private and secure, and is only used to create recommendations for your users.

Setting up and using recommendation filters is simple, taking only a few minutes to define and deploy your custom business rules with a real-time campaign. You can use the Amazon Personalize console or API to create a filter with your business logic using the Amazon Personalize domain specific language (DSL). You can apply this filter while querying for real-time recommendations using the GetRecommendations or GetPersonalizedRanking API, or while generating recommendations in batch mode through a batch inference job.

This post walks you through setting up and using item and user metadata-based recommendation filters in Amazon Personalize.

Prerequisites

To define and apply filters, you first need to set up the following Amazon Personalize resources. For instructions on the Amazon Personalize console, see Getting Started (Console).

1. Create a dataset group.
2. Create an Interactions dataset using the following schema and import data using the interactions-100k.csv data file:

   {
   	"type": "record",
   	"name": "Interactions",
   	"namespace": "com.amazonaws.personalize.schema",
   	"fields": [
   		{
   			"name": "USER_ID",
   			"type": "string"
   		},
   		{
   			"name": "ITEM_ID",
   			"type": "string"
   		},
   		{
   			"name": "EVENT_VALUE",
   			"type": [
   				"null",
   				"float"
   			]
   		},
   		{
   			"name": "TIMESTAMP",
   			"type": "long"
   		},
   		{
   			"name": "EVENT_TYPE",
   			"type": "string"
   		}
   	],
   	"version": "1.0"
   }
   

3. Create an Items dataset using the following schema and import data using the csv data file:

   {
   	"type": "record",
   	"name": "Items",
   	"namespace": "com.amazonaws.personalize.schema",
   	"fields": [
   		{
   			"name": "ITEM_ID",
   			"type": "string"
   		},
   		{
   			"name": "GENRE",
   			"type": "string"
   			"categorical": true
   		}
   	],
   	"version": "1.0"
   }
   

4. Create a solution using any recipe. In this post, we use the aws-hrnn recipe.
5. Create a campaign.

Creating your filter

Now that you have set up your Amazon Personalize resources, you can define and test custom filters.

Filter expression language

Amazon Personalize uses its own DSL called filter expressions to determine which items to exclude or include in a set of recommendations. Filter expressions are scoped to a dataset group. You can only use them to filter results for solution versions (an Amazon Personalize model trained using your datasets in the dataset group) or campaigns (a deployed solution version for real-time recommendations). Amazon Personalize can filter items based on user-item interaction, item metadata, or user metadata datasets.

The following are some examples of filter expressions by item:

• To remove all items in the "Comedy" genre, use the following filter expression:

  EXCLUDE ItemId WHERE item.genre in ("Comedy")

• To include items with a "number of downloads" less than 20, use the following filter expression:

  INCLUDE ItemId WHERE item.number_of_downloads < 20

The following are some examples of filter expressions by interaction:

• To remove items that have been clicked or streamed by a user, use the following filter expression:

  EXCLUDE ItemId WHERE interaction.event_type in ("click", "stream")

• To include items that a user has interacted with in any way, use the following filter expression:

  INCLUDE ItemId WHERE interactions.event_type in ("*")

You can also filter by user:

• To exclude items where the number of downloads is less than 20 if the current user’s age is over 18 but less than 30, use the following filter expression:

  EXCLUDE ItemId WHERE item.number_of_downloads < 20 IF CurrentUser.age > 18 AND CurrentUser.age < 30

You can also chain multiple expressions together, allowing you to pass the result of one expression to another in the same filter using a pipe ( | ) to separate them:

• The following filter expression example includes two expressions. The first expression includes items in the "Comedy" genre, and the result of this filter is passed to another expression that excludes items with the description "classic":

  INCLUDE Item.ID WHERE item.genre IN (“Comedy”) | EXCLUDE ItemID WHERE item.description IN ("classic”)

For more information, see Datasets and Schemas. For more information about filter definition DSL, see Filtering Recommendations.

Creating a filter on the console

You can use the preceding DSL to create a custom filter on the Amazon Personalize console. To create a filter, complete the following steps:

1. On the Amazon Personalize console, choose Filters.
2. Choose Create filter.
3. For Filter name, enter the name for your filter.
4. For Expression, select Build expression.

Alternatively, you can add your expression manually.

5. To chain additional expressions with your filter, choose +.
6. To add additional filter expressions, choose Add expression.
7. Choose Finish.

Creating a filter takes you to a page containing detailed information about your filter. You can view more information about your filter, including the filter ARN and the corresponding filter expression you created. You can also delete filters on this page or create more filters from the summary page.

You can also create filters via the createFilter API in Amazon Personalize. For more information, see Filtering Recommendations.

Applying your filter to real-time recommendations on the console

The Amazon Personalize console allows you to spot-check real-time recommendations on the Campaigns page. From this page, you can test your filters while retrieving recommendations for a specific user on demand. To do so, navigate to the Campaigns tab; this should be in the same dataset group that you used to create the filter. You can then test the impact of applying the filter on the recommendations.

Recommendations without a filter

The following screenshot shows recommendations returned with no filter applied.

Recommendations with a filter

The following screenshot shows results after you remove the "Action" genre from the recommendations by applying the filter we previously defined.

If we investigate the Items dataset provided in this example, item 546 is in the genre "Action" and we excluded the "Action" genre in our filter.

This information tells us that Item 546 should be excluded from recommendations. The results show that the filter removed items in the genre "Action" from the recommendation.

Applying your filter to batch recommendations on the console

To apply a filter to batch recommendations on the console, follow the same process as real-time recommendations. On the Create batch inference job page, choose the filter name to apply a previously created filter to your batch recommendations.

Applying your filter to real-time recommendations through the SDK

You can also apply filters to recommendations that are served through your SDK or APIs by supplying the filterArn as an additional and optional parameter to your GetRecommendations calls. Use "filterArn" as the parameter key and supply the filterArn as a string for the value. filterArn is a unique identifying key that the CreateFilter API call returns. You can also find a filter’s ARN on the filter’s detailed information page.

The following example code is a request body for the GetRecommendations API that applies a filter to a recommendation:

{
    "campaignArn": "arn:aws:personalize:us-west-2:000000000000:campaign/test-campaign",
    "userId": "1",
    "itemId": "1",
    "numResults": 5,
    "filterArn": "arn:aws:personalize:us-west-2:000000000000:filter/test-filter"
}

Applying your filter to batch recommendations through the SDK

To apply filters to batch recommendations when using a SDK, you provide the filterArn in the request body as an optional parameter. Use "filterArn" as the key and the filterArn as the value.

Summary

Customizable recommendation filters in Amazon Personalize allow you to fine-tune recommendations to provide more tailored experiences that improve customer engagement and conversion according to your business needs without having to implement post-processing logic on your own. For more information about optimizing your user experience with Amazon Personalize, see What Is Amazon Personalize?

About the Author

Matt Chwastek is a Senior Product Manager for Amazon Personalize. He focuses on delivering products that make it easier to build and use machine learning solutions. In his spare time, he enjoys reading and photography.

Read More

One of AWS’s goals is to put machine learning (ML) in the hands of every developer. With the open-source AutoML library AutoGluon, deployed using Amazon SageMaker and AWS Lambda, we can take this a step further, putting ML in the hands of anyone who wants to make predictions based on data—no prior programming or data science expertise required.

AutoGluon automates ML for real-world applications involving image, text, and tabular datasets. AutoGluon trains multiple ML models to predict a particular feature value (the target value) based on the values of other features for a given observation. During training, the models learn by comparing their predicted target values to the actual target values available in the training data, using appropriate algorithms to improve their predictions accordingly. When training is complete, the resulting models can predict the target feature values for observations they have never seen before, even if you don’t know their actual target values.

AutoGluon automatically applies a variety of techniques to train models on data with a single high-level API call—you don’t need to build models manually. Based on a user-configurable evaluation metric, AutoGluon automatically selects the highest-performing combination, or ensemble, of models. For more information about how AutoGluon works, see Machine learning with AutoGluon, an open source AutoML library.

To get started with AutoGluon, see the AutoGluon GitHub repo. For more information about trying out sophisticated AutoML solutions in your applications, see the AutoGluon website. Amazon SageMaker is a fully managed service that provides every developer and data scientist with the ability to build, train, and deploy ML models efficiently. AWS Lambda lets you run code without provisioning or managing servers, can be triggered automatically by other AWS services like Amazon Simple Storage Service (Amazon S3), and allows you to build a variety of real-time data processing systems.

With AutoGluon, you can achieve state-of-the-art predictive performance on new observations with as few as three lines of Python code. In this post, we achieve the same results with zero lines of code—making AutoML accessible to non-developers—by using AWS services to deploy a pipeline that trains ML models and makes predictions on tabular data using AutoGluon. After deploying the pipeline in your AWS account, all you need to do to get state-of-the-art predictions on your data is upload it to an S3 bucket with a provided AutoGluon package.

The code-free ML pipeline

The pipeline starts with an S3 bucket, which is where you upload the training data that AutoGluon uses to build your models, the testing data you want to make predictions on, and a pre-made package containing a script that sets up AutoGluon. After you upload the data to Amazon S3, a Lambda function kicks off an Amazon SageMaker model training job that runs the pre-made AutoGluon script on the training data. When the training job is finished, AutoGluon’s best-performing model makes predictions on the testing data, and these predictions are saved back to the same S3 bucket. The following diagram illustrates this architecture.

Deploying the pipeline with AWS CloudFormation

You can deploy this pipeline automatically in an AWS account using a pre-made AWS CloudFormation template. To get started, complete the following steps:

1. Choose the AWS Region in which you’d like to deploy the template. If you’d like to deploy it in another region, please download the template from GitHub and upload it to CloudFormation yourself.
   
   

   Northern Virginia
   Oregon
   Ireland
   Sydney

2. Sign in to the AWS Management Console.
3. For Stack name, enter a name for your stack (for example, code-free-automl-stack).
4. For BucketName, enter a unique name for your S3 bucket (for example, code-free-automl-yournamehere).
5. For TrainingInstanceType, enter your compute instance.

This parameter controls the instance type Amazon SageMaker model training jobs use to run AutoGluon on your data. AutoGluon is optimized for the m5 instance type, and 50 hours of Amazon SageMaker training time with the m5.xlarge instance type are included as part of the AWS Free Tier. We recommend starting there and adjusting the instance type up or down based on how long your initial job takes and how quickly you need the results.

6. Select the IAM creation acknowledgement checkbox and choose Create stack.
   
7. Continue with the AWS CloudFormation wizard until you arrive at the Stacks page.
   
   

It takes a moment for AWS CloudFormation to create all the pipeline’s resources. When you see the CREATE_COMPLETE status (you may need to refresh the page), the pipeline is ready for use.

9. To see all the components shown in the architecture, choose the Resources tab.
   
10. To navigate to the S3 bucket, choose the corresponding link.
    

Before you can use the pipeline, you have to upload the pre-made AutoGluon package to your new S3 bucket.

11. Create a folder called source in that bucket.
    
12. Upload the sourcedir.tar.gz package there; keep the default object settings.
    

Your pipeline is now ready for use!

Preparing the training data

To prepare your training data, go back to the root of the bucket (where you see the source folder) and make a new directory called data; this is where you upload your data.

Gather the data you want your models to learn from (the training data). The pipeline is designed to make predictions for tabular data, the most common form of data in real-world applications. Think of it like a spreadsheet; each column represents the measurement of some variable (feature value), and each row represents an individual data point (observation).

For each observation, your training dataset must include columns for explanatory features and the target column containing the feature value you want your models to predict.

Store the training data in a CSV file called <Name>_train.csv, where <Name> can be replaced with anything.

Make sure that the header name of the desired target column (the value of the very first row of the column) is set to target so AutoGluon recognizes it. See the following screenshot of an example dataset.

Preparing the test data

You also need to provide the testing data you want to make predictions for. If this dataset already contains values for the target column, you can compare these actual values to your model’s predictions to evaluate the quality of the model.

Store the testing dataset in another CSV file called <Name>_test.csv, replacing <Name> with the same string you chose for the corresponding training data.

Make sure that the column names match those of <Name>_train.csv, including naming the target column target (if present).

Upload the <Name>_train.csv and <Name>_test.csv files to the data folder you made earlier in your S3 bucket.

The code-free ML pipeline kicks off automatically when the upload is finished.

Training the model

When the training and testing dataset files are uploaded to Amazon S3, AWS logs the occurrence of an event and automatically triggers the Lambda function. This function launches the Amazon SageMaker training job that uses AutoGluon to train an ensemble of ML models. You can view the job’s status on the Amazon SageMaker console, in the Training jobs section (see the following screenshot).

Performing inference

When the training job is complete, the best-performing model or weighted combination of models (as determined by AutoGluon) is used to compute predictions for the target feature value of each observation in the testing dataset. These predictions are automatically stored in a new directory within a results directory in your S3 bucket, with the filename <Name>_test_predictions.csv.

AutoGluon produces other useful output files, such as <Name>_leaderboard.csv (a ranking of each individual model trained by AutoGluon and its predictive performance) and <Name>_model_performance.txt (an extended list of metrics corresponding to the best-performing model). All these files are available for download to your local machine from the Amazon S3 console (see the following screenshot).

Extensions

The trained model artifact from AutoGluon’s best-performing model is also saved in the output folder (see the following screenshot).

You can extend this solution by deploying that trained model as an Amazon SageMaker inference endpoint to make predictions on new data in real time or by running an Amazon SageMaker batch transform job to make predictions on additional testing data files. For more information, see Work with Existing Model Data and Training Jobs.

You can also reuse this automated pipeline with custom model code by replacing the AutoGluon sourcedir.tar.gz package we prepared for you in the source folder. If you unzip that package and look at the Python script inside, you can see that it simply runs AutoGluon on your data. You can adjust some of the parameters defined there to better match your use case. That script and all the other resources used to set up this pipeline are freely available in this GitHub repository.

Cleaning up

The pipeline doesn’t cost you anything more to leave up in your account because it only uses fully managed compute resources on demand. However, if you want to clean it up, simply delete all the files in your S3 bucket and delete the launched CloudFormation stack. Make sure to delete the files first; AWS CloudFormation doesn’t automatically delete an S3 bucket with files inside.

To delete the files from your S3 bucket, on the Amazon S3 console, select the files and choose Delete from the Actions drop-down menu.

To delete the CloudFormation stack, on the AWS CloudFormation console, choose the stack and choose Delete.

In the confirmation window, choose Delete stack.

Conclusion

In this post, we demonstrated how to train ML models and make predictions without writing a single line of code—thanks to AutoGluon, Amazon SageMaker, and AWS Lambda. You can use this code-free pipeline to leverage the power of ML without any prior programming or data science expertise.

If you’re interested in getting more guidance on how you can best use ML in your organization’s products and processes, you can work with the Amazon ML Solutions Lab. The Amazon ML Solutions Lab pairs your team with Amazon ML experts to prepare data, build and train models, and put models into production. It combines hands-on educational workshops with brainstorming sessions and advisory professional services to help you work backward from business challenges, and go step-by-step through the process of developing ML-based solutions. At the end of the program, you can take what you have learned through the process and use it elsewhere in your organization to apply ML to business opportunities.

About the Authors

Abhi Sharma is a deep learning architect on the Amazon ML Solutions Lab team, where he helps AWS customers in a variety of industries leverage machine learning to solve business problems. He is an avid reader, frequent traveler, and driving enthusiast.

Ryan Brand is a Data Scientist in the Amazon Machine Learning Solutions Lab. He has specific experience in applying machine learning to problems in healthcare and the life sciences, and in his free time he enjoys reading history and science fiction.

Tatsuya Arai Ph.D. is a biomedical engineer turned deep learning data scientist on the Amazon Machine Learning Solutions Lab team. He believes in the true democratization of AI and that the power of AI shouldn’t be exclusive to computer scientists or mathematicians.

Read More

Whether your jam is reggae, hip-hop or electronic you can get creative and enter the latest AWS DeepComposer Chartbusters challenge! The Spin the Model challenge launches today and is open until August 23, 2020. AWS DeepComposer gives developers a creative way to get started with machine learning. Chartbusters is a monthly challenge where you can use AWS DeepComposer to create original compositions and compete to top the charts and win prizes.

To participate in the challenge you first need to train a model and create a composition using your dataset and the Amazon SageMaker notebook. You don’t need a physical keyboard to participate in the challenge. Next, you import the composition on the AWS DeepComposer console, and submit the composition to SoundCloud.  When you submit a composition, AWS DeepComposer automatically adds it to the Spin the Model challenge playlist in SoundCloud.

You can use the A deep dive into training an AR-CNN model learning capsule available on the AWS DeepComposer console to learn the concepts to train a model. To access the learning capsule, sign in to the AWS DeepComposer console and choose learning capsules in the navigation pane. Choose A deep dive into training an AR-CNN model to begin learning.

Training a model

We have provided a sample notebook to create a custom model. To use the notebook, first create the Amazon SageMaker notebook instance.

1. On the Amazon SageMaker console, under Notebook, choose Notebook instances.
   
2. Choose Create notebook instance.
   
3. For Notebook instance type, choose ml.c5.4xlarge.
   
4. For IAM role, choose a new or existing role.
5. For Root access, select Enable.
6. For Encryption key, choose No Custom Encryption.
   
7. For Repository, choose Clone a public Git repository to this notebook instance only.
8. For Git repository URL, enter https://github.com/aws-samples/aws-deepcomposer-samples.
9. Choose Create notebook instance.
10. Select your notebook instance and choose Open Jupyter.
    
11. In the ar-cnn folder, choose AutoRegressiveCNN.ipynb.

You’re likely prompted to choose a kernel.

11. From the drop-down menu, choose conda_tensorflow_p36.
12. Choose Set Kernel.

This notebook contains instructions and code to create and train a custom model from scratch.

13. To run the code cells, choose the code cell you want to run and choose Run.
    

If the kernel has an empty circle, it means it’s available and ready to run the code.

If the kernel has a filled circle, it means the kernel is busy. Wait for it to become available before you run the next line of code.

14. Provide the path for your dataset in the dataset summary section. Replace the current data_dir path with your dataset directory.

Your dataset should be in the .mid format.

15. After you provide the dataset directory path, you can experiment by changing the hyperparameters to train the model.

Training a model typically takes 5 hours or longer, depending on the dataset size and hyperparameter choices.

16. After you train the model, create a composition by using the code in the Inference section.

You can use the sample input MIDI files provided in the GitHub repo to generate a composition. Alternatively, you can play the input melody in AWS DeepComposer and download the melody to create a new composition.

17. After you create your composition, download it by navigating to the /outputs folder and choosing the file to download.

Submitting your composition

You can now import your composition in AWS DeepComposer. This step is necessary to submit the composition to the Spin the Model Chartbusters challenge.

1. On the AWS DeepComposer console, choose Input melody.
2. For Source of input melody, choose Imported track.
3. For Imported track, choose Choose file to upload the file.
4. Use the AR-CNN algorithm to further enhance the input melody.
   
5. To submit your composition for the challenge, choose Chartbusters in the navigation pane.
6. Choose Submit a composition.
7. Choose your composition from the drop-down menu.
8. Provide a track name for your composition and choose Submit.
   

AWS DeepComposer submits your composition to the Spin the Model playlist on SoundCloud. You can choose Vote on SoundCloud on the console to review and listen to other submissions for the challenge.

Conclusion

Congratulations! You have submitted your entry for the AWS DeepComposer Chartbusters challenge. Invite your friends and family to listen to and like your composition!

Learn more about AWS DeepComposer Chartbusters at https://aws.amazon.com/deepcomposer/chartbusters.

About the Author

Jyothi Nookula is a Principal Product Manager for AWS AI devices. She loves to build products that delight her customers. In her spare time, she loves to paint and host charity fund raisers for her art exhibitions.

Read More

We are excited to announce the top 10 compositions and the winner for the AWS DeepComposer Chartbusters Bach to the Future challenge. AWS DeepComposer gives developers a creative way to get started with machine learning. Chartbusters is a monthly challenge where you can use AWS DeepComposer to create original compositions and compete to top the charts and win prizes. The first challenge, Bach to the Future, required developers to use a new generative AI algorithm provided on the AWS DeepComposer console to create compositions in the style of Bach. It was an intense competition with high-quality submissions, making it a good challenge for our judges to select the chart-toppers!

Top 10 compositions

First, we shortlisted the top 20 compositions by using a total of customer likes and count of plays on SoundCloud. Then, our human experts (Mike Miller and Gillian Armstrong) and the AWS DeepComposer AI judge evaluated compositions for musical quality, creativity, and emotional resonance to select the top 10 ranked compositions.

The winner for the Bach to the Future challenge is… (cue drum roll) Catherine Chui! You can listen to the winning composition on SoundCloud. The top 10 compositions for the Bach to the Future challenge are:

You can listen to the playlist featuring the top 10 compositions on SoundCloud or on the AWS DeepComposer console.

The winner, Catherine Chui, will receive an AWS DeepComposer Chartbusters gold record. Catherine will be telling the story of how she created this tune and the experience of getting hands on with AWS DeepComposer in an upcoming post, right here on the AWS ML Blog.

Congratulations, Catherine Chui!

It’s time to move onto the next Chartbusters challenge — Spin the Model. The challenge launches today and is open until August 23, 2020. For more information about the competition and how to participate, see Announcing the AWS DeepComposer Chartbusters Spin the Model challenge.

About the Author

Jyothi Nookula is a Principal Product Manager for AWS AI devices. She loves to build products that delight her customers. In her spare time, she loves to paint and host charity fund raisers for her art exhibitions.

Read More

AWS customers rely on Amazon Lex bots to power their Amazon Connect self service conversational experiences on telephone and other channels. With Lex, callers (or customers, in Amazon Connect terminology) can get their questions conveniently answered regardless of agent availability. What architecture patterns can you use to make a bot resilient to service availability issues? In this post, we describe a cross-regional approach to yield higher availability by deploying Amazon Lex bots in multiple Regions.

Architecture overview

In this solution, Amazon Connect flows can achieve business continuity with minimal disruptions in the event of service availability issues with Amazon Lex. The architecture pattern uses the following components:

• Two Amazon Lex bots, each in a different Region.
• An Amazon Connect flow integrated with the bots triggered based on the result from the region check AWS Lambda function.
• A Lambda function to check the health of the bot.
• A Lambda function to read the Amazon DynamoDB table for the primary bot’s Region for a given Amazon Connect Region.
• A DynamoDB table to store a Region mapping between Amazon Connect and Amazon Lex. The health check function updates this table. The region check function reads this table for the most up-to-date primary Region mapping for Amazon Connect and Amazon Lex.

The goal of having identical Amazon Lex Bots in two Regions is to bring up the bot in the secondary Region and make it the primary in the event of an outage in the primary Region.

Multi-region pattern for Amazon Lex

The next two sections describe how an Amazon Connect flow integrated with an Amazon Lex bot can recover quickly in case of a service failure or outage in the primary Region and start servicing calls using Amazon Lex in the secondary Region.

The health check function calls one of the two Amazon Lex Runtime API calls—PutSession or PostText, depending on the TEST_METHOD Lambda environment variable. You can choose either one based on your preference and use case. The PutSession API call doesn’t have any extra costs associated with Amazon Lex, but it doesn’t test any natural language understanding (NLU) features of Amazon Lex. The PostTextAPI allows you to check the NLU functionality of Amazon Lex, but includes a minor cost.

The health check function updates the lexRegion column of the DynamoDB table (lexDR) with the Region name in which the test passed. If the health check passes the test in the primary Region, lexRegion gets updated with the name of the primary Region. If the health check fails, the function issues a call to the corresponding Runtime API based on the TEST_METHOD environment variable in the secondary Region. If the test succeeds, the lexRegion column in the DynamoDB table gets updated to the secondary Region; otherwise, it gets updated with err, which indicates both Regions have an outage.

On every call that Amazon Connect receives, it issues a region check function call to get the active Amazon Lex Region for that particular Amazon Connect Region. The primary Region returned by the region check function is the last entry written to the DynamoDB table by the health check function. Amazon Connect invokes the respective Get Customer Input Block configured with the Amazon Lex bot in the Region returned by the region check function. If the function returns the same Region as the Amazon Connect Region, it indicates that the health check has passed, and Amazon Connect calls the Amazon Lex bot in its same Region. If the function returns the secondary Region, Amazon Connect invokes the bot in the secondary Region.

Deploying Amazon Lex bots

You need to create an identical bot in both your primary and secondary Region. In this blog post, we selected us-east-1 as the primary and us-west-2 secondary Region. Begin by creating the bot in your primary Region, us-east-1.

1. On the Amazon Lex console, click Create.
2. In the Try a Sample section, select OrderFlowers.  Select COPPA to No
3. Leave all other settings at their default value and click Create.
4. The bot is created and will start to build automatically.
5. After your bot is built (in 1–2 minutes), choose Publish.
6. Create an alias with the name ver_one.

Repeat the above steps for us-west-2.  You should now have a working Amazon Lex bot in both us-east-1 and us-west-2.

Creating a DynamoDB table

Make sure your AWS Region is us-east-1.

1. On the DynamoDB console, choose Create.
2. For Table name, enter lexDR.
3. For Primary key, enter connectRegion with type String.
4. Leave everything else at their default and choose Create.
5. On the Items tab, choose Create item.
6. Set the connectRegion value to us-east-1 , and Append a new column of type String called lexRegion and set its value to us-east-1.
   
7. Click Save.
   

Creating IAM roles for Lambda functions

In this step, you create an AWS Identity and Access Management (IAM) for both Lambda functions to use.

1. On the IAM console, click on Access management and select Policies.
2. Click on Create Policy.
3. Click on JSON.
4. Paste the following custom IAM policy that allows read and write access to the DynamoDB table, lexDR. Replace the “xxxxxxxxxxxx” in the policy definition with your AWS Account Number.

   {
   	"Version": "2012-10-17",
   	"Statement": [{
   		"Sid": "VisualEditor0",
   		"Effect": "Allow",
   		"Action": ["dynamodb:GetItem", "dynamodb:UpdateItem"],
   		"Resource": "arn:aws:dynamodb:us-east-1:xxxxxxxxxxxx:table/lexDR"
   	}]
   }

5. Click on Review Policy.
6. Give it a name DynamoDBReadWrite and click on Create Policy.
7. On the IAM console, click on Roles  under Access management  and then click on Create Role.
8. Select Lambda for the service and click Next.
9. Attach the following permissions policies:
   1. AWSLambdaBasicExecutionRole
   2. AmazonLexRunBotsOnly
   3. DynamoDBReadWrite
10. Click Next: Tags. Skip the Tags page by clicking Next: Review.
11. Name the role lexDRRole. Click Save.

Deploying the region check function

You first create a Lambda function to read from the DynamoDB table to decide which Amazon Lex bot is in the same Region as the Amazon Connect instance. This function is later called by Amazon Connect or your application that’s using the bot.

1. On the Lambda console, choose Create function.
2. For Function name, enter lexDRGetRegion.
3. For Runtime, choose Python 3.8.
4. Under Permissions, choose Use an existing role.
5. Choose the role lexDRRole.
6. Choose Create function.
7. In the Lambda code editor, enter the following code (downloaded from lexDRGetRegion.zip):

   import json
   import boto3
   import os
   import logging
   dynamo_client=boto3.client('dynamodb')
   logger = logging.getLogger()
   logger.setLevel(logging.DEBUG)
    
   def getCurrentPrimaryRegion(key):
       result = dynamo_client.get_item(
           TableName=os.environ['TABLE_NAME'],
           Key = { 
               "connectRegion": {"S": key } 
           }
       )
       logger.debug(result['Item']['lexRegion']['S'] )
       return result['Item']['lexRegion']['S'] 
    
   def lambda_handler(event, context):
       logger.debug(event)
       region = event["Details"]["Parameters"]["region"]
       return {
           'statusCode': 200,
           'primaryCode': getCurrentPrimaryRegion(region)
       }

8. In the Environment variables section, choose Edit.
9. Add an environment variable with Key as TABLE_NAME and Value as lexDR.
10. Click Save to save the environment variable.
11. Click Save to save the Lambda function.

Deploying the health check function

Create another Lambda function in us-east-1 to implement the health check functionality.

1. On the Lambda console, choose Create function.
2. For Function name, enter lexDRTest.
3. For Runtime, choose Python 3.8.
4. Under Permissions, choose Use an existing role.
5. Choose lexDRRole.
6. Choose Create function.
7. In the Lambda code editor, enter the following code (downloaded from lexDRTest.zip):

   import json
   import boto3
   import sys
   import os
   
   dynamo_client = boto3.client('dynamodb')
   primaryRegion = os.environ['PRIMARY_REGION']
   secondaryRegion = os.environ['SECONDARY_REGION']
   tableName = os.environ['TABLE_NAME']
   primaryRegion_client = boto3.client('lex-runtime',region_name=primaryRegion)
   secondaryRegion_client = boto3.client('lex-runtime',region_name=secondaryRegion)
   
   def getCurrentPrimaryRegion():
       result = dynamo_client.get_item(
           TableName=tableName,
           Key={  
               'connectRegion': {'S': primaryRegion}  
           }
       )
       return result['Item']['lexRegion']['S'] 
       
   def updateTable(region):
       result = dynamo_client.update_item( 
           TableName= tableName,
           Key={  
               'connectRegion': {'S': primaryRegion } 
           },  
           UpdateExpression='set lexRegion = :region',
           ExpressionAttributeValues={
           ':region': {'S':region}
           }
       )
       
   #SEND MESSAGE/PUT SESSION ENV VA
   def put_session(botname, botalias, user, region):
       print(region,botname, botalias)
       client = primaryRegion_client
       if region == secondaryRegion:
           client = secondaryRegion_client
       try:
           response = client.put_session(botName=botname, botAlias=botalias, userId=user)
           if (response['ResponseMetadata'] and response['ResponseMetadata']['HTTPStatusCode'] and response['ResponseMetadata']['HTTPStatusCode'] != 200) or (not response['sessionId']):  
               return 501
           else:
               if getCurrentPrimaryRegion != region:
                   updateTable(region)
           return 200
       except:
           print('ERROR: {}',sys.exc_info()[0])
           return 501
   
   def send_message(botname, botalias, user, region):
       print(region,botname, botalias)
       client = primaryRegion_client
       if region == secondaryRegion:
           client = secondaryRegion_client
       try:
           message = os.environ['SAMPLE_UTTERANCE']
           expectedOutput = os.environ['EXPECTED_RESPONSE']
           response = client.post_text(botName=botname, botAlias=botalias, userId=user, inputText=message)
           if response['message']!=expectedOutput:
               print('ERROR: Expected_Response=Success, Response_Received='+response['message'])
               return 500
           else:
               if getCurrentPrimaryRegion != region:
                   updateTable(region)
               return 200
       except:
           print('ERROR: {}',sys.exc_info()[0])
           return 501
   
   def lambda_handler(event, context):
       print(event)
       botName = os.environ['BOTNAME']
       botAlias = os.environ['BOT_ALIAS']
       testUser = os.environ['TEST_USER']
       testMethod = os.environ['TEST_METHOD']
       if testMethod == 'send_message':
           primaryRegion_response = send_message(botName, botAlias, testUser, primaryRegion)
       else:
           primaryRegion_response = put_session(botName, botAlias, testUser, primaryRegion)
       if primaryRegion_response != 501:
           primaryRegion_client.delete_session(botName=botName, botAlias=botAlias, userId=testUser)
       if primaryRegion_response != 200:
           if testMethod == 'send_message':
               secondaryRegion_response = send_message(botName, botAlias, testUser, secondaryRegion)
           else:
               secondaryRegion_response = put_session(botName, botAlias, testUser, secondaryRegion)
           if secondaryRegion_response != 501:
               secondaryRegion_client.delete_session(botName=botName, botAlias=botAlias, userId=testUser)
           if secondaryRegion_response != 200:
               updateTable('err')
       #deleteSessions(botName, botAlias, testUser)
       return {'statusCode': 200,'body': 'Success'}
   

8. In the Environment variables section, choose Edit, and add the following environment variables:
   • BOTNAME – OrderFlowers
   • BOT_ALIAS – ver_one
   • SAMPLE_UTTERANCE – I would like to order some flowers.
     (The example utterance you want to use to send a message to the bot.)
   • EXPECTED_RESPONSE – What type of flowers would you like to order?
     (The expected response from the bot when it receives the above sample utterance.)
   • PRIMARY_REGION – us-east-1
   • SECONDARY_REGION – us-west-2
   • TABLE_NAME – lexDR
   • TEST_METHOD – put_session or send_message
     • send_message : This method calls the Lex Runtime function postText function which takes an utterance and maps it to one of the trained intents. postText will test the Natural Language Understanding capability of Lex. You will also iincur a small charge of $0.00075 per request)
     • put_session: This method calls the Lex Runtime function put_session function which creates a new session for the user. put_session will NOT test the Natual Language Understanding capability of Lex.)
   • TEST_USER – test
9. Click Save to save the environment variable.
10. In the Basic Settings section, update the Timeout value to 15 seconds.
11. Click Save to save the Lambda function.

Creating an Amazon CloudWatch rule

To trigger the health check function to run every 5 minutes, you create an Amazon CloudWatch rule.

1. On the CloudWatch console, under Events, choose Rules.
2. Choose Create rule.
3. Under Event Source, change the option to Schedule.
4. Set the Fixed rate of to 5 minutes
5. Under Targets, choose Add target.
6. Choose Lambda function as the target.
7. For Function, choose lexDRTest.
8. Under Configure input, choose Constant(JSON text), and enter {}
9. Choose Configure details.
10. Under Rule definition, for Name, enter lexHealthCheckRule.
11. Choose Create rule.

You should now have a lexHealthCheckRule CloudWatch rule scheduled to invoke your lexDRTest function every 5 minutes. This checks if your primary bot is healthy and updates the DynamoDB table accordingly.

Creating your Amazon Connect instance

You now create an Amazon Connect instance to test the multi-region pattern for the bots in the same Region where you created the lexDRTest function.

1. Create an Amazon Connect instance if you don’t already have one.
2. On the Amazon Connect console, choose the instance alias where you want the Amazon Connect flow to be.
3. Choose Contact flows.
4. Under Amazon Lex, select OrderFlowers bot from us-east-1 and click Add Lex Bot
5. Select OrderFlowers bot from us-west-2 and click Add Lex Bot
   
6. Under AWS Lambda, select lexDRGetRegion and click Add Lambda Function.
7. Log in to your Amazon Connect instance by clicking Overview in the left panel and clicking the login link.
8. Click Routing in the left panel, and then click Contact Flows in the drop down menu.
9. Click the Create Contact Flow button.
10. Click the down arrow button next to the Save button, and click on Import Flow.
11. Download the contact flow Flower DR Flow. Upload this file in the Import Flow dialog.
    
12. In the Contact Flow, Click on the Inovke AWS Lambda Function block, and it will open a properties panel on the right.
13. Select the lexDRGetRegion function and click Save.
14. Click on the Publish button to publish the contact flow.

Associating a phone number with the contact flow

Next, you will associate a phone number with your contact flow, so you can call in and test the OrderFlowers bot.

1. Click on the Routing option in the left navigation panel.
2. Click on Phone Numbers.
3. Click on Claim Number.
4. Select your country code and select a Phone Number.
5. In the Contact flow/IVR select box, select the contact flow Flower DR Flow imported in the earlier step.
6. Wait for a few minutes, and then call into that number to interact with the OrderFlowers bot.

Testing your integration

To test this solution, you can simulate a failure in the us-east-1 Region by implementing the following:

1. Open Amazon Lex Console in us-east-1 Region
2. Select the OrderFlowers bot.
3. Click on Settings.
4. Delete the bot alias ver_one

When the health check runs the next time, it will try to communicate with the Lex Bot in us-east-1 region. It will fail in getting a successful response, as the bot alias no longer exists. So, it will then make the call to the secondary Region, us-west-2. Upon receiving a successful response. Upon receiving this response, it will update the lexRegion column in the lexDR, DynamoDB table with us-west-2.

After this, all subsequent calls to Connect in us-east-1 will start interacting with the Lex Bot in us-west-2. This automatic switch over demonstrates how this architectural pattern can help achieve business continuity in the event of a service failure.
Between the time you delete the bot alias, and the next health check run, calls to Amazon Connect will receive a failure. However, after the health check runs, you will see a continuity in business operational automatically. The smaller the duration between your health check runs, the shorter the outage you will have. The duration between your health check runs can be changed by editing the Amazon CloudWatch rule, lexHealthCheckRule .

To make the health check pass in us-east-1 again, recreate the ver_one alias of the OrderFlowers bot in us-east-1.

Cleanup

To avoid incurring any charges in the future, delete all the resources created above.

1. Amazon Lex bot OrderFlowers created in us-east-1 and us-west-2
2. The Cloudwatch rule lexHealthCheckRule
3. The DynamoDB Table lexDR
4. The Lambda functions lexDRTest and lexDRGetRegion
5. Delete the IAM role lexDRRole
6. Delete the Contact Flow Flower DR Flow

Conclusion

Coupled with Amazon Lex for self-service, Amazon Connect allows you to easily create intuitive customer service experiences. This post offers a multi-region approach for high availability so that, if a bot or the supporting fulfillment APIs are under pressure in one Region, resources from a different Region can continue to serve customer demand.

About the Authors

Shanthan Kesharaju is a Senior Architect in the AWS ProServe team. He helps our customers with their Conversational AI strategy, architecture, and development. Shanthan has an MBA in Marketing from Duke University, MS in Management Information Systems from Oklahoma State University, and a Bachelors in Technology from Kakaitya University in India. He is also currently pursuing his third Masters in Analytics from Georgia Tech.

Soyoung Yoon is a Conversation A.I. Architect at AWS Professional Services where she works with customers across multiple industries to develop specialized conversational assistants which have helped these customers provide their users faster and accurate information through natural language. Soyoung has M.S. and B.S. in Electrical and Computer Engineering from Carnegie Mellon University.

Read More

Today’s marketer has a wide array of channels to communicate with their customers. However, sending the right message to the right customer on the right channel at the right time remains the preeminent challenge marketers face. In this post, I show you how to combine Braze, a customer engagement platform built on AWS for today’s on-demand, always-connected customers, and Amazon Personalize to meet this challenge and deliver experiences that surprise and delight your customers.

Braze makes it easy to organize your customers into audiences, which update in real-time, based on their behavior and profile traits. Messaging campaigns are created to target audiences through messaging channels such as email, SMS, and push notifications. Multi-step and multi-channel engagement journeys can also be designed using Braze Canvas. Campaigns and Canvases are triggered manually, based on a schedule, or even due to customer actions. However, your ability to personalize messages sent to customers is limited to what is available in their profile. Including product and content recommendations based on the learned interests of each customer as they engage with your web and mobile application is needed to truly personalize each message.

Amazon Personalize is an AWS service that uses machine learning algorithms to create recommender systems based on the behavioral data of your customers. The recommenders are private to your AWS account and based only on the data you provide. Through the Braze Connected Content feature, you are able to connect Braze to the same Amazon Personalize recommenders used to power recommendations in your web and mobile application. Since Amazon Personalize is able to adjust recommendations for each customer based on their behavior in real-time, the messages sent through Braze reflect their current preferences and intent.

Overview of solutions

I present two architectures in this post: one that uses the real-time capabilities of Braze and Amazon Personalize, and another that trades some of the freshness of real-time recommendations for a more cost-effective batch approach. The approach you select should match the goals of your engagement strategy and the scale of your messaging needs. Fortunately, the features and integration options of Braze and Amazon Personalize provide the flexibility to suit your operational requirements.

Real-time integration

We start with a real-time integration architecture. The following diagram depicts the relevant components of a sample ecommerce application in which you use Amazon Personalize to provide machine learning (ML)-powered recommenders, referred to as solutions. The primary data used to build solutions is user-item interaction history. For an ecommerce application, this includes events such as viewing a product, adding a product to a shopping cart, and purchasing a product. When rich metadata on events, items, and users is available, you can incorporate it to further improve the relevance of recommendations from the recommender. Examples of metadata include device type, location, and season for events; category, genre, and price point for items; and users’ age, gender, and subscription tier. After you create solutions, you can create autoscaling API endpoints called campaigns with just a few clicks to retrieve personalized recommendations.

Later in this post, I show you how to deploy this application in your AWS account. A self-guided workshop is also packaged with the application that you use to walk through sending personalized emails with Braze.

Our example ecommerce application retrieves personalized recommendations from a Recommendations microservice that appends the recommended item IDs from Amazon Personalize with rich product information from a Products microservice. As users engage with the application and indicate interest by viewing a product, adding a product to their shopping cart, or purchasing a product, events representing these actions are streamed to Amazon Personalize via the AWS Amplify JavaScript client library where Amazon Personalize automatically adjusts recommendations in real time based on user activity.

With personalization built into the application, you can connect Amazon Personalize with Braze to deliver personalized recommendations through outbound engagement channels such as email, SMS, and push notifications.

Braze allows you to create message templates that use the Liquid templating language to substitute placeholders in your template with values from a customer’s profile or even from an external resource. In the real-time architecture, we use the Recommendations microservice from the sample application as the external resource and Braze Connected Content as the feature to retrieve personalized recommendations to include in your message templates. The following Connected Content Liquid tag, placed at the top of your message, illustrates how to call the Recommendations service from Braze to retrieve recommendations for a user:

{% connected_content http://<RecommendationsServiceHostName>/recommendations?userID={{${user_id}}}&fullyQualifyImageUrls=1&numResults=4 :save result %}

The tag has the following elements:

• Liquid tags are framed within {% and %} This allows you to embed tags and expressions inside message templates that may also contain text or HTML.
• The tag type is declared just after the start of the tag. In this case, connected_content is the tag type. For the full list of supported tags, see Personalization Using Liquid Tags.
• You next define a fully-qualified URL to the HTTP resource that Connected Content calls for each user. You replace <RecommendationsServiceHostName> with the host name for the Elastic Load Balancer for the Recommendations service in your deployment of the sample application.
• The Recommendations service provides a few resources for different personalization features. The resource for user recommendations is accessed from the /recommendations path.
• The query string parameters come next. The user is identified by the userID parameter, and the {{${user_id}}} expression instructs Braze to interpolate the user’s ID for each call to the service.
• The last two query string parameters, fullyQualifyImageUrls=1 and numResults=4, tell the Recommendations service that we want the product image URLs to be fully qualified so they can be displayed in the user’s email client and, in this case, to only return the top four recommendations, respectively.
• The :save result expression tells Braze to assign the JSON response from the Recommendations service to a template variable named result. With the response saved, you can then access elements of the response using Liquid tags in the rest of the template.

The following code shows the format of a response from the Recommendations service:

[ 
  { 
    "product": { 
      "id": "2", 
      "url": "http://recs.cloudfront.net/#/product/2", 
      "sk": "", 
      "name": "Striped Shirt", 
      "category": "apparel", 
      "style": "shirt", 
      "description": "A classic look for the summer season.", 
      "price": 9.99, 
      "image": "http://recs.cloudfront.net/images/apparel/1.jpg",
      "featured": "true" 
    } 
  }, 
  { 
    "product": { 
      "id": "1", 
      "url": "http://recs.cloudfront.net/#/product/1", 
      "sk": "", 
      "name": "Black Leather Backpack", 
      "category": "accessories", 
      "style": "bag", 
      "description": "Our handmade leather backpack will look great at the office or out on the town.", 
      "price": 109.99, 
      "image": "http://recs.cloudfront.net/images/accessories/1.jpg",
      "featured": "true" 
    } 
  }, 
  ... 
]

For brevity, the preceding code only shows the first two recommended products. Several product attributes are available that you can use in the Braze message template to represent each recommendation. To access a specific element of an array or list as we have here, you can use array subscripting notation in your Liquid tag. For example, the following tag interpolates the product name for the first recommended product in the response. For the preceding sample response, the tag resolves to “Striped Shirt”:

{{result[0].product.name}} 

When you combine the information in the personalized recommendation response from the Recommendations service with Liquid tags, the possibilities for building message designs are endless. The following code is a simplified example of how you could display a product recommendation in an HTML email template:

<table>
  <tr>
    <td>
      <a href="{{result[0].product.url}}" target="_blank">
        <img src="{{result[0].product.image}}" width="200" alt="{{result[0].product.name}}" />
      </a>
    </td>
    <td>
      <h2>{{result[0].product.name}}</h2>
      <p>{{result[0].product.description}}</p>
      <p>Only <strong>$ {{result[0].product.price}}</strong>!</p>
      <a class="button" href="{{result[0].product.url}}">Buy Now</a>
    </td>
  </tr>
</table>

Batch integration

The batch integration architecture replaces the use of the Braze Connected Content feature with an Amazon Personalize batch recommendations job that is used to push attribute updates to Braze. Batch recommendations involve creating a file in an Amazon Simple Storage Service (Amazon S3) bucket that includes the users who you wish to generate recommendations for. A reference to this file is then used to submit a job to Amazon Personalize to generate recommendations for each user in the file and output the results to another Amazon S3 file of your choosing. You can use the output of the batch recommendations job to associate personalized recommendations with user profiles in Braze as custom attributes. The Liquid tags in the message templates we saw earlier are changed to access the recommendations as custom attributes from the user profile rather than the Connected Content response.

As noted earlier, the trade-off you’re making with the batch approach is sacrificing the freshness of real-time recommendations for a more cost-effective solution. Because batch recommendations don’t require an Amazon Personalize campaign, the additional requests from Connected Content to your campaign for each user are eliminated. For Braze campaigns that target extremely large segments, this can result in a significant reduction in requests. Furthermore, if you don’t need an Amazon Personalize campaign for other purposes or you’re creating an Amazon Personalize solution dedicated to email personalization, you can forego creating a campaign entirely.

The following diagram illustrates one of the many possible approaches to designing a batch architecture. The web application components from the real-time architecture still apply; they are excluded from this diagram for brevity.

You use Amazon CloudWatch Events to periodically trigger an AWS Lambda function that builds an input file for an Amazon Personalize batch recommendations job. When the batch recommendations job is complete, another Lambda function processes the output file, decorates the recommended items with rich product information, and enqueues user update events in Amazon Kinesis Data Streams. Finally, another Lambda function consumes the stream’s events and uses the Braze User API to update user profiles.

The use of a Kinesis data stream provides a few key benefits, including decoupling the batch job from the transactional Braze user update process and the ability to pause, restart, and replay user update events.

Real-time integration walkthrough

You implement the real-time integration in the Retail Demo Store sample ecommerce application. In this post, we walk you through the process of deploying this project in your AWS account and describe how to launch the self-guided Braze workshop bundled with the application.

You complete the following steps:

1. Deploy the Retail Demo Store project to your AWS account using the supplied AWS CloudFormation templates (25–30 minutes).
2. Build Amazon Personalize solutions and campaigns that provide personalized recommendations (2 hours).
3. Import users into Braze and build a Braze campaign that uses Connected Content to retrieve personalized recommendations from Amazon Personalize (1 hour).
4. Clean up resources.

Prerequisites

For this walkthrough, you need the following prerequisites:

• An AWS account
• A user in your AWS account with the necessary privileges to deploy the project
• A Braze account

If you don’t have a Braze account, please contact your Braze representative. We also assume that you have completed at least the Getting Started with Braze LAB course.

Step 1: Deploying the Retail Demo Store to your AWS account

From the following table, choose Launch Stack in the Region of your choice. This list of Regions doesn’t represent all possible Regions where you can deploy the project, just the Regions currently configured for deployment.

Region	Launch
US East (N. Virginia)
US West (Oregon)
Europe (Ireland)

Accept all the default template parameter values and launch the template. The deployment of the project’s resources takes 25–30 minutes.

Step 2: Building Amazon Personalize campaigns

Before you can provide personalized product recommendations, you first need to train the ML models and provision the inference endpoints in Amazon Personalize that you need to retrieve recommendations. The CloudFormation template deployed in Step 1 includes an Amazon SageMaker notebook instance that provides a Jupyter notebook with detailed step-by-step instructions. The notebook takes approximately 2 hours to complete.

1. Sign in to the AWS account where you deployed the CloudFormation template in Step 1.
2. On the Amazon SageMaker console, choose Notebook instances.
3. If you don’t see the RetailDemoStore notebook instance, make sure you’re in the same Region where you deployed the project.
4. To access the notebook instance, choose Open Jupyter or Open JupyterLab.
5. When the Jupyter web interface is loaded for the notebook instance, choose the workshop/1-Personalization/1.1-Personalize.ipynb.

The notebooks are organized in a directory structure, so you may have to choose the workshop folder to see the notebook subdirectories.

6. When you have the 1.1-Personalize notebook open, step through the workshop by reading and running each cell.

You can choose Run from the Jupyter toolbar sequentially run the code in the cells.

Step 3: Sending personalized messages from Braze

With the Amazon Personalize solutions and campaigns to produce personalized recommendations in place, you can now import users into your Braze account, build a messaging template that uses Braze Connected Content to retrieve recommendations from Amazon Personalize, and build a Braze campaign to send targeted emails to your users.

Similar to the Personalization workshop in Step 1, the Braze messaging workshop steps you through the process. This notebook takes approximately 1 hour to complete.

1. If necessary, repeat the instructions in Step 1 to open a Jupyter or JupyterLab browser window from the Amazon SageMaker notebook instance in your Retail Demo Store deployment.
2. When the Jupyter web interface is loaded for the notebook instance, choose the workshop/4-Messaging/4.2-Braze.ipynb notebook.

As with before, you may have to choose the workshop folder to see the notebook subdirectories.

3. When you have the 4.2-Braze notebook open, step through the workshop by reading and running each cell.

Step 4: Cleaning up

To avoid incurring future charges, delete the resources the Retail Demo Store project created by deleting the CloudFormation stack you used during deployment. For more information about the source code for this post and the full Retail Demo Store project, see the GitHub repo.

Conclusion

As marketers compete for the attention of customers through outbound messaging, there is increasing pressure to effectively target the right users, at the right time, on the right channel, and with the right messaging. Braze provides the solution to the first three challenges. You can solve the final challenge with Braze Connected Content and Amazon Personalize, and deliver highly personalized product and content recommendations that reflect each customer’s current interests.

How are you using outbound messaging to reach your customers? Is there an opportunity to increase engagement with your customers with more relevant and personalized content?

About Braze

Braze is an AWS Advanced Technology Partner and holder of the AWS Digital Customer Experience and Retail competencies. Top global brands such as ABC News, Urban Outfitters, Rakuten, and Gap are sending tens of billions of messages per month to over 2 billion monthly active users with Braze.

About the Author

James Jory is a Solutions Architect in Applied AI with AWS. He has a special interest in personalization and recommender systems and a background in ecommerce, marketing technology, and customer data analytics. In his spare time, he enjoys camping and auto racing simulation.

Read More

Now you can translate .docx, .xlsx, and .pptx documents using Amazon Translate.

Every organization creates documents, spreadsheets, and presentations to communicate and share information with a large group and keep records for posterity. These days, we interact with people who don’t share the same language as ours. The need for translating such documents has become even more critical in a globally interconnected world. Some large organizations hire a team of professional translators to help with document translation, which involves a lot of time and overhead cost. Multiple tools are available online that enable you to copy and paste text to get the translated equivalent in the language of your choice, but there are few secure and easy methods that allow for native support of translating such documents while keeping formatting intact.

Amazon Translate now supports translation of Office Open XML documents in DOCX, PPTX, and XLSX format. Amazon Translate is a fully managed neural machine translation service that delivers high-quality and affordable language translation in 55 languages. For the full list of languages, see Supported Languages and Language Codes. The document translation feature is available wherever batch translation is available. For more information, see Asynchronous Batch Processing.

In this post, we walk you through a step-by-step process to translate documents on the AWS Management Console. You can also access the Amazon Translate BatchTranslation API for document translation via the AWS Command Line Interface (AWS CLI) or the AWS SDK.

Solution overview

This post walks you through the following steps:

1. Create an AWS Identity and Access Management (IAM) role that can access your Amazon Simple Storage Service (Amazon S3) buckets.
2. Sort your documents by file type and language.
3. Perform the batch translation.

Creating an IAM role to access your S3 buckets

In this post, we create a role that has access to all the S3 buckets in your account to translate documents, spreadsheets, and presentations. You provide this role to Amazon Translate to let the service access your input and output S3 locations. For more information, see AWS Identity and Access Management Documentation.

1. Sign in to your personal AWS account.
2. On the IAM console, under Access management, choose Roles.
3. Choose Create role.
   
4. Choose Another AWS account.
5. For Account ID, enter your ID.
   
6. Go to the next page.
7. For Filter policies, search and add the AmazonS3FullAccess policy.
   
8. Go to the next page.
9. Enter a name for the role, for example, TranslateBatchAPI.
10. Go to the role you just created.
11. On the Trust relationships tab, choose Edit trust relationship.
    
12. Enter the following service principals:

    "Service": [
    "translate.aws.internal",
    "translate.amazonaws.com"
    ],

    For example, see the following screenshot.
    

Sorting your documents

Amazon Translate batch translation works on documents stored in a folder inside an S3 bucket. Batch translation doesn’t work if the file is saved in the root of the S3 bucket. Batch translation also doesn’t support translation of nested files. So you first need to upload the documents you wish to translate in a folder inside an S3 bucket. Sort the documents such that the folders contain files of the same type (DOCX, PPTX, XLSX) and are in the same language. If you have multiple documents of different file types that you need to translate, sort the files such that each Amazon S3 prefix has only one type of document format written in one language.

1. On the Amazon S3 console, choose Create bucket.
2. Walk through the steps to create your buckets.

For this post, we create two buckets: input-translate-bucket and output-translate-bucket.

The buckets contain the following folders for each file type:

• docx
• pptx
• xlsx

Performing batch translation

To implement your batch translation, complete the following steps:

1. On to the Amazon Translate console, choose Batch Translation.
2. Choose Create job.

For this post, we walk you through translating documents in DOCX format.

3. For Name, enter BatchTranslation.
4. For Source language, choose En.
5. For Target language, choose Es.
6. For Input S3 location, enter s3://input-translate-bucket/docx/.
7. For File format, choose docx.
8. For Output S3 location, enter s3://output-translate-bucket/.
9. For Access permissions, select Use an existing IAM role.
10. For IAM role, enter TranslateBatchAPI.

Because this is an asynchronous translation, the translation begins after the machine resource for the translation is allocated. This can take up to 15 minutes. For more information about performing batch translation jobs, see Starting a Batch Translation Job.

The following screenshot shows the details of your BatchTranslation job.

When the translation is complete, you can find the output in a folder in your S3 bucket. See the following screenshot.

Conclusion

In this post, we discussed implementing asynchronous batch translation to translate documents in DOCX format. You can repeat the same procedure for spreadsheets and presentations. The translation is simple and you pay only for the number of characters (including spaces) you translate in each format. You can start translating office documents today in all Regions where batch translation is supported. If you’re new to Amazon Translate, try out the Free Tier, which offers 2 million characters per month for the first 12 months, starting from your first translation request.

About the Author

Watson G. Srivathsan is the Sr. Product Manager for Amazon Translate, AWS’s natural language processing service. On weekends you will find him exploring the outdoors in the Pacific Northwest.

Read More

Amazon CodeGuru Profiler provides recommendations to help you continuously fine-tune your application’s performance. It does this by collecting runtime performance data from your live applications. It looks for your most expensive lines of code continuously and provides intelligent recommendations. This helps you more easily understand your applications’ runtime behavior so you can optimize their performance, improve latency, and reduce infrastructure cost.

From a central dashboard, you get different visualizations of your profiling data and details to what CodeGuru Profiler recommends of your application’s performance profile. You also get a report with details on the impact of the issue on your application, what’s causing the issue, and a recommendation on what to change to resolve the issue.

In this post, I introduce you to two enhancements that make it even easier and faster for your applications to start using the machine learning (ML)-based capabilities of CodeGuru Profiler:

• Resource-based authorizations – You can use resource-based permissions to authorize an identity in your code to upload the profiled data instead of manually configuring AWS Identity and Access Manager (IAM). If the role or user already exists in IAM, you simply select the role or user on the CodeGuru Profiler console.
• Ability to start the profiler agent on the command line – You can now start the profiler agent on the command line using the -javaagent This means that you no longer need to recompile your application or set build dependencies; you simply download the latest JAR file and add the -javaagent switch to the command line and run. The whole process takes just minutes to complete.

What you can do with CodeGuru Profiler

CodeGuru Profiler is designed to run in your production environment with minimal CPU overhead to help improve your application’s performance and reduce infrastructure costs. With CodeGuru Profiler, you can:

• Troubleshoot latency and CPU utilization issues in your application
• Identify application performance issues
• Identify cost optimization opportunities and where you can reduce the infrastructure costs of running your application

CodeGuru Profiler works with your applications that are hosted on Amazon Elastic Compute Cloud (Amazon EC2), serverless applications running on AWS Fargate and AWS Lambda, and containerized applications running on Amazon Elastic Container Service (Amazon ECS) and Amazon Elastic Kubernetes Service (Amazon EKS). CodeGuru Profiler also works on-premises. It currently supports applications written in all Java virtual machine (JVM) languages, such as Java, Kotlin, and Scala.

Profiling groups

In CodeGuru Profiler, a profiling group is a set of applications that are profiled together as a single unit. The profiling agent sends application data to a single profiling group, where data from all applications in the profiling group are aggregated and analyzed. Your groups are managed on the Profiling groups page on the CodeGuru console. You can see a list of all your profiling groups, their status, or create or delete profiling groups. For more information, see Setting up Amazon CodeGuru Profiler.

A profiling group can profile a single application running on multiple hosts. It can also profile different but related applications. You can profile an application, regardless of what repository the code is in.

Resource-based authorization enabled

The improvements made to application onboarding remove many manual steps, enable resource-based authorization, and remove the need to configure IAM permissions each time you add a new application for profiling. This new setup option helps reduce configuration errors and enables quick onboarding of your application into the profiling group.

In this section, we show you how to grant the required permissions on the CodeGuru Profiler console. The first time you onboard your application, your admin needs to create the IAM role or user that can submit profiling data and configure the agent. That way, the roles and users can appear in the permissions drop-down on the CodeGuru Profiler console. After this setup is complete, you don’t need to go on the IAM console to set permissions.

Creating a profiling group with resource-based authorization

To create a profiling group with resource-based authorization enabled, complete the following steps:

1. On the CodeGuru Profiler console, choose Create profiling group.
   

2. For Name, enter test-group.
3. Choose Create.
   

We can now show you the resource-based authorization enhancement in action. Prior to the recent enhancement, you needed to set up access credentials to give an application permission to submit data to your account. You can now do this in a few clicks on the Profiling groups page.

4. In the Set permissions section, choose Give access to users and roles.
   
5. For Application permissions, choose the IAM users and roles that you want to give permissions to so they can submit data to CodeGuru Profiler.
6. Choose Save.
   

That’s it! You have set permissions for users and roles in your profiling group.

Starting the profiler agent without modifying your application’s code

Next, we walk you through a use case to demonstrate how easy and quick it is to start the profiler agent without modifying the application code.

Prerequisites

To complete this part of the post, you need the following:

• AWS account
• Laptop or desktop computer with internet access
• Terminal emulator of your choice
• Corretto 8 or JDK version 8 or later installed on your EC2 instance
• Maven installed on your EC2 instance

You no longer need to modify your application code or add dependencies to run the agent. The benefit to starting the agent with the -javaagent parameter is that you can profile existing applications without recompiling or changing your application’s code. You can still use the previous approach to start the profiling agent. For example, this approach is applicable as the only option to use for Lambda and Spark jobs.

To onboard your application, you complete the following steps:

1. Create your profiling group and set an environment variable for your Region.
2. Download the latest Java JAR file from the CodeGuru Profiler console.
3. Restart your JVM by running the -javaagent parameter

This post has some additional steps because we also set up the demo application to start profiling and onboard two different profiler groups: DemoApplication-WithIssues and DemoApplicationWithoutIssues.

Cloning the demo application

To clone the demo application to your EC2 instance, enter the following code:

git clone  https://github.com/aws-samples/aws-codeguru-profiler-demo-application
cd aws-codeguru-profiler-demo-application 

After you change directories to aws-codeguru-profiler-demo-application, you should see the pom.xml file.

Creating a profiling group

At the command line, enter the following commands, starting with the steps that you always need to perform to onboard the profiler (with aws configure, set up your AWS credentials and default Region, which are the same credentials you created the resource policies for):

aws codeguruprofiler create-profiling-group --profiling-group-name DemoApplication-WithIssues
aws codeguruprofiler create-profiling-group --profiling-group-name DemoApplication-WithoutIssues

Setting up the demo application

To complete the project, you create an Amazon Simple Storage Service (Amazon S3) bucket and an Amazon Simple Queue Service (Amazon SQS) queue. Creating an S3 bucket and SQS queue aren’t part of the onboarding process; you use these services for business logic. The SQS queue is polled for names of images to process and the images get loaded into an S3 bucket, does some image transformation, and then the results back to the S3 bucket.

To create these resources, enter the following code:

aws s3 mb s3://demo-application-test-bucket-YOUR BUCKET NAME
aws sqs create-queue --queue-name DemoApplicationQueue

For this post, replace YOUR BUCKET NAME with a random set of numbers. This helps make sure that your bucket contains a globally unique name.

Next, we set the environment variables by using the following commands. These steps are necessary for this particular application and not related to onboarding the profiler. Also, don’t forget to use your test-bucket name. Replace the referenced Amazon SQS URL with your Amazon SQS URL, which you can find on the Details tab for the queue on the Amazon SQS console.

export DEMO_APP_BUCKET_NAME="demo-application-test-bucket-10245"
export DEMO_APP_SQS_URL="https://sqs.us-east-1.amazonaws.com/12345678/DemoApplicationQueue"
export AWS_CODEGURU_TARGET_REGION=REPLACE WITH YOUR-AWS-REGION

Downloading the Java agent JAR file

First, set the environment variable:

export AWS_CODEGURU_PROFILER_GROUP_NAME=DemoApplication-WithIssues

To create a JAR file in the target directory, enter the following code:

mvn clean install

The process can take up to 1 minute to complete.

For this post, you don’t need to download the CodeGuru Profiler Java agent JAR file. It’s included with the demo application that you downloaded from GitHub. However, when you onboard your application for profiling, you need to download the JAR file from the CodeGuru Profiler console. See the following screenshot.

Running the demo application

Next, you restart your JVM by running the -javaagent switch. Make sure that the application file name is included in the command. When you run this project, the JAR file version may have been updated from the version you see in the following code:

java -javaagent:codeguru-profiler-java-agent-standalone-1.0.0.jar 
-jar target/DemoApplication-1.0-jar-with-dependencies.jar with-issues

The profiling group setup is successful when you see the following message:

INFO: Profiling scheduled, sampling rate is PT1S

You will see messages running on the screen for several minutes. You have the option to enter exit, enter on your keyboard. If you do that, reconnect back into your EC2 instance through SSH to verify that the application is still running in the background, using the following command:

ps -ef |grep javaagent

Checking the CodeGuru console for the profiling group

To verify that your application is profiling, return to the CodeGuru console. You should see the profiling group go from Inactive to Pending status, and then end in Profiling status.

When your profiling group shows the status Profiling, you can visualize the application’s runtime data. It takes about 5 minutes for the CodeGuru Profiling agent to submit code review data. After about 10 more minutes, you can see the flame graph visualizations. Within 1 hour, you have your first recommendation report.

If you want to run this project again, without issues, repeat the previous steps with the following changes:

• Set the export variables per your setup. As we discussed earlier when running the demo app WithIssues, these environment variables are specific to running the demo app and not part of the profiler onboarding.

  export DEMO_APP_SQS_URL=https://sqs.YOUR-AWS-REGION.queue.amazonaws.com/YOUR-ACCOUNT-ID/DemoApplicationQueue
  export DEMO_APP_BUCKET_NAME=demo-application-test-bucket-1092734-YOUR-BUCKET-NAME
  export AWS_CODEGURU_TARGET_REGION=YOUR-AWS-REGION
  

• Run the demo application with the following code:

  export AWS_CODEGURU_PROFILER_GROUP_NAME=DemoApplication-WithoutIssues
  mvn clean install ## This command will generate the DemoApplication-1.0-jar-with-dependencies.jar
  java -javaagent:codeguru-profiler-java-agent-standalone-1.0.0.jar 
    -jar target/DemoApplication-1.0-jar-with-dependencies.jar without-issues

For more information about visualizations in CodeGuru Profiler, see the section Understanding CodeGuru Profiler’s visualizations in Optimizing application performance with Amazon CodeGuru Profiler.

Cleaning up

To avoid incurring any future charges, delete the resources you created with this project:

• Profiling group DemoApplication-WithIssues
• SQS queue and the S3 bucket
• EC2 instance

Conclusion

We’re excited to help you make it even quicker and easier to onboard your applications using CodeGuru Profiler. In this post, we reviewed and learned how to use two recent enhancements to CodeGuru Profiler: resource-based permission setting and starting the profiler agent using the -javaagent switch, without needing to modify your application’s code.

CodeGuru Profiler is part of Amazon CodeGuru (Preview), an ML-based service that performs automated code reviews and application performance recommendations. It finds issues in your code and deviations from performance engineering best practices using AWS APIs, SDKs, and a variety of libraries to make specific recommendations to remediate identified issues. CodeGuru is powered by ML capabilities, best practices, and lessons learned from millions of code reviews and thousands of applications profiled on both open-source projects and internally at Amazon.

We hope that you find that using these feature enhancements is straightforward, quick, and easy. Let us know your progress on our GitHub project page!

About the Author

Charles Gibson is an Enterprise Transformation Architect in Professional Services at Amazon Web Services. He helps customers migrate and modernize their businesses on the AWS Cloud. Charles enjoys cooking Northern Italian food for friends and family.

Read More

This blog post is co-written by guest authors from SNCF and Olexya.

Transportation and logistics are fertile ground for machine learning (ML). In this post, we show how the French state-owned railway company Société Nationale des Chemins de fer Français (SNCF) uses ML from AWS with the help of its technology partner Olexya to research, develop, and deploy innovative computer vision solutions.

SNCF was founded in 1938 and employs more than 270,000 people. SNCF Réseau is a subsidiary of SNCF that manages and operates the infrastructure for the rail network. SNCF Réseau and its technology partner Olexya deploy innovative solutions to assist the operations of the infrastructure and keep the bar high for infrastructure safety and quality. The field teams detect anomalies in the infrastructure by using computer vision.

SNCF Réseau researchers have been doing ML for a long time. An SNCF Réseau team developed a computer vision detection model on premises using the Caffe2 deep learning framework. The scientists then reached out to SNCF Réseau technology partner Olexya to assist with the provisioning of GPU to support iteration on the model. To keep operational overhead low and productivity high while retaining full flexibility on the scientific code, Olexya decided to use Amazon SageMaker to orchestrate the training and inference of the Caffe2 model. The process involved the following steps:

1. Custom Docker creation.
2. Training configuration ingestion via an Amazon Simple Storage Service (Amazon S3) data channel.
3. Cost-efficient training via Amazon SageMaker Spot GPU training.
4. Cost-efficient inference with the Amazon SageMaker training API.

Custom docker creation

The team created a Docker image wrapping the original Caffe2 code that respected the Amazon SageMaker Docker specification. Amazon SageMaker can accommodate multiple data sources, and has advanced integration with Amazon S3. Datasets stored in Amazon S3 can be automatically ingested in training containers running on Amazon SageMaker. To be able to process training data available in Amazon S3, Olexya had to direct the training code to read from the associated local path opt/ml/input/data/<channel name>. Similarly, the model artifact writing location had to be set to opt/ml/model. That way, Amazon SageMaker can automatically compress and ship the trained model artifact to Amazon S3 when training is complete.

Training configuration ingestion via an Amazon S3 data channel

The original Caffe2 training code was parametrized with an exhaustive and flexible YAML configuration file, so that researchers could change model settings without altering the scientific code. This external file was easy to keep external and ingest at training time in the container via the use of data channels. Data channels are Amazon S3 ARNs passed to the Amazon SageMaker SDK at training time and ingested in the Amazon SageMaker container when training starts. Olexya configured the data channels to read via a copy (copy mode), which is the default configuration. It is also possible to stream the data via Unix pipes (Pipe mode).

Cost-efficient training via Amazon SageMaker Spot GPU training

The team configured training infrastructure to be an ml.p3.2xlarge GPU-accelerated compute instance. The Amazon SageMaker ml.p3.2xlarge compute instance is specifically adapted to deep learning computer vision workloads: it’s equipped with an NVIDIA V100 GPU featuring 5,120 cores and 16 GB of High-Bandwidth Memory (HBM), which enables the fast training of large models.

Furthermore, Amazon SageMaker training API calls were set with Managed Spot Instance usage activated, which contributed to a reported savings of 71% compared to the on-demand Amazon SageMaker price. Amazon SageMaker Managed Spot Training is an Amazon SageMaker feature that enables the use of Amazon Elastic Compute Cloud (Amazon EC2) Spot Instance capacity for training. Amazon EC2 Spot Instances allow you to purchase unused Amazon EC2 computer capacity at a highly-reduced rate. In Amazon SageMaker, Spot Instance usage is fully managed by the service, and you can invoke it by setting two training SDK parameters:

• train_use_spot_instances=True to request usage of Amazon SageMaker Spot Instances
• train_max_wait set to the maximal acceptable waiting time in seconds

Cost-efficient inference with the Amazon SageMaker training API

In this research initiative, inference interruptions and delayed instantiation were acceptable to the end-user. Consequently, to further optimize costs, the team also used the Amazon SageMaker training API to run inference code, so that managed Amazon SageMaker Spot Instances could be used for inference too. Using the training API came with the additional benefit of a simpler learning curve because the same API is used for both steps of the model life cycle.

Time and cost savings

By applying those four steps, Olexya successfully ported an on-premises Caffe2 deep computer vision detection model to Amazon SageMaker for both training and inference. More impressively, the team completed that onboarding in about 3 weeks, and reported that the training time of the model was reduced from 3 days to 10 hours! The team further estimated that Amazon SageMaker allows a 71% total cost of ownership (TCO) reduction compared the locally available on-premises GPU fleet. A number of extra optimization techniques could reduce the costs even more, such as intelligent hyperparameter search with Amazon SageMaker automatic model tuning and mixed-precision training with the deep learning frameworks that support it.

In addition to SNCF Réseau, numerous AWS customers operating in transportation and logistics have improved their operations and delivered innovation by applying ML to their business. For example:

• The Dubai-based logistics company Aramex uses ML for address parsing and transit time prediction. The company reports having 150 models in use, doing 450,000 predictions per day.
• Transport for New South Wales uses the cloud to predict patronage numbers across the entire transport network, which enables the agency to better plan workforce and asset utilization and improve customer satisfaction.
• Korean Air launched innovative projects with Amazon SageMaker to help predict and preempt maintenance for its aircraft fleet.

Conclusion

Amazon SageMaker supports the whole ML development cycle, from annotation to production deployment and monitoring. As illustrated by the work of Olexya and SNCF Réseau, Amazon SageMaker is framework-agnostic and accommodates a variety of deep learning workloads and frameworks. Although Docker images and SDK objects have been created to closely support Sklearn, TensorFlow, PyTorch, MXNet, XGBoost, and Chainer, you can bring custom Docker containers to onboard virtually any framework, such as PaddlePaddle, Catboost, R, or Caffe2. If you are an ML practitioner, don’t hesitate to test the service, and let us know what you build!

About the Authors

Olivier Cruchant is a Machine Learning Specialist Solution Architect at AWS, based in Lyon, France. Olivier helps French customers – from small startups to large enterprises – develop and deploy production-grade machine learning applications. In his spare time, he enjoys reading research papers and exploring the wilderness with friends and family.

Samuel Descroix is head manager of the Geographic and Analytic Data department at SNCF Réseau. He is in charge of all project teams and infrastructures. To be able to answer to all new use cases, he is constantly looking for most innovative and most relevant solutions to manage growing volumes and needs of complex analysis.

Alain Rivero is Project Manager in the Technology and Digital Transformation (TTD) department within the General Industrial and Engineering Department of SNCF Réseau. He manages projects implementing in-depth learning solutions to detect defects on rolling stock and tracks to increase traffic safety and guide decision-making within maintenance teams. His research focuses on image processing methods, supervised and unsupervised learning and their applications.

Pierre-Yves Bonnefoy is data architect at Olexya, currently working for SNCF Réseau IT department. One of his main assignments is to provide environments and sets of datas for Data Scientists and Data Analysts to work on complex analysis, and to help them with software solutions. Thanks to his large range of skills in development and system architecture, he accelerated the deployment of the project on Sagemaker instances, rationalization of costs and optimization of performance.

Emeric Chaize is certified Solution Architect in Olexya, currently working for SNCF Réseau IT department. He is in charge of Data Migration Project for IT Data Departement, with the responsabilty of covering all needs and usages of the company in data analysis. He defines and plans deployment of all the needed infrastructure for projects and Data Scientists.

Read More

You can use Amazon Lex to build a question and answer chatbot. However, if you live in a non-English-speaking country or your business has global reach, you will want a multilingual bot to cater to all your users. This post describes how to achieve that by using the multi-language functionality of your question and answer bot (QnABot).

The QnABot can detect the predominant language in an interaction by using Amazon Comprehend, a natural language processing (NLP) service that uses machine learning to find insights and relationships in text.

The bot then uses Amazon Translate, a neural machine translation service to translate the question to English. Then it can return a preconfigured answer in the end user’s language or translate it back from the default English text.

Although QnABot allows the end-user to interact with an Amazon Lex bot using text or voice, the multilingual feature primarily supports text interactions. Multilingual voice interactions are currently limited to use with Alexa skills.

The solution consists of three easy steps:

1. Configure the multi-language functionality.
2. Set up the alternate curated answers in a different language.
3. Configure your Alexa skill with multiple languages.

For instructions on creating and customizing your bot, see Create a Question and Answer Bot with Amazon Lex and Amazon Alexa or the Q&A Self-Paced Guide. You can also see the following videos on YouTube:

• Deploying Q&A Chatbot Using Cloudformation
• Using the Q&A Chatbot Content Designer, Question Bank and Trying the Chat Experience
• How to Enable Multi-language Support in Q&A Chatbot
• Creating a Alexa Experience from Q&A Chatbot

Prerequisites

To implement this solution, you must have an AWS account. If you don’t have a professional account, the AWS Free Tier lets you gain experience with the AWS platform, products, and services.

You also need to deploy QnABot. If you have not already done so, launch the QnABot on an AWS CloudFormation stack in one of the available Regions.

When specifying your stack name, include QnA in the name, for example, MultiLangQnABot.

After you successfully deploy your CloudFormation stack, complete the following steps:

1. Open the content designer page of your chatbot.

If this is the first time accessing the chatbot design console, you can find the correct URL on the AWS CloudFormation console on the Output tab of your bot stack. Look for the value for the ContentDesignerURL key. You should also receive an email with temporary credentials to access the QnABot designer.

2. On the designer page, choose the menu icon.
3. Under Tools, choose Import.
   
4. Expand the Examples/Extensions
5. Next to blog-samples, choose Load.
   

Configuring the multi-language functionality

You are now ready to configure the multi-language functionality. Complete the following steps:

1. In the content designer page, under Tools, choose Settings.
2. For the ENABLE_MULTI_LANGUAGE_SUPPORT parameter, change the value from false to true.
   
3. Choose Save.
4. To test the bot, open the client webpage.
5. From the designer page, under Tools, choose QnABot Client.
   
6. Enter the following questions (in English, Spanish, and French):
   • How do I modify Q and A Bot content ?
   • ¿Cómo modifico el contenido de Q y A Bot ?
   • Comment modifier le contenu Q et A Bot ?

The chatbot answers each time in the language you used, as shown in the following animation.

The QnABot is successfully using Amazon Translate to translate the answer automatically into the user’s native language.

Setting up alternate curated answers in a different language

You might need to provide a more natural experience and want to add a curated answer in the native language of your choice. To further customize the translation for each question, you can use the {{handlebar}} functionality. The QnABot provides the {{handlebar}} function ifLang, which takes the locale as a quoted parameter. You can use any of the languages that Amazon Translate supports. For more information, see What Is Amazon Translate?

For example, to customize the translation in Spanish, the ifLang function uses es as the locale parameter. See the following code:

{{#ifLang 'es'}}
          Su traducción al español
{{/ifLang}}

Additionally, if an unknown language is detected, you can support that with a default response by using the defaultLang function. See the following code:

{{#defaultLang}}
          Your default language answer
{{/defaultLang}}

As an example, modify the question you used earlier. Go back to the content designer and complete the following steps:

1. Under Tools, choose Edit.
2. Select 001 and choose the pencil icon on the right.
   
3. Replace the text in the answer with the following code:

   {{#ifLang 'es'}}
   Use las herramientas de 'Question and Test' de 'Content Designer' para encontrar sus documentos existentes y editarlos directamente en la consola. También puede exportar documentos existentes como un archivo JSON, realizar cambios en el archivo y volver a importar.
   {{/ifLang}}
   {{#ifLang 'fr'}}
   Utilisez les outils 'Question and Test' de 'Content Designer' pour trouver vos documents existants et les modifier directement dans la console. Vous pouvez également exporter des documents existants sous forme de fichier JSON, apporter des modifications au fichier et réimporter.
   {{/ifLang}}
   {{#defaultLang}} 
   Use the Content Designer Question and Test tools to find your existing documents and edit them directly in the console. You can also export existing documents as a JSON file, make changes to the file, and re-import.
   {{/defaultLang}}
   

   Multi-language and handlebars, in general, also support markdown answers. For example, you could modify the preceding code to highlight the name of the interface that isn’t translated. See the following code:

   {{#ifLang 'es'}}
   Use las herramientas de ***'Question and Test'*** de ***'Content Designer'*** para encontrar sus documentos existentes y editarlos directamente en la consola. También puede exportar documentos existentes como un archivo JSON, realizar cambios en el archivo y volver a importar.
   {{/ifLang}}
   {{#ifLang 'fr'}}
   Utilisez les outils ***'Question and Test'*** de ***'Content Designer'*** pour trouver vos documents existants et les modifier directement dans la console. Vous pouvez également exporter des documents existants sous forme de fichier JSON, apporter des modifications au fichier et réimporter.
   {{/ifLang}}
   {{#defaultLang}} 
   Use the ***Content Designer Question and Test*** tools to find your existing documents and edit them directly in the console. You can also export existing documents as a JSON file, make changes to the file, and re-import.
   {{/defaultLang}}
   

4. Choose Advanced and enter the new code in the Markdown Answer box.
   
   
5. Choose Update.

If you try to ask your questions again, the answers are different because the chatbot is using your curated version.

You can also import the sample or extension named Language / Multiple Language Support.

This adds two questions to the system: Language.000 and Language.001. The first question allows the end-user to set their preferred language explicitly; the latter resets the preferred language and allow the QnABot to choose the locale based on the automatically detected predominant language.

Debugging the answers in a different language

You can use the ENABLE_DEBUG_RESPONSES setting to see how local language questions are translated to English by QnABot, and to tune the content as needed to ensure QnABot finds the best answer to a non-English question.

Complete the following steps to set up and test:

1. In the content designer page, under Tools, choose Settings.
2. For the ENABLE_DEBUG_RESPONSES parameter, change the value from false to true.
   
3. Choose Save.
4. To test the bot, open the client webpage.
5. From the designer page, under Tools, choose QnABot Client.
6. Try one of the question we used before, you can read the translation and use this information to tune your answer.
   

Configuring your Alexa skill with multiple languages

You first need to create your Alexa skill. For instructions, see Create a Question and Answer Bot with Amazon Lex and Amazon Alexa.

When your Alexa skill is working, add the additional languages by completing the following steps:

1. On the Alexa developer console, open your skill.
2. From the drop-down menu with your default language, choose Language settings.
   
3. Add all the languages you want to support and choose Save.
   
4. Under CUSTOM, choose JSON Editor.
   
5. Copy the JSON from the editor, switch to the other language you want to support, and enter it in the editor pane (this overwrites the default).
6. Choose Save Model.
   
7. Choose Invocation and change the invocation name.
8. Choose Save Model.
   
9. Repeat these steps for any language you want to support.
10. Build the model.

Testing your Alexa skill

You can now test your Alexa skill in other languages.

1. On the Alexa developer console, select your skill.
2. Choose Test.
3. Change the language and type the invocation name of your skill for that language.
4. After Alexa gives her initial greeting, ask the question you used before or any other question you added in the content designer.

Alexa answers you in the selected language.

Now your multilingual chatbot can be published on your website or as an Alexa skill. To integrate the QnABot in your website, you can use lex-web-ui. For instructions, see Deploy a Web UI for your Chatbot.

Conclusion

This post shows you how to configure and use the out-of-the-box feature of your QnABot to localize answers in any language Amazon Translate supports. It is an inexpensive way to deploy a multi-language chatbot, and you don’t need to adapt it to accommodate new Amazon Lex features.

As of this writing, this approach works for text-based interactions only; support for voice is limited to use with Alexa skills only.

For more information about experimenting with the capabilities of QnABot, see the Q&A Self-Paced Guide.

About the Authors

Fabrizio is a Specialist Solutions Architect for Database and Analytics in the AWS Canada Public Sector team. He has worked in the analytics field for the last 20 years, and has recently, and quite by surprise, become a Hockey Dad after moving to Canada.

As a Solutions Architect at AWS supporting our Public Sector customers, Raj excites customers by showing them the art of the possible of what they can build on AWS and helps accelerate their innovation. Raj loves solving puzzles, mentoring, and supporting hackathons and seeing amazing ideas come to life.

Read More