35 lines
2.1 KiB
Markdown
35 lines
2.1 KiB
Markdown
# HUTAMS (AI 기반 전동차 운용관리 플랫폼 - 무전 STT 시스템)
|
|
|
|
본 프로젝트는 현장 철도 무전(LTE-R) 음성을 실시간으로 수집하고, Edge 단에서 AI(Faster-Whisper + 0.8B 온디바이스 LLM + RapidFuzz 결합)를 기반으로 고속 문맥 분석과 긴급 상황을 식별하는 STT 및 분석 시스템입니다.
|
|
|
|
## 핵심 기동 방법 (Vibe Coding with uv)
|
|
|
|
1. **사전 준비**:
|
|
- `uv` 설치 및 파이썬 패키지 세팅
|
|
```bash
|
|
uv sync
|
|
```
|
|
- **[주의] 대용량 언어모델 수동 배치**: `Qwen3.5-0.8B-Q4_K_M.gguf` (또는 지정된 모델 버전)와 같은 대형 `.gguf` 파일들은 `.gitignore` 처리되어 Git에서 제외되므로 개별적으로 다운로드 받아 프로젝트 내 **`llm_weights/`** 폴더 안에 배치해야 합니다. (동봉된 `setup.ps1` 스크립트를 관리자 권한으로 실행하면 모델 다운로드 및 폴더 생성까지 자동으로 처리됩니다).
|
|
- 최초 기동 시 오디오 저장 폴더(`data/audio/`, `data/samples/`) 및 로컬 DB 파일(`whisper.db`)은 시스템 내에 자동으로 초기화됩니다.
|
|
|
|
- whisper_weights 폴더와 llm_weights 폴더는 `.gitignore` 처리되어 Git에서 제외되므로 개별적으로 다운로드 받아 프로젝트 내 **`whisper_weights/`** 폴더와 **`llm_weights/`** 폴더 안에 배치해야 합니다.
|
|
2. **서버 실행**:
|
|
`run_server.ps1` 또는 아래 구문을 사용합니다.
|
|
```bash
|
|
uv run uvicorn app.main:app --host 0.0.0.0 --port 28000
|
|
```
|
|
|
|
3. **테스트 도구**:
|
|
현장 오디오 입력을 위해 USB 사운드카드로 Line-in을 받을 때 쓰는 샘플 스크립트입니다.
|
|
```bash
|
|
# 디바이스 목록 확인
|
|
uv run python tools/record_sample.py --list-devices
|
|
# 특정 인덱스로 녹음
|
|
uv run python tools/record_sample.py --device 2 --duration 10
|
|
```
|
|
|
|
4. **문서 구조**:
|
|
- `docs/project_spec.md`: 모듈 기능 구조와 파이프라인 정비
|
|
- `docs/api_contract.md`: REST API 및 WebSocket 명세서
|
|
- `docs/issue.md`: 작업 현황과 롤링 이슈
|