本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 集成指南
<a name="integration-guide"></a>

整个解决方案都设计为易于扩展。此解决方案的编排层是使用[LangChain](https://www.langchain.com/)构建的。您可以将 LangChain （或为这些组件提供 LangChain 连接器的第三方）支持的任何模型提供者、知识库或对话存储器类型添加到此解决方案中。

## 支持扩展 LLMs
<a name="expanding-supported-llms"></a>

要添加其他模型提供者，例如自定义 LLM 提供程序，必须更新解决方案的以下三个组件：

1. 创建新的 `TextUseCase` CDK 堆栈，该堆栈将部署使用您的自定义 LLM 提供程序配置的聊天应用程序：

   1. 克隆此解决方案的[GitHub 存储库](https://github.com/aws-solutions/generative-ai-application-builder-on-aws)，并按照 [README.m](https://github.com/aws-solutions/generative-ai-application-builder-on-aws/blob/main/README.md) d 文件中提供的说明设置您的构建环境。

   1. 复制（或新建）`source/infrastructure/lib/bedrock-chat-stack.ts`文件，将其粘贴到同一目录中，然后将其重命名为`custom-chat-stack.ts`。

   1. 将文件中的类重命名为合适的类，例如`CustomLLMChat`。

   1. 您可以选择将 Secrets Manager 密钥添加到此堆栈中，该堆栈用于存储您的自定义 LLM 的凭据。您可以在模型调用期间在下一段中讨论的聊天 Lambda 层中检索这些凭证。

1. 构建并附加一个 Lambda 层，其中包含待添加的模型提供者的 Python 库。对于亚马逊 Bedrock 用例聊天应用程序，`langchain-aws`Python 库在 LangChain 包顶部包含自定义连接器，用于连接到 AWS 模型提供商（亚马逊 Bedrock 和 A SageMaker I）、知识库（亚马逊 Kendra 和 Amazon Bedrock 知识库）和内存类型（例如 DynamoDB）。同样，其他模型提供商也有自己的连接器。该层可帮助您附加此模型提供者的 Python 库，以便您可以在调用 LLM 的聊天 Lambda 层中使用这些连接器（步骤 3）。在此解决方案中，使用自定义资产捆绑器来构建 Lambda 层，这些层使用 CDK 方面进行附加。要为自定义模型提供程序库创建新层，请执行以下操作：

   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`包含不同的 LangChain 连接 LLMs 以及用于构建这些连接的支持类 LLMs。这些支持类遵循生成器和面向对象的设计模式来创建 LLM。

   每个处理程序（例如`bedrock_handler.py`）首先创建一个*客户端*，检查环境中是否存在所需的环境变量，然后调用一个`get_model`方法来获取 LangChain LLM 类。然后调用 generate 方法来调用 LLM 并获取其响应。 LangChain 目前支持 Amazon Bedrock 的直播功能，但不支持 SageMaker AI。基于流式传输或非流式传输功能，调用相应的 WebSocket 处理程序（`WebsocketStreamingCallbackHandler`或`WebsocketHandler`），使用`post_to_connection`方法将响应发送回 WebSocket 连接。

   该`clients/builder`文件夹包含有助于使用生成器模式构建 LLM Builder 的类。首先，从 DynamoDB 配置存储中检索，该存储库存储了有关要构建的知识库类型、对话记忆和模型的详细信息。`use_case_config`它还包含相关的模型详细信息，例如模型参数和提示。然后，Builder 可以帮助执行以下步骤：创建知识库、创建对话记忆以维护 LLM 的对话上下文、为直播和非直播案例设置适当的 LangChain 回调，以及根据提供的模型配置创建 LLM 模型。DynamoDB 配置是在您从部署控制面板部署用例时存储的（或者当用户在没有部署控制面板的独立用例堆栈部署中提供用例时）。

   该`clients/factories`子文件夹有助于根据 LLM 配置设置相应的对话记忆和知识库类。这样可以轻松扩展到您希望实现支持的任何其他知识库或内存类型。

   `shared`子文件夹包含知识库和对话记忆的特定实现，这些实现由构建器在工厂内部实例化。它还包含 Amazon Kendra 和 Amazon Bedrock 知识库检索器，用于检索 RAG 用例的文档，以及 LLM 模型使用的回调。 LangChain LangChain 

   这些 LangChain 实现使用 LangChain 表达式语言 (LCEL) 将对话链组合在一起。 `RunnableWithMessageHistory`class 用于维护与自定义 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`的方法。此方法在生成器模式中充当*导*向器。

   1. 将其复制`clients/builders/bedrock_builder.py`并重命名为，其中的类继承 LLMBuilder (`llm_builder.py`)。`custom_provider_builder.py` `CustomProviderBuilder`您可以使用提供的方法 LLMBuilder 或编写自己的实现来覆盖这些方法。生成器步骤在客户端的`construct_chat_model`方法中按顺序调用`set_model_defaults`，例如`set_knowledge_base`、和`set_conversation_memory`。

      该`set_llm_model`方法将使用使用之前调用的方法设置的所有值来创建实际的 LLM 模型。具体而言，您可以根据从 DynamoDB 中的 LLM 配置中检索到的 RAG (`CustomProviderRetrievalLLM``CustomProviderLLM`) 或非 RAG () LLM。`rag_enabled variable`

      此配置是在`LLMChatClient`类的`retrieve_use_case_config`方法中获取的。

   1. 根据你`CustomProviderLLM`需要 RAG 还是非 RAG 用例，在`llm_models`子文件夹中实现或`CustomProviderRetrievalLLM`实现。对于非 RAG 和 RAG 用例，实现这些模型的大多数功能分别在它们的`BaseLangChainModel`和`RetrievalLLM`类中提供。

      您可以复制`llm_models/bedrock.py`文件并进行必要的更改，以调用引用您的自定义提供程序的 LangChain 模型。例如，Amazon Bedrock 使用一个`ChatBedrock`类来创建聊天模型。 LangChain

      *生成方法使用 L LangChain CEL 链生成 LLM 响应。*

      您也可以使用该`get_clean_model_params`方法根据您的模型要求对模型参数 LangChain 进行消毒。

## 扩展支持的 Strands 工具
<a name="expanding-strands-tools"></a>

该解决方案使您能够构建和部署 MCP 服务器、AI 代理和多代理工作流程。在 Agent Builder 体验中，您可以连接 MCP 服务器，为代理提供更多功能。除了 MCP 服务器外，您还可以利用 [Strands](https://strandsagents.com/latest/documentation/docs/user-guide/concepts/tools/community-tools-package/) 提供的内置工具（解决方案使用的底层框架）。

该解决方案开箱即用，预先配置了以下 Strands 工具：
+ 当前时间（默认启用）
+ 计算器（默认启用）
+ 环境

 **在 Agent Builder 向导中选择 MCP 服务器和工具，其中显示了内置 Strands 工具** 

![\[内置 strands 工具\]](http://docs.aws.amazon.com/zh_cn/solutions/latest/generative-ai-application-builder-on-aws/images/builtin-strands-tools.png)


要使用其他 Strands 工具扩展您的代理，请按照本节中概述的四步流程进行操作。

### 第 1 步：找到股线工具
<a name="find-the-strands-tool"></a>

浏览[可用的 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 参数
<a name="update-ssm-parameter"></a>

要在 Agent Builder 部署用户界面中提供工具，请更新定义支持哪些 Strands 工具的 AWS Systems Manager Parameter Store 参数。

1. 导航到您的 AWS 账户中的 AWS Systems Manager Parameter Store。

1. 找到参数：`/gaab/<stack-name>/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_cn/solutions/latest/generative-ai-application-builder-on-aws/integration-guide.html)

### 步骤 3：配置环境变量
<a name="configure-environment-variables"></a>

许多 Strands 工具都需要环境变量进行配置。您可以通过两种方式设置这些变量：

 **选项 1：在 AgentCore 运行时直接配置** 

使用所需的环境变量直接在 Amazon Bedrock AgentCore Runtime 上更新已部署的代理。

 **选项 2：部署向导中的模型参数** 

在 Agent Builder 向导的模型选择步骤中，使用模型参数部分添加环境变量。遵循命名约定的环境变量`ENV_<ALL_CAPS_TOOL_NAME>_<env_variable_name>`将在运行时自动加载到代理的执行环境中，即`<env_variable_name>`。

例如：
+  `ENV_RETRIEVE_KNOWLEDGE_BASE_ID` 变为 `KNOWLEDGE_BASE_ID` 
+  `ENV_RETRIEVE_MIN_SCORE` 变为 `MIN_SCORE` 

 **高级模型参数部分显示了 ENV\$1RETRIEVE\$1KNOWLEDGE\$1BASE\$1ID 配置** 

![\[模型参数环境变量\]](http://docs.aws.amazon.com/zh_cn/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 权限
<a name="add-iam-permissions"></a>

手动向您的 AgentCore 运行时执行角色添加任何必要的 IAM 权限，以允许代理使用该工具。

例如，要在 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"
   }
   ```

 **显示附加到 AgentCore 运行时执行角色的 StrandsRetrieveToolKBAccess 策略的 IAM 控制台** 

![\[代理执行角色更新 IAM\]](http://docs.aws.amazon.com/zh_cn/solutions/latest/generative-ai-application-builder-on-aws/images/agent-execution-role-update-IAM.png)


所需的特定权限将因工具而异。请查阅该工具的文档和 AWS 服务文档，以确定适当的 IAM 权限。

### 步骤 5：测试代理
<a name="test-the-agent"></a>

完成配置步骤后，测试您的代理以验证该工具是否正常运行。您应该在代理的执行日志和响应中看到工具调用。

 **代理成功使用检索工具回答了有关滑板公园的问题** 

![\[股线检索工具示例\]](http://docs.aws.amazon.com/zh_cn/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/)。

## 扩展支持的知识库和对话记忆类型
<a name="expanding-supported-kb-and-cm-types"></a>

要添加对话记忆或知识库的实现，请在`shared`文件夹中添加所需的实现，然后编辑工厂和相应的枚举以创建这些类的实例。

当您提供存储在参数存储库中的 LLM 配置时，将为您的 LLM 创建相应的对话存储器和知识库。例如，当指定`ConversationMemoryType`为 DynamoDB 时，将创建一个（`shared_components/memory/ddb_enhanced_message_history.py`内部可用）`DynamoDBChatMessageHistory`的实例。如果指定`KnowledgeBaseType`为 Amazon Kendra，则会创建一个`KendraKnowledgeBase`（内部可用`shared_components/knowledge/kendra_knowledge_base.py`）的实例。

## 生成和部署代码变更
<a name="building-and-deploying-code-changes"></a>

使用`npm run build`命令生成程序。解决所有错误后，运行`cdk synth`生成模板文件和所有 Lambda 资产。

1. 您可以使用该`–0—/stage-assets.sh`脚本将任何生成的资产手动暂存到账户中的暂存存储桶中。

1. 使用以下命令部署或更新平台：

   ```
   cdk deploy DeploymentPlatformStack --parameters AdminUserEmail='admin-email@amazon.com'
   ```

   任何其他 AWS CloudFormation 参数也应与**AdminUserEmail**参数一起提供。