HUTAMS_AUDIO/docs/project_spec.md

HUTAMS STT 파이프라인

이 시스템은 현장 관제를 위한 초저지연 오디오 인식 및 지식 결합 파이프라인을 구축하고 있습니다. 기반 아키텍처: FastAPI + SQLite + Faster-Whisper + On-device LLM + WebSocket.

1. 단계별 실행 흐름

1. 음성 포착 (VAD) MockAudioListener 또는 RadioListener(실마이크) 백그라운드 스레드가 임계치를 넘는 음성만을 분리하여 임시 wav 파일로 만들어 저장합니다. 해당 파일 완성 직후 on_segment 콜백이 트리거되어 STT Service에 넘깁니다.

2. 음성 처리 및 Opus 인코딩 (STT Service) Faster-Whisper V3 Turbo가 텍스트를 인식합니다. 음성은 고효율(16k libopus) .ogg 로 백업되어 보관(data/audio/)됩니다. 1차 보정: Rapidfuzz를 사용해 고속으로 4,000건의 철도 용어 사전(dictionary.py) 대조 작업을 거친 뒤 철자를 교정합니다.

3. Rule-based 긴급 상황 식별 (Analyzer) 교정된 문장에서 룰 기반 긴급 키워드 필터링과 다국어(한국어 단위)가 섞인 열차 번호("삼천사십이")를 정규식으로 직접 추출합니다. 이 룰 판별은 LLM에 들어가는 병목을 우회하여 즉시(Socket Event) Pydantic 모델로 주입됩니다.

4. Background Data Integration (LLM Worker) STT의 큐가 넘어간 다음 0.8B Qwen 로컬 모델(llm_service.py)이 다음과 같은 두 가지 행동을 백그라운드로 실행합니다:

   • thread_updated: 이전 대화와의 이어지는 맥락인지 화자를 식별.
   • context_discovered: 관련 철도 전문 사전 키워드가 있는지 추출해 우측 Context 패널에 띄웁니다.

5. 클린업 스케줄러 (lifespan) FastAPI 서비스 생명주기에 결합되어, 매 24시간마다 3일 이상 지난 일반 오디오(긴급 아님) 라인들을 삭제하며 디스크를 관리합니다.