Files
javis_bot/docs/v2/architecture.md
javis-bot d0ffa7f55e docs(v2): budget STT at its 10-speaker peak in the game VRAM estimate
The M0 stt stage measured 1300 MiB for the model and another 1440 MiB while
transcribing ten speakers at once. The game share now subtracts the 2.7 GB
peak: about 3.1 GB on the 16 GB game PC (not 4.6 GB), and the 2 GB expert
placement returns at a reserve of about 2.2 GB. Both are marked as sums of
separate LLM and STT runs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 18:44:29 +09:00

90 lines
6.8 KiB
Markdown

# 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-features.md#자동-성능-조절)에 정리했습니다.
## 구성 요소
```
[게임PC (Windows 11) 한 대에서 전부 실행]
1. Jarvis 관리 앱 (exe, Electron + TypeScript)
├─ GUI: 대시보드 / 봇 / 채널·호출 / 채팅 채널 / 대화 기억 / 모델 / 기능
│ / 게임 모드 / PC 제어 / 화면 보기 / 데이터 / 로그
├─ 서비스 관리자: 아래 프로세스를 띄우고, 감시하고, 죽으면 재시작
├─ 디스코드 음성 코어 (discord.js + @discordjs/voice + DAVE 복호화)
│ 화자별 Opus 수신 → PCM → 음성 워커로 전달 / TTS 음성 재생
├─ 채팅 채널 연결 (등록한 채널 읽기·보내기·수정·검색)
├─ 브라우저 에이전트 (Playwright + 봇용 크롬창, 백그라운드 가능)
├─ 게임·안티치트 감지 (게임 모드 전환, 자동 입력 차단)
└─ 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
```
## 기술 선택과 이유
| 부분 | 선택 | 이유 |
|---|---|---|
| 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`). 앱에 포함해 배포해도 라이선스 문제가 없습니다. |
| PC 프로그램 조작 | agent-desktop (Apache-2.0) | Windows UI Automation으로 버튼·입력칸을 읽고 직접 누릅니다. 좌표 클릭보다 정확하고, 커서와 포커스를 뺏지 않습니다. 실행 파일 하나라 설치 파일에 넣기 쉽습니다. ([pc-features.md](pc-features.md#키보드마우스-제어와-안티치트)) |
| LLM 예비 엔진 | OpenAI 호환 주소 | Strata에 문제가 생기면 같은 모델(GGUF)을 llama.cpp 같은 다른 로컬 엔진으로 돌려 연결합니다. 모델은 바꾸지 않습니다. |
| Python 런타임 | uv + 독립 실행형 Python 3.12 | 사용자가 Python을 따로 깔 필요가 없고 시스템 Python과 섞이지 않습니다. 전부 데이터 폴더 안에 설치됩니다. |
| 설치 파일 | NSIS (electron-builder) | 설치 파일은 약 200MB 내외로 두고, 모델과 런타임은 첫 실행 때 받습니다. |