Files
..

gvr-worker (겜녹이 STT 워커)

앱 코어(Electron/Node)가 자식 프로세스로 띄우는 Python 워커. 하는 일:

  • 발화 Ogg Opus → 음량 정규화(BS.1770 LUFS + 리미터) → Silero VAD → faster-whisper(한국어 고정, 핫워드, 단어별 시각)
  • 잡음 판정 4단계(VAD / no_speech / 환각 문구 / 반복) → noise, noise_reason
  • 교정 사전(정확 일치) + 한글 자모 유사도 교정 (단어 시각 유지)
  • GPU 감지(NVML → nvidia-smi)와 VRAM 별 모델 추천, 모델·CUDA 런타임 다운로드(이어받기, 해시 검사, 진행률)
  • r3dlog(롤 게임 로그 파일) 채팅 읽기. 화면 OCR 은 v1.3.3 에서 뺐다 (쓰지 않음)
  • 파인튜닝(별도 환경): TTS 합성 → LoRA → CER 비교 → CTranslate2 내보내기

프로토콜

docs/dev/ARCHITECTURE.md 1장이 계약이다. stdin/stdout JSON Lines, stdout 은 프로토콜 메시지만, 로그는 stderr. 계약 외 추가 사항:

op 설명
r3dlog_check {logs_dir} {found_chat, file, sample:[...]}
r3dlog_read {logs_dir, since_ms} 최신 *_r3dlog.txt(since_ms 이후 수정) 전체 채팅 → {file, lines:[{game_time, game_time_s, channel, sender, champion, message}]}
train {python?, args:{...}} 파인튜닝 환경의 파이썬(python 또는 GVR_FINETUNE_PYTHON)으로 finetune/run.py 실행. args 키는 --kebab-case 옵션으로 넘어감. 진행은 progress 이벤트(stage,step,total)로 중계
  • load 는 device 생략 시 GPU 있으면 cuda/float16, 없으면 cpu/int8. cuda 요청인데 GPU 가 없으면 cpu 로 바꾸고 "fallback":"no_gpu". cpu_threads 선택.
  • models 응답에 loaded(슬롯별 적재 상태)와 파인튜닝 모델(<이름>-ft-<날짜>, meta=gvr-model.json) 이 함께 나온다.
  • 잡음이면 text=null, words=[], raw_text 는 모델 출력(① VAD 단계에서 걸리면 Whisper 를 돌리지 않으므로 null).
  • 동시성: 같은 슬롯의 load/unload/transcribe 는 순서대로, realtime/precise 는 서로 병렬. download·train·r3dlog_read 는 별도 스레드.
  • 주요 오류 코드: bad_json bad_request unknown_op model_not_loaded model_not_installed unknown_model file_not_found decode_failed transcribe_failed load_failed cuda_runtime_missing disk_full network verify_failed busy finetune_env_missing train_failed internal.

환경변수: GVR_DATA_DIR, GVR_MODELS_DIR(선택), GVR_FINETUNE_PYTHON(선택), GVR_LOG_LEVEL(기본 INFO).

개발 환경 (리눅스)

cd worker
uv venv --python 3.11 .venv
uv pip install --python .venv/bin/python -r requirements-dev.txt
.venv/bin/python -m gvr_worker          # stdin 으로 JSON 한 줄씩

테스트

