Open-LLM-VTuber 딥다이브
— 음성으로 대화하고 표정 짓는, 완전 오프라인 AI 컴패니언

1프로젝트 한줄 요약

Open-LLM-VTuber는 음성으로 대화하는 AI 컴패니언입니다. 마이크에 말을 걸면, ① 그 음성을 텍스트로 받아쓰고(ASR), ② AI 두뇌(LLM)가 답을 생각하고, ③ 그 답을 다시 목소리로 합성하고(TTS), ④ 화면 속 Live2D 캐릭터가 그 목소리에 맞춰 입을 움직이고 표정까지 짓습니다. 이 모든 걸 로컬 모델만으로 인터넷 없이 돌릴 수 있다는 게 핵심입니다.

웹 브라우저로 쓰는 버전과, Electron 데스크톱 앱(투명 배경으로 화면 한구석에 캐릭터를 띄우는 '펫 모드')을 모두 제공하고, Windows·macOS·Linux를 전부 지원합니다. 처음 목표는 폐쇄형 상용 AI VTuber인 neuro-sama를 "오프라인 오픈소스로 재현하기"였고, 그래서 이름이 'Companion'이나 'Waifu'가 아니라 Open-LLM-VTuber입니다.

2왜 주목받는가

음성 챗봇은 많지만, 대부분 클라우드에 의존하거나(대화가 회사 서버로 전송됨), 특정 모델에 묶여 있습니다. Open-LLM-VTuber는 "완전 오프라인 + 부품을 마음대로 교체 + 살아 있는 캐릭터" 세 가지를 동시에 만족시켜 약 9,000개의 별을 모았습니다.

3기술 스택 전체 지도

이 프로젝트는 두 개의 저장소로 되어 있습니다. 두뇌·귀·입이 도는 백엔드(Python)가 본체이고, 화면과 캐릭터를 그리는 프론트엔드는 별도 레포(Open-LLM-VTuber-Web)를 Git 서브모듈로 끌어옵니다(그래서 클론할 때 --recursive가 필요합니다).

① 백엔드 — Python (코드의 약 97%)

② 프론트엔드 — Open-LLM-VTuber-Web (Electron · React)

③ 교체 가능한 '부품' 백엔드들 — 이 프로젝트의 자랑

conf.yaml 한 줄로 갈아끼우는 부품 카탈로그입니다. 종류가 워낙 많아 대표만 추립니다.

4아키텍처 심화 분석

먼저 전체 그림입니다. 사용자의 목소리가 왼쪽에서 들어와 여러 부품을 거쳐 오른쪽 캐릭터의 입과 표정으로 나옵니다. 브라우저(프론트)와 파이썬 서버(백)가 WebSocket이라는 한 통로로 연결돼 있습니다.

핵심 설계 패턴 1 — 클라이언트별 'ServiceContext'

여러 사람이 동시에 접속해도 서로 섞이지 않도록, 접속할 때마다 기본 설정을 통째로 복제(deep-copy)해 그 세션만의 ASR/TTS/VAD/Agent 인스턴스 묶음을 만듭니다. 이걸 ServiceContext라 부르고, client_uid(접속 고유 번호)로 연결·오디오 버퍼·진행 중 대화를 딕셔너리로 관리합니다. "손님마다 전용 테이블 세트를 새로 깔아 주는" 식이죠.

핵심 설계 패턴 2 — 메시지 타입으로 분기하는 라우팅

WebSocket으로 오는 모든 메시지는 type 필드를 보고 갈래를 정합니다(_message_handlers 매핑). 주요 타입은 mic-audio-data/mic-audio-end(음성), text-input(타이핑), interrupt-signal(끼어들기), ai-speak-signal(AI가 먼저 말 걸기), fetch/switch-config(설정 핫스왑) 등입니다. 설정을 껐다 켜지 않고 바꾸는 '핫스왑'이 이 라우팅 덕에 가능합니다.

핵심 설계 패턴 3 — 음성 끼어들기의 실제 구현

VAD가 사용자의 말소리를 감지하면, 백엔드가 {"type":"control","text":"interrupt"}를 보내 진행 중인 대화 task를 즉시 cancel() 합니다. 이때 영리한 디테일이 있습니다 — AI가 "들은 데까지"의 응답(heard_response)만 기억에 남깁니다. 그래야 다음 대화에서 "아까 하다 만 말"이 자연스럽게 이어지죠.

# 흐름 요약 (개념): 끼어들면 진행 task를 취소하고, 들은 만큼만 기억
on "interrupt-signal":
    current_task.cancel()                  # 말하던 거 멈춤
    memory.append(heard_response_so_far)    # 들린 데까지만 저장
    start_new_conversation(new_input)       # 새 입력 처리 시작

핵심 설계 패턴 4 — 감정→표정 매핑

