← Docs hub

보이스 프로필 4개 역할과 책임

개발은 내부(등록 App·AI-Agent), SoC(DeviceAgent·IotAgent), 모바일·관제(App·AWS Backend) 세 그룹으로 나눈다. 아래 실행 주체별 역할과 구분하며, 담당별 구현 범위와 연결 작업은 3개 개발 그룹과 연동 인터페이스에서 확인한다.

상위 기준: 보이스 프로필 등록 제품 구현 기준서 2장

아래 네 역할은 실행 영역 구분이다. 개발 담당은 위의 세 그룹 기준으로 배정한다.

역할과 책임 구조도 크게 보기

한눈에 보는 책임

화자인식 등록·인식 APP·Service는 하나의 역할 묶음이지만 한 프로세스는 아니다. Registration App은 화면만 담당하고, OnDevice Agent Service만 마이크와 화자 모델을 사용한다.

1. 모바일 APP

소유 범위

• 모바일에서 기기, 닉네임, 언어, 동의와 개인화 설정을 받는다.
• Backend HTTPS API로 등록·취소·조회·삭제를 요청한다.
• Backend가 전달한 진행 상태와 최종 결과를 화면에 표시한다.

완료 조건

1. 같은 요청의 중복 상태와 역순 상태를 화면에서 걸러낸다.
2. A1의 최종 결과가 모바일 화면까지 같은 request ID로 돌아온다.
3. Cloud 동기화 실패와 A1 로컬 등록 실패를 구분해 표시한다.
4. AWS IoT 인증서, PCM, WAV와 임베딩을 보유하지 않는다.

현재 미구현

• 제품 Backend HTTPS API와 실시간 상태 수신

2. AWS Backend·클라우드

소유 범위

• 사용자와 기기 소유권, 동의와 요청 만료 시간을 검증한다.
• requestId를 발급하고 AWS IoT Core command를 발행한다.
• response/event를 수집해 중복·역순을 제거하고 모바일 APP에 전달한다.
• Voice ID, nickname, 기준 임베딩과 사용자 계정을 연결해 저장·삭제한다.
• Cloud 저장 성공 후 기기로 ACK를 보낸다.

완료 조건

1. 같은 requestId가 재전송돼도 등록·저장을 다시 실행하지 않는다.
2. 만료되거나 권한 없는 기기 요청을 발행하지 않는다.
3. IoT Rule, SQS/DLQ와 저장 결과를 같은 request ID로 추적한다.
4. 저장 전 임베딩 크기·형식·해시를 검증하고 KMS로 암호화한다.
5. 원본 PCM/WAV와 Query Embedding을 수집하지 않는다.

현재 미구현

• 제품 AWS 인증·MQTT 토픽과 상태 저장
• DeviceAgent 전달 대기 저장소를 소비하는 Cloud sync worker와 실제 ACK
• Voice ID 기반 사용자 정보 조회와 Cloud 삭제

3. SoC·DeviceAgent

소유 범위

• IotAgent가 MQTT JSON을 수신·발행하고 DeviceAgent용 Bundle로 변환한다.
• DeviceAgent가 caller UID, contract version, request ID, TTL, method allowlist와 payload를 검사한다.
• 원격 등록 시작 시 Registration App Activity를 실행한다.
• Registration App과 OnDevice Agent Service 명령·콜백을 Binder로 중계한다.
• 최종 Voice ID와 기준 임베딩 한 개를 암호화된 전달 대기 저장소에 보관한다.
• 목록·삭제·상태 결과를 IotAgent를 통해 AWS Backend로 돌려보낸다.

완료 조건

1. method literal은 각 모듈의 VoiceProfileContract에만 정의한다.
2. 허용되지 않은 caller, 만료 요청, 잘못된 payload를 거부한다.
3. 시작·취소·조회·삭제가 올바른 대상 패키지로 전달된다.
4. 상태·목록 콜백에 PCM, WAV, embedding, 파일 경로가 섞이면 차단한다.
5. Binder 단절과 재부팅에서도 전달 대기 데이터와 중복 요청 처리 기준이 유지된다.
6. A1 시스템 APK는 대상 보드 platform certificate로 서명한다.

DeviceAgent의 ModuleCmdCallbackPolicy는 보이스 프로필 method 문자열을 직접 보유하지 않고 VoiceProfileContract.METHOD_*를 참조한다. Registration App callback caller도 CALLER_VOICE_PROFILE_REGISTRATION으로 분리한다. 이 상수와 허용 목록의 정합성은 SoC·DeviceAgent가 검증한다.

소유 코드

apps/IotAgent
apps/DeviceAgent
  app/src/main/java/com/sk/airbot/deviceagent/voiceprofile/VoiceProfileContract.java
  app/src/main/java/com/sk/airbot/deviceagent/app/ModuleCmdCallbackPolicy.java

SoC 영역은 음성을 녹음하거나 화자를 판정하지 않고, Registration App 화면 상태를 직접 만들지 않는다.

4. 화자인식 등록·인식 APP·Service

Registration App 책임

• Figma KO/EN 11개 화면과 버튼, 진행률, 오류·재시도·취소 UI
• 사용자 시작 버튼 이후 등록 명령 전송
• Service 상태 콜백을 화면 상태로 변환
• PCM/WAV와 임베딩을 받지 않음

OnDevice Agent Service 책임

• 등록 중 일반 WUW/STT 경로 정지와 speaker_enrollment 단일 마이크 소유
• 5세트 PCM 수집과 VoiceProfileAudioQualityGate
• 5세트 임베딩 생성과 VoiceProfileEmbeddingQualityGate
• UUID Voice ID, 최종 Reference Embedding, private profile store
• 실제 대화 PCM을 재사용한 CPU 화자 식별
• 완료·취소·실패 시 AudioRecord, 콜백, 타이머, 버퍼 정리와 일반 음성 복구

완료 조건

1. MQTT start만으로 녹음하지 않고 A1 시작 버튼 이후 녹음한다.
2. 품질 실패는 reason code와 같은 세트 재시도로 연결된다.
3. 취소 후 시험 프로필, 임시 PCM과 활성 콜백이 남지 않는다.
4. 완료된 프로필만 목록에 노출되고 Voice ID 삭제가 로컬 저장소에 반영된다.
5. 등록 중 Wake Word·일반 STT와 두 번째 AudioRecord가 동시에 실행되지 않는다.

소유 코드

apps/VoiceProfileRegistrationApp
skmagic_ondeviceai_agent_speaker_recognition

영역 사이 계약

MQTT 변경은 AWS Backend + SoC, Binder 변경은 SoC + 화자인식 등록·인식 APP·Service가 함께 검증한다.

변경 승인표

통합 검수 증거

각 영역은 “호출했다”가 아니라 다음 증거를 제공한다.

1. 모바일 APP: HTTPS 요청과 상태·결과 화면의 request ID
2. AWS Backend·클라우드: 인증·만료·중복 처리, MQTT 발행·수집과 저장 로그
3. SoC·DeviceAgent: MQTT 수신, Binder 전달, 콜백과 결과 발행 로그
4. 화자인식 등록·인식 APP·Service: UI 상태, 품질 reason, profile store 결과와 마이크 복구 로그
5. 공동: 등록·취소·조회·삭제 종단 간 시험과 PCM/WAV 비유출 검사