whisper-stt/README.md

VoiceScript — STT + OCR 통합 툴

faster-whisper(STT) + PaddleOCR 3.x / Ollama Vision / OpenRouter Vision(OCR)

---

빌드 전 필수 설정 (docker-compose.yml)

항목	설명
AUTH_USERNAME / AUTH_PASSWORD	로그인 계정 변경 필수
JWT_SECRET	openssl rand -hex 32 로 생성
OLLAMA_URL	호스트 실제 LAN IP (host.docker.internal 불안정)
CPU_THREADS	0 = 자동, 5825u 기준 8~12 권장
OLLAMA_TIMEOUT	큰 모델(11b+) 은 300+ 권장

빌드 & 실행

cd whisper-stt
docker compose up -d --build
docker compose logs -f worker   # 모델 다운로드 완료 확인

접속: http://서버IP:8800

기능

STT 탭

• faster-whisper: 로컬 CPU 변환
• + Ollama 교정: Whisper 후 Ollama로 문장부호·맞춤법 교정
• + OpenRouter 교정: 외부 AI(Claude/GPT 등)로 교정

OCR 탭

• PaddleOCR: 로컬 실행 (PaddleOCR 3.x, PPStructure 미사용)
• Ollama Vision: Vision 지원 모델만 가능 (granite3.2-vision 등)
• OpenRouter Vision: Claude-3, GPT-4o, Gemini 등 외부 Vision 모델

설정 탭

• 시스템 리소스 모니터 (RAM/CPU/Swap)
• CPU 스레드 슬라이더
• 변환 타임아웃 설정 (STT / Ollama)
• OpenRouter API 키 등록 + 모델 선택

이력 탭

• STT/OCR 변환 이력 (입력 파일·설정·결과 저장)
• 텍스트 미리보기 + 결과 파일 다운로드

관리자 탭

• 다중 사용자 관리 (추가/편집/삭제)
• 사용자별 STT/OCR 권한 설정
• 사용자별 허용 모델 제한

트러블슈팅

오류	해결
paddlepaddle 빌드 실패	Dockerfile에 -i pypi.tuna... 없는지 확인
SIGSEGV (worker 크래시)	--pool=solo 옵션 확인
Ollama 연결 실패	OLLAMA_URL에 host.docker.internal 대신 실제 IP 사용
OCR 빈 응답	Vision 미지원 모델 선택 여부 확인
Redis write 에러	redis-server --stop-writes-on-bgsave-error no 확인
PPStructure 오류	PaddleOCR 3.x 에서 제거됨, 표 추출은 Ollama/OpenRouter 사용