← Docs hub

보이스 프로필 제품 구조와 구현 현황

구현 요청 문서 분리 (2026-09-21): 직접 연동은 DeviceAgent ↔ AI-Agent, DeviceAgent ↔ 등록 App을 기준으로 검토한다. 담당별 구현 범위에서 전달 대상을 확인한다. 이 페이지의 APP·Backend·IoTAgent 연결은 E2E Sample 참고이며, 해당 구간의 제품 통신 설계는 SoC와 APP·Backend 담당이 협의한다.

설계·인터페이스 바로가기

제품 연동 보강: 완료 조건 · 실패·복구 · 삭제·동의 철회 · 계정 권한 · 변경 반영 · 관심사 활용 · 연동 시험 16건. 현행 코드와 제품 제안 규칙을 구분한다.

관심사는 샘플 서버 저장, 화자 프로필과 기준 임베딩은 현재 기기 파일 관리다. 제품에서는 서버에도 voiceId·계정 연결과 임베딩을 저장해야 하지만, 임베딩 업로드는 아직 연결되지 않았다. 실제 저장 위치와 남은 작업을 먼저 확인한다.

모바일 등록은 설정 → 관심사 선택(생략 가능) → 등록요청·진행 확인 순서다. 선택한 관심사는 기기 등록 성공 후 실제 voiceId에 저장한다. 이후에도 화자 탭에서 화자를 선택해 관심사를 수정할 수 있다. 화면 순서·저장·취소 명세.

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

이 문서는 보이스 프로필의 제품 흐름, 역할, 데이터 보관 위치와 현재 구현 범위를 설명한다. 토픽, 필드, Binder 메서드와 상태값은 보이스 프로필 연동 규격에서 확인한다.

한눈에 보기

• 등록 화면: A1의 화자인식 등록 App이 표시한다.
• 녹음·음질 검사: OnDevice Agent Service가 AudioRecord를 단독 소유하고 처리한다.
• Voice ID: OnDevice Agent Service가 UUID로 생성하며 실제 화자 식별 키로 사용한다.
• 닉네임: 화면·TTS용 이름이며 화자 식별 키가 아니다.
• 원본 음성: 클라우드로 보내지 않고 등록 처리 후 폐기한다.
• 등록 임베딩: 제품 구조에서는 암호화 전송 대상이다. 현재 PoC는 DeviceAgent 대기 저장까지만 구현했다.
• AWS 연동: 제품 publish/ACK와 재전송 경로는 아직 구현되지 않았다.

구조도 크게 보기

현재 구현과 제품 목표

중요: persist.sys.vp.local_ack=true는 로컬 PoC를 끝까지 시험하기 위한 설정이다. 클라우드 저장 완료를 증명하지 않는다.

역할과 책임

등록 흐름

아래는 제품 연결 목표를 포함한 흐름이다. 현재 PoC는 AWS Backend/IoT Core 대신 PC Gateway와 로컬 MQTT를 사용한다. Cloud 업로드·ACK는 아직 연결되지 않았다.

등록 흐름 크게 보기

1. 모바일 App이 AWS Backend에 등록을 요청한다.
2. AWS Backend가 기기 권한을 확인하고 AWS IoT Core에 명령을 발행한다.
3. IotAgent가 명령을 받아 DeviceAgent에 Binder Bundle로 전달한다.
4. DeviceAgent가 계약 버전, requestId, 유효 시간과 호출자를 검사하고 등록 App을 연다.
5. 사용자가 등록 App에서 시작을 누르면 OnDevice Agent Service가 등록 세션을 시작한다.
6. Service는 일반 Wake Word/STT 흐름을 멈추고 5개 음성 세트를 차례로 녹음한다.
7. 각 세트의 음질을 검사한다. 실패하면 해당 세트만 다시 녹음한다.
8. 5개 임베딩이 같은 화자인지 검사한 뒤 대표 임베딩과 voiceId를 만든다.
9. Service가 DeviceAgent에 프로필을 전달하고 DeviceAgent가 암호화 대기 저장소에 보관한다.
10. 제품 환경에서는 IotAgent가 AWS에 업로드하고 Cloud ACK가 돌아오면 완료 처리한다.
11. Service의 종료 경로에서 녹음을 정리하고 일반 음성 기능을 복구한다. 다만 생성 중 취소와 늦은 완료의 경합 방어는 아직 보완이 필요하다.

등록 화면과 상태

상태 이벤트는 stateSequence가 증가하는 순서로 표시한다. 이미 표시한 번호보다 작거나 같은 이벤트는 무시한다.

이는 UI의 수신 규칙이다. 현재 Service의 생성 완료·품질 실패 경로에서는 순번이 되돌아갈 수 있어 정상 이벤트도 누락될 수 있다. UI 규칙을 해제하는 대신 송신측 순번 관리를 보완해야 한다.

등록 시작 대기 화면은 5분, 완료 화면은 60초 후 자동으로 닫힌다.

녹음과 품질 검사

