분석을 위한 API 사용

포커스 모드

분석을 위한 API 사용 - Amazon Lex

결과 필터링 봇에 대한 지표 검색 봇의 세션 및 발화에 대한 메타데이터 검색 봇의 세션 및 발화에 대한 메타데이터 검색 Lex V2 대화에서 발화 통계 보기

이 섹션에서는 봇에 대한 분석을 검색하는 데 사용하는 API 작업에 대해 설명합니다.

참고

ListSutteranceMetrics 및 ListUtteranceAnalyticsData를 사용하려면 IAM 역할에 발화 관련 분석에 대한 액세스를 제공하는 ListAggregatedUtterances 작업을 수행할 수 있는 권한이 있어야 합니다. IAM 역할에 적용되는 IAM 정책 및 세부 정보는 Lex V2 대화에서 발화 통계 보기 단원을 참조하세요.

다음 API 작업은 봇에 대한 요약 지표를 검색합니다.
다음 API 작업은 세션 및 발화에 대한 메타데이터 목록을 가져옵니다.
- ListSessionAnalyticsData
- ListUtteranceAnalyticsData
ListIntentPaths 작업은 고객이 봇과 대화할 때 취하는 의도 순서에 대한 지표를 검색합니다.

결과 필터링

Analytics API 요청에는 startTime 및 endTime을 지정해야 합니다. API는 startTime 이후에 시작되어 endTime 이전에 종료된 세션, 의도, 의도 단계 또는 발화를 반환합니다.

filters는 Analytics API 요청의 선택적 필드입니다. AnalyticsSessionFilter, AnalyticsIntentFilter, AnalyticsIntentStageFilter 또는 AnalyticsUtteranceFilter 객체의 목록에 매핑됩니다. 각 객체에서 필드를 사용하여 필터링 기준으로 사용할 식을 만드세요. 예를 들어 목록에 다음 필터를 추가하면 봇은 30초 이상의 대화를 검색합니다.


{
    "name": "Duration",
    "operator": "GT",
    "value": "30 sec",
}

봇에 대한 지표 검색

ListSessionMetrics, ListIntentMetrics, ListIntentStageMetrics 및 ListUtteranceMetrics 작업을 사용하여 세션, 의도, 의도 단계 및 발화에 대한 요약 지표를 검색할 수 있습니다.

이러한 작업의 경우 다음 필수 필드를 채우세요.

결과를 검색하려는 시간 범위를 정의하려면 startTime 및 endTime을 입력합니다.
metrics에서 계산하려는 지표를 AnalyticsSessionMetric, AnalyticsIntentMetric, AnalyticsIntentStageMetric 또는 AnalyticsUtteranceMetric 객체 목록으로 지정합니다. 각 객체에서 name 필드를 사용하여 계산할 메트릭을 지정하고, statistic 필드를 사용하여 Sum, Average 또는 Max 수치를 계산할지 여부를 지정하고, order 필드를 사용하여 결과를 Ascending 또는 Descending 순서로 정렬할지 여부를 지정합니다.

참고
metrics와 binBy 객체 모두 order 필드를 포함합니다. 두 객체 중 하나에만 정렬 order를 지정할 수 있습니다.

요청의 나머지 필드는 선택 사항입니다. 다음과 같은 방법으로 결과를 필터링하고 구성할 수 있습니다.

결과 필터링 - filters 필드를 사용하여 결과를 필터링합니다. 자세한 내용은 결과 필터링 단원을 참조하세요.
범주별 결과 그룹화 – groupBy 필드, 즉 단일 AnalyticsSessionResult, AnalyticsIntentResult, AnalyticsIntentStageResult 또는 AnalyticsUtteranceResult 객체가 포함된 목록을 지정합니다. 객체에서 결과를 그룹화할 범주가 있는 name 필드를 지정합니다.

요청에 groupBy 필드를 지정한 경우 응답의 results 객체에는 groupByKeys, 요청에 지정한 name과 value 필드에 해당 카테고리의 멤버가 각각 포함된 AnalyticsSessionGroupByKey, AnalyticsIntentGroupByKey, AnalyticsIntentStageGroupByKey 또는 AnalyticsUtteranceGroupByKey 객체 목록이 포함되어 있습니다.
시간별 결과 이진화 – binBy 필드, 즉 단일 AnalyticsBinBySpecification 객체가 포함된 목록을 지정합니다. 객체에서 대화가 시작된 시점을 기준으로 결과를 범주화하려면 ConversationStartTime을 사용하여 name 필드를 지정하고, 발화가 발생한 시점을 기준으로 결과를 범주화하려면 UtteranceTimestamp를 사용하여 이름 필드를 지정합니다. interval 필드에서 결과를 구간화할 시간 간격을 지정하고, order 필드에서 Ascending 또는 Descending 순서로 정렬할지 여부를 지정합니다.

