← Docs hub

Speaker Identity A2A Implementation Roadmap

등록 데이터 경로 기준 변경: 일반 실행 음성과 등록 WAV는 Cloud로 보내지 않는다. OnDevice가 Voice ID와 Reference Embedding을 만들고 Cloud Voice Sync Registry에 둘을 동기화한다. 화자 매칭과 신뢰도 판정은 On-device에 남긴다. 최신 제품 구조는 보이스 프로필 등록 제품 구현 기준서를 우선한다.

이 문서는 화자 분리/인식 PoC를 제품 경로와 Cloud A2A Task Manager에 연결하기 위한 구현 로드맵이다.

앞선 문서들이 “현재 구조 분석”과 “확장 설계”라면, 이 문서는 후속 개발자가 실제 작업을 티켓으로 나눌 때 사용할 실행 순서다.

1. 구현 원칙

2. 구현 티켓 분해

SPK-07은 단순 문서 작업이 아니라 제품 architecture 결정이다. Voice ID를 계정/얼굴 ID에 직접 붙이는 방식과 Person Profile link 방식은 이후 DB, 앱 UI, 개인정보 동의, Cloud payload가 모두 달라진다.

3. 온디바이스 구현 상세

3.1 SPK-01: SpeakerContext DTO

권장 Kotlin 모델:

data class SpeakerContext(
    val contractVersion: String = "speaker-context-v2",
    val voiceId: String = "",
    val speakerConfidence: Float = 0f,
    val speakerState: SpeakerState = SpeakerState.UNKNOWN,
    val speakerCount: Int = 0,
    val overlapRatio: Float = 0f,
    val unknownRatio: Float = 0f,
    val maxScore: Float = 0f,
    val modelVersion: String = "",
    val profileVersion: Int = 0,
    val source: String = "ondevice_sherpa_cpu"
)

권장 상태:

identified
unknown
ambiguous
multi_speaker
overlap
far_speech
disabled

주의:

• voiceId는 OnDevice가 발급한 불투명 ID이며 nickname과 독립적이어야 한다.
• 표시명, 사람 ID, 개인화 동의, 권한은 Cloud lookup 결과이므로 이 DTO에 넣지 않는다.
• contractVersion은 Cloud 정규화에서 필수 확인해야 한다.

3.2 SPK-02: PoC 결과 변환 Adapter

현재 근거:

ForegroundService.kt
- speakerEnrollmentBufferLock
- pendingSpeakerPrefix
- lastIdentifiedSpeakerName
- idAcceptThreshold = 0.50f
- extensionFeatures.enableSpeakerStability = true

SpeakerIdentificationEngine.kt
- registerSpeakerFromWavPath()
- identifyFromSamples()
- identifyFromSegment()
- searchEmbeddingWithScoreRaw()

DiarizationEngine.kt
- diarize(samples)
- DiarizationSegment(startSec, endSec, speakerId)

SpeakerStabilityFeature.kt
- sessionBoostScore = 0.04f
- recentBoostScore = 0.02f
- sessionDecayMs = 20_000L

변환 규칙:

3.3 SPK-03: Cloud Request 삽입

삽입 위치는 Cloud LLM request를 구성하는 경로다.

원칙:

• 기존 recognized_text, asr_confidence, audio_locale, memory_context, device_context를 유지한다.
• voice_context.speaker_context를 새 field로 추가한다.
• log에는 raw audio, embedding, WAV path를 남기지 않는다.

요청 예시:

{
  "recognized_text": "거실 청정하고 10분 뒤에 돌아와",
  "voice_context": {
    "recognized_text": "거실 청정하고 10분 뒤에 돌아와",
    "asr_confidence": 0.94,
    "audio_locale": "ko-KR",
    "speaker_context": {
      "contract_version": "speaker-context-v2",
      "voice_id": "vp_opaque_uuid",
      "speaker_confidence": 0.72,
      "speaker_state": "identified",
      "speaker_count": 1,
      "overlap_ratio": 0.0,
      "unknown_ratio": 0.0,
      "max_score": 0.72,
      "model_version": "speaker-model-version",
      "profile_version": 1,
      "source": "ondevice_sherpa_cpu"
    }
  }
}