LLM 시스템 프롬프트에 "기쁘면 [joy], 화나면 [anger]처럼 감정 키워드를 붙여 말하라"고 지시합니다. 그러면 TTS 단계에서 그 키워드를 뽑아, model_dict.json의 emotionMap(예: joy→3, anger→2)으로 Live2D 모션 인덱스를 골라 표정을 바꿉니다. "텍스트 속 감정 태그 → 숫자 → 캐릭터 표정"으로 이어지는 깔끔한 변환입니다.

핵심 설계 패턴 5 — 인터페이스 + 팩토리로 부품 갈아끼우기

ASR·TTS·LLM·Agent 모두 *_interface.py(공통 약속) + *_factory.py(설정 보고 알맞은 구현을 만들어 주는 공장) 패턴을 씁니다. 그래서 새 백엔드를 추가하려면 인터페이스만 구현하면 끝이고, 사용자는 conf.yaml에서 이름만 바꾸면 됩니다. 3장에서 말한 "부품 자유 교체"가 코드 레벨에서 어떻게 가능한지의 답이 바로 이 패턴입니다.

5디렉토리 구조 해부

최상위에는 실행·설정 파일이, 진짜 로직은 src/open_llm_vtuber/ 패키지에 들어 있습니다. 프론트엔드는 frontend/가 서브모듈로 링크돼 있어, 그 폴더는 별도 레포의 내용입니다.

6학습 포인트 (기술별)

① WebSocket 실시간 양방향 통신

오디오 청크·제어 신호·자막이 끊김 없이 양방향으로 흐릅니다. websocket_handler.py는 접속 고유 번호로 다중 클라이언트를 관리하고, 메시지 type으로 분기하는 실전 패턴의 좋은 교본입니다. 실시간 협업·채팅·스트리밍 앱을 만들 때 그대로 응용됩니다.

② 음성 AI 파이프라인(VAD→ASR→LLM→TTS)

음성 인터페이스의 4대 부품이 어떻게 맞물리는지를 실제로 도는 코드로 볼 수 있습니다. 특히 "첫 콤마에서 바로 발화 시작"(faster_first_response)처럼 체감 지연을 줄이는 트릭은, 어떤 실시간 음성 서비스에도 통하는 노하우입니다.

③ 인터페이스 + 팩토리(플러그형 설계)

"기능을 코드가 아니라 설정으로 고른다"는 확장 가능한 설계의 정석입니다. asr/asr_interface.py → asr_factory.py → 구체 구현 순으로 읽으면, 새 기능을 추가해도 기존 코드를 안 건드리는 구조(개방-폐쇄 원칙)가 손에 잡힙니다.

④ 로컬 AI 모델 운용(ONNX·Ollama·GPU)

onnxruntime으로 가벼운 모델을 CPU/GPU에서 돌리고, Ollama로 로컬 LLM을 띄우고, VRAM에 맞춰 모델 크기를 고르는 실전 로컬 AI 운용 감각을 기를 수 있습니다. 클라우드 비용 없이 AI를 다뤄 보는 가장 좋은 놀이터 중 하나입니다.

⑤ 데스크톱 앱(Electron) + 펫 모드

투명 배경·항상 위·클릭 통과(click-through)로 캐릭터를 화면에 띄우는 '펫 모드'는, Electron의 창 제어를 깊이 다루는 흥미로운 예제입니다. 웹 기술로 네이티브 데스크톱 경험을 만드는 법을 배울 수 있습니다.

7하드웨어/시스템 요구사항

핵심은 두 갈래입니다. 모든 부품을 클라우드 API로 돌리면 라즈베리파이로도 가능하고, 로컬 모델로 돌리면 GPU 성능이 지연을 결정합니다. 공통으로 FFmpeg는 반드시 설치해야 합니다(없으면 오디오 에러).

# 1) 서브모듈까지 함께 클론
git clone https://github.com/Open-LLM-VTuber/Open-LLM-VTuber --recursive
cd Open-LLM-VTuber
# 2) 가상환경 + 의존성 (uv 권장 / pip도 가능)
uv sync
# 3) 1회 실행해 conf.yaml 생성 → Ctrl+C → 템플릿 복사해 편집
uv run run_server.py
# 4) 다시 기동 → 브라우저 http://localhost:12393
uv run run_server.py
# 기본 스택 = Ollama(LLM) + sherpa-onnx(ASR) + edge_tts(TTS)

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크

• 메인 저장소: github.com/Open-LLM-VTuber/Open-LLM-VTuber · 프론트엔드: Open-LLM-VTuber-Web
• 공식 문서: 영문 Quick Start · 프로젝트 소개 · 설정: conf.default.yaml
• 핵심 기술: Live2D · Ollama · sherpa-onnx · Silero VAD · Electron
• 배경 지식: WebSocket API (MDN) · MCP · Letta(MemGPT)