Wyoming Faster Whisper

개요

Wyoming Faster Whisper는 Wyoming 프로토콜을 구현한 서버이며(Home Assistant가 음성 인식에 사용하는 경량 RPC 프로토콜), 음성을 faster-whisper 음성 인식 엔진으로 전달합니다. 간단히 말해, Home Assistant(또는 다른 Wyoming 클라이언트)가 TCP 소켓을 통해 빠른 Whisper 기반 전사 모델과 통신할 수 있게 해줍니다.

주요 특징

속도 및 효율성 – faster-whisper는 CTranslate2를 사용하여 Whisper 모델을 실행하므로, 저사양 하드웨어(Raspberry Pi 등)에서도 실시간 전사가 가능합니다.
Home Assistant 통합 – 이 서버는 Wyoming STT 서비스로 자신을 알리므로, Home Assistant에서 즉시 음성 명령용으로 사용할 수 있습니다.
자동 언어 처리 – 선택한 백엔드가 지원하는 언어를 정확히 보고하므로, Home Assistant가 올바른 파이프라인을 선택할 수 있습니다.
이름 편향 설정 (Name-biasing) – Home Assistant 인스턴스에서 엔티티 이름을 추출하여 프롬프트로 모델에 제공함으로써, 장치 이름의 오인식을 획기적으로 줄일 수 있습니다.
유연한 배포 – 로컬, Docker, 또는 GPU 탑재 머신에서 실행 가능하며, 모델이 캐시되면 인터넷 없이도 작동합니다.

설치 방법

로컬 빠른 설치

git clone https://github.com/OHF-Voice/wyoming-faster-whisper.git
cd wyoming-faster-whisper
script/setup               # 가상 환경 생성 및 의존성 설치
script/run \
    --model tiny-int8 \
    --language en \
    --uri 'tcp://0.0.0.0:10300' \
    --data-dir /data \
    --download-dir /data

tiny-int8은 원하는 Whisper 모델로 교체하세요. Hugging-Face 체크포인트를 지정할 수도 있습니다.

Docker (CPU)

docker run -it -p 10300:10300 \
    -v /path/to/local/data:/data \
    rhasspy/wyoming-whisper \
    --model tiny-int8 --language en

모델 파일은 마운트된 /data 볼륨에 저장됩니다.

Docker (GPU) – 선택 사항

# GPU 이미지 빌드 (NVIDIA toolkit 필요)
git clone https://github.com/OHF-Voice/wyoming-faster-whisper.git
cd wyoming-faster-whisper
docker build -f Dockerfile.gpu -t wyoming-whisper:gpu .

# 실행
docker run -it --gpus all -p 10300:10300 \
    -v /path/to/local/data:/data \
    wyoming-whisper:gpu --model Systran/faster-whisper-large-v3 --language en

Home Assistant 애드온

이 프로젝트는 Home Assistant의 공식 core_whisper 애드온으로도 패키징되어 있습니다. UI에서 애드온을 활성화하기만 하면 자동으로 동일한 서버가 실행됩니다.

주요 기능 및 설정

기능	활성화 방법	내용
VAD 종료 처리	`--vad-endpointing <seconds>`	일정 시간 무음(Silero VAD로 감지)이 지속되면 듣기를 중단하고 즉시 전사 결과를 반환합니다. Home Assistant 자체의 종료 처리가 필요 없습니다.
이름 편향 설정	`--hass-token <token>` (`wyoming-faster-whisper[hass]` 설치)	Home Assistant의 엔티티/영역 이름을 추출하여 프롬프트로 제공함으로써 장치 이름 인식 정확도를 향상시킵니다.
백엔드 선택	`--stt-library <name>` 또는 `--stt-library auto`	faster-whisper, transformers, qwen3-asr, sherpa, funasr, onnx-asr 등 중에서 선택 가능하며, 각각 지원 언어가 다릅니다.
로컬 전용 모드	`--local-files-only` 또는 `WYO_WHISPER_LOCAL_FILES_ONLY=true`	서버가 누락된 모델을 다운로드하지 못하게 합니다. 오프라인 또는 에어갭 환경에서 유용합니다.
디버그 / 상태 확인	`--debug` 또는 `python -m wyoming_faster_whisper.health_check` 실행	추가 로그를 출력하고 Docker가 적절한 상태 확인 결과를 보고할 수 있게 합니다.

OHF-Voice/wyoming-faster-whisper