AMAZON.KendraSearchIntent - Amazon Lex V1
IAM 정책요청 및 세션 속성을 필터로 사용검색 응답 사용Lambda 함수를 사용하여 요청 및 응답 관리

Amazon Lex V2를 사용하는 경우 Amazon Lex V2 가이드를 대신 참조하십시오.

 

Amazon Lex V1을 사용하는 경우 봇을 Amazon Lex V2로 업그레이드하는하는 것이 좋습니다. 더 이상 V1에 새로운 기능을 추가하지 않으므로 모든 새 봇에 V2를 사용할 것을 강력히 권장합니다.

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

AMAZON.KendraSearchIntent

Amazon Kendra로 인덱싱된 문서를 검색하려면 AMAZON.KendraSearchIntent 의도를 사용합니다. Amazon Lex가 사용자와의 대화에서 다음 작업을 결정할 수 없으면 검색 의도가 트리거됩니다.

AMAZON.KendraSearchIntent는 영어(미국)(en-US) 및 미국 동부(버지니아 북부), 미국 서부(오레곤) 및 유럽(아일랜드) 리전만 사용 가능합니다.

Amazon Kendra는 PDF 문서 또는 Microsoft Word 파일과 같은 자연어 문서를 인덱싱하는 기계 학습 기반 검색 서비스입니다. 인덱싱된 문서를 검색하고 질문에 대해 다음 유형의 응답을 반환할 수 있습니다.

  • 대답

  • 질문에 대한 답이 될 수 있는 FAQ 항목

  • 질문과 관련된 문서

AMAZON.KendraSearchIntent 사용 예는 예제: Amazon Kendra 인덱스에 대한 FAQ 봇 생성 섹션을 참조하십시오.

봇에 AMAZON.KendraSearchIntent 의도를 구성하면 Amazon Lex가 슬롯 또는 의도에 대한 사용자 표현를 파악할 수 없을 때마다 이 의도를 호출합니다. 예를 들어 봇이 "피자 토핑"이라는 슬롯 유형에 대한 응답을 유도할 때 사용자가 "피자가 뭐야?"라고 말할 경우 Amazon Lex는 이 질문을 처리하기 위해 AMAZON.KendraSearchIntent를 호출합니다. Amazon Kendra에서 응답이 없으면 봇에 구성된 대로 대화가 계속됩니다.

동일한 봇에서 AMAZON.KendraSearchIntent와 AMAZON.FallbackIntent가 모두 사용되는 경우 Amazon Lex는 이러한 의도를 다음과 같이 사용합니다.

  1. Amazon Lex에서 AMAZON.KendraSearchIntent에 전화를 겁니다. 이 의도는 Amazon Kendra Query 작업을 호출합니다.

  2. Amazon Kendra에서 응답을 반환하면 Amazon Lex가 사용자에게 결과를 표시합니다.

  3. Amazon Kendra에서 응답이 없으면 Amazon Lex가 사용자에게 다시 메시지를 표시합니다. 다음 작업은 사용자의 응답에 따라 달라집니다.

    • 사용자의 응답에 슬롯 값을 채우거나 의도를 확인하는 것과 같이 Amazon Lex에서 인식하는 표현이 포함된 경우 봇에 구성된 대로 사용자와의 대화가 진행됩니다.

    • 사용자의 응답에 Amazon Lex에서 인식하는 표현이 포함되어 있지 않으면 Amazon Lex가 새로운 Query 작업을 호출합니다.

  4. 구성된 재시도 횟수 이후에 응답이 없으면 Amazon Lex가 AMAZON.FallbackIntent를 호출하여 사용자와의 대화를 종료합니다.