요청에서 binBy 필드를 지정하는 경우 응답의 results 객체에는 각각 요청에서 지정한 name과 value 필드에서 해당 구간을 정의하는 시간 간격을 가진 AnalyticsBinKey 객체 목록인 binKeys가 포함됩니다.

참고
metrics와 binBy 객체 모두 order 필드를 포함합니다. 두 객체 중 하나에만 정렬 order를 지정할 수 있습니다.

다음 필드를 사용하여 응답 표시를 처리하세요.

maxResults 필드에 1에서 1,000 사이의 숫자를 지정하여 단일 응답에서 반환되는 결과 수를 제한하세요.
결과 수가 maxResults 필드에 지정한 수보다 많으면 응답에 nextToken이 포함됩니다. 요청을 다시 하되, nextToken 필드에서 이 값을 사용하면 다음 일괄 결과를 반환할 수 있습니다.

ListUtteranceMetrics를 사용하는 경우 attributes 필드에 반환할 속성을 지정할 수 있습니다. 이 필드는 단일 AnalyticSutteranceAttribute 객체를 포함하는 목록에 매핑됩니다. 발화 당시 Amazon Lex V2가 사용 중인 의도를 반환하려면 name 필드에 LastUsedIntent를 지정하세요.

응답에서 results 필드는 AnalyticsSessionResult, AnalyticsIntentResult, AnalyticsIntentStageResult 또는 AnalyticsUtteranceResult 객체의 목록에 매핑됩니다. 각 객체에는 지정한 메서드에서 만든 구간차원 또는 그룹 외에도 요청한 지표에 대한 요약 통계 값을 반환하는 metrics 필드가 포함되어 있습니다.

봇의 세션 및 발화에 대한 메타데이터 검색

ListSessionAnalyticsData 및 ListUtteranceAnalyticsData 작업을 사용하여 개별 세션 및 발화에 대한 메타데이터를 검색할 수 있습니다.

필수 startTime 및 endTime 필드를 입력하여 결과를 검색할 시간 범위를 정의합니다.

요청의 나머지 필드는 선택 사항입니다. 결과를 필터링하고 정렬하는 방법:

결과 필터링 - filters 필드를 사용하여 결과를 필터링합니다. 자세한 내용은 결과 필터링 단원을 참조하세요.
결과 정렬 – SessionDataSortBy 또는 UtteranceDataSortBy 객체가 포함된 sortBy 필드를 사용하여 결과를 정렬합니다. name 필드에 정렬할 값을 지정하고 order 필드에 Ascending 또는 Descending 순서로 정렬할지 여부를 지정합니다.

다음 필드를 사용하여 응답 표시를 처리하세요.

maxResults 필드에 1에서 1,000 사이의 숫자를 지정하여 단일 응답에서 반환되는 결과 수를 제한하세요.
결과 수가 maxResults 필드에 지정한 수보다 많으면 응답에 nextToken이 포함됩니다. 요청을 다시 하되, nextToken 필드에서 이 값을 사용하면 다음 일괄 결과를 반환할 수 있습니다.

응답에서 sessions 또는 utterances 필드는 SessionSpecification 또는 UtteranceSpecification 객체 목록에 매핑됩니다. 각 객체에는 단일 세션 또는 발화에 대한 메타데이터가 들어 있습니다.

봇의 세션 및 발화에 대한 메타데이터 검색

ListIntentPaths 작업을 사용하면 고객이 봇과 대화할 때 취하는 의도 순서에 대한 메트릭을 검색할 수 있습니다.

이 작업을 수행하려면 다음 필수 필드를 채우세요.

결과를 검색하려는 시간 범위를 정의하려면 startTime 및 endTime을 입력합니다.
intentPath를 제공하여 지표를 검색할 의도의 순서를 정의합니다. 경로에 있는 의도를 슬래시로 구분합니다. 예를 들어 intentPath 필드에 /BookCar/BookHotel을 입력하면 사용자가 해당 순서로 BookCar 및 BookHotel 의도를 간접적으로 호출한 횟수에 대한 세부 정보가 표시됩니다.

선택적인 filters 필드를 사용하여 결과를 필터링할 수 있습니다. 자세한 내용은 결과 필터링을 참조하세요.

Lex V2 대화에서 발화 통계 보기

발화 통계를 사용하여 사용자가 봇에 보내는 발화를 확인할 수 있습니다. Amazon Lex V2에서 성공적으로 감지한 발화와 감지하지 못한 발화를 모두 볼 수 있습니다. 이 정보를 사용하여 봇을 조정하는 데 도움을 줄 수 있습니다.

