Guidance for Dynamic Non-Player Character (NPC) Dialogue on AWS

Table of Content

1. Overview
   • Architecture
   • Cost
2. Prerequisites
   • Operating System
   • Third-party tools
   • AWS account requirements
   • aws cdk bootstrap
   • Supported Regions
3. Deployment Steps
4. Deployment Validation
5. Running the Guidance
   • Quality Assurance
   • Hydrating the vector store
   • Unreal Engine sample project
6. Next Steps
7. Cleanup

Overview

Typical player interactions with NPCs are static, and require large teams of script writers to create static dialog content for each character, in each game, and each game version to ensure consistency with game lore. This Guidance helps game developers automate the process of creating a non-player character (NPC) for their games and associated infrastructure. It uses Unreal Engine MetaHuman, along with foundation models (FMs), for instance the large language models (LLMs) Claude 2, and Llama 2, to improve NPC conversational skills. This leads to dynamic responses from the NPC that are unique to each player, adding to scripted dialogue. By using the Large Language Model Ops (LLMOps) methodology, this Guidance accelerates prototyping, and delivery time by continually integrating, and deploying the generative AI application, along with fine-tuning the LLMs. All while helping to ensure that the NPC has full access to a secure knowledge base of game lore, using retrieval-augmented generation (RAG).

If you're looking for quick and easy step by step guide to get started, check out the Workshop - Operationalize Generative AI Applications using LLMOps.

Architecture

Cost

You are responsible for the cost of the AWS services used while running this Guidance. As of January 2024, the cost for running this Guidance with the default settings in the us-east-1 (N. Virginia) AWS Region is approximately $590.59 per month for processing 100 records.

For example, the following table shows a break-down of approximate costs (per month) to process 100 requests, using an Amazon OpenSearch Service vector database for RAG:

Service	Cost (per month)
OpenSearch Service	$586.65
SageMaker	$1.43
S3	$0.67
CodeBuild	$0.34
Secrets Manager	$0.20
Bedrock	$1.30
Total	$590.59

Prerequisites

Operating System

These deployment instructions are optimized to best work on a pre-configured Amazon Linux 2023 AWS Cloud9 development environment. Refer to the Individual user setup for AWS Cloud9 for more information on how to set up Cloud9 as a user in the AWS account. Deployment using another OS may require additional steps, and configured python libraries (see Third-party tools).

The Unreal Engine sample project has been tested using a Windows 2019 (g4dn.4xlarge) EC2 instance. See the Stream a remote environment with NICE DCV over QUIC UDP for a 4K monitor at 60 FPS blog post, for more information on setting up a similar environment.

NOTE: A Github dev container configuration has been provided should you wish to use GitHub codespaces, or Visual Studio Code Dev Containers as your development environment.

Third-party tools

Before deploying the guidance code, ensure that the following required tools have been installed:

• AWS Cloud Development Kit (CDK) >= 2.126.0
• Python >= 3.8
• NodeJS >= 18

NOTE: The Guidance has been tested using AWS CDK version 2.126.0. If you wish to update the CDK application to later version, make sure to update the requirements.txt, and cdk.json files, in the root of the repository, with the updated version of the AWS CDK.

• Unreal Engine 4.26 or 4.27.
• Microsoft Visual Studio 2019 for Unreal Engine 4 C++ development.
• Microsoft Visual Studio Code for editing.

NOTE: If you need help with these setup steps, refer to the Unreal Engine 4 documentation, especially "Setting Up Visual Studio for Unreal Engine". The was only tested with Visual Studio 2019 with Unreal Engine 4.27. The Unreal Engine sample DOES NOT work with Ureal Engine 5.

AWS account requirements

This deployment requires that you have an existing Amazon SageMaker Domain in your AWS account. A SageMaker Domain is required in order to provide access to monitor, and track the following SageMaker resources:

• SageMaker Pipelines
• SageMaker Model Registry

NOTE: See the Quick onboard to Amazon SageMaker Domain section of the Amazon SageMaker Developer Guide for more information on how to configure an Amazon SageMaker Domain in your AWS account.

• Bedrock Model Access
  • Anthropic Claude
  • Amazon Titan Embeddings G1 - Text

NOTE: AWS accounts do not have access to models by default, see the Model access section of the Amazon Bedrock User Guide to request access to the Claude v2, and Titan Embeddings foundation models.

aws cdk bootstrap

This Guidance uses AWS CDK. If you are using aws-cdk for the first time, please see the Bootstrapping section of the AWS Cloud Development Kit (AWS CDK) v2 developer guide, to provision the required resources, before you can deploy AWS CDK apps into an AWS environment.

NOTE: Since the guidance leveraged CDK PIpelines, it is recommended that you re-bootstrap the CDK, even if you have already bootstrapped the CDK.

Supported Regions

All features for this guidance are only available in the US East (N. Virginia) and US West (Oregon) AWS regions.

Deployment Steps

