Wyoming-Whisper Docker镜像文档

1. 镜像概述与主要用途

Wyoming-Whisper是一个基于Wyoming协议的语音转文本服务镜像，集成了faster-whisper（或可选的HuggingFace Transformers）语音识别引擎。其核心功能是提供高效的离线语音转文本能力，遵循Wyoming协议规范，可无缝集成到支持该协议的系统（如智能家居控制平台、语音助手等）中，作为后端语音识别服务。

2. 核心功能与特性

• 双引擎支持：默认使用faster-whisper（优化版Whisper模型，速度更快、资源占用更低），可通过参数切换为HuggingFace Transformers框架运行Whisper模型。
• 多语言识别：支持指定识别语言（如英语、中文等），适配多场景语音输入需求。
• 模型灵活选择：支持多种预训练模型（如tiny-int8、base等量化/非量化模型），平衡识别精度与性能。
• 本地数据持久化：通过数据卷挂载实现模型缓存、配置文件等数据的本地持久化，避免重复下载。
• Wyoming协议兼容：遵循Wyoming语音服务协议，可直接对接支持该协议的前端或中间件系统。

3. 使用场景与适用范围

• 智能家居系统：作为Home Assistant等平台的语音识别后端，支持离线语音指令解析（如控制设备、查询信息）。
• 语音助手后端：为自定义语音助手提供离线语音转文本能力，降低对云端服务的依赖。
• 离线语音应用：适用于无网络环境或对数据隐私有严格要求的场景（如企业内部语音记录转写、本地设备语音交互）。
• 轻量级语音服务：支持低资源设备（如树莓派）部署，通过选择轻量模型（如tiny系列）实现高效运行。

4. 使用方法与配置说明

4.1 前置要求

• 已安装Docker环境（参考Docker官方安装文档）。
• 本地需预留用于挂载数据卷的目录（存储模型缓存等数据）。

4.2 快速启动（基础用法）

通过docker run命令直接启动服务，默认使用faster-whisper引擎：

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

参数说明：

• -p 10300:10300：端口映射，将容器内服务端口（10300，Wyoming协议默认端口）映射到主机10300端口，供外部访问。
• -v /path/to/local/data:/data：数据卷挂载，将主机目录/path/to/local/data挂载到容器/data目录，用于持久化模型缓存、配置等数据（首次启动会自动下载模型到该目录）。
• --model tiny-int8：指定faster-whisper模型名称（支持tiny/tiny-int8/base/base-int8等，量化模型-int8后缀可降低内存占用）。
• --language en：指定识别语言（语言代码参考Whisper官方文档，如zh表示中文，fr表示法语）。

4.3 使用HuggingFace Transformers引擎

如需使用HuggingFace Transformers框架替代faster-whisper，通过--use-transformers参数启用，并指定Transformers模型ID：

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

参数说明：

• --use-transformers：启用HuggingFace Transformers引擎（需确保模型为Transformers兼容格式）。
• --model openai/whisper-tiny.en：指定Transformers模型ID（需为HuggingFace Hub上的公开模型，如openai/whisper-base、distil-whisper/distil-small.en等）。

4.4 Docker Compose配置示例

如需通过Docker Compose管理服务，可创建docker-compose.yml文件：

version: '3'
services:
  wyoming-whisper:
    image: rhasspy/wyoming-whisper
    container_name: wyoming-whisper
    restart: unless-stopped
    ports:
      - "10300:10300"
    volumes:
      - /path/to/local/data:/data  # 本地数据持久化目录
    command: >
      --model tiny-int8 
      --language zh 
      --device cpu  # 可选，指定运行设备（cpu/cuda，默认自动检测）

启动服务：

docker-compose up -d

4.5 核心配置参数说明

5. 数据持久化说明

容器内/data目录用于存储以下数据，需通过-v参数挂载至主机目录以实现持久化：

• 下载的语音模型文件（首次启动自动下载，避免重复消耗网络资源）；
• 运行时缓存（如模型加载缓存，提升重启后服务启动速度）。

示例：将主机/opt/wyoming-whisper/data目录作为数据存储目录：

-v /opt/wyoming-whisper/data:/data

6. 集成说明

该服务遵循Wyoming协议规范，可直接与支持该协议的客户端集成（如Home Assistant的Wyoming语音集成）。集成时需配置服务地址（主机IP:10300），客户端将通过TCP连接发送语音流并接收文本结果。