모델과 외부 제공자¶

외부 제공자는 Sohri 핵심 서비스가 소유하는 안정된 계약 뒤에 배치하는 교체 가능한 통합입니다. 저장소에 어댑터나 설정 항목이 존재하는 것과 특정 배포에서 자격 증명·네트워크·기능 플래그가 활성화된 것은 다릅니다. 운영 가능 여부는 배포별로 검증해야 합니다.

카탈로그와 소유권¶

기능	호출·조정 소유자	최소 입력	최소 출력	데이터 취급
EPD + STT	Socket Backend	PCM, 세션·재생 상태	activity, `END`, STT 텍스트, confidence, 선택적 음성 참조	발화 단위 최소 메타데이터만 저장
LLM NLU	Graph Builder	현재 발화, 제한된 최근 이력·상태	intent, dialog act, entity, confidence	시나리오와 정책 입력으로만 사용
LLM NLG	Graph Builder	노드 지침, NLU, 허용된 상태·skill 결과	응답 텍스트	외부 결과를 시스템 지시로 실행하지 않음
대화 요약	Socket Backend 최종화	확정 USER/BOT 메시지	요약, 키워드, 대표 정보	전체 대화 단위 결과를 PostgreSQL에 저장
TTS	Socket Backend	응답 텍스트, 언어·voice preset	WAV 또는 형식이 명시된 PCM	합성 자격 증명과 provider 세부값은 서버 내부
Vocal Biomarkers	Socket Backend 분석 경계	확정 발화 오디오/참조	감정·인지·정서 등 구성된 지표	건강 관련 결과는 민감 데이터로 취급
Sohri Skill Runtime	Graph Builder	`skill_id`, arguments, 제한된 context	성공/result 또는 정규화된 오류	범용 실행 계약 변환과 오류 정규화
Skill Engine / 외부 API	Sohri Skill Runtime / Skill Engine	스킬별 최소 인자	JSON object 결과	스킬별 검증·제공자 연동 책임을 Engine에 격리

계약 방향¶

flowchart LR
    CORE["Sohri 핵심 서비스"]
    AD["내부 어댑터<br/>timeout · retry · validation"]
    P["교체 가능한 외부 제공자"]
    SEC["비밀 관리"]
    OBS["로그 · 메트릭 · trace"]

    CORE -->|"안정된 내부 요청"| AD
    AD -->|"제공자별 protocol"| P
    P -->|"원시 응답"| AD
    AD -->|"정규화된 성공/오류"| CORE
    SEC -. "실행 시 자격 증명" .-> AD
    AD --> OBS

핵심 서비스는 공급자 원시 응답을 직접 확산시키지 않고, 어댑터에서 timeout, 크기 제한, schema 검증과 오류 정규화를 적용해야 합니다. 공급자를 바꿀 때 핵심 세션·상태·저장 계약이 함께 바뀌지 않도록 하는 것이 목적입니다.

기능별 데이터 계약¶

EPD + STT¶

입력 오디오는 실시간 파이프라인의 PCM 형식과 프레임 순서를 보존합니다.
턴 시작의 정본은 END에 포함된 비어 있지 않은 STT 텍스트입니다.
activity ID, confidence, duration과 음성 참조는 상관관계·분석에 필요한 경우만 유지합니다.
원시 오디오 보관은 선택 기능이며, 대화 처리를 위한 필수 성공 조건이 아닙니다.

LLM NLU/NLG와 요약¶

NLU/NLG 모델 선택은 Graph Builder의 런타임 구성 책임입니다.
현재 발화와 현재 세션 이력이 우선이며, 사용자 metadata나 검색 결과는 제한된 참고 자료입니다.
외부 문자열을 system instruction으로 승격하지 않습니다.
요약 모델에는 확정 메시지만 전달하며, DB 식별자나 운영 설정처럼 작업에 불필요한 값은 제외합니다.
모델 실패는 typed 오류 또는 fallback으로 수렴하고 내부 프롬프트·자격 증명을 응답에 노출하지 않습니다.

TTS¶

외부 계약은 텍스트와 논리적 voice preset이며, provider·모델·세부 파라미터는 서버가 해석합니다.
출력은 WAV 또는 sample rate·sample format이 명시된 PCM이어야 합니다.
스트리밍 출력은 시작, 오디오 청크, 종료 이벤트의 수명주기를 지켜야 합니다.
provider 장애는 저장된 텍스트 턴을 취소하지 않는 soft-fail로 처리할 수 있습니다.

Vocal Biomarkers¶

분석 대상은 확정 USER 발화이며 취소 발화는 기본 분석·요약에서 제외합니다.
즉시 분석과 최종화 시 지연 분석을 지원할 수 있지만 결과 schema와 저장 의미는 같아야 합니다.
점수는 진단 확정이 아니라 해당 모델의 분석 결과입니다. 소비자는 모델 버전·품질 기준과 동의·보존 정책을 배포 맥락에서 별도로 관리해야 합니다.

Skill Engine과 외부 API¶

Graph Builder는 Sohri Skill Runtime에 다음 논리 계약으로 요청합니다.

{
  "skill_id": "capability-name",
  "arguments": {},
  "context": {
    "request_id": "opaque-id",
    "session_id": "opaque-session-id",
    "skill_version": "v1",
    "locale": "ko-KR",
    "timezone": "region/city"
  }
}

성공 결과의 result는 JSON object여야 합니다. 시나리오의 input_map이 전송 필드의 allowlist이고, result_map과 allowed_updates가 상태 반영 범위를 제한합니다. Sohri Skill Runtime은 요청을 공통 Engine 계약으로 변환하고 응답·오류를 정규화합니다. 자동 재시도나 캐시는 수행하지 않으며, 스킬별 자격 증명과 외부 API 연동은 Skill Engine이 소유합니다.

운영 원칙¶

공급자 이름 목록을 아키텍처 계약으로 고정하지 않습니다.
endpoint, token, key, 모델 배포명과 내부 네트워크 주소를 문서나 클라이언트 계약에 넣지 않습니다.
기능 활성화 상태, 데이터 리전, timeout, 비용 한도와 장애 fallback을 배포 단위로 점검합니다.
요청·응답 로그는 음성, 발화, 건강 지표와 자격 증명을 기본적으로 마스킹합니다.