guidance for natural language queries of relational databases on aws
1.0.0
此 AWS 解決方案包含生成式 AI 的演示，特別是使用自然語言查詢 (NLQ) 向 Amazon RDS for PostgreSQL 資料庫提出問題。此解決方案為基礎模型提供了三種架構選項：1. Amazon SageMaker JumpStart、2. Amazon Bedrock 和 3. OpenAI API。該演示的基於 Web 的應用程式在 AWS Fargate 上的 Amazon ECS 上運行，結合使用了 LangChain、Streamlit、Chroma 和 HuggingFace SentenceTransformers。該應用程式接受最終用戶的自然語言問題並傳回自然語言答案，以及關聯的 SQL 查詢和 Pandas DataFrame 相容的結果集。
自然語言查詢 (NLQ) 的基礎模型 (FM) 的選擇對於應用程式能否準確地將自然語言問題翻譯為自然語言答案至關重要。並非所有 FM 都能夠執行 NLQ。除了模型選擇之外，NLQ 的準確性也很大程度取決於提示的品質、提示範本、用於上下文學習的標記樣本查詢（也稱為少樣本提示）以及用於資料庫模式的命名約定等因素。
NLQ 應用程式在各種開源和商業 FM 上進行了測試。作為基準，OpenAI 的生成式預訓練 Transformer GPT-3 和 GPT-4 系列模型（包括gpt-3.5-turbo和gpt-4 ）均使用平均值為各種簡單到複雜的自然語言查詢提供準確的回應大量的情境學習和最少的即時工程。
Amazon Titan Text G1 - Express、 amazon.titan-text-express-v1 （可透過 Amazon Bedrock 取得）也經過了測試。該模型使用一些特定於模型的提示最佳化來提供對基本自然語言查詢的準確回應。然而，該模型無法回應更複雜的查詢。進一步及時優化可以提高模型精度。
開源模型，例如google/flan-t5-xxl和google/flan-t5-xxl-fp16 （完整模型的半精度浮點格式 (FP16) 版本）可透過 Amazon SageMaker JumpStart 取得。雖然google/flan-t5系列模型是建立生成式 AI 應用程式的熱門選擇，但與較新的開源和商業模型相比，它們的 NLQ 功能有限。該演示的google/flan-t5-xxl-fp16能夠透過充分的上下文學習來回答基本的自然語言查詢。然而，它在測試過程中經常無法返回答案或提供正確答案，並且在面對中度到複雜的查詢時，經常會因資源耗盡而導致 SageMaker 模型端點逾時。
此解決方案使用開源資料庫的 NLQ 優化副本，即現代藝術博物館 (MoMA) 收藏（可在 GitHub 上取得）。 MoMA 資料庫包含超過 121,000 件藝術品和 15,000 名藝術家。此專案儲存庫包含以垂直線分隔的文字文件，可輕鬆匯入 Amazon RDS for PostgreSQL 資料庫執行個體中。
使用 MoMA 資料集，我們可以提出不同複雜程度的自然語言問題：
同樣，NLQ 應用程式返回答案和返回準確答案的能力主要取決於模型的選擇。並非所有模型都能夠進行 NLQ，而其他模型則不會返回準確的答案。針對特定型號最佳化上述提示有助於提高準確度。
google/flan-t5-xxl-fp16為ml.g5.24xlarge ） google/flan-t5-xxl-fp16型號）。有關實例類型的選擇，請參閱模型的文件。NlqMainStack CloudFormation 範本。請注意，您的帳戶中至少需要使用一個 Amazon ECS，否則AWSServiceRoleForECS服務相關角色將不存在且堆疊將失敗。在部署NlqMainStack堆疊之前檢查AWSServiceRoleForECS服務相關角色。該角色是您首次在帳戶中建立 ECS 叢集時自動建立的。nlq-genai:2.0.0-sm Docker 映像並將其推送到新的 Amazon ECR 儲存庫。或者，建置並推送nlq-genai:2.0.0-bedrock或nlq-genai:2.0.0-oai Docker 映像，以便與選項 2：Amazon Bedrock 或選項 3：OpenAI API 結合使用。nlqapp用戶加入 MoMA 資料庫。NlqSageMakerEndpointStack CloudFormation 範本。NlqEcsSageMakerStack CloudFormation 範本。或者，部署NlqEcsBedrockStack CloudFormation 範本以與選項 2：Amazon Bedrock 結合使用，或部署NlqEcsOpenAIStack範本以與選項 3：OpenAI API 結合使用。對於選項 1：Amazon SageMaker JumpStart，請確保您擁有 Amazon SageMaker JumpStart 終端節點推理所需的 EC2 實例，或者使用 AWS 管理控制台中的服務配額請求它（例如，對於google/flan-t5-xxl-fp16為ml.g5.24xlarge ） google/flan-t5-xxl-fp16型號）。有關實例類型的選擇，請參閱模型的文件。
請確保在繼續之前更新下面的秘密值。此步驟將為 NLQ 應用程式的憑證建立機密。 NLQ 應用程式對資料庫的存取僅限於唯讀。對於選項 3：OpenAI API，此步驟將建立一個金鑰來儲存您的 OpenAI API 金鑰。 Amazon RDS 執行個體的主用戶憑證會自動設定並儲存在 AWS Secret Manager 中，作為NlqMainStack CloudFormation 範本部署的一部分。這些值可以在 AWS Secret Manager 中找到。
aws secretsmanager create-secret
--name /nlq/NLQAppUsername
--description " NLQ Application username for MoMA database. "
--secret-string " <your_nlqapp_username> "
aws secretsmanager create-secret
--name /nlq/NLQAppUserPassword
--description " NLQ Application password for MoMA database. "
--secret-string " <your_nlqapp_password> "
# Only for Option 2: OpenAI API/model
aws secretsmanager create-secret
--name /nlq/OpenAIAPIKey
--description " OpenAI API key. "
--secret-string " <your_openai_api_key "對 ALB 和 RDS 的外部存取將僅限於您目前的 IP 位址。如果您的 IP 位址在部署後發生變化，您將需要更新。
cd cloudformation/
aws cloudformation create-stack
--stack-name NlqMainStack
--template-body file://NlqMainStack.yaml
--capabilities CAPABILITY_NAMED_IAM
--parameters ParameterKey= " MyIpAddress " ,ParameterValue= $( curl -s http://checkip.amazonaws.com/ ) /32根據您選擇的模型選項，建立 NLQ 應用程式的 Docker 映像。您可以使用 SageMaker Notebook 環境或 AWS Cloud9 在 CI/CD 管道中本機建置 Docker 映像。我更喜歡使用 AWS Cloud9 來開發和測試應用程式以及建立 Docker 映像。
cd docker/
# Located in the output from the NlqMlStack CloudFormation template
# e.g. 111222333444.dkr.ecr.us-east-1.amazonaws.com/nlq-genai
ECS_REPOSITORY= " <you_ecr_repository> "
aws ecr get-login-password --region us-east-1 |
docker login --username AWS --password-stdin $ECS_REPOSITORY選項 1：Amazon SageMaker JumpStart
TAG= " 2.0.0-sm "
docker build -f Dockerfile_SageMaker -t $ECS_REPOSITORY : $TAG .
docker push $ECS_REPOSITORY : $TAG選項 2：亞馬遜基岩
TAG= " 2.0.0-bedrock "
docker build -f Dockerfile_Bedrock -t $ECS_REPOSITORY : $TAG .
docker push $ECS_REPOSITORY : $TAG選項 3：OpenAI API
TAG= " 2.0.0-oai "
docker build -f Dockerfile_OpenAI -t $ECS_REPOSITORY : $TAG .
docker push $ECS_REPOSITORY : $TAG5a.使用您首選的 PostgreSQL 工具連接到moma資料庫。您需要暫時啟用 RDS 執行個體的Public access ，具體取決於您連接到資料庫的方式。
5b.將兩個 MoMA 收藏表建立到moma資料庫中。
CREATE TABLE public .artists
(
artist_id integer NOT NULL ,
full_name character varying ( 200 ),
nationality character varying ( 50 ),
gender character varying ( 25 ),
birth_year integer ,
death_year integer ,
CONSTRAINT artists_pk PRIMARY KEY (artist_id)
)
CREATE TABLE public .artworks
(
artwork_id integer NOT NULL ,
title character varying ( 500 ),
artist_id integer NOT NULL ,
date integer ,
medium character varying ( 250 ),
dimensions text ,
acquisition_date text ,
credit text ,
catalogue character varying ( 250 ),
department character varying ( 250 ),
classification character varying ( 250 ),
object_number text ,
diameter_cm text ,
circumference_cm text ,
height_cm text ,
length_cm text ,
width_cm text ,
depth_cm text ,
weight_kg text ,
durations integer ,
CONSTRAINT artworks_pk PRIMARY KEY (artwork_id)
) 5c.使用/data子目錄中的文字檔案解壓縮並匯入這兩個資料檔案到moma資料庫中。這兩個文件都包含標題行和管道分隔符號（“|”）。
# examples commands from pgAdmin4
--command " "\copy public.artists (artist_id, full_name, nationality, gender, birth_year, death_year) FROM 'moma_public_artists.txt' DELIMITER '|' CSV HEADER QUOTE '"' ESCAPE '''';""
--command " "\copy public.artworks (artwork_id, title, artist_id, date, medium, dimensions, acquisition_date, credit, catalogue, department, classification, object_number, diameter_cm, circumference_cm, height_cm, length_cm, width_cm, depth_cm, weight_kg, durations) FROM 'moma_public_artworks.txt' DELIMITER '|' CSV HEADER QUOTE '"' ESCAPE '''';""建立唯讀 NLQ 應用程式資料庫使用者帳戶。使用您在上面步驟 2 中設定的機密，在三個位置更新 SQL 腳本中的使用者名稱和密碼值。
CREATE ROLE < your_nlqapp_username > WITH
LOGIN
NOSUPERUSER
NOCREATEDB
NOCREATEROLE
INHERIT
NOREPLICATION
CONNECTION LIMIT - 1
PASSWORD ' <your_nlqapp_password> ' ;
GRANT
pg_read_all_data
TO
< your_nlqapp_username > ;選項 1：Amazon SageMaker JumpStart
cd cloudformation/
aws cloudformation create-stack
--stack-name NlqSageMakerEndpointStack
--template-body file://NlqSageMakerEndpointStack.yaml
--capabilities CAPABILITY_NAMED_IAM選項 1：Amazon SageMaker JumpStart
aws cloudformation create-stack
--stack-name NlqEcsSageMakerStack
--template-body file://NlqEcsSageMakerStack.yaml
--capabilities CAPABILITY_NAMED_IAM選項 2：亞馬遜基岩
aws cloudformation create-stack
--stack-name NlqEcsBedrockStack
--template-body file://NlqEcsBedrockStack.yaml
--capabilities CAPABILITY_NAMED_IAM選項 3：OpenAI API
aws cloudformation create-stack
--stack-name NlqEcsOpenAIStack
--template-body file://NlqEcsOpenAIStack.yaml
--capabilities CAPABILITY_NAMED_IAM您可以取代使用NlqSageMakerEndpointStack.yaml CloudFormation 範本檔案部署的預設google/flan-t5-xxl-fp16 JumpStart Foundation 模型。您首先需要修改NlqSageMakerEndpointStack.yaml檔案中的模型參數並更新已部署的 CloudFormation 堆疊NlqSageMakerEndpointStack 。此外，您還需要對 NLQ 應用程式app_sagemaker.py進行調整，修改ContentHandler類別以符合所選模型的回應負載。然後，使用Dockerfile_SageMaker Dockerfile 重建 Amazon ECR Docker 映像，增加版本（例如nlq-genai-2.0.1-sm並推送到 Amazon ECR 儲存庫。最後，您需要更新已部署的 ECS 任務和服務，它們是NlqEcsSageMakerStack CloudFormation 堆疊的一部分。
要從解決方案的預設 Amazon Titan Text G1 - Express ( amazon.titan-text-express-v1 ) 基礎模型切換，您需要修改並重新部署NlqEcsBedrockStack.yaml CloudFormation 範本檔案。此外，您還需要修改 NLQ 應用程式app_bedrock.py然後，使用Dockerfile_Bedrock Dockerfile 重建 Amazon ECR Docker 映像，並將產生的映像（例如nlq-genai-2.0.1-bedrock推送到 Amazon ECR 儲存庫。最後，您需要更新已部署的 ECS 任務和服務，它們是NlqEcsBedrockStack CloudFormation 堆疊的一部分。
從解決方案的預設 OpenAI API 切換到另一個第三方模型供應商的 API（例如 Cohere 或 Anthropic）也同樣簡單。要使用 OpenAI 的模型，您首先需要建立一個 OpenAI 帳戶並取得您自己的個人 API 金鑰。接下來，使用Dockerfile_OpenAI Dockerfile 修改並重建 Amazon ECR Docker 映像，並將產生的映像（例如nlq-genai-2.0.1-oai推送到 Amazon ECR 儲存庫。最後，修改並重新部署NlqEcsOpenAIStack.yaml CloudFormation 範本檔案。
請參閱貢獻以獲取更多資訊。
該庫根據 MIT-0 許可證獲得許可。請參閱許可證文件。
