← Docs hub

보이스 프로필 연동 규격

이 페이지는 E2E Sample 참고 자료다. 직접 구현 협의는 담당별 범위, DeviceAgent ↔ AI-Agent 구현 요청서, DeviceAgent ↔ 등록 App 구현 요청서를 사용한다. 아래 APP·Backend·IoTAgent의 API·토픽은 외부 담당들이 협의할 제품 설계를 강제하지 않는다.

09-17 변경: 관심사 원본은 서버로 이전했다. App의 최초 등록 후·상시 변경은 HTTPS 저장이며, AI-Agent 조회는 반대 방향인 AI-Agent → DeviceAgent → IoTAgent → 서버다. 신규 필드·토픽·그림. 아래 interestsSet/interestsGet은 이전 로컬 규격으로 현재 AI-Agent가 SERVER_OWNED_PERSONALIZATION을 반환한다.

담당별 시작 위치

이 페이지는 전체 연결과 시나리오의 기준이다. 실제 코딩에 필요한 필드·타입·예제는 아래 상세 명세에서 확인한다.

상세 명세에서 확인할 것

기기 Binder는 등록 App ↔ DeviceAgent와 AI-Agent ↔ DeviceAgent로 나눠 요청·응답 값을 확인한다.

현재 코드에 있는 계약과 제품에서 추가 정의할 계약을 혼동하지 않는다. 추가 항목은 Cloud 전달 경계에 모았다.

읽는 순서

1. 아래 흐름도에서 내 모듈의 송신·수신 상대를 확인한다.
2. 담당별 상세 명세에서 요청 Bundle/JSON과 결과 callback을 한 쌍으로 구현한다.
3. 상태·오류 표를 화면과 Backend 처리에 연결한다.
4. 상세 명세의 구현 확인 항목으로 정상·실패·취소를 각각 시험한다.

먼저 보는 결론

1. 모바일 App은 HTTPS만 사용하고 MQTT에 직접 연결하지 않는다.
2. A1에서 MQTT에 연결하는 모듈은 IotAgent 하나다.
3. DeviceAgent는 요청과 호출자를 검증하고 Binder 메시지를 중계한다.
4. 등록 App은 UI를, OnDevice Agent Service는 녹음·검증·프로필 생성을 담당한다.
5. 한 작업은 시작부터 종료까지 같은 requestId를 사용한다.
6. 원본 음성과 Query Embedding은 MQTT·Cloud로 보내지 않는다.
7. 현재 로컬 PoC와 제품 AWS 연동은 같은 것이 아니다.

프로토콜 흐름 크게 보기

구현 상태 표시

계약 버전

지원하지 않는 버전은 실행하지 않는다. 제품에서는 오류 응답까지 반환해야 하며, 현재 일부 수신 경로는 로그만 남기고 반환하므로 보완이 필요하다.

통신 경계

등록 메시지 흐름

등록 메시지 흐름 크게 보기

프로필 조회와 삭제 흐름

모바일 App의 목록은 Gateway 캐시가 아니라 A1 기기에 로컬 저장된 프로필을 조회한다. 조회는 기기에 저장된 프로필 목록이며 Cloud 동기화 완료 목록이 아니다. 삭제는 voiceId를 기준으로 로컬 프로필·임베딩을 정리한다. 서버 관심사 삭제는 서버 후속 처리다. DeviceAgent의 전달 대기 사본 삭제는 별도 시도이며 실패해도 기존 성공 결과가 전달될 수 있다. 전체 사본 삭제나 Cloud 삭제 완료로 해석하지 않는다.

프로필 조회와 삭제 흐름 크게 보기

서버 관심사 조회 흐름

관심사는 서버가 voiceId를 기준으로 관리하고 모바일 App에서 변경한다. AI-Agent가 getVoicePersonalization을 요청하면 DeviceAgent → IoTAgent → 서버로 전달하고, 역방향 voicePersonalizationResult 콜백의 interestCodes:ArrayList<String>으로 받는다. AI-Agent 로컬 DB 조회가 아니다. 현재 샘플 MQTT 경로와 실제 AWS 운영 연결은 구분한다.

