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 报告正确的健康检查状态。

适用对象

• Home Assistant 用户：希望拥有一个快速、本地运行且能理解设备名称的 STT 引擎。
• Raspberry Pi / 边缘设备爱好者：寻求无需将音频传送到云端即可实现实时转录的解决方案。
• 开发者：需要一个兼容 Wyoming 的 STT 服务来整合到其他语音助手项目中。

---

所有详细信息均直接取自仓库的 README；未推论任何额外功能。