AMAZON.KendraSearchIntent를 사용하여 Amazon Kendra에 요청을 하는 방법에는 다음 3가지가 있습니다.

  • 의도 검색이 대신 요청하도록 하세요. Amazon Lex는 사용자의 말을 검색 문자열로 사용하여 Amazon Kendra를 호출합니다. 의도를 생성할 때 Amazon Kendra에서 반환되는 응답 수를 제한하는 쿼리 필터 문자열을 정의할 수 있습니다. Amazon Lex는 쿼리 요청에서 필터를 사용합니다.

  • 대화 Lambda 함수를 사용하여 요청에 추가 쿼리 파라미터 추가하세요. delegate 대화 작업에 Amazon Kendra 쿼리 파라미터가 포함된 kendraQueryFilterString 필드를 추가합니다. Lambda 함수를 사용하여 요청에 쿼리 파라미터를 추가하면 해당 파라미터가 의도를 생성할 때 정의한 쿼리 필터보다 우선 적용됩니다.

  • 대화 Lambda 함수를 사용하여 새 쿼리 생성. Amazon Lex가 보내는 전체 Amazon Kendra 쿼리 요청을 생성할 수 있습니다. delegate 대화 작업의 kendraQueryRequestPayload 필드에 쿼리를 지정합니다. kendraQueryRequestPayload 필드가 kendraQueryFilterString 필드보다 우선 적용됩니다.

봇을 생성할 때 queryFilterString 파라미터를 지정하거나 대화 Lambda 함수에서 delegate 작업을 호출할 때 kendraQueryFilterString 필드를 지정하려면 Amazon Kendra 쿼리에 대한 속성 필터로 사용되는 문자열을 지정합니다. 문자열이 유효한 속성 필터가 아닌 경우 런타임에 InvalidBotConfigException 예외가 발생합니다. 속성 필터에 대한 자세한 내용은 Amazon Kendra 개발자 안내서의 문서 속성을 사용하여 쿼리 필터링을 참조하십시오.

Amazon Lex가 Amazon Kendra에 보내는 쿼리를 제어하려면 대화 Lambda 함수의 kendraQueryRequestPayload 필드에 쿼리를 지정합니다. 쿼리가 유효하지 않으면 Amazon Lex에서 InvalidLambdaResponseException 예외를 반환합니다. 자세한 내용은 Amazon Kendra 개발자 안내서의 쿼리 작업을 참조하세요.

AMAZON.KendraSearchIntent 사용 방법의 예는 예제: Amazon Kendra 인덱스에 대한 FAQ 봇 생성 섹션을 참조하십시오.

Amazon Kendra 검색에 사용되는 IAM 정책

AMAZON.KendraSearchIntent 의도를 사용하려면 AWS Identity and Access Management (IAM) 정책을 제공하는 역할을 사용하여 Amazon Lex가 Amazon Kendra Query 의도를 호출할 수 있는 권한을 가진 런타임 역할을 수임할 수 있도록 해야 합니다. 사용하는 IAM 설정은 AMAZON.KendraSearchIntent를 생성할 때 Amazon Lex 콘솔을 사용하는지 아니면 AWS SDK 또는 AWS Command Line Interface(AWS CLI)를 사용하는 지에 따라 달라집니다. 콘솔을 사용하는 경우 Amazon Lex 서비스 연결 역할에 Amazon Kendra 호출 권한을 추가하거나, Amazon Kendra Query 작업 호출을 위한 전용 역할을 사용할 수 있습니다. AWS CLI 또는 SDK를 사용하여 의도를 생성하는 경우 Query 작업 호출을 위한 전용 역할을 사용해야 합니다.

권한 연결

Amazon Kendra 콘솔을 사용하여 Query 작업에 액세스할 수 있는 권한을 기본 Amazon Lex 서비스 연결 역할에 연결할 수 있습니다. 서비스 연결 역할에 권한을 연결하면 Amazon Kendra 인덱스에 연결하기 위한 전용 런타임 역할을 생성하고 관리할 필요가 없습니다.

Amazon Lex 콘솔에 액세스하는 데 사용하는 사용자, 역할 또는 그룹에는 역할 정책을 관리할 수 있는 권한이 있어야 합니다. 콘솔 액세스 역할에 다음 IAM 정책을 연결합니다. 이러한 권한을 부여하면 해당 역할이 기존 서비스 연결 역할 정책을 변경할 수 있는 권한을 갖게 됩니다.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iam:AttachRolePolicy",
                "iam:PutRolePolicy",
                "iam:GetRolePolicy"
            ],
            "Resource": "arn:aws:iam::*:role/aws-service-role/lex.amazonaws.com/AWSServiceRoleForLexBots"
        },
        {
            "Effect": "Allow",
            "Action": "iam:ListRoles",
            "Resource": "*"
        }
    ]
}

