화자인식 담당별 구현 범위와 전달 문서
2026-09-29 구현 범위: 화자 등록·상태 전달·목록·삭제·서버 관심사 조회가 대상이다. 대화내역 저장·조회·삭제·용량 조회·실시간 저장 알림은 다음 차수로 제외했으며 현재 공개 인터페이스에 없다. 발음 보조 값도 외부에서 받거나 보내지 않고 AI-Agent 내부에서만 처리한다.
직접 맞출 경계는 DeviceAgent ↔ AI-Agent, DeviceAgent ↔ 등록 App이다. APP ↔ Backend ↔ IoTAgent는 SoC 담당과 APP·Backend 담당이 협의하여 설계한다. 기존 E2E 자료는 동작 시나리오와 Sample 구현 참고 자료이며, 외부 구간의 제품 API·토픽을 확정한 문서가 아니다.
1. 전달할 문서
| 문서 | 함께 검토할 담당 | 결정할 내용 |
|---|---|---|
| DeviceAgent ↔ AI-Agent 구현 요청서 | SoC DeviceAgent / AI-Agent Service | 요청 중계, 상태·관리 결과, 임베딩 전달, 저장 결과, 개인화 조회 |
| DeviceAgent ↔ 등록 App 구현 요청서 | SoC DeviceAgent / 등록 App | 화면 실행, Proxy 연결, 버튼 요청, 상태 callback, 종료 |
| 이 페이지 | 모든 담당 | 구현 책임, 외부 담당 간 협의 사항, 검증 범위 |
이 세 페이지를 구현 협의의 시작 문서로 전달한다. 상세 기존 문서나 전체 Sample 소스는 아래 참고 링크로 제공하되, 읽어야 할 필수 E2E 설계로 요구하지 않는다.
2. 책임 경계
| 담당 | 구현 책임 | 여기서 맡기지 않는 일 |
|---|---|---|
| AI-Agent Service | 마이크 소유, 녹음 검사, 등록·식별, voiceId 생성·로컬 프로필 관리, 등록 상태 생성 | 모바일 계정 DB, 토픽 설계, 등록 화면 UI |
| 등록 App | 화면·버튼·오류 표시, DeviceAgent 연결, 상태에 따른 화면 전환 | 직접 녹음, 임베딩 생성, 서버 관심사 저장 |
| SoC DeviceAgent | 호출자·Bundle 검증, AI-Agent 요청 중계, 등록 화면 실행, callback 배선, 프로필 인수·결과 반환 | 화자 모델 실행, 임의 등록 상태 생성, Backend API 설계 단독 결정 |
| SoC IoTAgent | 기기 외부 통신과 DeviceAgent 연결 | AI-Agent·등록 App의 Binder 규격 임의 변경 |
| 모바일 APP | 사용자 입력·관심사 변경·기기 상태 표시 | 기기 모델·마이크 제어 직접 구현 |
| Backend | 계정·voiceId 연결, 관심사 원본과 서버 저장 결과 관리 | 기기 등록 상태를 임의 성공 처리 |
DeviceAgent가 외부와 연결할 때도 AI-Agent·등록 App에 보이는 Bundle 규격은 유지한다. 외부 프로토콜을 바꾸면 DeviceAgent/IoTAgent 경계에서 맞춘다.
3. SoC와 APP·Backend 담당이 협의할 항목
아래는 설계해야 할 범위다. 이 페이지에서 URL, topic, QoS, 인증 방법이나 JSON 형식을 지정하지 않는다.
| 협의 항목 | 두 담당이 마련할 결과 | 기기 경계에서 보존할 조건 |
|---|---|---|
| 등록 시작·취소 | 인증된 요청을 기기로 전달하는 방법 | requestId, nickname, locale 등 입력 보존 |
| 상태 전달 | APP에 진행·오류·완료를 전달하는 방법 | AI-Agent가 만든 상태·요청 ID·순번을 보존 |
| 임베딩 저장 | 보안 전송, 저장, 재전송·중복 처리 | AI-Agent가 만든 voiceId와 임베딩을 유지. 원본 녹음은 전송하지 않음 |
| 서버 저장 결과 | 저장 성공·실패를 기기에 반환하는 방법 | 기기 접수와 서버 저장 완료를 구분 |
| 개인화 정보 | 초기 등록 후/상시 관심사 변경, 필요 시 조회 | voiceId 기반 조회 결과와 요청 기한 보존 |
| 목록·삭제 | 계정 권한과 기기 데이터 접근 정책 | 해당 관리 요청과 결과의 requestId 보존 |
| 단절·재부팅 | 복구와 중복 방지, 지연 응답 처리 | 오래된 요청이 현재 등록을 종료·완료시키지 않음 |
운영 외부 통신 구현이 없어도 두 직접 경계는 시험용 호출자와 결과 주입으로 먼저 검증할 수 있다. 이 시험은 실제 서버 저장 완료 증거와 구분한다.
4. 구현과 시험 순서
- DeviceAgent–AI-Agent: Bundle 전달·상태 callback·프로필 인수·실패 결과를 맞춘다.
- DeviceAgent–등록 App: 화면 실행·시작·재시도·취소·완료 표시를 맞춘다.
- SoC–APP·Backend: 외부 통신을 설계하고, 앞의 두 경계를 유지하며 연결한다.
- 통합: 등록·조회·삭제·관심사 갱신과 네트워크 단절·늦은 응답을 시험한다.
| 단계 | 완료 증거 |
|---|---|
| 인터페이스 | 송수신 Bundle의 method·타입·requestId·callback 대상이 일치 |
| 기기 동작 | 녹음 시작·중단, 재시도, 종료 화면, 로컬 프로필 결과를 실기기에서 확인 |
| 서버 동작 | 서버 저장 결과와 기기 최종 상태를 같은 요청으로 연결하여 확인 |
sendModuleCommand 반환 0이나 MQTT 전송 성공만으로 기능 완료를 판정하지 않는다.
5. 소스 전달 기준과 남은 부분
전달본 voice-profile-complete-sample-20260921.zip은 09-20 소스에 착수 안내를 더한 묶음이다. 등록 App·AI-Agent 전체 프로젝트와 DeviceAgent·IoTAgent diff를 포함한다. 적용 기준은 묶음의 SOURCE-ORIGINS.json, integration/manifest.json을 확인한다. 미커밋 작업도 포함하므로 HEAD만 비교하여 같은 소스라고 판단하지 않는다.
현재 확인: 소스 기반 메서드·라우팅·상태 경계. 별도 검증: 서명된 APK 조합, 실기기 경합, 운영 AWS 통신, 서버 저장 후 ACK, 재부팅 복구. 로컬 시험 ACK는 서버 저장 증거가 아니다.
6. DeviceAgent가 연결해야 하는 명령과 상태
DeviceAgent의 핵심 작업은 명령을 한 번 전달하는 것뿐 아니라, 실행 중 발생하는 상태와 최종 결과를 알맞은 수신자에게 계속 전달하는 것이다. 녹음 진행이나 등록 성공 여부를 DeviceAgent가 추정하지 않는다.
| 종류 | 요청 / 상태의 출발점 | DeviceAgent의 전달 대상 | 전달할 내용 |
|---|---|---|---|
| 등록 시작·재녹음·취소 | 등록 App | AI-Agent, CALLER_LLM=1 | 요청 method와 Bundle |
| 등록 상태·진행률·오류·완료 | AI-Agent | 등록 App(8)과 IoTAgent(2) | voiceProfileStateChanged, requestId, stateSequence, state, progress, reasonCode, terminal |
| 프로필 인수 | AI-Agent | DeviceAgent 내부 인수·대기 저장 경로 | commitVoiceProfile, voiceId, nickname, 임베딩 |
| 프로필 인수 결과 | DeviceAgent | AI-Agent(1) | voiceProfileCommitResult, accepted, cloudSynced, reasonCode |
| 기기 목록·삭제 요청 | IoTAgent | AI-Agent(1) | 관리 method, requestId, 해당 조회·삭제 필드 |
| 관리 요청 결과 | AI-Agent | IoTAgent(2) | 결과 method와 같은 requestId, success, 결과 데이터 |
| 서버 개인화 조회 | AI-Agent | IoTAgent(2), 이후 외부 조회 경로 | getVoicePersonalization, requestId, voiceId, 기한 |
| 서버 개인화 조회 결과 | IoTAgent | AI-Agent(1) | voicePersonalizationResult, 같은 요청 ID·voiceId·기한 |
위 번호는 현재 callback 대상 상수다. Bundle 안의 임의 caller 값만 믿고 권한을 부여하는 방식이 아니다. DeviceAgent에서 실제 호출자와 허용 메서드를 확인한다.
실제 전송 방식
- 등록 App/AI-Agent → DeviceAgent:
sendModuleCommand(input: Bundle, output: Bundle). - DeviceAgent → 등록 App/AI-Agent: 등록된 대상의
onModuleCallback(outdata: Bundle?). - 요청의 최종 결과는 동기 output에 담겨 돌아오는 일반적인 함수 반환 형태가 아니라 별도 callback이다.
- DeviceAgent 내부
onModuleCallbackLoop(...)는 대상 선택·전달 함수다. 등록 App이 직접 호출할 API가 아니다.
Kotlin Bundle 생성·수신 코드와 실제 필드 값은 AI-Agent 명세 16절, 등록 App 명세 14절에 있다.
7. 주요 시나리오에서 확인할 연결
등록 시작부터 완료까지
- DeviceAgent가 등록 App 화면을 열고 requestId·닉네임 등 시작 정보를 전달한다. 화면 실행만으로 녹음은 시작하지 않는다.
- 등록 App이 Proxy에 연결하고 현재 상태를 조회한다. 사용자가 시작 버튼을 누르면 등록 명령을 보낸다.
- DeviceAgent가 명령을 AI-Agent로 전달한다. AI-Agent가 녹음·검사를 수행하며 상태를 발행한다.
- DeviceAgent는 진행 상태를 등록 App과 IoTAgent에 전달한다. 등록 App은 상태에 따라 진행률·오류·재녹음 버튼을 표시한다.
- AI-Agent가 프로필을 만들면 voiceId와 임베딩을 DeviceAgent에 전달한다.
- 기기 인수 결과와 서버 저장 결과를 구분한다. 최종 완료 조건을 충족한 뒤 AI-Agent가 COMPLETED를 발행하고, DeviceAgent가 이를 전달한다.
중간 취소와 다시 녹음
| 상황 | 연결할 동작 | 완료 판단 |
|---|---|---|
| 녹음 실패 후 다시 녹음 | 등록 App의 retryVoiceProfileSet → DeviceAgent → AI-Agent | 새로운 RECORDING_SET 또는 오류 callback 확인 |
| 나가기 확인창 표시 | pauseVoiceProfileEnrollmentForExit 전달 | 현재 녹음 정지. 별도 PAUSED 상태는 없음 |
| 나가기 확정 | cancelVoiceProfileEnrollment 전달 | 해당 requestId의 종료 상태 확인 |
| 나가기 취소·계속하기 | retryVoiceProfileSet 전달 | 현재 세트를 처음부터 다시 녹음 |
| 정상 완료 후 화면 닫기 | closeVoiceProfileRegistration 전달 | 세션·화면 정리. 등록된 화자 삭제가 아님 |
취소 이후 도착한 생성·저장 결과로 화면을 다시 완료 상태로 바꾸지 않아야 한다. 현재 구현의 상태별 허용 조건과 무응답 처리 한계는 등록 App 명세에 구분했다.
관심사 조회
관심사는 APP에서 초기 등록 후 또는 상시 변경하고 서버가 원본을 관리한다. AI-Agent는 필요할 때 DeviceAgent에 조회를 요청한다. DeviceAgent가 외부 조회 경로로 연결하고 결과를 AI-Agent에 돌려준다. 등록 App에 관심사 저장소나 서버 조회 기능을 추가하는 구조가 아니다.
8. 공통으로 유지할 값과 제외 가능한 값
| 값 | 역할 | 구현 시 주의 |
|---|---|---|
| requestId | 요청·상태·결과 연결 | 해당 흐름에서 같은 값 보존. nickname으로 대체하지 않음 |
| voiceId | 등록된 화자 식별 | AI-Agent에서 생성. 계정 연결은 서버 소관 |
| nickname | 사용자 표시 이름 | 화자 식별 키와 구분 |
| stateSequence | 동일 등록 요청의 상태 순번 | Long 유지. UI는 중복·이전 순번을 적용하지 않음 |
| terminal | 해당 등록 상태가 종료 상태인지 표시 | Boolean 유지. 명령 전달 성공과 구분 |
| accepted / cloudSynced | 기기 인수 / 서버 저장 완료 구분 | accepted=true만으로 등록 완료를 만들지 않음 |
| issuedAtMs / expiresAtMs | 개인화 조회 등의 유효 시간 | 사용하는 계약에서 Long 유지. 등록 UI 명령에 expiresAtMs를 임의 추가하지 않음 |
발음 보조 기능을 제외할 때는 입력 UI, 송수신·검증, 저장·조회, TTS 참조를 함께 정리한다. 현재 모든 경로에서 필드를 생략해도 된다는 검증 결과를 의미하지 않는다.
9. 구현 완료 판단과 현재 제한
| 확인 항목 | 확인할 증거 |
|---|---|
| 명령 전달 | 요청 method·requestId·필드 타입과 AI-Agent 수신 로그가 연결됨 |
| 지속 상태 전달 | 녹음 진행·오류·재시도·완료 상태가 등록 App과 IoTAgent에 도착함 |
| 대상 분리 | 관리 결과·개인화 결과를 등록 화면 상태로 잘못 전달하지 않음 |
| 취소 처리 | 현재 요청의 종료 callback, 녹음 중단, 늦은 결과 미적용을 확인 |
| 프로필 전달 | voiceId와 임베딩 인수 결과를 확인. 원본 음성은 외부 전달하지 않음 |
| 서버 완료 | 실제 서버 저장 ACK와 최종 상태를 같은 요청으로 확인 |
| 개인화 | 서버 조회 결과의 voiceId·기한·관심사 반영 및 조회 실패 처리를 확인 |
| 연결 단절 | 재연결 후 상태 조회와 중복·오래된 callback 처리 확인 |
현재 소스 검토와 문서 검증으로 확인한 범위와 실기기/운영 검증을 구분한다.
- 기기 대기 저장만 성공한 WAITING_CLOUD_SYNC는 서버 등록 완료가 아니다. LOCAL_TEST_ACK도 운영 서버 저장 증거가 아니다.
- 실제 서버 저장 ACK를 기기에 연결하는 경로는 별도 구현·통합 시험 대상이다.
- callback 유실 시 모든 명령이 자동 재전송되는 구조는 아니다. 명령별 타임아웃·재시도 조건을 따른다.
- 프로세스 재시작 후 등록 세션/pending 복원, 동일 요청의 전달 재시도 회차 구분에는 현재 제한이 있다.
- 서명된 APK 설치, Binder 왕복, 녹음 중 취소, 서버 저장까지의 통합 시험은 문서 검사만으로 완료 판정하지 않는다.
Connections
- 전체 시나리오·Sample 구현 현황: 사용자 동작과 E2E 참고.
- 기존 E2E 프로토콜 자료: Sample 구성과 전달 예시.
- 기존 IoT 토픽 자료: 외부 담당 간 설계 참고. 제품 확정 규격으로 강제하지 않음.