← Docs hub

Speaker Context Contract

이 문서는 OnDevice 화자 인식 결과와 Cloud 사용자 조회 결과를 섞지 않기 위한 계약이다.

1. 소유권 원칙

Cloud는 embedding으로 화자를 다시 판정하지 않는다. OnDevice도 계정, 사람 ID, 동의, 권한을 주장하지 않는다. 같은 payload에 두 종류의 사실을 섞으면 spoofing과 stale profile 문제가 생긴다.

2. OnDevice 요청: speaker_context

speaker_context는 기존 voice_context에 추가하는 optional field다.

{
  "voice_context": {
    "recognized_text": "거실 청정하고 10분 뒤에 침실로 와",
    "session_id": "sess_001",
    "asr_confidence": 0.94,
    "audio_locale": "ko-KR",
    "speaker_context": {
      "contract_version": "speaker-context-v2",
      "voice_id": "vp_opaque_uuid",
      "speaker_state": "identified",
      "speaker_confidence": 0.72,
      "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"
    }
  }
}

2.1 런타임 요청에서 신뢰하면 안 되는 필드

다음 값은 기기 요청에서 제거한다.

• person_id
• display_name
• identity_link_state
• personalization_allowed
• authority_level
• consent_scope
• linked_vital_face_ids
• 외부 계정 식별자
• raw audio, local path

이 값들은 Cloud의 신뢰 가능한 사용자 정보에서 만들어야 한다. queryEmbedding은 PPT 3페이지 호환 요청에 포함될 수 있지만 Cloud Identity Resolver는 이를 lookup key나 화자 판정 근거로 사용하지 않는다.

2.2 등록 동기화와 런타임 조회를 분리

두 계약을 같은 endpoint와 retention 정책으로 처리하면 Query Embedding이 등록 자산처럼 쌓일 수 있다. 저장 허용 대상은 등록 동기화의 Reference Embedding뿐이다.

3. Cloud 내부 결과: person_context

Cloud는 voice_id로 사용자 mapping을 조회한 뒤 별도 context를 만든다. Cloud Registry에 Reference Embedding이 있더라도 이 lookup에서 재매칭하지 않는다.

{
  "person_context": {
    "person_id": "person_001",
    "display_name": "나무",
    "identity_link_state": "linked",
    "personalization_allowed": true,
    "authority_level": "normal",
    "consent_scope": {
      "voice_personalization": true,
      "vital_history_summary": false,
      "external_calendar": false
    }
  }
}

4. speaker_state

화자 미확인은 Cloud LLM 전체 실패 사유가 아니다. 기본 동작은 개인화만 끄고 현재 발화를 정상 처리하는 것이다.

5. Cloud 적용 순서

normalize voice_context
  -> validate speaker_context-v2
  -> identified인 경우 Voice ID lookup
  -> build person_context
  -> consent / authority policy
  -> router, memory, RAG, TaskManager

6. Session과 workflow

Cloud가 멀티턴 owner를 유지할 때 OnDevice Voice ID와 Cloud Person ID를 구분한다.

{
  "session_state": {
    "last_voice_id": "vp_opaque_uuid",
    "workflow_owner_person_id": "person_001",
    "speaker_policy": {
      "personalization_applied": true,
      "confirmation_required": false
    }
  }
}

• last_voice_id: 직전 발화에서 기기가 관측한 로컬 identity
• workflow_owner_person_id: Cloud가 lookup으로 확인한 사용자
• 후속 발화가 unknown이면 이전 사람으로 자동 간주하지 않는다.
• 민감 동작의 권한은 Voice ID 존재만으로 부여하지 않는다.

7. 호환성과 검증

• speaker_context가 없으면 기존 익명 경로로 동작한다.
• speaker-context-v1은 migration 기간에만 읽고 서버에서 v2로 정규화한다.
• 모르는 필드는 무시하되 잘못된 enum과 범위는 unknown으로 낮춘다.
• confidence는 0.0..1.0, ratio는 0.0..1.0, speaker count는 음수가 될 수 없다.
• log에는 Voice ID 전체값 대신 trace용 hash 또는 마스킹 값을 사용한다.
• Reference Embedding은 sync endpoint에서만 암호화 저장하고, runtime Query Embedding은 저장하지 않는다.
• E2E 테스트는 identified, unknown, mapping miss, revoked, timeout을 모두 포함한다.

등록 계약과 저장 수명은 보이스 프로필 등록 제품 구현 기준서를 따른다.