역할 지정

Amazon Kendra Query 작업을 호출할 때 런타임 역할을 지정하기 위하여 콘솔 AWS CLI을 사용하거나 API를 사용할 수 있습니다.

런타임 역할을 지정하는 데 사용하는 사용자, 역할 또는 그룹에는 iam:PassRole 권한이 있어야 합니다. 다음 정책은 권한을 정의합니다. iam:AssociatedResourceArn 및 iam:PassedToService 조건 컨텍스트 키를 사용해 권한 범위를 추가로 제한할 수 있습니다. 자세한 내용은 AWS Identity and Access Management사용 설명서의 IAM 및 AWS STS 조건 컨텍스트 키를 참조하세요.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "iam:PassRole",
            "Resource": "arn:aws:iam::account:role/role"
        }
    ]
}

Amazon Lex가 Amazon Kendra를 호출하는 데 사용하는 런타임 역할에는 kendra:Query 권한이 있어야 합니다. Amazon Kendra Query 작업을 호출할 수 있는 권한을 위해 기존 IAM 역할 을 사용하는 경우 역할에 다음 정책이 연결되어 있어야 합니다.

IAM 콘솔, IAM API 또는 AWS CLI를 사용하여 정책을 생성하고 역할에 연결할 수 있습니다. 여기에 나온 지침에서는 AWS CLI를 사용하여 역할과 정책을 생성합니다.

참고

다음 코드는 Linux 및 MacOS용으로 형식이 지정됩니다. Windows의 경우 Linux 줄 연속 문자(\)를 캐럿(^)으로 바꿉니다.

역할에 쿼리 작업 권한을 추가하려면

  1. 현재 디렉터리에 KendraQueryPolicy.json이라는 문서를 만들고 다음 코드를 추가한 다음 저장합니다.

    {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "kendra:Query"
            ],
            "Resource": [
                "arn:aws:kendra:region:account:index/index ID"
            ]
        }
    ]
}

  2. AWS CLI에서 다음 명령을 실행하여 Amazon Kendra Query 작업 실행을 위한 IAM 정책 을 생성합니다.

    aws iam create-policy \
    --policy-name query-policy-name \
    --policy-document file://KendraQueryPolicy.json

  3. Query 작업을 호출하는 데 사용하는 IAM 역할 에 정책을 연결합니다.

    aws iam attach-role-policy \
    --policy-arn arn:aws:iam::account-id:policy/query-policy-name
    --role-name role-name

Amazon Lex 서비스 연결 역할을 업데이트하거나 봇에 AMAZON.KendraSearchIntent를 만들 때 생성한 역할을 사용하도록 선택할 수 있습니다. 다음 절차에서는 사용할 IAM 역할 을 선택하는 방법을 보여 줍니다.

AMAZON.KendraSearchItent에 대한 런타임 역할을 지정하려면

  1. AWS Management Console에 로그인하고 https://console.aws.amazon.com/lex에서 Amazon Lex 콘솔을 엽니다.

  2. AMAZON.KendraSearchIntent를 추가할 봇을 선택합니다.

  3. 의도 옆에 있는 더하기(+) 기호를 선택합니다.

  4. 의도 추가에서 기존 의도 검색을 선택합니다.

  5. 검색 의도에 AMAZON.KendraSearchIntent를 입력한 다음 추가를 선택합니다.

  6. 기본 제공 의도 복사에서 의도의 이름(예: KendraSearchIntent)을 입력한 다음 추가를 선택합니다.

  7. Amazon Kendra 쿼리 섹션을 엽니다.

  8. IAM 역할에서 다음 옵션 중 하나를 선택합니다.

    • 봇이 Amazon Kendra 인덱스를 쿼리할 수 있도록 Amazon Lex 서비스 연결 역할을 업데이트하려면 Amazon Kendra 권한 추가를 선택합니다.

    • Amazon Kendra Query 작업을 호출할 수 있는 권한이 있는 역할을 사용하려면 기존 역할 사용을 선택합니다.

