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, 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, Tools, and Configuration

These deployment instructions are optimized to best work on a Amazon Linux 2023 based development environment. Deployment using another OS may require additional steps, and configured Python libraries (see Third-party tools). The instructions also use the GitHub fork feature that will connect to AWS CodePipeline. Once the project is deployed, you may use any code editor and Git client to make and push changes to your fork. When developing this project, we used Visual Studio Code and its Git integration.

The Unreal Engine sample project has been tested using a Windows 2022 Datacenter (g5.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.178.2
• Python >= 3.8
• NodeJS >= 18

NOTE: The Guidance has been tested using AWS CDK version 2.178.2. 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 2022 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 2022 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. Make a fork of this project in GitHub. Select Fork and follow the instructions to create a fork in your own GitHub account.
2. Connect GitHub to the AWS Developer Tools in the AWS Console. Though this could be done in the CDK scripts, you would still need to verify the connection in the AWS Console, so it's easier to make the connection there:
   • a. Open the AWS Management Console, and switch to the region where you will deploy the project
   • b. Navigate to the CodePipeline service
   • c. In the left navigation pane, choose "Settings" and then "Connections"
   • d. Select "Create Connection"
   • e. Choose "GitHub" as the provider
   • f. Name the connection "DynamicNPC"
   • g. Select "Connect to GitHub"
   • h. Authorize AWS Connector for GitHub (you may need to log in to GitHub if you aren't already)
   • i. Leave the defaults, and select "Connect"
   • j. Keep a note of the Arn for the connection

NOTE: Verify the configuration in GitHub to ensure that the AWS Connector for GitHub has access to the repository.

3. Clone the repository. Note that you will need to provide a personal access token, or authenticate in some other way:

   git clone https://github.com/[your GitHub user name]/guidance-for-dynamic-game-npc-dialogue-on-aws dynamic-npc

4. Change to the repository root folder:

   cd dynamic-npc

5. Initialize the Python virtual environment:

   python3 -m venv .venv

6. Activate the virtual environment:

   source .venv/bin/activate

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

   python3 -m pip install -r requirements.txt

8. Type nano constants.py to 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"
   • GITHUB_REPO_NAME
     • Description: The name of your forked GitHub repo, including your username in the format github_username/repo_name.
     • Type: String
     • Example: "my-github-username/guidance-for-dynamic-game-npc-dialogue-on-aws"
   • CODESTAR_CONNECTION_ARN
     • Description: The Arn for the CodeStar Connection you noted above
     • Type: String
     • Example: "arn:aws:codeconnections:us-east-1:555555555555:connection/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
   • 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"
9. Save the constants.py file after updating your use case settings.
10. Verify that the CDK deployment correctly synthesizes the CloudFormation template:

    cdk synth

11. 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, add the source code to trigger a CI/CD/CT pipeline execution:

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

   NOTE: Specifies that you want to push to the main branch.

2. 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 2022 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. 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. Change to the root of the cloned repository:

   cd 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
5. Remove the git repository with the commands:

   cd ~
   rm -r dynamic-npc

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.