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

# 에이전트 검색을 사용하여 지식 기반 쿼리
<a name="kb-test-agentic-retrieve"></a>

에이전트 검색은 파운데이션 모델을 사용하여 복잡한 쿼리를 하위 쿼리로 지능적으로 분해하고, 지식 기반에서 관련 정보를 반복적으로 검색하고, 검색된 결과가 원래 쿼리에 응답하기에 충분한지 평가합니다. 이 접근 방식은 단일 검색 패스가 완전히 해결하지 못할 수 있는 복잡한 다단계 질문의 검색 정확도를 개선합니다.

예를 들어 *"어떤 잡지가 처음 시작되었는지, Arthur's™ 또는 First for Women?"* 쿼리를 고려할 때 에이전트 검색은 이를 *"Athur's™가 언제 설립되었나요?"*와 같은 별도의 하위 쿼리로 나눕니다. 및 *"First for 우먼이 처음 설립된 시기"*는 각각에 대한 결과를 검색하고 결합된 결과가 충분한지 평가합니다.

## 에이전트 검색 작동 방식
<a name="kb-agentic-retrieve-how-it-works"></a>

`AgenticRetrieveStream` API에 요청을 보내면 다음 프로세스가 수행됩니다.

1. **계획** - 파운데이션 모델은 쿼리를 분석하고 하나 이상의 하위 쿼리로 분해할 계획을 생성합니다. 각 하위 쿼리는 구성한 특정 리트리버를 대상으로 합니다. 검색 결과를 수집한 후 파운데이션 모델은 원래 쿼리에 응답하기에 충분한지 평가합니다. 그렇지 않은 경우 구성된 최대값까지 추가 검색 반복을 계획하고 실행합니다.

1. **검색** - 하위 쿼리는 구성된 지식 기반 리트리버에 대해 실행됩니다. 결과는 각 검색에서 수집됩니다.

1. **전체 문서 확장** - 파운데이션 모델이 문서의 전체 콘텐츠가 필요하다고 판단하면(예: 요약, 완전성 확인 또는 특정 섹션 액세스) GetDocumentContent API를 호출하여 전체 문서 콘텐츠를 검색합니다.

1. **응답 생성** - `generateResponse`가 `true` (기본값)으로 설정된 경우 파운데이션 모델은 검색된 결과에서 자연어 응답을 합성합니다. 응답은 `responseEvent` 이벤트를 통해 다시 스트리밍됩니다.

1. **결과 이벤트** - 모든 반복에서 중복 제거된 검색 결과, 완전히 합성된 자연어 답변 및 인용이 반환됩니다. 추적 이벤트는 관찰성을 위해 프로세스 전체에서 스트리밍됩니다.

## 사전 조건
<a name="kb-agentic-retrieve-prereqs"></a>

