Files
game_voice_recorder/worker
EJClaw e6723a49ea M4: Windows 에서 첫 변환이 멈추던 문제 수정 (scipy 를 주 스레드에서 먼저 적재)
- 원인: 요청 스레드에서 scipy.linalg.blas(OpenBLAS DLL)를 처음 불러오면 Windows 에서 영원히 멈춤
  (faulthandler 스택: transcribe → audio.measure_lufs → pyloudnorm → scipy.signal → scipy.linalg.blas)
- 주 스레드에서 미리 불러오면 정상인 것을 win-ci 에서 확인 → preload_native_runtimes 에 추가

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-15 03:36:42 +09:00
..

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 런타임 다운로드(이어받기, 해시 검사, 진행률)
  • 롤 채팅 화면 OCR(Windows.Media.Ocr), r3dlog 채팅 확인
  • 파인튜닝(별도 환경): 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) 이 함께 나온다.
  • ocr_start 중 창 상태가 바뀌면 {"event":"ocr_status","state":"window_not_found"|"capturing"|"error"}.
  • ocr_line.parsed 에 game_time_s(초, 없으면 null) 포함. 시각 없는 줄은 dedupe 키에 시각이 없어 같은 내용 반복이 한 번만 잡힌다 → 게임 옵션에서 채팅 타임스탬프를 켜도록 안내.
  • 잡음이면 text=null, words=[], raw_text 는 모델 출력(① VAD 단계에서 걸리면 Whisper 를 돌리지 않으므로 null).
  • 동시성: 같은 슬롯의 load/unload/transcribe 는 순서대로, realtime/precise 는 서로 병렬. download·train·ocr_image·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 ocr_unavailable ocr_lang_missing 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).
  • 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 내보내기까지 돈다.

알려진 한계

  • 화면 OCR 과 Windows OCR 경로는 리눅스에서 실행 검증하지 못했다(파싱·중복 제거만 단위 테스트). 실제 게임 PC 에서 확인 필요. '전체 화면(독점)' 모드는 캡처가 검게 나올 수 있어 '테두리 없음' 창 모드를 권장한다.
  • r3dlog 채팅 형식은 2024년 이전 보고 기준 추정이다. r3dlog_check 로 실제 로그를 확인해야 한다.
  • 잡음 판정 기준값은 추정치다. 실제 녹음으로 noise_sensitivity 와 noise.py 임계값을 조정해야 한다.
  • 정규화 음량은 16kHz 로 디코딩한 신호에서 잰다(48k 원본과 소폭 차이 가능).
  • CUDA 경로(GPU 추론, cuDNN/cuBLAS DLL 다운로드·로딩)는 이 개발 머신에서 실행하지 않았다(M0 에서 게임 PC 로 확인).

Windows 주의: pywinrt 의 오래된 MSVC 런타임

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 로 다시 확인할 수 있다.