- 원인: 요청 스레드에서 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>
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_jsonbad_requestunknown_opmodel_not_loadedmodel_not_installedunknown_modelfile_not_founddecode_failedtranscribe_failedload_failedcuda_runtime_missingdisk_fullnetworkverify_failedbusyocr_unavailableocr_lang_missingfinetune_env_missingtrain_failedinternal.
환경변수: 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가 있으면 링크하고, 없으면 테스트가downloadop 로 받는다. - 픽스처(
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-cu12win_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 로 다시 확인할 수 있다.