rayenfeng/riko_project

해결하는 문제

많은 AI 컴패니언은 정적이거나 클라우드 서비스에 의존하며, 커스터마이징이 어렵습니다. Riko는 성격, 음성, 외형을 단일 설정 파일에서 제어할 수 있는 간결한 오픈 소스 기반(500줄 미만)을 제공합니다. 표준 채팅 스크립트를 물리적인 존재로 변환하여, 사용자가 말하면 그녀가 대답하고 3D 아바타가 입 모양을 동기화하며 움직입니다. 이 모든 과정이 사용자의 PC에서 이루어집니다.

작동 방식

핵심 루프는 다음과 같습니다: Enter를 눌러 녹음을 시작하고, 말한 뒤, 다시 Enter를 눌러 중지합니다. 음성은 로컬의 Faster-Whisper 또는 온라인의 Groq Whisper를 사용하여 텍스트로 변환됩니다. 이 텍스트는 OpenAI GPT(기본값 gpt-4.1-mini 등 원하는 모델)로 전달되어 답변을 생성합니다. 답변은 GPT-SoVITS(로컬 음성 복제) 또는 Fish Audio(클라우드 음성)를 사용하여 음성 클립으로 변환됩니다. 마지막으로, 브라우저에 표시된 VRM 아바타가 three.js와 three-vrm을 사용하여 클립을 재생하고 입 모양을 동기화합니다. 각 단계는 별도의 파일(asr.py, llm.py, tts.py, viewer.py)로 구성되어 있으며, main.py가 이 시퀀스를 루프로 실행합니다. 대화 기록은 chat_history.json에 저장되어 기억을 유지합니다.

대상 사용자

이 오픈 소스 스냅샷은 자신만의 AI 컴패니언을 커스터마이징하기 위해 깔끔하고 읽기 쉬운 기반을 원하는 개발자와 애호가를 대상으로 합니다. 터미널(uv 및 Python) 사용에 익숙해야 하며, OpenAI(선택적으로 Fish Audio 또는 Groq) API 키가 필요합니다. Windows 10/11 또는 Python 3.11+가 설치된 Linux에서 실행됩니다. 노코드 경험이나 최신 기능을 원하신다면 README에 안내된 유료 옵션(Patreon의 전체 소스 또는 데스크톱 앱)을 확인하세요.

주요 특징

• 푸시 투 토크 음성 입력: Enter를 누르고 말한 뒤 다시 Enter를 누름.
• 로컬 Faster-Whisper 또는 클라우드 Groq를 통한 음성 인식.
• OpenAI GPT를 통한 답변(원하는 모델 선택 가능).
• GPT-SoVITS(로컬 음성 복제) 또는 Fish Audio(클라우드)를 통한 음성 생성.
• 브라우저 내 VRM 아바타의 입 모양 동기화; 드래그로 회전, 우클릭 드래그로 이동, 스크롤로 확대/축소.
• 성격, 아바타, 음성 설정이 단일 YAML 파일(character_config.yaml)에 포함.
• 누락된 키, 서버, 파일을 보고하는 설정 검사기.
• 총 코드베이스 500줄 미만, MIT 라이선스.
• 대화 기록을 사용자가 제어 가능한 파일로 저장.