화자인식 개발 분담과 인터페이스
실제 연동 구현용 명세 - 등록 App·AI-Agent ↔ DeviceAgent 인터페이스 정의 - 등록 App ↔ DeviceAgent: 화면 제어·상태 수신 값 - AI-Agent ↔ DeviceAgent: 실행 요청·임베딩·저장 결과 값 - IoTAgent·AWS 담당: 토픽·발행/구독·메시지 명세 - 모바일·Backend 담당: HTTPS 요청/결과 명세
등록 App·AI-Agent는 내부 개발, DeviceAgent·IotAgent는 SoC 개발 그룹, 모바일 App·관제는 모바일/관제 개발 그룹이 담당한다. 개발 그룹은 세 개지만 모바일 App과 AWS Backend의 실행 주체는 구분한다. 이 문서는 역할과 연결 작업을 정리하며, 필드·상태의 상세 규격은 연동 규격, 제품 동작은 제품 기준서를 따른다.
1. 개발 그룹
| 개발 그룹 | 담당 모듈 | 책임과 산출물 |
|---|---|---|
| 내부 개발 | 등록 App | A1 등록 화면, 다시 녹음·나가기·취소, 상태 callback 표시. Android 프로젝트와 플랫폼 서명 APK |
| 내부 개발 | AI-Agent Service | 녹음·품질 검사·동일 화자 검사, voiceId/임베딩 생성, 저장·식별, 서버 관심사 조회. 소스와 APK |
| SoC 개발 (업체 1) | DeviceAgent | Binder 호출자/계약 검증, 등록 App 실행, Service 명령 전달, 결과 callback, 전달 대기 저장. 제공 Diff를 관리 소스에 반영 |
| SoC 개발 (업체 1) | IotAgent | AWS IoT Core 접속·구독·발행, JSON↔Bundle 변환, 결과/ACK 전달. 제공 Diff 및 제품 MQTT 결과 경로 구현 |
| 모바일/관제 개발 (업체 2) | 모바일 App | 사용자 입력·진행 상태·목록·삭제·관심사 화면. HTTPS API 사용 |
| 모바일/관제 개발 (업체 2) | AWS Backend·관제 | 계정/기기 권한, API, MQTT 발행·결과 처리, voiceId↔계정 연결, 등록 임베딩 저장, ACK와 복구 처리 |
PC Gateway와 모바일 Sample은 시험 참고 구현이다. 제품 Backend의 인증·권한·저장 기능을 대신하지 않는다.
2. 경계별 계약
| 경계 | 요청 방향 | 결과 방향 | 함께 맞출 내용 |
|---|---|---|---|
| A: 기기 내부 | 등록 App/IotAgent → DeviceAgent → AI-Agent | AI-Agent → DeviceAgent → 등록 App/IotAgent | Binder 메서드·Bundle 타입·callback 허용 목록·등록 App 실행 |
| B: 기기와 관제 | Backend → AWS IoT Core → IotAgent | IotAgent → AWS IoT Core → Backend | 토픽·action·JSON·QoS·만료·중복·Cloud ACK |
| C: 모바일과 관제 | 모바일 App → Backend | Backend → 모바일 App | HTTPS API·계정 권한·상태 조회·실시간 이벤트·오류 UI |
등록 App과 AI-Agent 사이의 표에 적힌 논리 호출도 DeviceAgent Binder 중계를 통한다. 녹음은 AI-Agent만 수행하며 모바일 App·등록 App·DeviceAgent·IotAgent는 PCM을 소유하지 않는다.
3. 등록 화면과 Service
계약 버전은 voice-profile-v2다. 아래 요청은 등록 App에서 DeviceAgent를 통해 Service로 전달한다.
| 메서드 | 목적 | 결과 처리 |
|---|---|---|
getVoiceProfileEnrollmentState |
화면 재진입 시 현재 등록 상태 조회 | 현재 상태 표시 |
startVoiceProfileEnrollment |
사용자 시작 후 등록 진행 | voiceProfileStateChanged |
retryVoiceProfileSet |
실패한 음성 세트 재녹음 | 해당 세트 상태 갱신 |
pauseVoiceProfileEnrollmentForExit |
나가기 확인 중 녹음 일시 정지 | 화면 확인 결과에 따라 계속/취소 |
cancelVoiceProfileEnrollment |
등록 취소 | CANCELLED, terminal=true |
setVoiceProfilePersonalization |
enabled Boolean으로 개인화 설정 |
상태 callback |
retryVoiceProfileCreation |
로컬 프로필 생성 재시도 | 생성/실패 상태 |
retryVoiceProfileDelivery |
DeviceAgent 전달 재시도 | 전달/실패 상태 |
closeVoiceProfileRegistration |
등록 화면 종료 | 등록 엔진 종료 정책과 함께 처리 |
원격 등록 시작은 DeviceAgent가 등록 화면을 여는 단계이며, 사용자가 화면에서 시작하는 단계와 구분한다.
화면 상태는 Service가 판단한다. 등록 App은 다른 requestId 및 오래된 stateSequence를 반영하지 않는다.
등록 세션 중 Wake Word 기반 일반 음성 처리를 제한하고, 종료/실패/취소 시 해제하는 책임은 AI-Agent에 있다.
4. 모바일 요청부터 기기 결과까지
아래 HTTPS 경로는 현재 Sample/PC Gateway 기준이다. 제품 Backend 담당은 인증을 추가하고 같은 동작을 제공한다. 모든 원격 요청은 B 경계를 통과하며 등록 App을 열 필요가 없는 조회·삭제는 Service로 바로 중계한다.
| 모바일 HTTPS | MQTT action | 기기 메서드 | 결과 method |
|---|---|---|---|
POST /voice-profiles/enrollments |
start |
startVoiceProfileEnrollment |
voiceProfileStateChanged |
POST /voice-profiles/enrollments/{requestId}/cancel |
cancel |
cancelVoiceProfileEnrollment |
voiceProfileStateChanged |
GET /voice-profiles?deviceId=... |
list |
listVoiceProfiles |
voiceProfileListResult |
DELETE /voice-profiles/{voiceId}?deviceId=... |
delete |
deleteVoiceProfile |
voiceProfileDeleteResult |
GET /voice-profiles/{voiceId}/interests |
interestsGet |
getVoiceProfileInterests |
voiceProfileInterestsResult |
PUT /voice-profiles/{voiceId}/interests |
interestsSet |
setVoiceProfileInterests |
voiceProfileInterestsResult |
등록·프로필은 voice-profile-v2, 서버 관심사 조회는 voice-personalization-v1을 사용한다. 구형 로컬 관심사 메서드는 지원 거절만 반환한다.
GET /voice-profiles/enrollments/{requestId}는 Backend/Gateway의 등록 상태 조회다.
GET /voice-events?deviceId=...는 현재 PoC의 SSE 이벤트 경로이며 제품의 SSE/WebSocket/푸시는 Backend가 구현한다.
5. MQTT 발행과 구독
| 토픽 | 발행자 | 구독자 | 내용 |
|---|---|---|---|
skmg/airbot/{deviceId}/v1/command/voiceProfileEnrollment |
AWS Backend | IotAgent | {action, payload} 요청 |
skmg/airbot/{deviceId}/v1/response/voiceProfileEnrollment/{requestId} |
IotAgent | AWS Backend | 상태·관리 결과. 현재 PoC response 구조 |
모바일 App은 MQTT를 구독하지 않는다. Backend가 기기 결과를 모바일에 전달한다. QoS 1은 전달 확인과 재전송을 사용하는 설정이며 중복 수신 가능성이 있다. 제품 권장값은 명령·최종 결과 QoS 1, retained=false다. 수신자는 요청 ID로 중복 실행을 방지한다. Broker의 PUBACK는 메시지 전달 확인이며 프로필이 AWS 저장소에 저장됐다는 Cloud ACK와 다르다.
제품 상태/결과 publish, Cloud ACK 토픽과 action, 임베딩 업로드 메시지는 아직 제품 연동을 완료하지 않았다.
syncAck 같은 이름은 현재 확정 구현 메서드로 사용하지 않는다. 아래 9절 항목을 함께 확정한다.
6. 공통 필드
| 필드 | 타입/의미 | 담당 |
|---|---|---|
contractVersion |
String, 등록 voice-profile-v2 / 메모리 voice-memory-v1 |
전 구간 보존·검증 |
requestId |
String, 요청과 결과를 연결하는 작업 ID | Backend 생성/확정, 모든 중계 보존 |
deviceId |
String, 대상 기기. MQTT 토픽에도 포함 | Backend 권한 검사, IotAgent 대상 확인 |
method / action |
String, Binder 동작 / MQTT 동작 | DeviceAgent·IotAgent 상수로 변환 |
issuedAtMs / expiresAtMs |
Long, 생성/만료 시각(ms) | Backend 생성, 기기 만료 검증 |
voiceId |
String, AI-Agent가 생성하는 화자 ID | AI-Agent 생성, Backend가 계정과 연결 |
nickname |
String, 화면 표시 이름 | 모바일 입력, 식별 키로 사용하지 않음 |
locale |
String, 등록 언어 | 모바일/Backend 전달 |
personalizationEnabled |
Boolean, 개인화 동의/설정 | 모바일/등록 App 입력, Service 보존 |
enabled |
Boolean, setVoiceProfilePersonalization 요청의 설정 값 |
등록 App → DeviceAgent → Service |
stateSequence |
증가하는 상태 순번 | Service 생성, 화면/Backend에서 역전 방지 |
state / terminal |
String 상태 / Boolean 종료 여부 | Service 생성 |
setIndex / setCount / progress |
현재 세트 / 전체 세트 / 단계 진행률 | Service 생성 |
success / reasonCode |
관리 성공 여부 / 실패·대기 사유 | 실행 주체가 반환, 중계 보존 |
accepted / cloudSynced |
DeviceAgent 수락 / Cloud 저장 확인 | 아래 완료 규칙 적용 |
referenceEmbedding |
등록 대표 임베딩. Binder FloatArray | Service → DeviceAgent; Cloud 인코딩은 제품 계약 확정 필요 |
interestCodes |
String 목록, 화자별 관심사 | 모바일 입력, voiceId 기준 저장 |
userText / assistantText |
사용자/응답 텍스트 | 저장·조회·실시간 반영 |
기존 코드의 userId 필드는 서비스의 로그인 계정을 증명하지 않는다. 계정-voiceId 접근 권한은 Backend에서 판단한다.
원본 PCM/WAV와 인식 시 Query Embedding은 외부로 전송하지 않는다.
7. 완료·실패·취소
| 상황 | 처리 | 책임 |
|---|---|---|
| 녹음 불합격 | SET_REJECTED와 reasonCode, 다시 녹음 |
Service 판단, 등록 App 표시 |
| 생성 실패 | PROFILE_FAILED |
Service 정리, 등록 App 재시도 |
| DeviceAgent 저장 수락 | accepted=true |
DeviceAgent. Cloud 완료로 표시하지 않음 |
| Cloud 연결 미완료 | cloudSynced=false, WAITING_CLOUD_SYNC; 현재 Service는 DELIVERY_FAILED |
SoC/Backend 연동 필요 |
| 제품 Cloud 저장 성공 | 저장 확인 ACK를 DeviceAgent→Service로 전달하고 완료 상태 생성 | Backend·SoC·내부 공동 구현 |
| 최종 등록 완료 | COMPLETED, terminal=true, voiceId |
Service 이벤트를 모바일까지 전달 |
| PoC 강제 완료 | LOCAL_TEST_ACK |
테스트 전용, 제품 성공 근거로 사용하지 않음 |
| 취소 | 같은 requestId의 녹음/임시 데이터 정리 후 CANCELLED |
Service 실행, 모든 화면 종료 반영 |
| 목록 조회 | 기기에 실제 저장된 프로필 반환 | Service. Gateway 등록 요청 이력과 구분 |
| 삭제 | 로컬 프로필·식별과 DeviceAgent 대기 데이터 정리; 서버 관심사 삭제는 서버 담당 | Service + DeviceAgent |
| Cloud 사본 삭제 | Backend 저장소·계정 연결 정리, 실패 시 재처리 | Backend. 제품 경로 추가 필요 |
취소와 commit이 겹쳤을 때 이미 저장된 Cloud 사본 처리, 단절 중 삭제, ACK 중복/지연 처리는 제품 통합 시 확정해야 한다. 단순 timeout을 삭제/등록 성공으로 처리하지 않는다. 전체 상태 enum과 오류값은 상태·오류 규격에서 유지한다.
8. 등록 후 인식과 대화
AI-Agent가 음성에서 임베딩을 추출해 기기 등록 프로필과 비교한다. 등록 시 UUID로 만든 voiceId를 매칭 결과로 반환한다. 모델이 모바일 계정 ID나 nickname을 생성하는 구조가 아니다. 관심사는 서버가 voiceId 기준으로 관리한다. AI-Agent는 getVoicePersonalization을 요청하고 voicePersonalizationResult를 수신한다. 대화내역 이벤트는 이번 계약에 없다. 모바일은 등록 상태 순번을 확인하고 재연결 시 등록 상태·화자 목록을 다시 조회한다.
첫 화자 A 이후 unknown은 A를 유지하고, 등록 화자 B로 식별되면 B로 바뀐다. 새 대화의 unknown은 미귀속이다. 제품 AWS 이벤트 발행은 추가 연결이 필요하다. 발행 주기/텍스트 포함 범위도 Backend와 SoC가 맞춘다.
9. 개발 착수 전 맞출 항목
| 항목 | 주 담당 | 완료 기준 |
|---|---|---|
| Binder method/key/타입 및 callback 허용 목록 | 내부 + SoC | 각 모듈 Contract 상수와 동일, 상태가 등록 App/IotAgent 모두에 도착 |
| 잘못된 요청의 오류 응답 | SoC + 내부 | 현재 일부 로그 후 반환 경로를 보완해 모바일에서 실패 이유 확인 |
| 제품 MQTT response 발행 | SoC | 로컬 시험 Bridge 없이 AWS IoT Core에서 결과 수신 |
| HTTPS 인증·기기 소유권 | 모바일/관제 | 다른 계정의 deviceId/voiceId 요청 거절 |
| 임베딩 Cloud wire format | 내부 + SoC + 모바일/관제 | 차원·모델 버전·인코딩·크기·검증 값·암호화·저장 API 합의 |
| Cloud ACK | SoC + 모바일/관제 + 내부 | 토픽/action/payload 확정, 저장 성공에 한해 Service 완료 |
| 전달 대기 재전송 | SoC | 현재 save/remove 외에 재부팅·단절 복구·ACK 후 정리 구현 |
| 재전송·중복·만료 | SoC + 모바일/관제 | 같은 요청 중복 실행 방지, 오래된 명령/ACK 처리 검증 |
| 취소/삭제와 Cloud 저장 경합 | 세 그룹 | 취소 후 저장 잔존·삭제 후 늦은 ACK로 프로필 복원 방지 |
| 이벤트 UI·재연결 | 모바일/관제 | 등록 상태 순번 처리, 끊긴 뒤 조회로 화면 복구 |
10. 적용 자료와 검증 순서
DeviceAgent/IotAgent는 각각 01a-deviceagent.patch, 01b-iotagent.patch를 제공한다.
SoC Diff 기준 커밋은 1398d109c391c4044cae26d0e9aea4d3f08d9670,
현재 검토 HEAD는 e54419a2c67c0c0963a15b651856cd2346332445다.
AI-Agent는 091e52bc69360147ecc9c6f7276bb0b63cb21fb4와 전달본의 미커밋 변경을 포함한다.
키·인증 설정과 제품 버전은 각 개발 환경에서 관리한다.
- 내부↔SoC: 등록 화면 실행, 5세트 진행, 다시 녹음, 나가기/원격 취소, 상태 callback.
- SoC↔Backend: 실제 command 구독과 response 발행, 같은 requestId 왕복.
- Backend↔모바일: 인증, 상태 표시, 등록 후 조회/삭제, 화자별 관심사.
- 세 그룹: Cloud 저장 ACK, 네트워크 단절/복구, 중복 요청, 재부팅, 취소/삭제 경합.
이번 문서의 근거는 현재 Contract/라우터/commit 소스다. 제품 AWS 연동 완료나 실기기 통합 시험 통과를 뜻하지 않는다.
관련 문서
코드 근거: DeviceAgent voiceprofile/VoiceProfileContract.java, ModuleCmdCallbackPolicy.java,
DeviceAgent.java, VoiceProfilePendingStore.java; IotAgent mqtt/VoiceProfileContract.java,
mqtt/topic/CmdTopic.java, VoiceProfileMqttTestBridge.java; AI-Agent VoiceProfileIpcContract.kt.