요청 및 세션 속성을 필터로 사용

Amazon Kendra의 응답을 현재 대화와 관련된 항목으로 필터링하려면 봇을 생성할 때 queryFilterString 파라미터를 추가하여 세션 및 요청 속성을 필터로 사용합니다. 의도를 생성할 때 속성의 자리 표시자를 지정하면 Amazon Lex V2가 Amazon Kendra를 호출하기 전에 해당 값을 대체합니다. 요청 속성에 대한 자세한 내용은 Setting Request Attributes 섹션을 참조하십시오. 세션 속성에 대한 자세한 내용은 Setting Session Attributes 섹션을 참조하십시오.

다음은 Amazon Kendra라는 요청 속성을 사용하여 쿼리를 필터링하는 queryFilterString 파라미터의 예입니다.

"{"equalsTo": {"key": "City", "value": {"stringValue": "Seattle"}}}"

다음은 "SourceURI"이라는 세션 속성을 사용하여 Amazon Kendra 쿼리를 필터링하는 queryFilterString 파라미터의 예입니다.

"{"equalsTo": {"key": "SourceURI","value": {"stringValue": "[FileURL]"}}}"

다음은 "DepartmentName" 이라는 요청 속성을 사용하여 Amazon Kendra 쿼리를 필터링하는 queryFilterString 파라미터의 예입니다.

"{"equalsTo": {"key": "Department","value": {"stringValue": "((DepartmentName))"}}}"

AMAZON.KendraSearchInteng 필터는 Amazon Kendra 검색 필터와 동일한 형식을 사용합니다. 자세한 내용은 Amazon Kendra 개발자 안내서의 문서 속성을 사용하여 검색 결과 필터링을 참조하십시오.

AMAZON.KendraSearchIntent과 함께 사용되는 쿼리 필터의 문자열은 각 필터의 첫 글자에 소문자를 사용해야 합니다. 예를 들어, 다음은 AMAZON.KendraSearchIntent에 대한 유효한 쿼리 필터입니다.

{
    "andAllFilters": [
        {
            "equalsTo": {
                "key": "City",
                "value": {
                    "stringValue": "Seattle"
                }
            }
        },
        {
            "equalsTo": {
                "key": "State",
                "value": {
                    "stringValue": "Washington"
                }
            }
        }
    ]
}

검색 응답 사용

Amazon Kendra는 의도의 conclusion 문에서 검색에 대한 응답을 반환합니다. 이행 Lambda 함수가 결론 메시지를 생성하지 않는 한, 의도에 conclusion 문이 있어야 합니다.

Amazon Kendra에는 네 가지 유형의 응답이 있습니다.

  • x-amz-lex:kendra-search-response-question_answer-question-<N> – 검색과 일치하는 FAQ 질문

  • x-amz-lex:kendra-search-response-question_answer-answer-<N> – 검색과 일치하는 FAQ 답변

  • x-amz-lex:kendra-search-response-document-<N> – 표현 텍스트와 관련된 인덱스에 있는 문서의 발췌문

  • x-amz-lex:kendra-search-response-document-link-<N> – 표현 텍스트와 관련된 인덱스에 있는 문서의 URL

  • x-amz-lex:kendra-search-response-answer-<N> – 질문에 대한 답이 되는 인덱스에 있는 문서의 발췌문

응답은 request 속성에서 반환됩니다. 각 속성에 1부터 5까지 번호가 매겨진 최대 5개의 응답이 있을 수 있습니다. 서비스 이름 변경에 대한 자세한 내용을 알아보려면 Amazon Kendra 개발자 가이드의 응답 유형을 참조하세요.

