기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# 통합 가이드
<a name="integration-guide"></a>

전체 솔루션은 쉽게 확장할 수 있도록 설계되었습니다. 이 솔루션의 오케스트레이션 계층은 [LangChain](https://www.langchain.com/)을 사용하여 빌드됩니다. LangChain(또는 이러한 구성 요소에 LangChain 커넥터를 제공하는 타사)에서 지원하는 모든 모델 공급자, 지식 기반 또는 대화 메모리 유형을이 솔루션에 추가할 수 있습니다.

## 지원되는 LLMs 확장
<a name="expanding-supported-llms"></a>

사용자 지정 LLM 공급자와 같은 다른 모델 공급자를 추가하려면 솔루션의 다음 세 가지 구성 요소를 업데이트해야 합니다.

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. 사용자 지정 LLM의 자격 증명을 저장하는 Secrets Manager 암호를이 스택에 추가하도록 선택할 수 있습니다. 다음 단락에서 설명하는 채팅 Lambda 계층에서 모델 호출 중에 이러한 자격 증명을 검색할 수 있습니다.

1. 추가할 모델 공급자의 Python 라이브러리가 포함된 Lambda 계층을 빌드하고 연결합니다. Amazon Bedrock 사용 사례 채팅 애플리케이션의 경우 `langchain-aws` Python 라이브러리에는 AWS 모델 공급자(Amazon Bedrock 및 SageMaker AI), 지식 기반(Amazon Kendra 및 Amazon Bedrock 지식 기반) 및 메모리 유형(예: DynamoDB)에 연결하기 위한 LangChain 패키지 위에 사용자 지정 커넥터가 포함되어 있습니다. 마찬가지로 다른 모델 공급자에도 자체 커넥터가 있습니다. 이 계층을 사용하면이 모델 공급자의 Python 라이브러리를 연결하여 LLM을 호출하는 채팅 Lambda 계층에서 이러한 커넥터를 사용할 수 있습니다(3단계). 이 솔루션에서는 사용자 지정 자산 번들러를 사용하여 CDK 측면을 사용하여 연결된 Lambda 계층을 빌드합니다. 사용자 지정 모델 공급자 라이브러리에 대한 새 계층을 생성하려면:

   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 함수를 확장하여 새 공급자에 대한 빌더, 클라이언트 및 핸들러를 구현합니다.

   에는 이러한 LLM을 빌드하기 위한 지원 클래스와 함께 다양한 LLM에 대한 LangChain 연결이 `source/lambda/chat` 포함되어 있습니다. LLMs 이러한 지원 클래스는 Builder 및 객체 지향 설계 패턴을 따라 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`를 검색합니다. 또한 모델 파라미터 및 프롬프트와 같은 관련 모델 세부 정보도 포함되어 있습니다. 그런 다음 Builder는 지식 기반을 생성하고, LLM에 대한 대화 컨텍스트를 유지하기 위한 대화 메모리를 생성하고, 스트리밍 및 비스트리밍 사례에 적합한 LangChain 콜백을 설정하고, 제공된 모델 구성을 기반으로 LLM 모델을 생성하는 단계를 수행하는 데 도움이 됩니다. DynamoDB 구성은 배포 대시보드에서 사용 사례를 배포할 때(또는 배포 대시보드 없이 독립 실행형 사용 사례 스택 배포에서 사용자가 제공하는 경우) 사용 사례 생성 시 저장됩니다.

   `clients/factories` 하위 폴더는 LLM 구성을 기반으로 적절한 대화 메모리 및 지식 기반 클래스를 설정하는 데 도움이 됩니다. 이를 통해 구현에서 지원하려는 다른 지식 기반 또는 메모리 유형을 쉽게 확장할 수 있습니다.

   `shared` 하위 폴더에는 빌더가 공장 내에서 인스턴스화하는 지식 기반 및 대화 메모리의 특정 구현이 포함되어 있습니다. 또한 LangChain LLM 모델에서 사용하는 콜백과 함께 RAG 사용 사례에 대한 문서를 검색하기 위해 LangChain 내에서 호출된 Amazon Kendra 및 Amazon Bedrock 지식 기반 리트리버도 포함되어 있습니다.

   LangChain 구현은 LangChain Expression Language(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` 메서드를 호출합니다. 이 메서드는 빌더 패턴에서 *디렉터* 역할을 합니다.

   1. 복사`clients/builders/bedrock_builder.py`하여 로 이름을 `custom_provider_builder.py` 바꾸고 그 안의 클래스를 LLMBuilder()를 상속`CustomProviderBuilder`하는 로 이름을 바꿉니다`llm_builder.py`. LLMBuilder에서 제공하는 메서드를 사용하거나 자체 구현을 작성하여 이를 재정의할 수 있습니다. 빌더 단계는 , `set_model_defaults` `set_knowledge_base`및와 같은 클라이언트의 `construct_chat_model` 메서드 내에서 순서대로 호출됩니다`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 도구 확장
<a name="expanding-strands-tools"></a>

솔루션을 사용하면 MCP 서버, AI 에이전트 및 다중 에이전트 워크플로를 구축하고 배포할 수 있습니다. 에이전트 빌더 경험 내에서 MCP 서버를 연결하여 에이전트에게 추가 기능을 제공할 수 있습니다. MCP 서버 외에도 [Strands](https://strandsagents.com/latest/documentation/docs/user-guide/concepts/tools/community-tools-package/)(솔루션에서 사용하는 기본 프레임워크)에서 제공하는 내장 도구를 활용할 수 있습니다.

기본적으로 솔루션은 다음 Strands 도구로 사전 구성되어 제공됩니다.
+ 현재 시간(기본적으로 활성화됨)
+ 계산기(기본적으로 활성화됨)
+ 환경

 **기본 제공 Strands 도구를 보여주는 Agent Builder 마법사의 MCP 서버 및 도구 선택** 

![\[내장 스트랜드 도구\]](http://docs.aws.amazon.com/ko_kr/solutions/latest/generative-ai-application-builder-on-aws/images/builtin-strands-tools.png)


추가 Strands 도구로 에이전트를 확장하려면이 섹션에 설명된 4단계 프로세스를 따르세요.

### 1단계: Strands 도구 찾기
<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 배포 UI에서 도구를 사용할 수 있도록 하려면 지원되는 Strands 도구를 정의하는 AWS Systems Manager Parameter Store 파라미터를 업데이트합니다.

1. AWS 계정의 AWS Systems Manager 파라미터 스토어로 이동합니다.

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/ko_kr/solutions/latest/generative-ai-application-builder-on-aws/integration-guide.html)

### 3단계: 환경 변수 구성
<a name="configure-environment-variables"></a>

많은 Strands 도구에는 구성을 위한 환경 변수가 필요합니다. 다음 두 가지 방법으로 이러한 변수를 설정할 수 있습니다.

 **옵션 1: AgentCore 런타임의 직접 구성** 

Amazon Bedrock AgentCore 런타임에서 배포된 에이전트를 필요한 환경 변수로 직접 업데이트합니다.

 **옵션 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 구성을 보여주는 고급 모델 파라미터 섹션** 

![\[모델 파라미터 env vars\]](http://docs.aws.amazon.com/ko_kr/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/ko_kr/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/ko_kr/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에 적합한 대화 메모리와 지식 기반이 생성됩니다. 예를 들어이 DynamoDB로 `ConversationMemoryType` 지정되면 `DynamoDBChatMessageHistory` ( 내에서 사용 가능`shared_components/memory/ddb_enhanced_message_history.py`)의 인스턴스가 생성됩니다. `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** 파라미터와 함께 제공해야 합니다.