관심사 흐름 크게 보기

전체 시나리오 흐름

등록 시작, 진행 상태, 완료와 Cloud ACK, 취소·실패, 목록 조회·삭제를 한 화면에서 확인할 수 있다. 실선은 현재 기기 구현 경로이고, 보라색 점선은 제품 AWS 연동에서 추가해야 하는 경로다.

전체 시나리오 흐름 크게 보기

모바일 HTTPS API

아래 경로는 현재 PC Gateway와 모바일 Sample App에서 동작한다. 제품 AWS Backend는 같은 의미를 유지해 구현한다.

등록 시작 요청

{
  "contractVersion": "voice-profile-v2",
  "requestId": "vp-20260911-0001",
  "method": "startVoiceProfileEnrollment",
  "deviceId": "A1-001",
  "nickname": "silogood",
  "locale": "ko-KR",
  "personalizationEnabled": true,
  "issuedAtMs": 1789092000000,
  "expiresAtMs": 1789092300000
}

MQTT 계약

토픽

상태 이벤트와 최종 결과는 현재 PoC에서 같은 response 토픽에 발행된다. 제품 AWS에서도 requestId가 포함된 동일 응답 경로를 사용하면 모바일·Backend의 상관관계 처리가 단순해진다.

명령 봉투

{
  "action": "start",
  "payload": {
    "contractVersion": "voice-profile-v2",
    "requestId": "vp-20260911-0001",
    "nickname": "silogood",
    "locale": "ko-KR",
    "personalizationEnabled": true,
    "issuedAtMs": 1789092000000,
    "expiresAtMs": 1789092300000
  }
}

상태 이벤트

{
  "contractVersion": "voice-profile-v2",
  "method": "voiceProfileStateChanged",
  "requestId": "vp-20260911-0001",
  "stateSequence": 8,
  "state": "SET_ACCEPTED",
  "setIndex": 2,
  "setCount": 5,
  "progress": 100,
  "reasonCode": "",
  "terminal": false,
  "nickname": "silogood"
}

Binder 메서드

등록 화면과 세션 제어

프로필 전달과 관리

등록 상태 enum

SET_REJECTED, PROFILE_FAILED, DELIVERY_FAILED는 재시도 UI를 제공할 수 있지만 해당 상태 이벤트 자체는 현재 세션 결과를 나타낸다.

오류와 대기 코드

오디오·임베딩 검사

취소·전달

프로필 commit 계약

Service가 DeviceAgent에 전달하는 필드는 다음과 같다.

현재 DeviceAgent는 payload를 검증한 뒤 EncryptedSharedPreferences 기반 대기 저장소에 저장한다.

{
  "contractVersion": "voice-profile-v2",
  "method": "voiceProfileCommitResult",
  "requestId": "vp-20260911-0001",
  "accepted": true,
  "cloudSynced": false,
  "reasonCode": "WAITING_CLOUD_SYNC"
}

현재 대기 저장소에 구현된 기능은 save()와 removeByVoiceId()다. 목록 조회, 재부팅 후 자동 재전송, Cloud ACK 수신 및 ACK 후 삭제는 제품 구현이 필요한 기능이다.

순서·중복·만료 처리

• requestId: 요청과 모든 상태·결과를 연결한다.
• stateSequence: 같은 요청에서 더 큰 값만 UI에 반영한다.
• 만료 검사는 expiresAtMs 기준이다. issuedAtMs 자체로 만료를 판단하지 않으며, 만료값 누락 시 현재 기본값은 Long.MAX_VALUE다. 제품 발신자는 만료값을 반드시 지정해야 한다.
• IotAgent 명령 경로와 DeviceAgent 원격 시작·취소 경로에 만료 검사가 있고 Service 자체에는 없다.
• MQTT QoS 1의 재전달을 안전하게 처리하는 것은 제품 요구사항이다. 현재 같은 requestId의 start도 세트를 초기화하므로 자동 재시작 대신 상태 조회가 필요하다.
• 다른 활성 요청은 Service에서 ANOTHER_SESSION_ACTIVE로 거절하지만, 등록 App을 거치는 원격 요청은 화면에서 무시되어 실패가 돌아오지 않을 수 있다.

