# 統合ガイド
このソリューションは、簡単に拡張できるように設計されています。このソリューションのオーケストレーションレイヤーは、[LangChain](https://www.langchain.com/) を使用して構築されています。任意のモデルプロバイダー、ナレッジベース、または会話メモリタイプ (LangChain またはサードパーティー製で、LangChain コネクタを通じてコンポーネントが提供されているもの) を追加できます。
## サポートされている LLM の拡張
カスタム LLM プロバイダーなどの別のモデルプロバイダーを追加するには、ソリューションの次の 3 つのコンポーネントを更新する必要があります。
1. カスタム LLM プロバイダーで設定されたチャットアプリケーションをデプロイする新しい `TextUseCase` CDK スタックを作成します。
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 ライブラリをアタッチすることを目的としており、これにより、LLM を呼び出すチャット Lambda レイヤーでこれらのコネクタを使用できるようになります (ステップ 3)。このソリューションでは、カスタムアセットバンドラーを使用して Lambda レイヤーを構築し、CDK のアスペクトを使用してアタッチします。カスタムモデルプロバイダーライブラリの新しいレイヤーを作成するには:
1. `LambdaAspects` ファイルの `source/infrastructure/lib/utils/lambda-aspects.ts` クラスに移動します。
1. ファイル内で提供されている Lambda アスペクトクラスの機能を拡張する方法 (`getOrCreateLangchainLayer` メソッドの追加など) についての手順に従います。この新しいメソッド (`getOrCreateCustomLLMLayer` など) を使用するには、`source/infrastructure/lib/utils/constants.ts` ファイル内の `LLM_LIBRARY_LAYER_TYPES` 列挙型も更新します。
1. `chat` Lambda 関数を拡張して、新しいプロバイダーのビルダー、クライアント、ハンドラーを実装します。
`source/lambda/chat` には、さまざまな LLM の LangChain 接続と、これらの LLM を構築するためのサポートクラスが含まれています。これらのサポートクラスは、ビルダーとオブジェクト指向の設計パターンに従って LLM を作成します。
各ハンドラー (`bedrock_handler.py` など) は、まず *client* を作成し、必要な環境変数について環境をチェックしてから、`get_model` メソッドを呼び出して LangChain LLM クラスを取得します。その後、生成メソッドが呼び出されて LLM が起動し、その応答を取得します。LangChain は現在 Amazon Bedrock のストリーミング機能をサポートしていますが、SageMaker AI はサポートしていません。ストリーミング機能または非ストリーミング機能に基づいて、適切な WebSocket ハンドラー (`WebsocketStreamingCallbackHandler` または `WebsocketHandler`) が呼び出され、 `post_to_connection` メソッドを使用して応答が WebSocket 接続に送り返されます。
`clients/builder` フォルダには、ビルダーパターンを使用して LLM ビルダーを構築するのに役立つクラスが含まれています。まず、DynamoDB の設定ストアから `use_case_config` が取得されます。このストアには、構築するナレッジベース、会話メモリ、モデルのタイプに関する詳細が格納されています。また、モデルパラメータやプロンプトなど、関連するモデルの詳細も含まれています。ビルダーは、ナレッジベースの作成、会話コンテキストを維持するための LLM 用会話メモリの作成、ストリーミングケースと非ストリーミングケースに応じた LangChain コールバックの設定、提供されたモデル設定に基づく LLM モデルの作成の手順を支援します。この DynamoDB 設定は、デプロイダッシュボードからユースケースをデプロイするとき (またはデプロイダッシュボードなしでスタンドアロンのユースケーススタックデプロイでユーザーによって提供されるとき) に、ユースケースの作成時に保存されます。
`clients/factories` サブフォルダには、LLM の設定に基づいて適切な会話メモリとナレッジベースクラスを設定するのに役立ちます。これにより、実装でサポートする他のナレッジベースやメモリタイプへの拡張が容易になります。
`shared` サブフォルダには、ビルダーがファクトリー内でインスタンス化するナレッジベースと会話メモリの具体的な実装が含まれています。また、RAG ユースケースでのドキュメント取得のために、LangChain 内で呼び出される Amazon Kendra および Amazon Bedrock ナレッジベース用のリトリーバーのほか、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` など、特定のモデルプロバイダー名に応じた名前) に変更します。その中のクラスにも適切な名前を付けます (`LLMChatClient` を継承する `CustomProviderClient` など)。
`LLMChatClient` が提供するメソッドを使用することも、独自の実装を作成してこれらをオーバーライドすることもできます。
`get_model` メソッドは `CustomProviderBuilder` をビルドし (次のステップを参照)、ビルダーステップを使用してチャットモデルを構築する `construct_chat_model` メソッドを呼び出します。このメソッドは、ビルダーパターンの *Director* として機能します。
1. `clients/builders/bedrock_builder.py` をコピーして名前を `custom_provider_builder.py` に変更し、その中のクラスの名前を LLMBuilder (`llm_builder.py`) を継承する `CustomProviderBuilder` に変更します。LLMBuilder が提供するメソッドを使用することも、独自の実装を作成してこれらをオーバーライドすることもできます。ビルダーの各ステップは、クライアントの `construct_chat_model` メソッド内で順番に呼び出されます (例: `set_model_defaults`、`set_knowledge_base`、`set_conversation_memory` など)。
`set_llm_model` メソッドは、それ以前に呼び出されたメソッドによって設定されたすべての値を使用して、実際の LLM モデルを作成します。具体的には、RAG あり (`CustomProviderRetrievalLLM`) または RAG なし (`CustomProviderLLM`) の LLM を、DynamoDB に保存された LLM 設定から取得した `rag_enabled variable` に基づいて作成します。
この設定は、`LLMChatClient` クラスの `retrieve_use_case_config` メソッドで取得されます。
1. RAG ありと RAG なしのユースケースのどちらが必要かに基づいて、`CustomProviderLLM` または `CustomProviderRetrievalLLM` を `llm_models` サブフォルダに実装します。これらのモデルを実装するために必要な機能の大部分は、RAG なしのユースケースでは `BaseLangChainModel` クラスで、RAG ありのユースケースでは `RetrievalLLM` クラスで提供されています。
`llm_models/bedrock.py` ファイルをコピーし、独自のカスタムプロバイダーを参照する LangChain モデルを呼び出すために必要な変更を加えることができます。例えば、Amazon Bedrock では、`ChatBedrock` クラスを使用して LangChain を通じてチャットモデルを作成します。
generate メソッドは、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 ツールが事前設定されています。
+ 現在の時刻 (デフォルトで有効)
+ 計算ツール (デフォルトで有効)
+ 環境
**組み込みの Strands ツールが表示されている、エージェントビルダーウィザードの MCP サーバーとツールの選択**
![\[組み込み Strands ツール\]](http://docs.aws.amazon.com/ja_jp/solutions/latest/generative-ai-application-builder-on-aws/images/builtin-strands-tools.png)
追加の Strands ツールを使用してエージェントを拡張するには、このセクションで説明されている 4 ステップのプロセスに従います。
### ステップ 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 パラメータを更新する
エージェントビルダーデプロイ UI でツールを使用できるようにするには、サポートされている Strands ツールを定義する AWS Systems Manager Parameter Store のパラメータを更新します。
1. AWS アカウントの AWS Systems Manager Parameter Store に移動します。
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/ja_jp/solutions/latest/generative-ai-application-builder-on-aws/integration-guide.html)
### ステップ 3: 環境変数を設定する
多くの Strands ツールでは、設定に環境変数が必要です。変数は次の 2 つの方法で定義できます。
**オプション 1: AgentCore Runtime での直接設定**
必要な環境変数を使用して、Amazon Bedrock AgentCore Runtime でデプロイされたエージェントを直接更新します。
**オプション 2: デプロイウィザードのモデルパラメータ**
モデルパラメータセクションを使用して、エージェントビルダーウィザードのモデル選択ステップ中に環境変数を追加します。命名規則 `ENV__` に従う環境変数は、実行時にエージェントの実行環境に `` として自動的にロードされます。
例えば、次のようになります。
+ `ENV_RETRIEVE_KNOWLEDGE_BASE_ID` が になります`KNOWLEDGE_BASE_ID`
+ `ENV_RETRIEVE_MIN_SCORE` が になります`MIN_SCORE`
**ENV\$1RETRIEVE\$1KNOWLEDGE\$1BASE\$1ID 設定を示す高度なモデルパラメータセクション**
![\[モデルパラメータ環境変数\]](http://docs.aws.amazon.com/ja_jp/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 アクセス許可を追加する
AgentCore Runtime 実行ロールに必要な IAM アクセス許可を手動で追加して、エージェントがツールを使用できるようにします。
例えば、Amazon Bedrock ナレッジベースで取得ツールを使用するには、以下を行います。
1. 使用中の AWS アカウントで IAM コンソールに移動します。
1. エージェントの AgentCore Runtime 実行ロールを見つけます。
1. 以下のアクセス許可を追加します。
```
{
"Effect": "Allow",
"Action": "bedrock:Retrieve",
"Resource": "arn:aws:bedrock:region:account-id:knowledge-base/knowledge-base-id"
}
```
**AgentCore Runtime 実行ロールにアタッチされた StrandsRetrieveToolKBAccess ポリシーを示す IAM コンソール**
![\[エージェント実行ロールの更新 IAM\]](http://docs.aws.amazon.com/ja_jp/solutions/latest/generative-ai-application-builder-on-aws/images/agent-execution-role-update-IAM.png)
どんな特定のアクセス許可が必要になるかは、ツールによって異なります。ツールのドキュメントと AWS のサービスドキュメントを参照して、適切な IAM アクセス許可を決定します。
### ステップ 5: エージェントをテストする
設定ステップを完了したら、エージェントをテストしてツールが正しく動作していることを確認します。エージェントの実行ログとレスポンスにツール呼び出しが表示されます。
**エージェントが取得ツールを使用してスケートパークに関する質問に回答する**
![\[Strands 取得ツールの例\]](http://docs.aws.amazon.com/ja_jp/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` フォルダに必要な実装を追加し、ファクトリーと適切な列挙を編集して、これらのクラスのインスタンスを作成します。
Parameter Store 内に保存されている 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** パラメータとともに指定する必要があります。