conclusion 문에는 하나 이상의 메시지 그룹이 있어야 합니다. 각 메시지 그룹에는 하나 이상의 메시지가 포함됩니다. 각 메시지에는 Amazon Kendra의 응답에서 요청 속성으로 대체되는 하나 이상의 자리 표시자 변수가 포함될 수 있습니다. 메시지 그룹에는 해당 메시지의 모든 변수가 런타임 응답에서 요청 속성 값으로 대체되는 메시지가 하나 이상 있어야 합니다. 그렇지 않은 경우 자리 표시자 변수가 없는 메시지 하나가 그룹에 있어야 합니다. 요청 속성은 이중 괄호("((" "))")로 묶입니다. 다음 메시지 그룹 메시지는 Amazon Kendra의 모든 응답과 일치합니다.

  • "질문에 대한 FAQ를 찾았습니다: ((x-amz-lex:kendra-search-response-question_answer-question-1)), and the answer is ((x-amz-lex:kendra-search-response-question_answer-answer-1))"

  • "I found an excerpt from a helpful document: ((x-amz-lex:kendra-search-response-document-1))"

  • "질문에 대한 답변은 다음과 같습니다 ((x-amz-lex:kendra-search-response-answer-1))"

Lambda 함수를 사용하여 요청 및 응답 관리

AMAZON.KendraSearchIntent 의도는 대화 코드 후크 및 이행 코드 후크를 사용하여 Amazon Kendra에 대한 요청과 응답을 관리할 수 있습니다. Amazon Kendra에 보내는 쿼리를 수정하려면 대화 코드 후크 Lambda 함수를 사용하고, 응답을 수정하려면 이행 코드 후크 Lambda 함수를 사용합니다.

대화 코드 후크를 사용하여 쿼리 생성

대화 코드 후크를 사용하여 Amazon Kendra에 보낼 쿼리를 생성할 수 있습니다. 대화 코드 후크 사용은 선택 사항입니다. 대화 코드 후크를 지정하지 않으면 Amazon Lex가 사용자 표현으로부터 쿼리를 구성하고 의도 구성 시 제공된(있는 경우) queryFilterString를 사용합니다.

Amazon Kendra에 대한 요청을 수정하기 위해 대화 코드 후크 응답에서 다음 두 필드를 사용할 수 있습니다.

  • kendraQueryFilterString – Amazon Kendra 요청에 대한 속성 필터를 지정하려면 이 문자열을 사용합니다. 인덱스에 정의된 인덱스 필드 중 하나를 사용하여 쿼리를 필터링할 수 있습니다. 필터 문자열의 구조는 Amazon Kendra 개발자 안내서의 문서 속성을 사용하여 쿼리 필터링을 참조하십시오. 지정된 필터 문자열이 유효하지 않으면 InvalidLambdaResponseException 예외가 발생합니다. kendraQueryFilterString 문자열은 해당 의도에 구성된 queryFilterString에 지정되어 있는 모든 쿼리 문자열을 재정의합니다.

  • kendraQueryRequestPayload – Amazon Kendra 쿼리를 지정하려면 이 문자열을 사용합니다. 쿼리에서 Amazon Kendra의 모든 기능을 사용할 수 있습니다. 유효한 쿼리를 지정하지 않으면 InvalidLambdaResponseException 예외가 발생합니다. 자세한 정보는 Amazon Kendra 개발자 안내서의 쿼리를 참조하세요.

필터 또는 쿼리 문자열을 생성한 후 응답 dialogAction 필드를 delegate로 설정하여 Amazon Lex에 응답을 보냅니다. Amazon Lex는 Amazon Kendr 에 쿼리를 보낸 다음 이행 코드 후크에 쿼리 응답을 반환합니다.

응답에 이행 코드 후크 사용

Amazon Lex가 Amazon Kendra에 쿼리를 보내면 쿼리 응답이 AMAZON.KendraSearchIntent 이행 Lambda 함수로 반환됩니다. 코드 후크에 대한 입력 이벤트에는 Amazon Kendra의 전체 응답이 포함되어 있습니다. 쿼리 데이터는 Amazon Kendra Query 작업에서 반환된 것과 동일한 구조입니다. 자세한 정보는 Amazon Kendra 개발자 안내서의 쿼리 응답 구문을 참조하세요.

이행 코드 후크는 선택 사항입니다. 이행 코드 후크가 존재하지 않거나 이행 코드 후크가 응답에 메시지를 반환하지 않는 경우 Amazon Lex는 응답에 conclusion 문을 사용합니다.