1. In the Cloud9 IDE, use the terminal to clone the repository:

   git clone https://github.com/aws-solutions-library-samples/guidance-for-dynamic-game-npc-dialogue-on-aws dynamic-npc

2. Change to the repository root folder:

   cd dynamic-npc

3. Initialize the Python virtual environment:

   python3 -m venv .venv

4. Activate the virtual environment:

   source .venv/bin/activate

5. Install the necessary python libraries in the virtual environment:

   python -m pip install -r requirements.txt

6. Open the constants.py file for editing. The following settings can be adjusted to suite your use case:
   • WORKLOAD_NAME
     • Description: The name of the workload that matches your use case. This will be used as a prefix for an component deployed in your AWS account.
     • Type: String
     • Default: "Ada"
   • REGION
     • Description: The name of the AWS region into which you want to deploy the use case.
     • Type: String
     • Example: "us-east-1"
   • SM_DOMAIN_ID
     • Description: The ID for your prerequisite Amazon SageMaker Domain in your configured AWS region. You can view the ID for your domain in the AWS Console, or by running the aws sagemaker list-domains --query "Domains[*].DomainId" --output text command.
     • Type: String
     • Example: "d-abcdef12gh3i"
   • QA_ENV_NAME
     • Description: The name of the "Quality Assurance" stage of the LLMOps pipeline.
     • Type: String
     • Default: "QA"
   • PROD_ENV_NAME
     • Description: The name of the "Production" stage of the LLMOps pipeline.
     • Type: String
     • Default: "PROD"
7. Save the constants.py file after updating your use case settings.
8. Verify that the CDK deployment correctly synthesizes the CloudFormation template:

   cdk synth

9. Deploy the guidance:

   cdk deploy --require-approval never

Deployment Validation

To verify a successful deployment of this guidance, open CloudFormation console, and verify the status of the stack infrastructure stack is CREATE_COMPLETE. For example, if your WORKLOAD_NAME parameter is Ada, CloudFormation will reflect that the Ada-Toolchain stack has a CREATE_COMPLETE status.

Running the Guidance

Quality Assurance

Once the deployment has been validated, you can deploy the infrastructure into the QA stage, as part of an LLMOps pipeline, using the following steps:

1. Once the toolchain stack has been deployed, use the Cloud9 IDE, to initialize the main branch:

   rm -rf .git && \
   git init --initial-branch=main

2. Add the newly AWS CodeCommit repository as the upstream origin, substituting the appropriate WORKLOAD_NAME, and REGION parameters. For example if your WORKLOAD_NAME parameter is Ada, and the REGION is us-east-1, the the repository url is https://git-codecommit.us-east-1.amazonaws.com/v1/repos/ada,

   git remote add origin https://git-codecommit.<REGION>.amazonaws.com/v1/repos/<WORKLOAD_NAME>

   NOTE: The WORKLOAD_NAME is lower case.

3. Add the source code to to trigger a CI/CD/CT pipeline execution.

   git add -A
   
   git commit -m "Initial commit"
   
   git push --set-upstream origin main

4. Open the CodePipeline console, and click on the LLMOps pipeline for the workload. For example, if your WORKLOAD_NAME parameter is Ada, CodePipeline will reflect that the Ada-Pipeline is In progress.

Once the QA stage of the pipeline is complete, and the SystemTest stage action is successful, indicating the backend infrastructure is deployed, you can hydrate the vector store.

Hydrating the vector store

The following steps will demonstrate how to hydrate the Amazon OpenSearch Service vector database for RAG:

1. Download a copy of Treasure Island by Robert Louis Stevenson to test vector store hydration and RAG.
2. Using the AWS Console, navigate to Amazon S3 service, and select the bucket with the following format, <WORKLOAD NAME>-qa-<REGION>-<ACCOUNT NUMBER>. For example, ada-qa-us-east-1-123456789.
3. Upload the Treasure Island File, by clicking on the upload button, and selecting the file pg120.txt file. This will trigger the AWS Lambda function that starts a an Amazon SageMaker Processing Job to hydrate the Amazon OpenSearch Service database.
4. Open the SageMaker console. Using the navigation panel on the left-hand side, expand the Processing option, and then select Processing jobs. You'll see a processing job has been started, for example Ada-RAG-Ingest-01-21-20-13-20. This jobs executes the process of chunking the ebook data, converting it to embeddings, and hydrating the database.
5. Clink on the running processing job to view its configuration. Under the Monitoring, click the View logs link to see see the processing logs for your job in Amazon CloudWatch. After roughly 5 minutes, the log stream becomes available, and after clicking on the log stream, you will see that each line of the log output represents the successful processing of a chunk of the text inserted into the vector store. For example:

NOTE: The Treasure Island by Robert Louis Stevenson is available for reuse under the terms of the Project Gutenberg License, included with the ebook or online at www.gutenberg.org.

Unreal Engine sample project

An Unreal Engine sample project, AmazonPollyMetaHuman, has been provided for download. This sample MetaHuman digital character can be used to showcase dynamic NPC dialog. Use the following steps to integrate the sample MetaHuman with the deployed guidance infrastructure:

1. Open the IAM console in your AWS account, create a new IAM user.
2. Assign the AmazonPollyReadOnlyAccess policy to the newly created user.
3. Create a new access key for the user.
4. Install and configure the AWS CLI on the computer that will run the Unreal Engine sample project to use the Access Key ID, and Secret Access Key values for the IA M user you created previously.
5. Using the CloudFormation console, click the deployed QA stack. For example, if your WORKLOAD_NAME parameter is Ada, CloudFormation will reflect that Ada-QA as the deployed QA stack.
6. Select the Outputs tab, and capture the values for TextApiEndpointUrl, and RagApiEndpointUrl.
7. Download, the AmazonPollyMetaHuman zipped Unreal Engine project.
8. Extract the AmazonPollyMetaHuman project folder to the Unreal Projects folder of the Unreal Engine development environment.
9. Launch Unreal Engine 4.27, and open the AmazonPollyMetaHuman sample project.
10. Using the Unreal Editor, select File --> Generate Visual Studio Code Project to use VS Code for editing source code.
11. Using the Unreal Editor, select File --> Open Visual Studio Code to open the project for code editing.
12. In VS Code, open the /Source/AmazonPollyMetaHuman/Private/Private/SpeechComponent.cpp file for editing.
13. Navigate to the following code section, and replace the ComboboxUri variables with the TextApiEndpointUrl, and RagApiEndpointUrl CloudFormation outputs.

        void USpeechComponent::CallAPI(const FString Text, const FString Uri)
        {
            FString ComboBoxUri = "";
            FHttpRequestRef Request = FHttpModule::Get().CreateRequest();
            UE_LOG(LogPollyMsg, Display, TEXT("%s"), *Uri);
            if(Uri == "Regular LLM")
            {
                UE_LOG(LogPollyMsg, Display, TEXT("If Regular LLM"));
                ComboBoxUri = "<ADD `TextApiEndpointUrl` VALUE FROM GUIDANCE DEPLOYMENT>";
            } else {
                UE_LOG(LogPollyMsg, Display, TEXT("If Else"));
                
                ComboBoxUri = "<ADD `RagApiEndpointUrl` VALUE FROM GUIDANCE DEPLOYMENT>";
            }

14. Save the SpeechComponent.cpp file, and close VS Code.
15. Using the Unreal Editor, click the Compile button to recompile the C++ code.
16. Once the updated code has been compiled, click the Play button to interact with the Ada NPC.

NOTE: Review the detailed installation guide for Windows 2019 for more information on installing, and configuring both Unreal Engine, and the sample project.

Next Steps

Once the sample application has been validated using the QA deployment, you can deploy the infrastructure into production, as part of an LLMOps pipeline, using the following steps:

1. Using the Cloud9 IDE, open the stacks/toolchain.py file for editing.
2. Uncomment the following code to enable the PROD, and TUNING stages of the LLMOps pipeline:

   # Add Production Stage
   ToolChainStack._add_stage(
       pipeline=pipeline,
       stage_name=constants.PROD_ENV_NAME,
       stage_account=self.account,
       stage_region=self.region,
       model_parameter_name="CustomModelName"
   )
   
   # Add tuning stack as CT stage
   ToolChainStack._add_stage(
       pipeline=pipeline,
       stage_name="TUNING",
       stage_account=self.account,
       stage_region=self.region,
       model_parameter_name="CustomModelName"
   )

3. Save the toolchain.py file.
4. Commit the updates to the source repository using the following commands:

   git add -A
   
   git commit -m "Enabled PROD and TUNING stages"
   
   git push

5. Open the CodePipeline console, and click on the LLMOps pipeline for the workload. For example, if your WORKLOAD_NAME parameter is Ada, CodePipeline will reflect that the Ada-Pipeline is In progress.

NOTE: Review the Continuous Tuning using FMOps section of the Operationalize Generative AI Applications using LLMOps workshop for a step-by-step guide to implementing continuous fine-tuning of a custom foundation model for the use case.

Cleanup

To delete the deployed resources, use the AWS CDK CLI to run the following steps:

1. Using the Cloud9 terminal window, change to the root of the cloned repository:

   cd ~/environment/dynamic-npc

2. Run the command to delete the CloudFormation stack:

   cdk destroy

3. When prompted, Are you sure you want to delete, enter y to confirm stack deletion.
4. Use the CloudFormation console to manually delete the following stacks in order. For example, if your WORKLOAD_NAME parameter is Ada, CloudFormation will reflect that the QA stack is Ada-QA.
   • <WORKLOAD_NAME>-Tuning
   • <WORKLOAD_NAME>-PROD
   • <WORKLOAD_NAME>-QA

NOTE: Deleting the deployed resources will not delete the Amazon S3 bucket, in order to protect any training data already stored. See the Deleting a bucket section of the Amazon Simple Storage Service user guide for the various ways to delete the S3 bucket.