기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# Amazon Chime SDK 음성 분석 사용
Amazon Chime SDK 음성 분석 기능을 사용하면 화자 검색 및 음성 톤 분석을 구현할 수 있습니다. 화자 검색을 사용하여 새 발신자를 식별 및 등록하고, 반복 발신자를 식별하여 해당 식별에 신뢰도 점수를 할당합니다. 음성 톤 분석을 사용하여 발신자의 감정을`neutral`, `positive`, 또는 `negative`로 예측합니다.
음성 분석은 Amazon Chime SDK 호출 분석 세션의 선택적 구성 요소로 실행합니다.
음성 분석은 미디어 인사이트 파이프라인 또는 Amazon Chime SDK 음성 커넥터 호출과 함께 작동합니다. 작업을 보다 세밀하게 제어하고 정보를 얻으려면 [ 미디어 파이프라인 SDK](media-pipelines.md)를 사용하고 미디어 인사이트 파이프라인에서 작업을 호출하는 것이 좋습니다.
이전 버전과의 호환성을 보장하기 위해 음성 커넥터를 사용할 수 있지만, 새로운 기능으로 미디어 인사이트 파이프라인 API만 업데이트합니다.
음성 커넥터 생성 및 사용에 대한 자세한 내용은 Amazon Chime SDK 관리자 안내서**의 [Amazon Chime SDK 음성 커넥터 관리](https://docs.aws.amazon.com/chime-sdk/latest/ag/voice-connectors.html)를 참조하세요.
음성 분석은 다음도 제공합니다.
+ 비동기 작업 처리. 서로 독립적으로 실행되는 작업.
+ 인사이트 처리 시기 제어.
[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartSpeakerSearchTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartSpeakerSearchTask.html) 및 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartVoiceToneAnalysisTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartVoiceToneAnalysisTask.html) API를 직접 호출하여 음성 분석을 시작할 수 있습니다.
다음 항목에서는 음성 분석 사용 방법을 설명합니다.
**Topics**
+ [Amazon Chime SDK의 음성 분석 아키텍처 이해](va-architecture.md)
+ [Amazon Chime SDK의 화자 검색 워크플로 이해](va-data-flow.md)
+ [Amazon Chime SDK의 샘플 음성 톤 분석 워크플로](va-tone-flow.md)
+ [Amazon Chime SDK의 작업 결과 폴링](va-task-result-poll.md)
+ [Amazon Chime SDK의 알림 이해](va-notification-targets.md)
+ [Amazon Chime SDK의 데이터 스토리지, 옵트아웃, 데이터 보존 정책 이해](va-opt-out.md)
+ [음성 API를 사용하여 Amazon Chime SDK용 음성 분석 실행](va-in-voice-namespace.md)
# Amazon Chime SDK의 음성 분석 아키텍처 이해
이 섹션의 주제에서는 각 기능에 대한 데이터 흐름을 포함하여 Amazon Chime SDK 음성 분석 아키텍처에 대한 개요를 제공합니다.
이 다이어그램은 음성 분석을 통한 데이터 흐름 방식을 간략하게 보여 줍니다.
![\[음성 분석을 통한 높은 수준의 데이터 흐름을 보여주는 다이어그램입니다.\]](http://docs.aws.amazon.com/ko_kr/chime-sdk/latest/dg/images/va-architecture-kvs.png)
다이어그램에서
1. 오디오는 발신자 및 상담원을 위해 Kinesis Video Stream으로 스트리밍됩니다. Kinesis Video Streams 프로듀서 또는 Amazon Chime SDK 음성 커넥터 스트리밍을 사용하여 이 작업을 수행할 수 있습니다. 자세한 내용은 이 안내서의 [Amazon Chime SDK의 기계 학습 기반 분석을 위한 워크플로 이해](ml-based-analytics.md) 항목과 Amazon Chime SDK 관리자 안내서**의 [ Kinesis로 Amazon Chime SDK 음성 커넥터 미디어 스트리밍](https://docs.aws.amazon.com/chime-sdk/latest/ag/start-kinesis-vc.html)을 참조하세요.
1. 애플리케이션 또는 빌더는 발신자의 동의 후 오디오 스트림에 대해 화자 검색, 음성 톤 분석 또는 두 가지 모두를 트리거합니다.
1. 통화 중 음성 분석은 Amazon SQS(Simple Queue Service), SNS(Simple Notification Service), AWS Lambda, Amazon Kinesis Data Streams 중 하나로 대상에 알림을 보냅니다.
또한 음성 분석은 생성된 데이터를 관리하기 위한 이러한 도구를 제공합니다.
**음성 프로필**
음성 임베딩, 임베딩의 고유 ID, 만료 날짜의 조합입니다. 음성 프로필은 보안상의 이유와 시간이 지남에 따라 음성이 변하기 때문에 3년 후에 만료됩니다. 음성 프로필을 다시 만들지 않으려면 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_UpdateVoiceProfile.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_UpdateVoiceProfile.html) API를 직접 호출하세요. 만료 날짜에 대한 자세한 내용은 [Amazon Chime SDK 음성 분석을 위한 데이터 보존 이해](va-data-retention.md) 섹션을 참조하세요.
음성 임베딩을 등록하거나 등록된 음성 임베딩을 업데이트하려면 통화 종료 후 24시간 이내에 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateVoiceProfile.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateVoiceProfile.html) 또는 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_UpdateVoiceProfile.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_UpdateVoiceProfile.html) API를 직접 호출해야 합니다.
**음성 프로필 도메인**
음성 프로필 모음입니다.
# Amazon Chime SDK의 화자 검색 워크플로 이해
이 단원에서는 Amazon Chime SDK 화자 검색 분석을 위한 예제 데이터 및 프로그램 흐름을 보여줍니다.
화자 검색 기능에는 음성 임베딩 생성이 포함되며, 이를 통해 발신자의 음성을 이전에 저장된 음성 데이터와 비교할 수 있습니다. 생체 식별자 및 생체 인식 정보를 디지털 성문 형태로 수집, 사용, 저장 및 보관하려면 서면 동의서를 통한 발신자의 사전 동의가 필요할 수 있습니다. 이러한 동의는 일리노이주, 텍사스주, 워싱턴주의 생체인식법 및 기타 주 개인정보 보호법을 비롯한 다양한 주법에 따라 요구됩니다. 화자 검색 기능을 사용하기 전에 관련 법률 및 기능 사용에 적용되는 [AWS 서비스 약관](https://aws.amazon.com/service-terms/)에 따라 필요한 대로 모든 통지를 제공하고 모든 동의를 얻어야 합니다.
다음 다이어그램은 화자 검색 분석 작업을 통한 데이터 흐름 예를 보여줍니다. 다이어그램 아래에 번호가 매겨진 설명은 프로세스의 각 단계를 설명합니다. 이 다이어그램에서는 이미 `VoiceAnalyticsProcessor`가 있는 통화 분석 구성으로 Amazon Chime SDK 음성 커넥터를 구성했다고 가정합니다. 자세한 내용은 [음성 커넥터 통화 레코딩](record-vc-calls.md) 단원을 참조하십시오.
![\[화자 검색 분석을 통한 데이터 흐름을 보여주는 다이어그램입니다.\]](http://docs.aws.amazon.com/ko_kr/chime-sdk/latest/dg/images/speaker-search-workflow-2.png)
1. 사용자 또는 시스템 관리자는 음성 임베딩 및 음성 프로필을 저장하기 위한 음성 프로필 도메인을 생성합니다. 음성 프로필 도메인 생성에 대한 자세한 내용은 Amazon Chime SDK** 관리자 안내서의 [음성 프로필 도메인 생성](https://docs.aws.amazon.com/chime-sdk/latest/ag/create-vp-domain.html)을 참조하세요. [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateVoiceProfileDomain.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateVoiceProfileDomain.html) API를 사용할 수도 있습니다.
1. 발신자는 Amazon Chime SDK 음성 커넥터에 할당된 전화번호를 사용하여 전화를 겁니다. 또는 상담원이 음성 커넥터 번호를 사용하여 아웃바운드 전화를 걸 수도 있습니다.
1. Amazon Chime SDK 음성 커넥터 서비스는 트랜잭션 ID를 생성하고 이를 호출과 연결합니다.
1. 애플리케이션이 EventBridge 이벤트를 구독한다고 가정하면 애플리케이션은 미디어 인사이트 파이프라인 구성을 사용하여 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html) API를 직접 호출하고 음성 커넥터 호출을 위한 Kinesis Video Stream ARN을 직접 호출합니다.
EventBridge 사용에 대한 자세한 내용은 [Amazon Chime SDK의 기계 학습 기반 분석을 위한 워크플로 이해](ml-based-analytics.md) 섹션을 참조하세요.
1. 대화형 음성 응답 시스템과 같은 애플리케이션 또는 상담원은 발신자에게 통화 레코딩 및 음성 분석을 위한 음성 임베딩 사용에 대해 고지하고 참여에 대한 동의를 구합니다.
1. 발신자가 동의를 제공하면 음성 커넥터와 트랜잭션 ID가 있는 경우 애플리케이션이나 상담원이 [음성 SDK](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Voice.html)를 통해 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask.html) API를 직접 호출할 수 있습니다. 또는 트랜잭션 ID 대신 미디어 인사이트 파이프라인 ID가 있는 경우 [미디어 파이프라인 SDK](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Media_Pipelines.html)에서 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartSpeakerSearchTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartSpeakerSearchTask.html) API를 직접 호출합니다.
발신자가 동의를 제공하면 애플리케이션 또는 상담원이 `StartSpeakerSearchTask` API를 호출합니다. 음성 커넥터 ID, 트랜잭션 ID 및 음성 프로필 도메인 ID를 API에 전달해야 합니다. 비동기 작업을 식별하기 위해 화자 검색 작업 ID가 반환됩니다.
**참고**
SDK 중 하나에서 `StartSpeakerSearchTask` API를 호출하기 전에 법률 및 [AWS 서비스 약관](https://aws.amazon.com/service-terms/)에 따라 필요한 대로 필요한 공지를 제공하고 필요한 동의를 얻어야 합니다.
1. 시스템은 10초 분량의 발신자 음성을 누적합니다. 발신자는 최소한 그 시간 동안 통화해야 합니다. 시스템은 침묵을 캡처하거나 분석하지 않습니다.
1. 미디어 인사이트 파이프라인은 해당 도메인의 음성 프로필과 음성을 비교하여 신뢰도가 높은 상위 10개 일치 항목을 나열합니다. 일치하는 항목을 찾지 못하면 음성 커넥터가 음성 프로필을 생성합니다.
1. 미디어 인사이트 파이프라인 서비스는 구성된 알림 대상에 알림 이벤트를 보냅니다.
1. 발신자는 계속 말하고 추가로 10초 동안 비침묵 발화를 제공합니다.
1. 미디어 인사이트 파이프라인은 음성 프로필을 생성하거나 기존 음성 프로필을 업데이트하는 데 사용할 수 있는 등록 음성 임베딩을 생성합니다.
1. 미디어 인사이트 파이프라인은 구성된 `VoiceprintGenerationSuccessful` 알림 대상에 알림을 보냅니다.
1. 애플리케이션에서 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateVoiceProfile.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateVoiceProfile.html) 또는 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_UpdateVoiceProfile.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_UpdateVoiceProfile.html) API를 직접 호출하여 프로필을 만들거나 업데이트합니다.
1. 애플리케이션에서 필요에 따라 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_GetSpeakerSearchTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_GetSpeakerSearchTask.html) API를 직접 호출하여 화자 검색 작업의 최신 상태를 가져옵니다.
# Amazon Chime SDK의 샘플 음성 톤 분석 워크플로
**중요**
음성 톤 분석에는 언어 및 음조 정보를 기반으로 화자의 감정을 예측하는 작업이 포함됩니다. 개인에게 법적 또는 유사하게 중대한 영향을 미칠 수 있는 개인에 대한 결정을 내리는 경우(예: 고용, 주택, 신용 등급 또는 금융 제안 등과 관련하여)를 포함하여 법률에서 금지하는 방식으로는 감정 분석을 사용해서는 안 됩니다.
음성 톤 분석은 통화 중인 사람들의 목소리를 분석하고 그들의 감정(`positive`, `negative`, 또는 `neutral`)을 예측합니다.
다음 다이어그램은 음성 톤 분석을 위한 워크플로의 예를 보여 줍니다. 이미지 아래의 번호가 매겨진 항목은 프로세스의 각 단계를 설명합니다.
**참고**
이 다이어그램에서는 이미 `VoiceAnalyticsProcessor`가 있는 통화 분석 구성으로 Amazon Chime SDK 음성 커넥터를 구성했다고 가정합니다. 자세한 내용은 [음성 커넥터 통화 레코딩](record-vc-calls.md) 단원을 참조하십시오.
![\[음성 톤 분석을 통한 데이터 흐름을 보여주는 다이어그램입니다.\]](http://docs.aws.amazon.com/ko_kr/chime-sdk/latest/dg/images/voice-tone-workflow-v2.png)
다이어그램에서
1. 발신자는 Amazon Chime SDK 음성 커넥터에 할당된 전화번호를 사용하여 전화를 겁니다. 또는 상담원이 음성 커넥터 번호를 사용하여 아웃바운드 전화를 걸 수도 있습니다.
1. 음성 커넥터 서비스는 트랜잭션 ID를 생성하여 통화와 연결합니다.
1. 대화형 음성 응답 시스템과 같은 애플리케이션 또는 상담원은 발신자에게 통화 레코딩 및 음성 분석을 위한 음성 임베딩 사용에 대해 고지하고 참여에 대한 동의를 구합니다.
1. 애플리케이션이 EventBridge 이벤트를 구독한다고 가정하면 애플리케이션은 미디어 인사이트 파이프라인 구성을 사용하여 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html) API를 직접 호출하고 음성 커넥터 호출을 위한 Kinesis Video Stream ARN을 직접 호출합니다.
EventBridge 사용에 대한 자세한 내용은 [Amazon Chime SDK의 기계 학습 기반 분석을 위한 워크플로 이해](ml-based-analytics.md) 섹션을 참조하세요.
1. 발신자가 동의를 제공하면 음성 커넥터와 트랜잭션 ID가 있는 경우 애플리케이션이나 상담원이 [음성 SDK](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Voice.html)를 통해 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask.html) API를 직접 호출할 수 있습니다. 또는 트랜잭션 ID 대신 미디어 인사이트 파이프라인 ID가 있는 경우 [미디어 파이프라인 SDK](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Media_Pipelines.html)에서 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartSpeakerSearchTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartSpeakerSearchTask.html) API를 직접 호출합니다.
발신자가 동의를 제공하면 애플리케이션 또는 상담원이 `StartSpeakerSearchTask` API를 호출합니다. 음성 커넥터 ID, 트랜잭션 ID 및 음성 프로필 도메인 ID를 API에 전달해야 합니다. 비동기 작업을 식별하기 위해 화자 검색 작업 ID가 반환됩니다.
1. 사용자는 통화 내내 말을 합니다.
1. 상담원은 통화 내내 말을 합니다.
1. 미디어 인사이트 파이프라인은 5초마다 기계 학습 모델을 사용하여 마지막 30초 간의 음성을 분석하고 해당 인터벌, 그리고 `StartVoiceToneAnalysisTask`가 처음 호출된 시점부터 전체 통화에 대한 발신자의 어조를 예측합니다.
1. 미디어 인사이트 파이프라인은 해당 정보가 포함된 알림을 구성된 알림 대상에 보냅니다. 스트림 ARN 및 채널 ID를 기반으로 알림을 식별할 수 있습니다. 자세한 내용은 이 섹션 뒷부분의 [Amazon Chime SDK의 알림 이해](va-notification-targets.md) 항목을 참조하세요.
1. 통화가 종료될 때까지 9단계와 10단계를 반복합니다.
1. 통화가 끝나면 미디어 인사이트 파이프라인은 지난 30초 동안의 현재 평균 톤 예측치에 전체 통화의 평균 톤을 더한 최종 알림 하나를 보냅니다.
1. 애플리케이션에서 필요에 따라 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_GetVoiceToneAnalysisTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_GetVoiceToneAnalysisTask.html) API를 직접 호출하여 음성 톤 분석 작업의 최신 상태를 가져옵니다.
**참고**
`GetVoiceToneAnalysisTask` API는 톤 데이터를 스트리밍하지 않습니다.
**참고**
[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_GetVoiceToneAnalysisTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_GetVoiceToneAnalysisTask.html) API는 음성 톤 데이터를 반환하지 않습니다.
# Amazon Chime SDK의 작업 결과 폴링
**중요**
기본적으로 음성 분석은 7일 동안 결과를 제공하고 나면 데이터가 자동으로 삭제됩니다. 작업 데이터를 더 오래 사용하거나 데이터 보존법을 준수하려면 작업 데이터를 저장해야 합니다. 자세한 내용은 이 안내서 뒷부분의 [Amazon Chime SDK 음성 분석을 위한 데이터 보존 이해](va-data-retention.md) 섹션을 참조하세요.
음성 분석은 각 작업 결과가 최소 한 번 이상 전달되도록 합니다. 하지만 네트워크 문제로 인해 지연이 증가할 수 있습니다. 잠재적인 문제를 해결하거나 동기식 프로세스를 선호하는 경우 [미디어 파이프라인](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Media_Pipelines.html) SDK 또는 [음성 SDK](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Voice.html)에서 다음 API를 사용할 수 있습니다.
+ [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_GetSpeakerSearchTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_GetSpeakerSearchTask.html)
+ [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_GetVoiceToneAnalysisTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_GetVoiceToneAnalysisTask.html)
**중요**
`GetVoiceToneAnalysisTask` API는 작업 상태만 반환합니다. 작업 결과는 반환하지 않습니다. 결과를 보려면 Amazon SQS, Amazon SNS 또는 AWS Lambda 알림 대상을 사용합니다.
`GetSpeakerSearchTask` API는 작업 ID, 지연된 메시지 또는 잘못 도착한 메시지에 대한 최신 결과를 동기적으로 가져옵니다. 그러나 알림 대상과 비동기 처리를 사용하는 것이 좋습니다. 이렇게 하면 컴퓨팅 리소스 사용량이 줄어듭니다.
# Amazon Chime SDK의 알림 이해
음성 분석은 화자 검색 또는 음성 톤 분석 작업이 시작될 때, 실행 중일 때, 완료될 때 자동으로 이벤트를 대상으로 전송합니다. 알림 대상을 사용하여 이러한 이벤트를 수신합니다. 워크플로 또는 애플리케이션에 고가용성이 필요한 경우 여러 알림 대상을 사용하는 것이 좋습니다.
또한 알림 대상에 액세스하는 데 필요한 정책이 포함된 IAM 역할을 사용해야 합니다. 자세한 내용은 [Amazon Chime SDK의 통화 분석 리소스 액세스 역할 사용](call-analytics-resource-access-role.md) 단원을 참조하십시오.
**참고**
Amazon SQS 및 Amazon SNS의 경우 선입선출 대기열이 지원되지 않습니다. 따라서 메시지가 잘못된 순서로 도착할 수 있습니다. 타임스탬프를 확인하여 필요에 따라 메시지를 정렬하고 Amazon DynamoDB와 같은 데이터 스토어에 메시지를 보관하는 것이 좋습니다. [Amazon Chime SDK의 작업 결과 폴링](va-task-result-poll.md)에 설명된 Get API를 사용하여 최신 결과를 받을 수도 있습니다.
다음 표에는 이벤트와 해당 세부 정보 유형이 나와 있습니다.
| 알림 이벤트 | 세부 정보 유형 |
| --- | --- |
| 음성 분석 메타데이터 | `VoiceAnalyticsStatus` |
| 화자 검색 | `SpeakerSearchStatus` |
| 음성 톤 분석 | `VoiceToneAnalysisStatus` |
# Amazon Chime SDK의 알림 대상에 대한 IAM 정책 이해
Amazon SQS, Amazon SNS, AWS Lambda 또는 Amazon KDS 알림 대상에 대한 액세스를 허용하는 호출 분석 구성의 IAM 역할 정책을 사용해야 합니다. 자세한 내용은 이 안내서의 [Amazon Chime SDK의 통화 분석 리소스 액세스 역할 사용](call-analytics-resource-access-role.md) 섹션을 참조하세요.
## 화자 검색 이벤트
화자 검색 이벤트에는 `SpeakerSearchStatus` 세부 유형이 있습니다.
Amazon Chime SDK 음성 커넥터는 다음과 같은 화자 검색 이벤트를 전송합니다.
+ 식별 일치
+ 음성 임베딩 생성
이벤트에는 다음과 같은 상태가 있을 수 있습니다:
+ `IdentificationSuccessful` – 주어진 음성 프로필 도메인에서 높은 신뢰도 점수로 일치하는 음성 프로필 ID를 하나 이상 식별하는 데 성공했습니다.
+ `IdentificationFailure` – 식별을 수행하지 못했습니다. 원인: 발신자가 10초 이상 말을 하지 않았으며, 음질이 좋지 않습니다.
+ `IdentificationNoMatchesFound` – 해당 음성 프로필 도메인에서 신뢰도가 높은 일치 항목을 찾을 수 없습니다. 전화를 건 사람이 처음이거나 목소리가 바뀌었을 수 있습니다.
+ `VoiceprintGenerationSuccessful` – 시스템이 20초 분량의 무음이 아닌 오디오를 사용하여 음성 임베딩을 생성했습니다.
+ `VoiceprintGenerationFailure` – 시스템에서 음성 임베딩을 생성하지 못했습니다. 원인: 발신자가 20초 이상 말을 하지 않았으며, 음질이 좋지 않습니다.
### 식별 일치
특정 `transactionId`로 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask) API를 직접 호출한 후 음성 커넥터 서비스는 10초 동안 무음이 아닌 발화가 지속되면 식별 일치 알림을 반환합니다. 이 서비스는 음성 프로필 ID와 [0, 1] 범위의 신뢰도 점수와 함께 상위 10개의 매칭을 반환합니다. 신뢰도 점수가 높을수록 통화 중인 화자가 음성 프로필 ID와 일치할 가능성이 높아집니다. 기계 학습 모델에서 일치하는 항목이 없는 경우 알림의 `detailStatus` 필드에 `IdentificationNoMatchesFound`가 포함됩니다.
다음 예제는 매칭 성공 알림을 보여줍니다.
```
{
"version": "0",
"id": "12345678-1234-1234-1234-111122223333",
"detail-type": "SpeakerSearchStatus",
"service-type": "VoiceAnalytics",
"source": "aws.chime",
"account": "111122223333",
"time": "yyyy-mm-ddThh:mm:ssZ",
"region": "us-east-1",
"resources": [],
"detail": {
"taskId": "uuid",
"detailStatus": "IdentificationSuccessful",
"speakerSearchDetails" : {
"results": [
{
"voiceProfileId": "vp-505e0992-82da-49eb-9d4a-4b34772b96b6",
"confidenceScore": "0.94567856",
},
{
"voiceProfileId": "vp-fba9cbfa-4b8d-4f10-9e41-9dfdd66545ab",
"confidenceScore": "0.82783350",
},
{
"voiceProfileId": "vp-746995fd-16dc-45b9-8965-89569d1cf787",
"confidenceScore": "0.77136436",
}
]
},
"mediaInsightsPipelineId": "87654321-33ca-4dc6-9cdf-abcde6612345",
"sourceArn": "arn:aws:chime:us-east-1:111122223333:media-pipeline/87654321-33ca-4dc6-9cdf-abcde6612345",
"streamArn": "arn:aws:kinesisvideo:us-east-1:111122223333:stream/my-stream/0123456789012",
"channelId": 0
}
}
```
### 음성 임베딩 생성
추가로 10초 동안 무음이 아닌 발화가 지속되면 음성 커넥터는 알림 대상에 음성 임베딩 생성 알림을 보냅니다. 음성 프로필에 새 음성 임베딩을 등록하거나 이미 음성 프로필에 있는 성문을 업데이트할 수 있습니다.
다음 예제는 매칭에 성공하면 관련 음성 프로필을 업데이트할 수 있다는 의미의 알림을 보여줍니다.
```
{
"version": "0",
"id": "12345678-1234-1234-1234-111122223333",
"detail-type": "SpeakerSearchStatus",
"service-type": "VoiceAnalytics",
"source": "aws.chime",
"account": "111122223333",
"time": "yyyy-mm-ddThh:mm:ssZ",
"region": "us-east-1",
"resources": [],
"detail": {
"taskId": "guid",
"detailStatus": "VoiceprintGenerationSuccess",
"mediaInsightsPipelineId": "87654321-33ca-4dc6-9cdf-abcde6612345",
"sourceArn": "arn:aws:chime:us-east-1:111122223333:media-pipeline/87654321-33ca-4dc6-9cdf-abcde6612345",
"streamArn": "arn:aws:kinesisvideo:us-east-1:111122223333:stream/my-stream/0123456789012",
"channelId": 0
}
}
```
## 음성 톤 분석 이벤트
음성 톤 분석 이벤트에는 `VoiceToneAnalysisStatus` 세부 유형이 있습니다. 분석 결과 다음과 같은 상태가 반환될 수 있습니다.
+ `VoiceToneAnalysisSuccessful` – 발신자와 상담원의 음성을 긍정, 부정, 중립 등 감정의 확률로 분석하는 데 성공했습니다.
+ `VoiceToneAnalysisFailure` – 톤 분석을 수행하지 못했습니다. 발신자가 10초 동안 말을 하지 않고 전화를 끊거나 오디오 품질이 너무 나빠지면 이런 일이 발생할 수 있습니다.
+ `VoiceToneAnalysisCompleted` – 사용자와 상담원의 음성을 전체 통화에 대한 감정 확률로 분석하는 데 성공했습니다. 음성 톤 분석이 완료될 때 전송되는 마지막 이벤트입니다.
다음 예제에서는 일반적인 음성 톤 분석 이벤트를 보여줍니다.
```
{
"detail-type": "VoiceToneAnalysisStatus",
"service-type": "VoiceAnalytics",
"source": "aws.chime",
"account": "216539279014",
"time": "2022-08-26T17:55:15.563441Z",
"region": "us-east-1",
"detail": {
"taskId": "uuid",
"detailStatus": "VoiceToneAnalysisSuccessful",
"voiceToneAnalysisDetails": {
"currentAverageVoiceTone": {
"startTime": "2022-08-26T17:55:15.563Z",
"endTime": "2022-08-26T17:55:45.720Z",
"voiceToneLabel": "neutral",
"voiceToneScore": {
"neutral": "0.83",
"positive": "0.13",
"negative": "0.04"
}
},
"overallAverageVoiceTone": {
"startTime": "2022-08-26T16:23:13.344Z",
"endTime": "2022-08-26T17:55:45.720Z",
"voiceToneLabel": "positive",
"voiceToneScore": {
"neutral": "0.25",
"positive": "0.65",
"negative": "0.1"
}
}
},
"startFragmentNumber": "01234567890123456789",
"mediaInsightsPipelineId": "87654321-33ca-4dc6-9cdf-abcde6612345",
"sourceArn": "arn:aws:chime:us-east-1:111122223333:media-pipeline/87654321-33ca-4dc6-9cdf-abcde6612345",
"streamArn": "arn:aws:kinesisvideo:us-east-1:111122223333:stream/my-stream/0123456789012",
"channelId": 0
},
"version": "0",
"id": "Id-f928dfe3-f44b-4965-8a17-612f9fb92d59"
}
```
## 통화 후 요약 이벤트
통화 종료 후 5분 후에 통화 요약 이벤트가 전송됩니다. 이 요약은 통화 중에 발생한 화자 검색 작업에 대한 개요를 제공합니다.
다음 예에서는 가장 일치하는 음성 프로필, 확인된 화자 ID, 통화 중에 이루어진 `CreateVoiceProfile` 및 `UpdateVoiceProfile` API 호출을 통해 생성되거나 업데이트된 음성 프로필 목록을 포함한 통화 후 요약 정보를 보여줍니다.
```
{
"version": "0",
"id": "12345678-1234-1234-1234-111122223333",
"detail-type": "VoiceAnalyticsStatus",
"service-type": "VoiceAnalytics",
"source": "aws.chime",
"account": "111122223333",
"time": "yyyy-mm-ddThh:mm:ssZ",
"region": "us-east-1",
"resources": [],
"detail": {
"detailStatus": "PostCallVoiceAnalytics",
"callId": "22e8dee8-bbd7-4f94-927b-2d0ebaeddc1c",
"transactionId": "daaeb6bf-2fe2-4e51-984e-d0fbf2f09436",
"voiceConnectorId": "abcdef1ghij2klmno3pqr4",
"isCaller": true | false,
"speakerSearchResults": {
"bestMatchedVoiceProfileId": "vp-04c25ba1-a059-4fd3-8495-4ac91b55e2bf",
"customerValidatedCallerIdentity": "vp-04c25ba1-a059-4fd3-8495-4ac91b55e2bf",
"createVoiceProfileTransactions": [
{
"voiceProfileId": "vp-04c25ba1-a059-4fd3-8495-4ac91b55e2bf",
"requestTimestamp": "2022-12-14T18:38:38.796Z"
},
{
"voiceProfileId": "vp-04c25ba1-a059-4fd3-8495-4ac91b55e2bf",
"requestTimestamp": "2022-12-14T18:38:38.796Z",
}
],
"updateVoiceProfileTransactions": [
{
"voiceProfileId": "vp-04c25ba1-a059-4fd3-8495-4ac91b55e2bf",
"requestTimestamp": "2022-12-14T18:38:38.796Z",
},
{
"voiceProfileId": "vp-04c25ba1-a059-4fd3-8495-4ac91b55e2bf",
"requestTimestamp": "2022-12-14T18:38:38.796Z",
}
]
}
}
}
```
# Amazon Chime SDK용 음성 분석 예제 Lambda 함수
다음 예제의 Python 코드는 음성 커넥터에서 받은 알림을 처리합니다. AWS Lambda 함수에 코드를 추가할 수 있습니다. 또한 이를 사용하여 Amazon SQS 대기열, Amazon SNS 주제 또는 Amazon Kinesis Data Stream을 트리거할 수 있습니다. 그런 다음 향후 처리를 위해 알림을 `EventTable`에 저장할 수 있습니다. 정확한 알림 형식은 [Amazon Chime SDK의 알림 이해](va-notification-targets.md) 섹션을 참조하세요.
```
import base64
import boto3
import json
import logging
import time
from datetime import datetime
from enum import Enum
log = logging.getLogger()
log.setLevel(logging.INFO)
dynamo = boto3.client("dynamodb")
EVENT_TABLE_NAME = "EventTable"
class EventType(Enum):
"""
This example code uses a single Lambda processor to handle either
triggers from SQS, SNS, Lambda, or Kinesis. You can adapt it to fit your
desired infrastructure depending on what you prefer. To distinguish
where we get events from, we use an EventType enum as an
example to show the different ways of parsing the notifications.
"""
SQS = "SQS"
SNS = "SNS"
LAMBDA = "LAMBDA"
KINESIS = "KINESIS"
class AnalyticsType(Enum):
"""
Define the various analytics event types that this Lambda will
handle.
"""
SPEAKER_SEARCH = "SpeakerSearch"
VOICE_TONE_ANALYSIS = "VoiceToneAnalysis"
ANALYTICS_READY = "AnalyticsReady"
UNKNOWN = "UNKNOWN"
class DetailType(Enum):
"""
Define the various detail types that Voice Connector's voice
analytics feature can return.
"""
SPEAKER_SEARCH_TYPE = "SpeakerSearchStatus"
VOICE_TONE_ANALYSIS_TYPE = "VoiceToneAnalysisStatus"
ANALYTICS_READY = "VoiceAnalyticsStatus"
def handle(event, context):
"""
Example of how to handle incoming Voice Analytics notification messages
from Voice Connector.
"""
logging.info(f"Received event of type {type(event)} with payload {event}")
is_lambda = True
# Handle triggers from SQS, SNS, and KDS. Use the below code if you would like
# to use this Lambda as a trigger for an existing SQS queue, SNS topic or Kinesis
# stream.
if "Records" in event:
logging.info("Handling event from SQS or SNS since Records exists")
is_lambda = False
for record in event.get("Records", []):
_process_record(record)
# If you would prefer to have your Lambda invoked directly, use the
# below code to have the Voice Connector directly invoke your Lambda.
# In this scenario, there are no "Records" passed.
if is_lambda:
logging.info(f"Handling event from Lambda")
event_type = EventType.LAMBDA
_process_notification_event(event_type, event)
def _process_record(record):
# SQS and Kinesis use eventSource.
event_source = record.get("eventSource")
# SNS uses EventSource.
if not event_source:
event_source = record.get("EventSource")
# Assign the event type explicitly based on the event source value.
event_type = None
if event_source == "aws:sqs":
event = record["body"]
event_type = EventType.SQS
elif event_source == "aws:sns":
event = record["Sns"]["Message"]
event_type = EventType.SNS
elif event_source == "aws:kinesis":
raw_data = record["kinesis"]["data"]
raw_message = base64.b64decode(raw_data).decode('utf-8')
event = json.loads(raw_message)
event_type = EventType.KINESIS
else:
raise Exception(f"Event source {event_source} is not supported")
_process_notification_event(event_type, event)
def _process_notification_event(
event_type: EventType,
event: dict
):
"""
Extract the attributes from the Voice Analytics notification message
and store it as a DynamoDB item to process later.
"""
message_id = event.get("id")
analytics_type = _get_analytics_type(event.get("detail-type"))
pk = None
if analytics_type == AnalyticsType.ANALYTICS_READY.value or analytics_type == AnalyticsType.UNKNOWN.value:
transaction_id = event.get("detail").get("transactionId")
pk = f"transactionId#{transaction_id}#notificationType#{event_type.value}#analyticsType#{analytics_type}"
else:
task_id = event.get("detail").get("taskId")
pk = f"taskId#{task_id}#notificationType#{event_type.value}#analyticsType#{analytics_type}"
logging.info(f"Generated PK {pk}")
_create_request_record(pk, message_id, json.dumps(event))
def _create_request_record(pk: str, sk: str, body: str):
"""
Record this notification message into the Dynamo db table
"""
try:
# Use consistent ISO8601 date format.
# 2019-08-01T23:09:35.369156 -> 2019-08-01T23:09:35.369Z
time_now = (
datetime.utcnow().isoformat()[:-3] + "Z"
)
response = dynamo.put_item(
Item={
"PK": {"S": pk},
"SK": {"S": sk},
"body": {"S": body},
"createdOn": {"S": time_now},
},
TableName=EVENT_TABLE_NAME,
)
logging.info(f"Added record in table {EVENT_TABLE_NAME}, response : {response}")
except Exception as e:
logging.error(f"Error in adding record: {e}")
def _get_analytics_type(detail_type: str):
"""
Get analytics type based on message detail type value.
"""
if detail_type == DetailType.SPEAKER_SEARCH_TYPE.value:
return AnalyticsType.SPEAKER_SEARCH.value
elif detail_type == DetailType.VOICE_TONE_ANALYSIS_TYPE.value:
return AnalyticsType.VOICE_TONE_ANALYSIS.value
elif detail_type == DetailType.ANALYTICS_READY.value:
return AnalyticsType.ANALYTICS_READY.value
else:
return AnalyticsType.UNKNOWN.value
```
**중요**
[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask) 또는 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartVoiceToneAnalysis.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartVoiceToneAnalysis.html) API를 직접 호출하려면 먼저 동의를 받아야 합니다. 동의를 받을 때까지 Amazon DynamoDB와 같은 보류 영역에서 이벤트를 지속하는 것이 좋습니다.
# Amazon Chime SDK의 데이터 스토리지, 옵트아웃, 데이터 보존 정책 이해
Amazon Chime SDK는 음성 데이터를 사용하여 화자 검색 서비스를 제공하고 개선합니다. 그 일환으로 음성 임베딩을 생성하는 데 사용되는 녹음된 스니펫인 등록 오디오를 사용하여 기계 학습 및 인공 지능 모델을 교육합니다. 모델 학습에 데이터를 사용하지 않도록 선택할 수 있으며, 이 섹션의 항목에서는 그 방법을 설명합니다.
**Topics**
+ [Amazon Chime SDK의 화자 검색을 위한 데이터 스토리지 이해](speaker-search-data-storage.md)
+ [Amazon Chime SDK의 화자 검색에 대한 옵트아웃 처리](va-handle-opt-outs.md)
+ [Amazon Chime SDK 음성 분석을 위한 데이터 보존 이해](va-data-retention.md)
# Amazon Chime SDK의 화자 검색을 위한 데이터 스토리지 이해
Amazon Chime SDK는 화자 검색을 위해 다음 데이터를 저장합니다.
+ 화자 검색 기능을 제공하는 데 사용하는 음성 프로필에 첨부된 음성 임베딩.
+ 등록 오디오는 각 음성 프로필의 음성 임베딩을 만드는 데 사용되는 녹음된 음성 스니펫입니다. 등록 오디오 레코딩을 사용하여 다음을 수행합니다.
+ 화자 검색 기능을 제공하는 데 있어 중요한 부분인 화자 검색 모델을 최신 상태로 유지합니다.
+ 기계 학습 모델을 학습시켜 서비스를 개발하고 개선합니다. 교육에 등록 오디오를 사용하는 것은 선택 사항이며, 다음 섹션에 설명된 대로 옵트아웃 정책을 선택하여 이러한 사용을 거부할 수 있습니다.
# Amazon Chime SDK의 화자 검색에 대한 옵트아웃 처리
최종 사용자 및 전체 조직에 대한 옵트아웃을 처리할 수 있습니다. 옵트아웃은 다음과 같은 효과가 있습니다.
+ 옵트아웃한 후에는 음성 분석에서 모델 교육에 새 등록 오디오를 사용하지 않으며 옵트아웃 전에 수집 및 저장된 등록 오디오도 사용하지 않습니다.
+ 옵트아웃한 후에는 음성 분석이 화자 검색 서비스를 제공하기 위해 등록 오디오를 저장하고 사용합니다.
**주의**
다음 옵트아웃 조치는 되돌릴 수 없습니다. 삭제한 데이터는 복구할 수 없습니다.
**최종 사용자 옵트아웃 처리**
최종 사용자가 화자 검색을 거부하면 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_DeleteVoiceProfile.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_DeleteVoiceProfile.html) API를 직접 호출하세요. 이 작업을 수행하면 음성 프로필은 물론 음성 임베딩 및 등록 오디오도 제거됩니다.
음성 임베딩 그룹을 삭제하려면 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_DeleteVoiceProfileDomain.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_DeleteVoiceProfileDomain.html) API를 직접 호출하여 도메인을 제거합니다. 이 작업을 수행하면 도메인의 *모든* 음성 프로필이 삭제됩니다.
**조직 수준에서 옵트아웃 처리**
전체 조직의 옵트아웃을 처리하려면 AWS Organizations 옵트아웃 정책을 사용합니다. `chimesdkvoiceanalytics` 서비스 이름을 사용합니다. 정책에 대한 자세한 내용은AWS Organizations 사용 설명서**의 [AI 서비스 옵트아웃 정책](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_ai-opt-out.html)을 참조하세요.
**참고**
옵트아웃 정책을 사용하려면 AWS Organizations에서 AWS 계정을 중앙에서 관리해야 합니다. AWS 계정에 대한 조직을 아직 만들지 않았다면AWS Organizations 사용 설명서**의 [조직 생성 및 관리](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org.html)를 참조하세요.
# Amazon Chime SDK 음성 분석을 위한 데이터 보존 이해
기본적으로 Amazon Chime SDK 음성 분석은 3년이 지나면 음성 임베딩을 삭제합니다. 이는 사람들의 목소리가 시간이 지남에 따라 변하기 때문이며 보안을 위해서도 그렇게 합니다. [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_UpdateVoiceProfile.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_UpdateVoiceProfile.html) API를 사용하여 만료된 음성 임베딩을 업데이트할 수 있습니다.
[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask.html) 및 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartVoiceToneAnalysisTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartVoiceToneAnalysisTask.html)의 결과는 최대 7일 동안 해당 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_GetSpeakerSearchTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_GetSpeakerSearchTask.html) 및 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_GetVoiceToneAnalysisTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_GetVoiceToneAnalysisTask.html) API에서도 사용할 수 있습니다.
[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask.html)에서 생성된 음성 임베딩은 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateVoiceProfile.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateVoiceProfile.html) 및 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_UpdateVoiceProfile.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_UpdateVoiceProfile.html) API를 통해 24시간 동안 지속 가능하며 그 이후에는 삭제되어 사용할 수 없습니다.
결과를 삭제하고 고객의 동의 철회를 처리하려면 이전 섹션을 참조하세요.
# 음성 API를 사용하여 Amazon Chime SDK용 음성 분석 실행
이전 버전과의 호환성을 위해 Amazon Chime SDK Voice API를 사용하여 음성 분석을 시작하고 관리할 수 있습니다. 그러나 음성 분석을 위한 미디어 인사이트 파이프라인 API만 새로운 기능을 제공하므로 대신 해당 API를 사용하는 것이 좋습니다.
다음 섹션에서는 음성 및 미디어 인사이트 파이프라인 API의 차이점을 설명합니다.
## 작업 중지
음성 커넥터를 사용하여 음성 분석 작업을 시작한 다음 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_UpdateMediaInsightsPipelineStatus.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_UpdateMediaInsightsPipelineStatus.html) API를 사용하여 파이프라인을 일시 중지하면 작업이 계속 실행됩니다. 작업을 중지하려면 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StopSpeakerSearchTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StopSpeakerSearchTask.html) 및 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StopVoiceToneAnalysisTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StopVoiceToneAnalysisTask.html) API를 직접 호출해야 합니다.
## 알림의 차이점 이해
음성 API를 사용하여 음성 분석을 실행하는 경우 알림은 미디어 인사이트 파이프라인에서 생성되는 알림과 다릅니다.
+ 음성 분석 준비 이벤트는 음성 API를 사용하여 시작된 작업에만 사용할 수 있습니다.
+ 음성 분석 작업을 통화와 연결하려면 알림의 `voiceConnectorId`, `transactionId`, 또는 `callId` 필드를 사용해야 합니다. 미디어 인사이트 파이프라인을 사용하여 음성 분석을 실행하는 경우 `mediaInsightsPipelineId` `streamArn` 및/또는 `channelId` 필드를 사용하여 작업을 통화와 연결합니다.
다음 주제에서는 음성 API로 알림을 사용하는 방법을 설명합니다.
**Topics**
+ [음성 분석 준비 이벤트](#va-ready-events)
+ [화자 검색 이벤트](#va-speaker-search-events)
+ [음성 톤 분석 이벤트](#va-tone-status)
### 음성 분석 준비 이벤트
음성 분석 준비 이벤트에는 `VoiceAnalyticsStatus` 세부 유형이 있습니다.
Amazon Chime SDK 음성 커넥터를 사용하여 분석 작업을 시작합니다. 음성 분석 준비 이벤트를 수신하면 다음 속성으로 식별되는 통화의 화자 검색 또는 음성 톤 분석 작업을 트리거할 수 있습니다.
+ `voiceConnectorId`
+ `transactionId`
**참고**
이 알림은 음성 분석이 활성화되고 음성 커넥터와 연결된 미디어 인사이트 파이프라인 구성이 있는 경우에만 제공됩니다. 고객이 `CreateMediaInsightsPipeline` API를 호출하고 Media Pipelines SDK를 통해 화자 검색 작업 또는 음성 톤 분석 작업을 시작하는 경우에는 이 알림이 제공되지 않습니다.
음성 커넥터에서 반환되는 SIP 헤더에는 `transactionId`가 포함됩니다. SIP 헤더에 액세스할 수 없는 경우 `AnalyticsReady` 알림 이벤트에는 `voiceConnectorId` 및 `transactionId`도 포함됩니다. 이를 통해 프로그래밍 방식으로 정보를 수신하고 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask) 또는 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartVoiceToneAnalysis.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartVoiceToneAnalysis.html) API를 직접 호출할 수 있습니다.
음성 분석을 처리할 준비가 되면 음성 커넥터는 `"detailStatus": "AnalyticsReady"`와 함께 이벤트를 알림 대상에 JSON 본문으로 보냅니다. Amazon SNS 또는 Amazon SQS를 사용하는 경우 해당 본문은 Amazon SNS 또는 Amazon SQS 페이로드의 ‘레코드’ 필드에 표시됩니다.
다음 예에서는 일반적인 JSON 본문을 보여줍니다.
```
{
"detail-type": "VoiceAnalyticsStatus",
"version": "0",
"id": "Id-f928dfe3-f44b-4965-8a17-612f9fb92d59",
"source": "aws.chime",
"account": "123456789012",
"time": "2022-08-26T17:55:15.563441Z",
"region": "us-east-1",
"resources": [],
"detail": {
"detailStatus": "AnalyticsReady",
"callDetails": {
"isCaller": false,
"transactionId": "daaeb6bf-2fe2-4e51-984e-d0fbf2f09436",
"voiceConnectorId": "fuiopl1fsv9caobmqf2vy7"
}
}
}
```
이 알림을 통해 음성 분석 작업 API를 호출하기 전에 애플리케이션에 대한 추가 콜백을 트리거하고 통지 및 동의와 같은 법적 요구 사항을 처리할 수 있습니다.
### 화자 검색 이벤트
화자 검색 이벤트에는 `SpeakerSearchStatus` 세부 유형이 있습니다.
Amazon Chime SDK 음성 커넥터는 다음과 같은 화자 검색 이벤트를 전송합니다.
+ 식별 일치
+ 음성 임베딩 생성
이벤트에는 다음과 같은 상태가 있을 수 있습니다:
+ `IdentificationSuccessful` – 주어진 음성 프로필 도메인에서 높은 신뢰도 점수로 일치하는 음성 프로필 ID를 하나 이상 식별하는 데 성공했습니다.
+ `IdentificationFailure` – 식별을 수행하지 못했습니다. 원인: 발신자가 10초 이상 말을 하지 않았으며, 음질이 좋지 않습니다.
+ `IdentificationNoMatchesFound` – 해당 음성 프로필 도메인에서 신뢰도가 높은 일치 항목을 찾을 수 없습니다. 전화를 건 사람이 처음이거나 목소리가 바뀌었을 수 있습니다.
+ `VoiceprintGenerationSuccessful` – 시스템이 20초 분량의 무음이 아닌 오디오를 사용하여 음성 임베딩을 생성했습니다.
+ `VoiceprintGenerationFailure` – 시스템에서 음성 임베딩을 생성하지 못했습니다. 원인: 발신자가 20초 이상 말을 하지 않았으며, 음질이 좋지 않습니다.
#### 식별 일치
특정 `transactionId`로 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask) API를 직접 호출한 후 음성 커넥터 서비스는 10초 동안 무음이 아닌 발화가 지속되면 식별 일치 알림을 반환합니다. 이 서비스는 음성 프로필 ID와 [0, 1] 범위의 신뢰도 점수와 함께 상위 10개의 매칭을 반환합니다. 신뢰도 점수가 높을수록 통화 중인 화자가 음성 프로필 ID와 일치할 가능성이 높아집니다. 기계 학습 모델에서 일치하는 항목이 없는 경우 알림의 `detailStatus` 필드에 `IdentificationNoMatchesFound`가 포함됩니다.
다음 예제는 매칭 성공 알림을 보여줍니다.
```
{
"version": "0",
"id": "12345678-1234-1234-1234-111122223333",
"detail-type": "SpeakerSearchStatus",
"service-type": "VoiceAnalytics",
"source": "aws.chime",
"account": "111122223333",
"time": "yyyy-mm-ddThh:mm:ssZ",
"region": "us-east-1",
"resources": [],
"detail": {
"taskId": "uuid",
"detailStatus": "IdentificationSuccessful",
"speakerSearchDetails" : {
"results": [
{
"voiceProfileId": "vp-505e0992-82da-49eb-9d4a-4b34772b96b6",
"confidenceScore": "0.94567856",
},
{
"voiceProfileId": "vp-fba9cbfa-4b8d-4f10-9e41-9dfdd66545ab",
"confidenceScore": "0.82783350",
},
{
"voiceProfileId": "vp-746995fd-16dc-45b9-8965-89569d1cf787",
"confidenceScore": "0.77136436",
}
]
},
"isCaller": false,
"voiceConnectorId": "abcdef1ghij2klmno3pqr4",
"transactionId": "daaeb6bf-2fe2-4e51-984e-d0fbf2f09436"
}
}
```
#### 음성 임베딩 생성
추가로 10초 동안 무음이 아닌 발화가 지속되면 음성 커넥터는 알림 대상에 음성 임베딩 생성 알림을 보냅니다. 음성 프로필에 새 음성 임베딩을 등록하거나 이미 음성 프로필에 있는 성문을 업데이트할 수 있습니다.
다음 예제는 매칭에 성공하면 관련 음성 프로필을 업데이트할 수 있다는 의미의 알림을 보여줍니다.
```
{
"version": "0",
"id": "12345678-1234-1234-1234-111122223333",
"detail-type": "SpeakerSearchStatus",
"service-type": "VoiceAnalytics",
"source": "aws.chime",
"account": "111122223333",
"time": "yyyy-mm-ddThh:mm:ssZ",
"region": "us-east-1",
"resources": [],
"detail": {
"taskId": "guid",
"detailStatus": "VoiceprintGenerationSuccess",
"isCaller": false,
"transactionId": "12345678-1234-1234",
"voiceConnectorId": "abcdef1ghij2klmno3pqr"
}
}
```
### 음성 톤 분석 이벤트
음성 톤 분석 이벤트에는 `VoiceToneAnalysisStatus` 세부 유형이 있습니다. 분석 결과 다음과 같은 상태가 반환될 수 있습니다.
+ `VoiceToneAnalysisSuccessful` – 발신자와 상담원의 음성을 긍정, 부정, 중립 등 감정의 확률로 분석하는 데 성공했습니다.
+ `VoiceToneAnalysisFailure` – 톤 분석을 수행하지 못했습니다. 발신자가 10초 동안 말을 하지 않고 전화를 끊거나 오디오 품질이 너무 나빠지면 이런 일이 발생할 수 있습니다.
+ `VoiceToneAnalysisCompleted` – 사용자와 상담원의 음성을 전체 통화에 대한 감정 확률로 분석하는 데 성공했습니다. 음성 톤 분석이 완료될 때 전송되는 마지막 이벤트입니다.
다음 예제에서는 일반적인 음성 톤 분석 이벤트를 보여줍니다.
```
{
"detail-type": "VoiceToneAnalysisStatus",
"service-type": "VoiceAnalytics",
"source": "aws.chime",
"account": "216539279014",
"time": "2022-08-26T17:55:15.563441Z",
"region": "us-east-1",
"detail": {
"taskId": "uuid",
"detailStatus": "VoiceToneAnalysisSuccessful",
"voiceToneAnalysisDetails": {
"currentAverageVoiceTone": {
"startTime": "2022-08-26T17:55:15.563Z",
"endTime": "2022-08-26T17:55:45.720Z",
"voiceToneLabel": "neutral",
"voiceToneScore": {
"neutral": "0.83",
"positive": "0.13",
"negative": "0.04"
}
},
"overallAverageVoiceTone": {
"startTime": "2022-08-26T16:23:13.344Z",
"endTime": "2022-08-26T17:55:45.720Z",
"voiceToneLabel": "positive",
"voiceToneScore": {
"neutral": "0.25",
"positive": "0.65",
"negative": "0.1"
}
}
},
"isCaller": true,
"transactionId": "daaeb6bf-2fe2-4e51-984e-d0fbf2f09436",
"voiceConnectorId": "fuiopl1fsv9caobmqf2vy7"
},
"version": "0",
"id": "Id-f928dfe3-f44b-4965-8a17-612f9fb92d59"
}
```