EMERGENCY_ANY_TECH_DOC.md

emergency_any 기술 문서

1) 목표

• 긴급 호출어(예: 살려주세요, 도와주세요)를 실시간으로 감지하는 단일 wakeword 모델(emergency_any.onnx)을 구축한다.
• 일반 대화/생활 소음에서 오탐을 줄이기 위해 실시간 후처리 필터를 함께 적용한다.

2) 구성 파일

• 모델 학습 스크립트: train_model.py
• 실시간 콘솔 테스트: run_live.py
• 실시간 Gradio 테스트: gradio_live.py
• 최종 모델: emergency_any.onnx

3) 학습 데이터 구성

• Positive(긴급): positive_help/ (총 419개)
  • help_me: 212
  • save_me: 207
• Negative(일반): /home/dusen0528/Keyword-Spotting/data에서 샘플링
  • 기본 비율 negative_ratio=3.0 적용 → 1257개

4) 학습 파이프라인

학습 명령:

cd /home/dusen0528/openWake/my_custom_model
source .venv/bin/activate
python train_model.py --positive_dir ./positive_help --model_name emergency_any --epochs 50

처리 흐름:

1. Positive/Negative WAV 로드
2. 16kHz 리샘플
3. 2초(32000 샘플) 길이로 패딩/자르기
4. openWakeWord AudioFeatures로 embedding 추출
5. DNN 이진 분류기 학습
6. ONNX export (emergency_any.onnx)

5) Gradio 실시간 감지 로직

실행 명령:

cd /home/dusen0528/openWake/my_custom_model
source .venv/bin/activate
python gradio_live.py --model ./emergency_any.onnx --threshold 0.5 --share

스트리밍 로직:

• 16kHz로 정규화 후 80ms 프레임(1280 샘플) 단위 추론
• 점수 기반 후보 검출 + 후처리 필터 적용

필터 항목:

• RMS Gate: 무음/작은 소리 차단
• Score Margin vs Baseline: 환경 베이스라인 대비 점수 상승분 조건
• Min Consecutive Hits: 연속 히트 횟수 조건
• Debounce: 감지 후 재감지 간격

권장 초기값(현장 튜닝 시작점):

• Threshold: 0.55 ~ 0.65
• RMS Gate: 0.008 ~ 0.015
• Score Margin: 0.00 ~ 0.05 (필요 시 증가)
• Min Consecutive Hits: 2 ~ 4
• Debounce: 0.6 ~ 1.0

5-1) 테스트 버전 확정값 (2026-02-27)

실제 테스트에서 인식/오탐 균형이 가장 안정적이었던 값:

• Detection Threshold: 0.55
• Debounce: 0.6
• RMS Gate: 0.014
• Score Margin vs Baseline: 0.0 (off)
• Min Consecutive Hits: 2 (오탐 증가 시 3)

메모:

• 위 설정은 살려주세요 감지를 유지하면서 책상/부스럭 소리 오탐을 줄이는 목적의 테스트 세팅이다.
• 환경 소음이 높아지면 RMS Gate를 0.016~0.020까지 올려 재조정한다.

6) 트러블슈팅 요약

A. onnxscript 누락으로 export 실패

• 증상: ModuleNotFoundError: No module named 'onnxscript'
• 조치:

python -m ensurepip --upgrade
python -m pip install -U pip onnx onnxscript

B. melspectrogram.onnx 파일 없음 오류

• 증상: NO_SUCHFILE ... openwakeword/resources/models/melspectrogram.onnx
• 원인: 로컬 리포 경로에 리소스가 없고, site-packages 경로를 못 참조
• 조치: train_model.py, gradio_live.py에서 .venv/site-packages/openwakeword/resources/models 자동 폴백 적용 완료

7) 재현에 필요한 최소 파일

다른 서버/PC에서 동일하게 테스트하려면 아래 파일을 우선 가져간다.

필수:

1. emergency_any.onnx
2. gradio_live.py

권장(재학습/유지보수 대비):

1. train_model.py
2. run_live.py
3. requirements.txt
4. positive_help/ (또는 원본 positive 데이터)

8) 운영 메모

• 단일 모델(emergency_any)은 긴급 키워드를 "통합 감지"한다. (어느 단어인지 구분하지 않음)
• 키워드별 구분이 필요하면 모델을 키워드별로 분리(help_me.onnx, save_me.onnx 등)해 멀티모델 방식으로 운용한다.