4. Cloud A2A 구현 상세

4.1 SPK-04: normalize_voice_context() 확장

현재 근거:

gemini/a2a/runtime/session_state.py
normalize_voice_context()

현재 기본화:

recognized_text
asr_confidence
audio_locale
slot_state
handoff_chain
replan_reason
selected_flow_id
owner_selection

추가 권장:

def _normalize_speaker_context(value):
    speaker = value if isinstance(value, dict) else {}
    return {
        "contract_version": str(speaker.get("contract_version") or "speaker-context-v2"),
        "voice_id": str(speaker.get("voice_id") or ""),
        "speaker_confidence": _safe_float(speaker.get("speaker_confidence"), 0.0),
        "speaker_state": _allowed_state(speaker.get("speaker_state")),
        "speaker_count": _safe_int(speaker.get("speaker_count"), 0),
        "overlap_ratio": _safe_float(speaker.get("overlap_ratio"), 0.0),
        "unknown_ratio": _safe_float(speaker.get("unknown_ratio"), 0.0),
        "max_score": _safe_float(speaker.get("max_score"), 0.0),
        "model_version": str(speaker.get("model_version") or ""),
        "profile_version": _safe_int(speaker.get("profile_version"), 0),
        "source": str(speaker.get("source") or "unknown"),
    }

Cloud는 값이 없으면 unknown으로 낮춰야 한다. 값이 없다고 제품 경로를 실패시키면 기존 기능 회귀가 생긴다.

Identity 확장 필드는 기기 요청을 신뢰하지 않고 Voice ID lookup 결과로 별도 생성한다.

4.2 SPK-05: Speaker-scoped Memory

현재 근거:

gemini/a2a/runtime/memory_context.py
normalize_memory_context()
build_memory_update()

추가 권장:

{
  "write_candidates": {
    "short_term_pair": {
      "person_id": "person_001",
      "speaker_state": "identified",
      "write_policy": "speaker_scoped",
      "user_text": "...",
      "assistant_text": "...",
      "route_family": "ODL",
      "workflow_id": "wf_001"
    },
    "profile_candidates": []
  }
}

정책:

4.3 SPK-06: TaskManager Side-effect Gate

현재 근거:

gemini/a2a/runtime/task_manager.py
build_device_task_requests()
execute_task_plan()

적용 위치:

• device task request를 만들기 전 speaker safety를 확인한다.
• side-effect가 큰 기능은 safety_gate=pass가 아니면 confirmation_required 또는 blocked로 낮춘다.
• active workflow가 있을 때 Cloud가 확인한 workflow_owner_person_id와 현재 person_id가 다르면 takeover 정책을 적용한다.

정책 예시:

5. 권장 구현 순서

Phase 1: OnDevice Voice ID generator와 local repository 구현
Phase 2: 5세트 등록 controller와 Voice ID/Reference Embedding Sync Outbox 구현
Phase 3: Cloud Voice Sync Registry, delete/resolve와 Person mapping 구현
Phase 4: Cloud request에 speaker_context-v2 추가
Phase 5: Cloud에서 person_context를 만들고 memory scope 적용
Phase 6: TaskManager side-effect gate 적용
Phase 7: 실기기 E2E evidence 수집
Phase 8: threshold tuning과 privacy/delete 정책 확정

이 순서를 지키는 이유는 rollback 위험을 줄이기 위해서다. Cloud가 speaker_context를 아직 사용하지 않더라도 payload에 추가하는 것은 additive change다. 반대로 TaskManager gate를 먼저 넣으면 기존 기능 실행이 막히는 회귀가 생길 수 있다.

6. 테스트 매트릭스

7. 릴리즈 게이트

8. 후속 의사결정

아래 항목은 구현 전에 소유자 합의가 필요하다.