本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 整合指南 整個解決方案的設計可輕鬆擴充。此解決方案的協同運作層是使用 [LangChain](https://www.langchain.com/) 建置。您可以將 LangChain （或為這些元件提供 LangChain 連接器的第三方） 支援的任何模型提供者、知識庫或對話記憶體類型新增至此解決方案。 ## 展開支援的 LLMs 若要新增另一個模型提供者，例如自訂 LLM 提供者，您必須更新解決方案的下列三個元件： 1. 建立新的 `TextUseCase` CDK 堆疊，部署使用自訂 LLM 提供者設定的聊天應用程式： 1. 複製此解決方案的 [GitHub 儲存庫](https://github.com/aws-solutions/generative-ai-application-builder-on-aws)，並遵循 [README.md](https://github.com/aws-solutions/generative-ai-application-builder-on-aws/blob/main/README.md) 檔案中提供的指示來設定您的建置環境。 1. 複製 （或建立新的） `source/infrastructure/lib/bedrock-chat-stack.ts` 檔案，將其貼到相同的目錄，並將其重新命名為 `custom-chat-stack.ts`。 1. 將 檔案中的 類別重新命名為適當的類別，例如 `CustomLLMChat`。 1. 您可以選擇將 Secrets Manager 秘密新增至此堆疊，以存放自訂 LLM 的登入資料。您可以在下一段討論的聊天 Lambda 層中，在模型調用期間擷取這些登入資料。 1. 建置並連接包含要新增之模型提供者 Python 程式庫的 Lambda 層。對於 Amazon Bedrock 使用案例聊天應用程式，`langchain-aws`Python 程式庫包含 LangChain 套件上方的自訂連接器，以連接至 AWS 模型提供者 (Amazon Bedrock 和 SageMaker AI)、知識庫 (Amazon Kendra 和 Amazon Bedrock 知識庫） 和記憶體類型 （例如 DynamoDB)。同樣地，其他模型提供者也有自己的連接器。此層可協助您連接此模型提供者的 Python 程式庫，以便在聊天 Lambda 層中使用這些連接器，這會叫用 LLM （步驟 3)。在此解決方案中，自訂資產綁定器用於建置使用 CDK 層面連接的 Lambda 層。若要為自訂模型提供者程式庫建立新的 layer： 1. 導覽至 `source/infrastructure/lib/utils/lambda-aspects.ts` 檔案中的 `LambdaAspects`類別。 1. 遵循如何擴展檔案中提供的 Lambda 觀點類別功能的指示 （例如新增 `getOrCreateLangchainLayer`方法）。若要使用此新方法 （例如 `getOrCreateCustomLLMLayer`)，請同時更新 `source/infrastructure/lib/utils/constants.ts` 檔案中的`LLM_LIBRARY_LAYER_TYPES`列舉。 1. 擴展 `chat` Lambda 函數以實作新供應商的建置器、用戶端和處理常式。 `source/lambda/chat` 包含不同 LLMs 的 LangChain 連線，以及建置這些 LLMs的支援類別。這些支援類別遵循建置器和物件導向設計模式來建立 LLM。 每個處理常式 （例如 `bedrock_handler.py`) 會先建立*用戶端*、檢查環境是否有所需的環境變數，然後呼叫 `get_model`方法來取得 LangChain LLM 類別。接著會呼叫 產生方法，以叫用 LLM 並取得其回應。LangChain 目前支援 Amazon Bedrock 的串流功能，但不支援 SageMaker AI。根據串流或非串流功能，呼叫適當的 WebSocket 處理常式 (`WebsocketStreamingCallbackHandler` 或 `WebsocketHandler`)，以使用 `post_to_connection`方法將回應傳回 WebSocket 連線。 `clients/builder` 資料夾包含的類別可協助使用 Builder 模式建置 LLM Builder。首先，會從 DynamoDB 組態存放區`use_case_config`擷取 ，存放要建構之知識庫、對話記憶體和模型類型的詳細資訊。它還包含相關的模型詳細資訊，例如模型參數和提示。建置器接著有助於遵循建立知識庫、建立對話記憶體以維護 LLM 的對話內容、為串流和非串流案例設定適當的 LangChain 回呼，以及根據提供的模型組態建立 LLM 模型。當您從部署儀表板部署使用案例時 （或使用者在沒有部署儀表板的獨立使用案例堆疊部署中提供使用案例時），DynamoDB 組態會在建立使用案例時存放。 `clients/factories` 子資料夾可協助根據 LLM 組態設定適當的對話記憶體和知識庫類別。這可讓您輕鬆地延伸到您希望實作支援的任何其他知識庫或記憶體類型。 `shared` 子資料夾包含建置器在工廠內執行個體化的知識庫和對話記憶體的特定實作。它還包含在 LangChain 內呼叫的 Amazon Kendra 和 Amazon Bedrock 知識庫擷取器，以擷取 RAG 使用案例的文件，以及 LangChain LLM 模型使用的回呼。 LangChain 實作使用 LangChain 表達式語言 (LCEL) 來組合對話鏈。 `RunnableWithMessageHistory`類別用於維護具有自訂 LCEL 鏈的對話歷史記錄，啟用功能，例如傳回來源文件，以及使用傳送至知識庫的重述 （或取消歧義） 問題，以同時傳送至 LLM。 若要建立自訂提供者的自有實作，您可以： 1. 複製 `bedrock_handler.py` 檔案並建立您的自訂處理常式 （例如 `custom_handler.py`)，這會建立您的自訂用戶端 （例如 `CustomProviderClient`) （在下列步驟中指定）。 1. `bedrock_client.py` 在用戶端資料夾中複製 。將其重新命名為 `custom_provider_client.py`（或您的特定模型提供者名稱，例如 `CustomProvider`)。適當地命名其中的類別，例如`CustomProviderClient`繼承 的 `LLMChatClient`。 您可以使用 提供的方法，`LLMChatClient`或撰寫自己的實作來覆寫這些實作。 `get_model` 方法會建置 `CustomProviderBuilder`（請參閱下列步驟），並使用建置器步驟呼叫建構聊天模型`construct_chat_model`的方法。此方法在建置器模式中充當 *Director*。 1. 將其複製`clients/builders/bedrock_builder.py`至 `custom_provider_builder.py`，並將其重新命名為繼承 LLMBuilder `CustomProviderBuilder`的 類別 (`llm_builder.py`)。您可以使用 LLMBuilder 提供的方法，或撰寫您自己的實作來覆寫這些實作。建置器步驟會在用戶端的 `construct_chat_model`方法內依序呼叫，例如 `set_model_defaults`、 `set_knowledge_base`和 `set_conversation_memory`。 該`set_llm_model`方法將使用之前稱為 的方法設定的所有值來建立實際 LLM 模型。具體而言，您可以根據從 DynamoDB 中的 LLM 組態擷取`rag_enabled variable`的 建立 RAG () `CustomProviderRetrievalLLM`或非 RAG (`CustomProviderLLM`) LLM。 此組態會在 `LLMChatClient`類別的 `retrieve_use_case_config`方法中擷取。 1. 根據您是否需要 RAG 或非 RAG 使用案例，在`llm_models`子資料夾中實作您的 或 `CustomProviderLLM``CustomProviderRetrievalLLM`實作。實作這些模型的大多數功能分別在非 RAG `BaseLangChainModel`和 RAG 使用案例的 和 `RetrievalLLM`類別中提供。 您可以複製 `llm_models/bedrock.py` 檔案並進行必要的變更，以呼叫參考自訂提供者的 LangChain 模型。例如，Amazon Bedrock 使用`ChatBedrock`類別來建立使用 LangChain 的聊天模型。 產生方法會使用 LangChain LCEL *鏈*產生 LLM 回應。 您也可以使用 `get_clean_model_params`方法來淨化每個 LangChain 或模型需求的模型參數。 ## 展開支援的 Strands 工具 解決方案可讓您建置和部署 MCP 伺服器、AI 代理器和多代理程式工作流程。在客服人員建置器體驗中，您可以連接 MCP 伺服器，為客服人員提供額外的功能。除了 MCP 伺服器之外，您還可以利用 [Strands](https://strandsagents.com/latest/documentation/docs/user-guide/concepts/tools/community-tools-package/) （解決方案所使用的基礎架構） 提供的內建工具。 現成可用的解決方案已預先設定下列 Strands 工具： + 目前時間 （預設為啟用） + 計算器 （預設為啟用） + Environment **客服人員建置器精靈中的 MCP 伺服器和工具選擇，顯示內建 Strands 工具** ![\[內建絞線工具\]](http://docs.aws.amazon.com/zh_tw/solutions/latest/generative-ai-application-builder-on-aws/images/builtin-strands-tools.png) 若要使用其他 Strands 工具擴展您的代理程式，請遵循本節中概述的四個步驟。 ### 步驟 1：尋找 Strands 工具 瀏覽[可用的 Strands 工具](https://strandsagents.com/latest/documentation/docs/user-guide/concepts/tools/community-tools-package/#available-tools)，以識別您要使用的工具。每個工具都有特定的功能和組態需求。 例如，若要新增 Amazon Bedrock 知識庫擷取功能，您可以使用[擷取](https://github.com/strands-agents/tools/blob/main/src/strands_tools/retrieve.py)工具。 ### 步驟 2：更新 SSM 參數 若要在 Agent Builder 部署 UI 中提供工具，請更新 AWS Systems Manager 參數存放區參數，以定義支援哪些 Strands 工具。 1. 導覽至您 AWS 帳戶中的 AWS Systems Manager 參數存放區。 1. 找到 參數： `/gaab//strands-tools` 1. 使用下列 JSON 結構將您的工具組態新增至現有清單的結尾： ``` { "name": "Bedrock KB Retrieve", "description": "Retrieve information from Bedrock Knowledge Base", "value": "retrieve", "category": "AI", "isDefault": false } ``` [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/solutions/latest/generative-ai-application-builder-on-aws/integration-guide.html) ### 步驟 3：設定環境變數 許多 Strands 工具需要環境變數才能進行組態。您可以透過兩種方式設定這些變數： **選項 1：AgentCore 執行期上的直接組態** 使用所需的環境變數，直接在 Amazon Bedrock AgentCore 執行期更新部署的代理程式。 **選項 2：部署精靈中的模型參數** 在客服人員建置器精靈的模型選取步驟期間，使用模型參數區段新增環境變數。遵循命名慣例的環境變數`ENV__`會在執行時間自動載入代理程式的執行環境，做為 ``。 例如： + `ENV_RETRIEVE_KNOWLEDGE_BASE_ID` 成為 `KNOWLEDGE_BASE_ID` + `ENV_RETRIEVE_MIN_SCORE` 成為 `MIN_SCORE` **顯示 ENV\$1RETRIEVE\$1KNOWLEDGE\$1BASE\$1ID 組態的進階模型參數區段** ![\[模型參數 env vars\]](http://docs.aws.amazon.com/zh_tw/solutions/latest/generative-ai-application-builder-on-aws/images/model-parameters-env-vars.png) 請參閱特定工具的文件或原始程式碼，以識別所需的環境變數。對於擷取工具，您可以在[原始程式碼](https://github.com/strands-agents/tools/blob/main/src/strands_tools/retrieve.py#L293)中找到組態選項。 ### 步驟 4：新增 IAM 許可 手動將任何必要的 IAM 許可新增至 AgentCore 執行期執行角色，以允許代理程式使用 工具。 例如，若要搭配 Amazon Bedrock 知識庫使用擷取工具： 1. 導覽至 AWS 帳戶中的 IAM 主控台。 1. 尋找代理程式的 AgentCore 執行期執行角色。 1. 新增下列許可： ``` { "Effect": "Allow", "Action": "bedrock:Retrieve", "Resource": "arn:aws:bedrock:region:account-id:knowledge-base/knowledge-base-id" } ``` **IAM 主控台顯示連接到 AgentCore 執行期執行角色的 StrandsRetrieveToolKBAccess 政策** ![\[代理程式執行角色更新 IAM\]](http://docs.aws.amazon.com/zh_tw/solutions/latest/generative-ai-application-builder-on-aws/images/agent-execution-role-update-IAM.png) 所需的特定許可會根據工具而有所不同。請參閱工具的文件和 AWS 服務文件，以判斷適當的 IAM 許可。 ### 步驟 5：測試代理程式 完成組態步驟後，測試您的代理程式以確認工具是否正常運作。您應該會在客服人員的執行日誌和回應中看到工具叫用。 **客服人員成功使用擷取工具來回答有關滑板公園的問題** ![\[絞線擷取工具範例\]](http://docs.aws.amazon.com/zh_tw/solutions/latest/generative-ai-application-builder-on-aws/images/strands-retrieve-tool-example.png) **注意** 如需可用 Strands 工具及其功能的完整清單，請參閱 [Strands 社群工具文件](https://strandsagents.com/latest/documentation/docs/user-guide/concepts/tools/community-tools-package/)。 ## 擴展支援的知識庫和對話記憶體類型 若要新增對話記憶體或知識庫的實作，請在 `shared` 資料夾中新增所需的實作，然後編輯工廠和適當的列舉，以建立這些類別的執行個體。 當您提供存放在參數存放區中的 LLM 組態時，將會為您的 LLM 建立適當的對話記憶體和知識庫。例如，`ConversationMemoryType`當 指定為 DynamoDB 時，會建立 執行個體 `DynamoDBChatMessageHistory`（可在 內取得`shared_components/memory/ddb_enhanced_message_history.py`)。當 `KnowledgeBaseType` 指定為 Amazon Kendra 時，會建立 執行個體 `KendraKnowledgeBase`（可在 內取得`shared_components/knowledge/kendra_knowledge_base.py`)。 ## 建置和部署程式碼變更 使用 `npm run build`命令建置程式。解決任何錯誤後，請執行 `cdk synth`以產生範本檔案和所有 Lambda 資產。 1. 您可以使用`–0—/stage-assets.sh`指令碼，將任何產生的資產手動暫存到帳戶中的預備儲存貯體。 1. 使用下列命令來部署或更新平台： ``` cdk deploy DeploymentPlatformStack --parameters AdminUserEmail='admin-email@amazon.com' ``` 任何其他 AWS CloudFormation 參數也應該與 **AdminUserEmail** 參數一起提供。