예를 들어, 사용자가 Amazon Lex V2에서 놓친 내용을 보내는 것을 발견한 경우 해당 발화를 의도에 추가할 수 있습니다. 의도의 초안 버전이 새 말로 업데이트되므로 봇에 배포하기 전에 테스트할 수 있습니다.

Amazon Lex V2가 해당 발화를 봇용으로 구성된 의도를 간접적으로 호출하려는 시도로 인식하면 발화가 감지됩니다. Amazon Lex V2가 표현을 인식하지 못하고 대신 AMAZON.FallbackIntent를 간접적으로 호출하면 표현을 놓친 것입니다.

발화 통계는 ListUtteranceMetrics API와 ListAggregatedUtterance API를 사용하여 볼 수 있습니다.

다음 조건에서는 ListUtteranceMetrics API를 사용하여 발화 통계가 생성되지 않습니다.

콘솔을 사용하여 봇을 만들 때는 Child Online Privacy Protection Act 설정이 예로 설정되었고, CreateBot 작업을 통해 봇을 만들 때는 childDirected 필드가 true로 설정되었습니다.

ListUtteranceMetrics API는 다음과 같은 추가 기능을 제공합니다.

감지된 발화에 대한 매핑된 의도와 같은 추가 정보를 확인할 수 있습니다.
더 많은 필터링 기능(채널 및 모드 포함).
보존 날짜 범위 연장(30일).
데이터 스토리지를 옵트아웃한 경우에도 API를 사용할 수 있습니다. 놓친 발화 및 감지된 발화에 대한 콘솔 기능은 ListUtteranceMetrics API에 따라 달라집니다.

다음 조건에서는 ListAggregatedUtterance API를 사용하여 발화 통계가 생성되지 않습니다.

콘솔을 사용하여 봇을 만들 때는 Child Online Privacy Protection Act 설정이 예로 설정되었고, CreateBot 작업을 통해 봇을 만들 때는 childDirected 필드가 true로 설정되었습니다.
하나 이상의 슬롯에서 슬롯 난독화 기능을 사용하고 있습니다.
Amazon Lex 개선에 참여하지 않기로 선택했습니다.

ListAggregatedUtterance API는 다음과 같은 기능을 제공합니다.

사용 가능한 세부 정보가 적습니다(발화에 대해 매핑된 의도 없음).
제한된 필터링 기능(채널 및 모드 제외).
짧은 보존 날짜 범위(15일).

발화 통계를 사용하면 봇 상호 작용에서 해당 발화가 마지막으로 사용된 시간과 함께 특정 발화가 감지되었는지 또는 누락되었는지 확인할 수 있습니다.

Amazon Lex V2는 사용자가 봇과 상호 작용하는 동안 지속적으로 발화를 저장합니다. 콘솔 또는 ListAggregatedUtterances 작업을 사용하여 통계를 쿼리할 수 있습니다. 데이터 보존 기간은 15일이며, 사용자가 데이터 스토리지에서 옵트아웃한 경우에는 사용할 수 없습니다. DeleteUtterances 작업을 사용하거나 데이터 스토리지에서 옵트아웃하여 발화를 삭제할 수 있습니다. AWS 계정을 해지하면 모든 발화가 삭제됩니다. 저장된 발화는 서버에서 관리하는 키로 암호화됩니다.

봇 버전을 삭제하면 ListUtteranceMetrics를 사용하여 최대 30일 동안 버전에 대한 발화 통계를 사용할 수 있고 ListAggregatedUtterances를 사용하여 15일 동안 사용할 수 있습니다. Amazon Lex V2 콘솔에서는 삭제된 버전에 대한 통계를 볼 수 없습니다. 삭제된 버전의 통계를 보려면 ListAggregatedUtterances 및 ListUtteranceMetrics 작업을 모두 사용할 수 있습니다.

ListAggregatedUtterances 및 ListUtteranceMetrics API 모두에서 발화는 발화 텍스트를 기준으로 집계됩니다. 예를 들어 고객이 “피자를 주문하고 싶어요”라는 문구를 사용한 모든 인스턴스는 응답에서 동일한 행으로 집계됩니다. RecognizEtterance 작업을 사용할 때 사용되는 텍스트는 입력 대화 기록입니다.

ListAggregatedUtterances 및 ListUtteranceMetrics API를 사용하려면 다음 정책을 역할에 적용하세요.


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "ListAggregatedUtterancesPolicy",
            "Effect": "Allow",
            "Action": "lex:ListAggregatedUtterances",
            "Resource": "*"
        }
    ]
}