실행 흐름 · ELI5 · 2026-10-01

HC는 소리를 바로 보내고,
VP는 글로 바꿔서 보냅니다.

마지막 업데이트 2026-10-01

답변을 생각하는 곳에 도착하기 전이 다릅니다. 마지막에 Typecast가 목소리로 읽어주는 과정은 같습니다.

코드 기준: develop · 0f94a87a · 일반 수업 경로 · 운영 배포 상태와 응답 속도는 별도 확인 필요

HC

Half-Cascade · 두 역할을 묶음

아동이 말합니다

LiveKit으로 음성 전달 ↓

OpenAI Realtime음성을 직접 받아 이해하고 답변 생성
별도 STT → 텍스트 LLM 단계를 두지 않음

답변 텍스트 ↓

Typecast → 아동 스피커글을 목소리로 읽고, LiveKit으로 돌려줌

VP

Voice Pipeline · 역할을 나눔

아동이 말합니다

LiveKit으로 음성 전달 ↓

STT소리 → 아동의 글

글
→

별도 LLM글 → 답변 생성

답변 텍스트 ↓

Typecast → 아동 스피커글을 목소리로 읽고, LiveKit으로 돌려줌

HC도 전사문을 생성하지만, 그 전사문을 별도 텍스트 LLM에 전달하는 VP 구조와는 다릅니다. 화살표는 데이터 의존 관계이며, 전체 문장이 완성될 때까지 모든 단계가 기다린다는 뜻은 아닙니다.

01 · 시작할 때는 같은 길을 갑니다

1모드·목소리 확인

아동 설정과 아바타 목소리로 실제 실행 경로 결정

2접속 정보 만들기

Web API가 설정을 저장하고 LiveKit 입장 토큰 발급

3Agent 준비

저장된 설정을 읽어 HC 또는 VP 세션 구성

4준비 확인 후 시작

브라우저가 Agent 준비를 기다린 뒤 시작 메시지 전송

LiveKit은 음성과 제어 메시지를 나르는 연결 계층입니다. HC·VP는 그 뒤에서 Agent가 구성하는 AI 처리 방식입니다.

실제 설정값과 예외

conversationMode=livekit → runtime=livekit + pipeline_mode=half_cascade. livekit_vp → 같은 runtime + voice_pipeline. 모드 기본값은 HC입니다.
아바타의 유효한 Typecast 목소리가 없고 Realtime 목소리가 있으면 실제 runtime은 realtime으로 바뀝니다. 이유는 avatar_livekit_tts_voice_missing입니다. 둘 다 없을 때 성공을 보장하는 폴백은 아닙니다.
/api/livekit/call은 modelConfig 스냅샷을 Redis에 저장하고 참조와 토큰을 만듭니다. 저장 실패 시 500을 반환합니다. Agent와 Web은 같은 설정 저장소를 읽어야 합니다.
브라우저는 waitUntilAgentReady()를 기다리고 확인된 pipeline_mode를 기록합니다. Room 연결 성공만으로 Agent 준비 완료를 판단하지 않습니다.
운영에서는 요청 모드, 실제 runtime, 준비 완료 모드, fallback 사유를 함께 확인합니다. 진단용 voiceProfile override는 이 그림의 범위 밖입니다.

02 · “말을 다 했나?”를 판단합니다

HC · 판단 경로를 선택

LiveKit VAD를 쓰거나, OpenAI Realtime의 턴 감지를 사용할 수 있습니다.

음성 입력→발화 끝 판단→응답 요청

VP · LiveKit 쪽에서 조정

LiveKit VAD와 STT를 연결해 발화·전사를 처리하고 별도 LLM 응답으로 이어갑니다.

음성·STT→턴 확정→LLM 응답

VAD는 “지금 말소리가 있나?”를 감지합니다. “답해도 되는 시점”은 턴 감지·대기 시간·전사 상태 같은 정책까지 함께 결정합니다.

현재 기본값과 지원 기능을 구분하기

구분	HC	VP
일반 수업의 턴 엔진 기본값	LiveKit VAD	LiveKit VAD 사용
OpenAI 턴 감지	server_vad / semantic_vad 선택 가능	텍스트 LLM 경로에 적용하지 않음
EOU 문맥 분류기	별도 live STT가 없어 비활성화	Agent는 지원하지만 Web 설정은 현재 none
선제 응답 생성	RealtimeModel 경로에서 전달하지 않음	설정 시 사용 가능한 경로. 모드 선택만으로 ON 아님
끼어들기	일반 Web 설정 기본값 false. 실제 동작은 사용자 설정과 런타임 제어에 따라 달라짐

HC에서 OpenAI 턴 감지와 끼어들기 OFF가 함께 들어오면 LiveKit VAD로 방어적 전환합니다. HC/VP의 VAD 모델 선택은 각각의 설정을 사용하며 기본 모델은 Silero입니다.

03 · 답변을 듣고, 수업을 이어갑니다

1답변 텍스트

HC: Realtime
VP: 별도 LLM

2Typecast 음성

아바타 목소리로 합성

3LiveKit 재생

브라우저에서 AI 오디오 트랙 수신·재생