녹음 기준

각 세트의 음질 기준

5개 세트의 임베딩은 차원이 같고 값이 유효해야 한다. 모든 쌍의 코사인 유사도 최솟값이 0.45 미만이면 INCONSISTENT_SPEAKER로 거절한다.

데이터 모델과 보관 위치

표의 Cloud 저장은 제품 목표다. 현재 확인된 저장은 기기 로컬과 DeviceAgent 전달 대기 저장이며, Cloud 저장 완료를 뜻하지 않는다. 원본 음성의 메모리 보관·비전송 설명은 새 voice-profile-v2 등록 경로에 한정한다. 기존 수동 등록 경로의 WAV 저장과 구분한다.

nickname은 변경 가능한 표시 이름이고 voiceId는 식별 키다. Cloud는 voiceId를 실제 사용자 계정과 연결한다. 기기는 사용자 계정 ID를 화자 매칭 키로 사용하지 않는다.

모바일 Sample App은 닉네임만 전달한다. 발음 처리는 AI-Agent 내부에서 선택적으로 수행하며 기본값은 비활성이다.

취소와 실패 처리

• 등록 중 나가기 또는 원격 취소가 오면 같은 requestId 세션만 취소한다.
• 세트 녹음 실패는 현재 세트를 다시 받는다. 생성 단계의 동일 화자 품질 실패는 SET_REJECTED로 돌아가며 5개 세트를 모두 다시 받아야 한다.
• 프로필 생성 실패와 전달 실패를 구분한다.
• DELIVERY_FAILED + WAITING_CLOUD_SYNC는 음성 등록 실패가 아니라 Cloud 동기화 미완료다.
• 완료·취소는 terminal=true다. 실패는 경로별로 다르며, 생성/전달 실패는 재시도 가능한 false도 있다.
• 생성 재시도·취소 경합·중복 start의 현재 한계는 전체 Binder 명세에서 확인한다.
• 취소 처리 경로는 녹음 정리와 Wake Word/STT 복구를 수행한다. 생성 coroutine과 700ms 후속 작업의 늦은 실행까지 차단하는 보장은 아직 없다. 이미 저장된 프로필의 삭제도 취소와 별도다.

등록 후 식별

1. Wake Word 이후 들어온 음성에서 Query Embedding을 만든다.
2. 기기 안의 Reference Embedding과 비교한다.
3. 임계값을 넘으면 voiceId를 확정하고 nickname을 화면·TTS에 사용한다.
4. 첫 턴이 화자 A이고 후속 턴이 unknown이면 A를 유지한다.
5. 후속 턴에서 등록 화자 B가 확인되면 B로 바꾼다.
6. 새 대화의 첫 턴이 unknown이면 특정 화자에게 귀속하지 않는다.

대화내역은 이번 차수에서 제외한다. 관심사는 서버에서 voiceId를 기준으로 관리한다. 관심사는 최초 보이스 등록 후와 상시 App 설정에서 모두 수정한다. 서버 조회 규격을 우선 적용한다. 등록 상태와 관심사 흐름은 화자별 관심사 관리를 참고한다.

구현 완료와 남은 작업

현재 코드에서 확인된 범위

• 등록 App 화면과 상태 reducer
• DeviceAgent의 호출자·payload 검증과 App 실행
• OnDevice Agent Service의 5세트 녹음, 품질 검사, 임베딩 검사, Voice ID 생성
• 등록 중 일반 Wake Word/STT 정지와 종료 후 복구
• DeviceAgent의 암호화 전달 대기 저장
• 로컬 MQTT Bridge와 PC Gateway를 이용한 등록·조회·삭제 PoC
• 기기 내 화자 식별·프로필 파일 관리, 서버 관심사 API (작업본·샘플 Backend 기준)

제품 적용 전에 필요한 범위

• AI-Agent: 중복 start, 생성 중 취소, 지연 작업, 상태 순번, 생성 재시도 보완
• 등록 App·SoC: 다른 등록 요청과 충돌하거나 화면 실행이 실패할 때 원격 호출자에게 실패 전달

• SoC: 공유 system UID의 호출자 검사 한계와 삭제 대기 사본 정리 실패 처리 보완

• AWS Backend API와 계정-voiceId Registry

• IotAgent의 제품 AWS response/event publish
• Reference Embedding 암호화 업로드와 Cloud ACK
• DeviceAgent 대기 저장소의 조회·재전송·ACK 후 삭제
• 네트워크 중단, 재부팅, 중복 명령에 대한 제품 환경 통합 시험

담당별 완료 조건은 프로토콜의 보완 작업표를 기준으로 확인한다. 이번 검토는 소스 대조이며 새 APK 설치나 실기기 회귀 시험 완료를 뜻하지 않는다.

구현 근거

관련 문서

• 보이스 프로필 연동 규격
• 등록 음성 검증 상세
• 실패·취소·복구
• 로컬 PoC 시험 환경
• 화자별 대화 기록과 관심사