<a id="implementation-gaps"></a>

현행 한계와 담당별 보완

아래는 구현 완료 항목이 아니라 제품 적용 전 남은 작업이다. 실제 메서드·기본값은 Binder 13절을 함께 확인한다.

등록 Service의 세션/pending은 메모리다. DeviceAgent의 암호화 대기 파일이 있다고 해서 Service 세션이 재부팅 후 자동 복구되는 것은 아니다.

보안과 데이터 제한

• 모바일 App에는 AWS IoT 인증서나 MQTT 비밀값을 넣지 않는다.
• IotAgent만 기기 MQTT 연결을 소유한다.
• DeviceAgent는 UID에 속한 패키지와 허용 메서드를 검사한다. android.uid.system을 공유하는 앱 각각의 신원까지 분리해 인증하는 것은 아니다. Bundle의 caller 문자열만으로 이 한계를 해결할 수 없다.
• 새 voice-profile-v2 등록 경로는 원본 PCM/WAV를 외부로 보내지 않는다. Query Embedding도 기기 내부에서 사용한다. 기존 수동 등록의 WAV 저장 경로는 별도로 점검한다.
• Reference Embedding은 최소 권한, 전송 암호화, 저장 암호화와 삭제 추적을 적용한다.
• 로그에는 임베딩 배열, 원본 음성, 계정 식별정보를 출력하지 않는다.
• 제품 삭제 목표는 로컬·전달 대기·Cloud 사본 정리다. 현재 로컬 성공 응답만으로 모든 사본 삭제를 보장하지 않는다.

PoC 실행 경로

현재 로컬 시험은 다음 경로를 사용한다.

모바일 Sample App
  → HTTP/SSE
PC Gateway :8788
  → 로컬 MQTT :1883
IotAgent VoiceProfileMqttTestBridge
  → DeviceAgent → 등록 App / OnDevice Agent Service

IotAgent 시험 Bridge는 persist.sys.vp.mqtt_test_uri로 활성화한다. adb reverse tcp:1883 tcp:1883은 USB/ADB 연결 시험용이며 제품 통신 경로가 아니다.

제품 구현 점검표

연동 시험 순서

아래는 완료 판정에 필요한 시험 목록이며 모두 통과했다는 결과표가 아니다. 특히 중복 시작·생성 중 취소·순번 역전은 위 보완 이후 회귀 시험이 필요하다.

1. 같은 requestId가 모바일, Gateway/Backend, MQTT, IotAgent, DeviceAgent, Service 로그에 남는지 확인한다.
2. WAITING_START → RECORDING_SET → ... → COMPLETED와 증가하는 stateSequence를 확인한다.
3. 실패 세트에서 SET_REJECTED와 정확한 reasonCode가 오는지 확인한다.
4. 취소 후 녹음이 멈추고 CANCELLED, terminal=true가 오는지 확인한다.
5. COMPLETED에 유효한 voiceId가 있는지 확인한다.
6. 등록 후 list 결과와 기기 로컬 매칭 결과가 같은 voiceId인지 확인한다.
7. 패킷·로그·저장소에 원본 PCM/WAV가 없는지 확인한다.
8. 제품 AWS 경로에서는 Cloud ACK 전후의 대기 저장 유지·삭제를 별도로 확인한다.

/health 성공이나 빈 profile 목록 응답은 연결만 증명한다. 등록 성공은 같은 requestId의 COMPLETED + terminal=true + voiceId까지 확인해야 한다.

구현 근거와 상세 문서

• 제품 구조와 구현 현황
• 로컬 PoC 시험 환경
• 등록 음성 검증
• 실패·취소·복구
• 화자별 관심사와 등록 상태

기준 코드는 VoiceProfileContract.java, CmdTopic.java, VoiceProfileMqttTestBridge.java, DeviceAgent.java, VoiceProfilePendingStore.java, VoiceProfileIpcContract.kt와 ForegroundService.kt다.