Files
javis_bot/docs/v2/architecture.md
javis-bot e23a962923 feat(app): side menu in groups that open, settings split into tidy screens
The side menu keeps 대시보드 and 대화 on top and puts the rest in groups that
open when their name is pressed (디스코드, 대화 방식, 음성·모델, 기능, PC, 관리);
the shown screen's group opens and open groups are kept. 채널·호출 is split
into 음성 채널, 호출 and 여럿이 말할 때, and 모델 into 받아 적기·말하기 and 대화
모델; the chat wake words join 호출, the recording switch 음성 채널 and the
default location 기능 켜기·MCP.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 14:01:16 +09:00

7.4 KiB

v2 전체 구조

목표

지금 서버와 Windows Docker에 나뉘어 돌던 자비스봇을 게임PC 한 대에서 완전 로컬로 돌립니다. 설치 파일 하나로 깔리는 Windows 관리 앱에서 모든 것을 설정·관리합니다. 기존 기능(음성 대화, 메모리, 날씨, 웹 검색, 식단 기록, MCP, 브라우저 제어)은 그대로 유지합니다.

v1과 비교

항목 v1 (지금) v2
LLM 엔진 Ollama, 기본 qwen2.5:3b Strata (RAM+VRAM 하이브리드, OpenAI 호환 API). MoE 모델로 교체
LLM 모델 3B급 소형 모델 Qwen3.6-35B-A3B 하나. 게임 중이나 PC가 바쁠 때는 같은 모델의 배치를 자동으로 바꿈
STT faster-whisper(small/medium), 말이 끝나고 0.8초 침묵 후 통째 전사, beam 5 faster-whisper large-v3-turbo 상주, 말하는 중 부분 전사, 발화 종료 즉시 확정
TTS MeloTTS (GPU) MeloTTS 유지(한국어 검증됨), 문장 단위 스트리밍. CosyVoice2 선택지 추가
실행 위치 Windows Docker(약 25GB 이미지) + 서버(브라우저) 게임PC 단독, Docker 없음
관리 방법 .env 파일 직접 수정 Windows exe 앱(GUI)
동시 대화 사실상 1명씩 처리 최대 10명 동시 수신·전사. 응답 정책은 GUI에서 선택, 기본은 "처음 대화만"
채팅 채널 슬래시 명령만. 채팅은 읽지 못함 등록한 채팅 채널을 AI가 읽고, 보내고, 수정
대화 기억 최근 5분 원문 + 과거 기록에서 관련 내용 3개 본인이 말했던 기록 전체, 등록한 채팅 채널, 같은 음성 채널에 함께 있던 다른 사람 말에서 관련 내용을 찾아 참고
화면 보기 없음 전체 화면, 모니터별, 창별 화면을 봇이 직접 봄
설치 Docker, CUDA, 환경변수 수동 구성 설치 파일 하나. 첫 실행 때 고른 폴더에 전부 저장

v1 기준 값: bot/src/config.ts의 VOICE_SILENCE_MS=800, bridge/server.py의 STT_BEAM_SIZE=5, src/jarvis/config.py의 dialogue_memory_timeout=300, memory_enrichment_max_results=3.

v1도 STT는 이미 faster-whisper입니다. 느린 진짜 이유는 엔진이 아니라 다음 세 가지입니다.

  1. 말이 끝난 뒤 0.8초를 기다립니다.
  2. 끝난 다음에야 통째로 전사합니다.
  3. beam 5로 정확도 위주 설정입니다.

그래서 v2의 STT 개선은 엔진 교체보다 스트리밍 전사와 종료 판정 방식 변경이 핵심입니다.

하드웨어 기준과 자원 배분

기준 게임PC: RTX 5070 Ti 16GB (Blackwell, sm_120), DDR5 128GB, Ryzen 9 9950X3D (16코어/32스레드)

자원 용도 예상 사용량
VRAM 16GB STT: faster-whisper large-v3-turbo (int8_float16) 모델 1.3GB, 10명 동시 전사 때 최대 약 2.7GB (M0 실측)
TTS: MeloTTS 한국어 약 1GB
LLM 활성 부분 (Strata가 자동 배치) 나머지 11~13GB
RAM 128GB LLM 전체 가중치(전문가 층), 브라우저, 앱 약 32~52GB (게임 중에는 전문가 층을 더 많이 RAM에 둠)
CPU 32스레드 화자별 VAD(Silero), Opus 디코딩, 리샘플, 크로미움 10명 동시여도 여유 있음
디스크 모델, Python 런타임, 캐시 최소 120GB, 권장 200GB 이상 (NVMe 권장)

게임을 켜면 VRAM을 두고 다투므로 앱이 게임을 감지해 LLM 배치를 자동으로 바꿉니다. pc-features.md에 정리했습니다.

