- 선수 이름은 한글이 들어간 것만 핫워드로 넣는다 - 결과가 선수 이름(조각)뿐이면 워커가 이름을 빼고 다시 변환 (is_name_echo, player_names) - 예전에 이렇게 적힌 발화는 한 번만 정밀 모델로 다시 변환 (파일 없으면 숨김, 고친 발화 제외) 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 런타임 다운로드(이어받기, 해시 검사, 진행률)
- 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_jsonbad_requestunknown_opmodel_not_loadedmodel_not_installedunknown_modelfile_not_founddecode_failedtranscribe_failedload_failedcuda_runtime_missingdisk_fullnetworkverify_failedbusyfinetune_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). - 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 로 다시 확인할 수 있다.