4다음 턴·스텝

계속 대화하거나, 수업의 전환 조건 적용

“답변 한 번 끝남”과 “수업 스텝 끝남”은 다릅니다. 스텝 이동은 별도의 자동종료 조건·진행자 요청·분기 규칙으로 결정합니다.

응답 완료·스텝 이동의 코드 경계

두 모드는 공통 HalfDuplexInputGuardAgent를 사용하되 HC는 completion_contract="vendor_exact", VP는 "local_stt"를 전달합니다. VP만 guard_llm_output을 켭니다. 동일한 음성 전송 경로를 쓰더라도 내부 완료 판정 계약은 다릅니다.

게스트의 useStepNavigation은 자동종료와 다음 스텝을 결정합니다. 비-AI 스텝 중 자동종료를 무시하고, 시간종료·활동종료·조건부 점프를 구분합니다. 이 문서는 모든 스텝마다 새 Agent가 생긴다고 가정하지 않습니다.

더 궁금하면 펼쳐 보세요

지금 VP의 STT·LLM은 무엇인가요?

현재 Web 코드에서 STT 기본 provider는 asr_server이며 기본 모델은 dubu/multi-stt-h4-soniox-daglo-qwen3.5-9b-v2입니다. 설정으로 soniox를 고르면 stt-rt-v5를 사용합니다. 그림의 STT 한 칸 안에는 여러 인식 후보와 선택 과정이 들어갈 수 있습니다.

별도 LLM은 현재 코드 상수 openai / gpt-5.6-terra, reasoning effort none입니다. 이는 조사한 코드의 설정값이며 운영 환경의 활성 모델·배포 여부를 확인한 결과가 아닙니다.

HC는 RealtimeModel(modalities=["text"])과 별도 TTS를 구성합니다. 따라서 HC 그림의 OpenAI Realtime이 아동에게 들리는 최종 목소리를 생성하는 것은 아닙니다.

어느 쪽이 더 빠른가요? 문제가 나면 어디를 보나요?

이 구조만으로 속도 우열을 확정할 수 없습니다. STT 확정 시간, 턴 대기, LLM 첫 응답, TTS 첫 오디오, 네트워크·기기 재생 시간을 같은 조건에서 측정해야 합니다.

HC에서는 Realtime 입력·응답과 TTS 경계를, VP에서는 STT 확정 → LLM 응답 → TTS 경계를 나눠 추적합니다. 두 모드 모두 Agent 준비, 마이크 송출, LiveKit 수신·브라우저 재생도 함께 확인해야 합니다.

코드 근거 · 확인 범위 · 관련 문서

2026-10-01, PPI develop / 0f94a87a의 소스를 읽어 확인했습니다. 애플리케이션 코드는 변경하지 않았으며 실시간 대화·운영 배포·성능 비교는 실행하지 않았습니다. 이 문서는 신규 실행 흐름 요약이며, 8월 장단점 분석의 현재 설정값을 대체하는 참조입니다.

apps/web/lib/voice-agent/conversation-mode.ts — 기본 모드
apps/web/lib/voice-agent/resolver.ts — 모드·runtime·fallback·VAD 선택
apps/web/lib/voice-agent/livekit-token.ts — HC/VP 모델 설정
apps/web/lib/voice-agent/vp-stt-config.ts, asr-model.ts — VP provider·모델 정규화
apps/web/app/api/livekit/call/route.ts — 설정 저장·토큰 발급
apps/web/entities/guest-session/model/use-ai-session.ts — 접속·준비 대기·시작 메시지
apps/web/lib/voice-agent/livekit-client-session.ts — 마이크 게시·오디오 수신·준비 확인
apps/livekit-agent/agent.py — _build_half_cascade_session, _build_voice_pipeline_session, 공통 Agent 구성
apps/web/entities/guest-page-session/model/use-step-navigation.ts — 자동종료·스텝 이동

8월 구조·장단점 분석 (당시 모델 설정) · Multi-STT 내부 흐름 · 게스트 입출력 경로 분석

LLM용 복사 · 핵심 맥락

PPI develop 0f94a87a, 2026-10-01 코드 조사. HC=conversationMode livekit / pipeline half_cascade, VP=livekit_vp / voice_pipeline. 둘 다 runtime livekit. HC는 음성을 OpenAI Realtime에 직접 입력하고 text modality 답변을 별도 Typecast TTS로 합성한다. VP는 STT→별도 LLM→Typecast. VP Web 기본 STT는 asr_server multi-STT v2, Soniox 선택 가능. VP LLM 코드 상수는 openai/gpt-5.6-terra. Web API의 Redis 설정 스냅샷과 LiveKit token, Agent 준비 대기·시작 메시지, 오디오 전송 경로는 공통. HC는 LiveKit VAD 또는 OpenAI 턴 감지, VP는 LiveKit VAD. 지원 기능과 활성 기본값은 구분할 것. Typecast 목소리 누락+Realtime 목소리 존재 시 runtime realtime으로 fallback 가능. 응답 완료와 수업 스텝 이동은 별개. 운영 배포 상태·속도 우열은 확인하지 않음.