구성 요소

[게임PC (Windows 11) 한 대에서 전부 실행]

1. Jarvis 관리 앱 (exe, Rust. 화면은 Tauri 2 + Windows 기본 WebView2)
   ├─ GUI: 대시보드 / 대화 / 디스코드 / 대화 방식 / 음성·모델 / 기능 / PC / 관리
   │        / 게임 모드 / PC 제어 / 화면 보기 / 데이터 / 로그
   ├─ 서비스 관리자: 아래 프로세스를 띄우고, 감시하고, 죽으면 재시작
   ├─ 디스코드 음성 코어 (serenity + songbird + DAVE 복호화, Opus 해독은 앱이 직접)
   │     화자별 Opus 수신 → PCM → 음성 워커로 전달 / TTS 음성 재생
   ├─ 채팅 채널 연결 (등록한 채널 읽기·보내기·수정·검색)
   ├─ 브라우저 에이전트 (크롬 개발자 프로토콜(CDP) + 봇용 크롬창, 백그라운드 가능)
   ├─ 게임·안티치트 감지 (게임 모드 전환, 자동 입력 차단)
   └─ PC 제어 모듈 (전체·모니터별·창별 화면 캡처, agent-desktop으로 프로그램 조작,
                    접근성 정보가 없는 화면만 키보드/마우스 입력)
          │
          │  로컬 WebSocket (127.0.0.1, 앱이 발급한 토큰으로만 접속)
          ▼
2. 음성·두뇌 워커 (Python, 데이터 폴더 안 가상환경)
   ├─ STT: 화자별 VAD → 공용 faster-whisper(GPU, 배치) → 부분/최종 전사
   ├─ 두뇌: 기존 jarvis 코드 재사용 (메모리, 날씨, 웹 검색, 식단, MCP, 플래너)
   ├─ 대화 기록 저장소: 음성 전사와 채팅 채널 메시지 저장·검색 (SQLite)
   └─ TTS: MeloTTS / CosyVoice2, 문장 단위 스트리밍
          │
          │  OpenAI 호환 HTTP (127.0.0.1:8080)
          ▼
3. Strata LLM 서버
      strata launch --yes --no-tui --data-dir <데이터 폴더>\models\llm

기술 선택과 이유

부분 선택 이유
관리 앱 Rust (화면은 Tauri 2) 처음에는 Electron + TypeScript로 정했지만 더 빠르고 가벼운 진짜 앱으로 바꿈(사용자 결정, 2026-11-11). 디스코드 음성(serenity, songbird, DAVE), 브라우저 조종(CDP), 화면 캡처(Windows Graphics Capture)를 모두 Rust로 할 수 있어 Node 사이드카가 필요 없습니다. 화면은 Tauri 2가 Windows에 이미 있는 WebView2로 그리므로 크로미움을 따로 싣지 않습니다. 같은 음성 코어를 이 서버에서 띄웠을 때 실행 파일 하나, 메모리 약 16MB였습니다(Electron은 프로세스 5개). songbird 0.6.1은 DAVE로 받은 소리를 해독할 때 조각 3분의 1가량을 깨뜨려서, 암호 풀기만 맡기고 순서 맞추기와 Opus 해독은 앱이 직접 합니다 (discord_core.spec.md).
음성 워커 Python (faster-whisper, MeloTTS, 기존 jarvis) STT·TTS 모델과 기존 두뇌 코드(메모리, 도구, 스펙 문서)가 Python입니다. 다시 짜는 것보다 재사용이 안전합니다.
LLM 엔진 Strata (MIT) Windows 설치 지원, RTX 50 지원, --data-dir로 저장 위치 지정, 헤드리스 실행(--no-tui). 앱에 포함해 배포해도 라이선스 문제가 없습니다.
PC 프로그램 조작 agent-desktop (Apache-2.0) Windows UI Automation으로 버튼·입력칸을 읽고 직접 누릅니다. 좌표 클릭보다 정확하고, 커서와 포커스를 뺏지 않습니다. 실행 파일 하나라 설치 파일에 넣기 쉽습니다. (pc-features.md)
LLM 예비 엔진 OpenAI 호환 주소 Strata에 문제가 생기면 같은 모델(GGUF)을 llama.cpp 같은 다른 로컬 엔진으로 돌려 연결합니다. 모델은 바꾸지 않습니다.
Python 런타임 uv + 독립 실행형 Python 3.12 사용자가 Python을 따로 깔 필요가 없고 시스템 Python과 섞이지 않습니다. 전부 데이터 폴더 안에 설치됩니다.
설치 파일 NSIS (Tauri 번들러) 설치 파일은 약 200MB 내외로 두고, 모델과 런타임은 첫 실행 때 받습니다.