Files
javis_bot/docs/v2/architecture.md
javis-bot 4f90701112 docs(v2): record answers on channel sync, memory scope, popout and legacy branch
- Chat channel name/description edits also rename the real Discord
  channel and topic by default (toggle kept)
- Memory: separate toggles for registered chat channels and other
  speakers in the same voice channel, both on by default
- Screen-share popout is requested by voice, never automated
- v1 head bb60c4d preserved as the remote legacy branch

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-09 13:25:28 +09:00

6.3 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 / 권장: Qwen3.8-Flash-Next (앱에서 선택)
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.5~2.5GB (동시 처리 배치 포함)
TTS: MeloTTS 한국어 약 1GB
LLM 활성 부분 (Strata가 자동 배치) 나머지 11~13GB
RAM 128GB LLM 전체 가중치(전문가 층), 브라우저, 앱 빠름 모델 약 3252GB / 권장 모델 약 4460GB
CPU 32스레드 화자별 VAD(Silero), Opus 디코딩, 리샘플, 크로미움 10명 동시여도 여유 있음
디스크 모델, Python 런타임, 캐시 최소 120GB, 권장 200GB 이상 (NVMe 권장)

게임을 켜면 VRAM을 두고 다투므로 게임 모드를 둡니다. 게임 모드는 pc-features.md에 정리했습니다.

구성 요소

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

1. Jarvis 관리 앱 (exe, Electron + TypeScript)
   ├─ GUI: 대시보드 / 봇 / 채널·호출 / 채팅 채널 / 대화 기억 / 모델 / 기능
   │        / 게임 모드 / PC 제어 / 화면 보기 / 데이터 / 로그
   ├─ 서비스 관리자: 아래 프로세스를 띄우고, 감시하고, 죽으면 재시작
   ├─ 디스코드 음성 코어 (discord.js + @discordjs/voice + DAVE 복호화)
   │     화자별 Opus 수신 → PCM → 음성 워커로 전달 / TTS 음성 재생
   ├─ 채팅 채널 연결 (등록한 채널 읽기·보내기·수정·검색)
   ├─ 브라우저 에이전트 (Playwright + 봇용 크롬창, 백그라운드 가능)
   ├─ 게임·안티치트 감지 (게임 모드 전환, 자동 입력 차단)
   └─ PC 제어 모듈 (전체·모니터별·창별 화면 캡처, 키보드/마우스 입력)
          │
          │  로컬 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

기술 선택과 이유

부분 선택 이유
GUI 앱 Electron + TypeScript (React UI) 디스코드 음성 코어(discord.js), Playwright, 화면 캡처가 모두 Node 생태계라 한 언어로 묶입니다. v1 봇 코드(TypeScript)를 옮길 수 있습니다. Tauri는 가볍지만 Rust와 Node 사이드카를 따로 둬야 해서 복잡해집니다.
음성 워커 Python (faster-whisper, MeloTTS, 기존 jarvis) STT·TTS 모델과 기존 두뇌 코드(메모리, 도구, 스펙 문서)가 Python입니다. 다시 짜는 것보다 재사용이 안전합니다.
LLM 엔진 Strata (MIT) Windows 설치 지원, RTX 50 지원, --data-dir로 저장 위치 지정, 헤드리스 실행(--no-tui). 앱에 포함해 배포해도 라이선스 문제가 없습니다.
LLM 예비 엔진 OpenAI 호환 주소 직접 입력 Strata에 문제가 생기면 llama.cpp, Ollama 같은 다른 로컬 엔진으로 바꿔 끼웁니다.
Python 런타임 uv + 독립 실행형 Python 3.12 사용자가 Python을 따로 깔 필요가 없고 시스템 Python과 섞이지 않습니다. 전부 데이터 폴더 안에 설치됩니다.
설치 파일 NSIS (electron-builder) 설치 파일은 약 200MB 내외로 두고, 모델과 런타임은 첫 실행 때 받습니다.