에이전트 검색을 사용하려면 먼저 다음이 있어야 합니다.
+ 완전 관리형 Amazon Bedrock 지식 기반. 에이전트 검색은 현재 관리형 지식 기반만 지원합니다.
+ Amazon Bedrock의 파운데이션 모델에 액세스하여 쿼리 계획 및 평가에 사용할 수 있습니다.
+ 필요한 IAM 권한입니다. 자세한 내용은 [에이전트 검색에 필요한 권한](#kb-agentic-retrieve-permissions) 단원을 참조하십시오.

## 에이전트 검색으로 지식 기반 쿼리
<a name="kb-agentic-retrieve-api"></a>

에이전트 검색을 사용하려면 [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_AgenticRetrieveStream.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_AgenticRetrieveStream.html) 요청을 보냅니다. 응답은 검색 결과 및 추적 이벤트를 포함하는 스트림입니다.

다음 표에서는 키 요청 필드를 설명합니다.


**필수 필드**  

| 필드 | 설명 | 
| --- | --- | 
| messages | 입력 쿼리 및 대화 기록입니다. 각 메시지에는 text 값과 content 필드(user 또는 )가 있는 role 필드가 포함됩니다assistant. | 
| 리트리버 | 데이터를 가져올 지식 기반 리트리버입니다. 최대 5개의 리트리버를 지정할 수 있으며, 각 리트리버는 ID별로 관리형 지식 기반을 가리킵니다. 각 리트리버에는 선택적으로 메타데이터 필터와 최대 결과 수가 포함될 수 있습니다. | 
| agenticRetrieveConfiguration | 쿼리 계획 및 평가에 사용할 파운데이션 모델과 선택적으로 순위 변경 모델 및 최대 에이전트 반복 수를 포함한 에이전트 검색 구성입니다. | 


**선택 필드**  

| 필드 | 설명 | 
| --- | --- | 
| policyConfiguration | 에이전트 검색 중에 적용되도록 Amazon Bedrock 가드레일을 구성합니다. guardrailId 및를 지정합니다guardrailVersion. | 
| userContext | 액세스 제어 필터링을 위한 사용자 컨텍스트를 제공합니다. | 
| generateResponse | true (기본값)로 설정하면 파운데이션 모델에 검색된 결과에서 자연어 응답을 생성하도록 지시하는 부울 필드입니다. 답변은 텍스트 청크로 다시 스트리밍되어 결과 이벤트에 포함됩니다. | 

전체 요청 및 응답 구문은 API 참조[https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_AgenticRetrieveStream.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_AgenticRetrieveStream.html)의 섹션을 참조하세요.

## 에이전트 검색 응답
<a name="kb-agentic-retrieve-response"></a>

`AgenticRetrieveStream` 응답은 다음 이벤트 유형을 포함하는 스트림입니다.
+ **결과 이벤트**(`AgenticRetrieveResultEvent`) - 처리가 완료될 때 전달되는 최종 이벤트입니다. 검색 결과와 응답 생성이 활성화되면 생성된 응답을 포함합니다. 결과 이벤트에는 다음이 포함됩니다.
  + **검색 결과**(`results`) - 모든 반복에서 검색된 소스 청크입니다. 각 결과에는 콘텐츠, 소스 리트리버 식별자 및 선택적 메타데이터가 포함됩니다. 여러 하위 쿼리에서 동일한 청크를 검색하면 최종 결과에 한 번만 나타납니다.
  + **생성된 응답**(`generatedResponse`) - `generateResponse`이 `true` (기본값)으로 설정된 경우 결과 이벤트에는 다음이 포함된 `generatedResponse` 객체가 포함됩니다.
    + `answer` - 합성된 전체 자연어 응답 텍스트입니다.
    + `citations` - 답변 범위를 지원되는 검색 결과에 매핑하는 선택적 목록입니다. 각 인용에는 다음이 포함됩니다.
      + `startIndex` - `answer` 문자열 내에서 인용된 구절이 시작되는 문자 오프셋입니다.
      + `endIndex` - 인용된 구절이 끝나는 문자 오프셋입니다(제외 - 인용된 텍스트는에서 `startIndex` 까지 실행되지만는 포함하지 않음`endIndex`).
      + `references` - 각 참조에 동일한 결과 이벤트의 `results` 배열로 인덱싱하는 `resultIndex` 필드가 있는 목록으로, 인용된 범위를 지원하는 검색 결과를 나타냅니다.
+ **응답 이벤트**(`AgenticRetrieveResponseEvent`) - `generateResponse`이 `true` (기본값)로 설정되면 응답 생성 중에 `responseEvent` 이벤트가 스트리밍됩니다. 각 이벤트에는 합성된 자연어 답변의 증분 부분이 있는 `text` 필드가 포함되어 있습니다.
+ **트레이스 이벤트**(`AgenticRetrieveTraceEvent`) - 에이전트 검색 프로세스 중에 스트리밍되어 각 단계에 대한 가시성을 제공하는 이벤트입니다. 추적 이벤트의 유형은 다음과 같습니다.
  + **계획** - 파운데이션 모델이 쿼리를 분석하고 하위 쿼리를 생성하고 있음을 나타냅니다. 계획된 작업과 대상 리트리버를 포함합니다.
  + **검색** - 지식 기반에 대해 검색이 실행되고 있음을 나타냅니다. 검색 입력, 출력 및 경고 또는 실패를 포함합니다.
  + **추측 검색** - 지연 시간을 줄이기 위해 첫 번째 계획 단계 전에 실행되는 초기 검색입니다. 단일 지식 기반의 경우 원시 사용자 쿼리를 사용하여 결과를 검색합니다. 여러 지식 기반의 경우 프로브 검색을 수행하여 쿼리를 적절한 리트리버로 라우팅하는 데 도움이 됩니다.
  + **전체 문서 확장** - 에이전트가 특정 문서의 전체 콘텐츠를 검색하고 있음을 나타냅니다. 문서 ID, 소스 리트리버 및 상태(InProgress, 성공 또는 실패)를 포함합니다.

## 에이전트 검색에 필요한 권한
<a name="kb-agentic-retrieve-permissions"></a>

`AgenticRetrieveStream` API를 사용하려면 호출 IAM 자격 증명에 다음 권한이 있어야 합니다.

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "bedrock:AgenticRetrieveStream",
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "bedrock:Retrieve",
                "bedrock:GetDocumentContent"
            ],
            "Resource": "arn:aws:bedrock:{{region}}:{{account-id}}:knowledge-base/*"
        },
        {
            "Effect": "Allow",
            "Action": "bedrock:InvokeModelWithResponseStream",
            "Resource": "*"
        }
    ]
}
```

에이전트 검색과 함께 가드레일을 사용하는 경우 다음 권한을 추가합니다.

```
{
    "Effect": "Allow",
    "Action": [
        "bedrock:GetGuardrail",
        "bedrock:ApplyGuardrail"
    ],
    "Resource": "*"
}
```

## 고려 사항
<a name="kb-agentic-retrieve-considerations"></a>

에이전트 검색을 사용할 때는 다음 사항에 유의하세요.
+ 에이전트 검색은 관리형 Amazon Bedrock 지식 기반만 지원합니다.
+ 요청당 리트리버 할당량, 검색 호출당 결과 및 최대 에이전트 반복은 섹션을 참조하세요[관리형 지식 기반에 대한 서비스 할당량](kb-managed-quotas.md).
+ 최대 반복 횟수를 줄이면 에이전트가 더 일찍 중지되어 복잡한 쿼리의 정확도가 저하될 수 있습니다.
+ 가드레일을 구성할 때는 `BLOCK` 작업만 지원됩니다. `MASK` 작업은 에이전트 검색에서 지원되지 않습니다.
+ 고객은 제공된 경우 에이전트 검색 중에 사용되는 파운데이션 모델, 임베딩 모델 및 순위 조정 모델을 제공하고 소유합니다. IAM 자격 증명은 이러한 모델을 호출하는 데 사용됩니다.