React와 Vite로 만든 IRI의 프로젝트 소개 페이지와 음성 대화 앱이다. 별도 iri-orb 저장소에 있던 시각 시제품을 이 디렉터리로 옮기고 IRI의 익명 세션과 음성 대화 API에 연결했다. 실행과 빌드는 이 저장소만 사용한다.
| 경로 | 화면 |
|---|---|
/ |
논문형 프로젝트 소개와 대화 미리보기, 학습 기록 및 대화 처리 구조 |
/chat |
마이크와 텍스트 입력, 답변 재생 및 대화 기록을 제공하는 Orb 화면 |
루트 /는 아동용 한국어 음성 대화 AI를 소개하는 흰 배경의 논문형 레이아웃이다. Times 계열 세리프와 가운데 제목, 2단 설명 및 집약형 표를 유지하되 내용은 제품과 QLoRA 학습 및 대화 하네스를 설명한다. 헤더에는 GitHub와 Hugging Face 및 대화 시작을 표시한다. 상단의 ‘데모 보기’는 실제 /chat 화면을 캡처한 작은 브라우저 창이며 클릭하면 대화 화면을 새 탭에서 연다. 헤더의 대화 시작도 새 탭에서 열린다. Hugging Face와 GitHub 링크는 각각 학습 설명과 하네스 설명 위에 공식 로고와 함께 표시한다. 그림 보기 선택은 각 그림 오른쪽 위에 두고 평가 기록 링크는 학습 기록 표 제목 옆에 배치한다.
다섯 Three.js 인포그래픽은 입력 경로와 QLoRA 학습을 설명하고 검사 분기와 연령 설정 및 최근 6턴 문맥을 보여준다. 선택 메뉴로 설명 상태를 전환한다. 연결선은 도형 테두리 좌표에 맞추며 일정한 굵기와 둥근 직각 모서리 및 평면 화살촉을 사용한다. 모바일에서는 그림 확대와 내부 가로 스크롤을 지원한다. 행렬 크기와 입자는 개념 설명용이며 실제 모델의 실행 계측값이 아니다. 생성 이미지와 외부 모델 에셋은 사용하지 않는다. 화면 밖이나 숨겨진 탭에서는 렌더링을 멈춘다. 움직임 중지와 운영체제의 움직임 줄이기 설정을 지원하며 WebGL을 사용할 수 없으면 같은 내용을 텍스트로 표시한다. 실제 음성 및 텍스트 대화 화면은 /chat에서 연다.
저장소 루트에서 웹 의존성을 설치하고 검증한 뒤 개발 서버를 시작한다.
cd web
npm ci
npm test
npm run build
npm run dev개발 서버는 127.0.0.1:5173에서 실행되며 /api 요청을 로컬 FastAPI 서버의 8000번 포트로 전달한다. 프로덕션에서는 vercel.json의 HTTPS API 경로를 사용한다. 브라우저에 API 키를 전달하지 않는다.
사용자는 로그인이나 참여 코드 없이 구를 누르거나 글로 질문한다. 구 위의 안내에 따라 누르면 별도 확인창 없이 브라우저에 마이크 권한을 요청하고 녹음을 시작한다. 다시 누르면 녹음을 마치며 권한 요청 중에 누르면 연결을 취소한다. 음성 입력은 최대 60초 동안 받으며 STT가 만든 문장을 사용자가 화면에서 확인한 뒤 답변을 요청한다. 하단에는 모양 변경과 답변 재생 및 글 입력 버튼을 둔다.
페이지를 열 때에는 새 토큰을 발급하지 않는다. 첫 상태 변경 요청에서 대화 분리와 요청 제한에 필요한 익명 HttpOnly 쿠키만 자동으로 만든다. 검사된 답변만 TTS로 전달한다. 최근 6턴은 서버의 세션 메모리에 남고 새 이야기 또는 연령 변경으로 삭제된다.
그림의 보기 선택은 사이트 스타일에 맞춘 목록으로 제공한다. 방향키와 Home 및 End로 이동하고 Enter로 선택한다. Escape와 바깥 클릭으로 닫을 수 있으며 Tab으로 다음 컨트롤로 이동한다. 파란 기본 테두리 대신 차분한 포커스 표시를 사용한다. 대화 설정의 연령 제목과 중복 안내 문구는 줄였으며 응답 전 모델 연결 확인 문구는 표시하지 않는다.
대화 기록에서는 각 답변 옆의 듣기 버튼으로 이전 답변을 재생한다. 음성을 준비하거나 재생하는 동안 같은 버튼으로 중지할 수 있으며 기록 창을 닫아도 재생을 멈춘다. 완료 검증을 통과한 음성이 있으면 다시 듣기에 재사용한다.
음성 스트림은 검증된 PCM 조각과 완료 메타데이터를 SSE로 받는다. 브라우저는 최종 audio.done의 바이트 수와 SHA-256이 실제 수신 데이터와 일치할 때만 다시 듣기 캐시에 저장한다. EOF, 시간 초과, audio.error, 무결성 불일치가 발생한 부분 음성은 재사용하지 않는다. 비스트리밍 대체 경로는 같은 서버 검증을 통과한 WAV를 사용한다.
중앙 Orb는 현재 상태를 표시한다. 듣는 동안에는 실제 마이크 RMS, 말하는 동안에는 실제 재생 오디오 파형에 반응한다. 답변을 생각하거나 합성할 때에는 잔잔한 대기 움직임을 사용한다. WebGL 또는 WebGPU를 쓸 수 없는 환경에는 정적 Orb와 CSS 버튼 표면을 제공한다. 운영체제의 움직임 줄이기 설정도 따른다.
npm test는 음성 신호 보정과 애니메이션 완화 수식, 응답 제공자 표시를 확인한다. 또한 네트워크 경계에서 나뉜 SSE 데이터의 재조립과 완료 여부 및 무결성을 검사한다. npm run build는 TypeScript와 프로덕션 번들을 검증한다. STT부터 TTS까지의 서버 계약은 저장소 루트에서 실행하는 Python API 테스트로 확인하며, 실제 기기의 마이크와 스피커 동작은 별도로 검증해야 한다.
시각 구현의 출처와 라이선스는 ATTRIBUTIONS.md와 licenses/에 보관한다.