cd worker && .venv/bin/python -m pytest -q
  • 모델은 tiny(CPU, int8). ~/.cache/huggingface 에 Systran/faster-whisper-tiny 가 있으면 링크하고, 없으면 테스트가 download op 로 받는다.
  • 픽스처(tests/fixtures/*.ogg, 48kHz mono Opus)는 tests/make_fixtures.py 로 다시 만들 수 있다 (edge-tts + ffmpeg, 인터넷 필요).

패키징 (Windows)

py -3.11 -m venv .venv && .venv\Scripts\pip install -r requirements-dev.txt
.venv\Scripts\pyinstaller gvr-worker.spec      REM → dist\gvr-worker\gvr-worker.exe (onedir)

콘솔 앱이며 부모가 windowsHide 로 띄운다. faster-whisper VAD onnx, ctranslate2/onnxruntime/av DLL, pywinrt 가 포함되고 gvr_worker/finetune/*.py 는 데이터 파일로만 들어간다 (torch 등은 exe 에 넣지 않음).

Windows CUDA 메모

  • ctranslate2 4.8.x Windows 휠은 CUDA 12.8 + cuDNN 9 로 빌드되어 RTX 50(Blackwell, sm_120)을 지원한다. 그래픽 드라이버는 CUDA 12.8 이상을 지원해야 한다(R570+).
  • cuBLAS/cuDNN DLL 은 exe 에 넣지 않고 첫 실행 때 download {target:"cuda_runtime"} 으로 PyPI 의 nvidia-cublas-cu12, nvidia-cudnn-cu12 win_amd64 휠(약 1.2GB)을 받아 bin/*.dll 만 GVR-Data/cuda/ 에 푼다(sha256 검사). 워커는 시작할 때 이 폴더를 os.add_dll_directory + PATH 앞에 넣으므로, 받은 뒤에는 워커를 재시작한다(restart_required:true).
  • 기본 연산 정밀도는 float16. RTX 50 에서 int8 계열이 cuBLAS 오류를 낸 보고가 있어 int8 은 VRAM 이 빠듯할 때만 추천하고 경고를 붙인다.
  • 리눅스에서 cuda_runtime 다운로드는 skipped:true 로 끝난다.

파인튜닝 (M8, 별도 환경)

uv venv --python 3.11 .venv-ft
uv pip install --python .venv-ft/bin/python torch --index-url https://download.pytorch.org/whl/cu128   # CPU: /whl/cpu
uv pip install --python .venv-ft/bin/python -r gvr_worker/finetune/requirements.txt
.venv-ft/bin/python gvr_worker/finetune/run.py --data-dir GVR-Data \
    --dictionary words.txt --sentences sentences.txt --user-corrections corrections.jsonl
  • 단계: synth.py(edge-tts SunHi/InJoon/Hyunsu, 속도·피치 변화, 30% 확률 배경 잡음) → build_dataset.py(문장 해시로 고정 검증 세트) → evaluate.py(학습 전 CER) → train_lora.py(LoRA r=32, q/k/v/out_proj, CUDA bf16 autocast / CPU fp32, gradient checkpointing) → evaluate.py(학습 후 CER) → export_ct2.py(병합 → CTranslate2 float16 → models/<이름>-ft-<YYYYMMDD>/ + gvr-model.json).
  • GPU 에서는 얼려 둔 원본 가중치를 bf16 으로 올린다(LoRA 만 fp32). large-v3-turbo, 배치 4 기준 최대 VRAM 2.7GB.
  • 라벨의 절반은 <|0.00|> 문장 <|말끝|> 타임스탬프 형식이다. 앱은 타임스탬프 모드로 변환하므로, <|notimestamps|> 로만 학습하면 끝맺음을 잊고 문장 뒤에 말을 지어낸다(M8 시험 학습에서 확인). evaluate.py 도 같은 이유로 타임스탬프 모드로 잰다.
  • adopt = cer_after < cer_before 일 때만 내보낸다(--export-always 로 강제). 앱은 models 의 meta 를 보고 교체/되돌리기.
  • 중지 파일(기본 GVR-Data/finetune.stop)이 있으면 시작하지 않고, 학습 중 생기면 어댑터를 저장하고 stopped:true 로 끝난다.
  • 사용자 교정 jsonl: {"audio":"<training/xxx.ogg>","text":"<고친 문장>"}.

CPU 스모크 테스트(openai/whisper-tiny, 합성 30개, --max-steps 3)는 약 30초에 전체 단계와 CT2 내보내기까지 돈다.

알려진 한계

  • r3dlog 채팅 형식은 2024년 이전 보고 기준 추정이다. r3dlog_check 로 실제 로그를 확인해야 한다.
  • 잡음 판정 기준값은 추정치다. 실제 녹음으로 noise_sensitivity 와 noise.py 임계값을 조정해야 한다.
  • 정규화 음량은 16kHz 로 디코딩한 신호에서 잰다(48k 원본과 소폭 차이 가능).
  • GPU 추론·학습은 개발 서버 RTX 5050(리눅스, CUDA float16)에서 확인했다(M7·M8, docs/dev/test-results.md). Windows 의 cuDNN/cuBLAS DLL 다운로드·로딩은 게임 PC 진단으로 확인한다.

Windows 주의: pywinrt 의 오래된 MSVC 런타임 (v1.3.2 까지, OCR 을 쓰던 때)

winrt 패키지는 msvcp140.dll 14.29 를 자기 폴더에 넣어 둔다. 이게 먼저 올라가면 onnxruntime(Silero VAD)이 0xC0000005 로 프로세스째 죽는다 (win-ci 에서 확인: OCR 을 한 번 쓴 뒤 첫 변환에서 워커가 조용히 종료, PyInstaller 분석도 같은 이유로 실패). 대응: ① 워커 시작 때 onnxruntime·ctranslate2 를 먼저 불러온다(preload_native_runtimes) ② 빌드 전에 site-packages/winrt/msvcp140*.dll 을 지운다(tools/win-ci/gvr.ps1).

Windows 주의: scipy 는 주 스레드에서 먼저 불러온다

요청 처리 스레드에서 scipy 를 처음 import 하면 scipy.linalg.blas(OpenBLAS DLL) 적재 중에 프로세스가 멈춘다 (win-ci 에서 확인: 첫 transcribe 의 음량 측정 pyloudnorm → scipy.signal 에서 응답 없음, faulthandler 스택으로 위치 확인). 같은 import 를 시작할 때 주 스레드에서 먼저 하면 정상이라, preload_native_runtimes 가 scipy.linalg/signal/ndimage, pyloudnorm 도 미리 불러온다. worker/scripts/win_debug.py protocol 로 다시 확인할 수 있다.