# docker_wyoming_sensevoice

**Repository Path**: HappyEventKing/docker_wyoming_sensevoice

## Basic Information

- **Project Name**: docker_wyoming_sensevoice
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-16
- **Last Updated**: 2026-04-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Wyoming SenseVoice ASR Server

基于 [Wyoming 协议](https://github.com/rhasspy/wyoming) 的 [SenseVoice](https://github.com/FunAudioLLM/SenseVoice) ASR 服务，适用于 Home Assistant 语音助手等场景。

> **说明**：本项目代码主要由 AI 辅助生成，并经过人工审查与测试验证。

## 功能特性

- **多语言识别**：支持中文、英文、日语、韩语、粤语等（由 SenseVoiceSmall 提供）
- **Wyoming 协议兼容**：可作为 Home Assistant 的 Wyoming ASR 服务直接接入
- **灵活部署**：支持 CPU / GPU（CUDA）运行，通过环境变量切换
- **情绪/事件标签**：可选保留或去除 SenseVoice 的情感/事件标签（如 `<|NEUTRAL|>`、`<|Laughter|>`）
- **异常容错**：ASR 推理失败时返回空字符串，不会导致连接断开

## 目录结构

```text
.
├── Dockerfile                  # CPU 镜像构建
├── Dockerfile.cuda             # GPU 镜像构建
├── docker-compose.yml          # CPU 运行配置
├── docker-compose.cuda.yml     # GPU 运行配置
├── requirements.txt            # Python 依赖
├── run.sh                      # 容器启动脚本
├── wyoming_sensevoice/         # 服务端代码
│   ├── __init__.py
│   ├── __main__.py             # 入口
│   ├── server.py               # Wyoming TCP 服务端
│   └── asr.py                  # SenseVoice 封装
├── tests/                      # 单元测试
│   └── test_all.py
├── .gitignore
├── LICENSE
└── README.md
```

## 快速开始

### 1. 构建并运行（CPU）

```bash
docker compose up --build -d
```

查看日志：
```bash
docker compose logs -f
```

### 2. 构建并运行（GPU / CUDA）

> 需要宿主机已安装 NVIDIA Container Toolkit。请注意，部分老显卡（计算能力 < 6.0）可能不被 PyTorch 2.x 支持，建议优先使用 CPU 镜像。

```bash
docker compose -f docker-compose.cuda.yml up --build -d
```

### 3. 连接到 Home Assistant

在 Home Assistant 的 **Wyoming** 集成中，添加服务：

- **Host**: `wyoming-sensevoice`（或 Docker 宿主机的 IP）
- **Port**: `10300`

## 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `WYOMING_PORT` | `10300` | Wyoming TCP 服务端口 |
| `SENSEVOICE_DEVICE` | `cpu` | 推理设备：`cpu` 或 `cuda` |
| `SENSEVOICE_LANGUAGE` | `auto` | 识别语言：`auto`、`zh`、`en`、`ja`、`ko`、`yue` |
| `SENSEVOICE_WITH_EMOJI` | `false` | `true` 时保留情感/事件标签 |

## 情绪与事件标签

SenseVoice 会在识别结果中嵌入语言、情绪和事件标签。当 `SENSEVOICE_WITH_EMOJI=true` 时，以下标签会被保留：

| 标签 | 含义 |
|------|------|
| `<\|zh\|>` `<\|en\|>` `<\|ja\|>` `<\|ko\|>` `<\|yue\|>` | 语言标记（始终被过滤，不保留） |
| `<\|NEUTRAL\|>` | 中性 |
| `<\|HAPPY\|>` / `<\|Laughter\|>` | 开心 / 笑声 |
| `<\|SAD\|>` | 悲伤 |
| `<\|ANGRY\|>` | 愤怒 |
| `<\|EMO_UNKNOWN\|>` | 未知情绪 |
| `<\|Speech\|>` | 正常语音 |
| `<\|Music\|>` `<\|Noise\|>` `<\|Applause\|>` `<\|Breath\|>` | 音乐 / 噪声 / 掌声 / 呼吸声 |

示例输出（`with_emoji=true`）：
```
<|NEUTRAL|><|Speech|>开饭时间早上9点至下午5点。
```

当 `with_emoji=false` 时，只返回纯文本：
```
开饭时间早上9点至下午5点。
```

## 本地运行（非 Docker）

```bash
# 创建虚拟环境并安装依赖
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# 运行测试
python3 -m unittest discover -s tests -v

# 启动服务
python3 -m wyoming_sensevoice \
    --uri "tcp://0.0.0.0:10300" \
    --device cpu \
    --language auto \
    --with-emoji false
```

## 开发测试

项目包含基于 `unittest` 的测试套件，覆盖：

- PCM → WAV 格式转换
- 后处理标签清洗（语言标签、情绪标签、ITN 标记）
- `recognize()` 对 dict / str / 空结果 / 异常场景的兼容
- Wyoming 事件流处理（AudioStart / Chunk / Stop / Describe）

运行测试：
```bash
python3 -m unittest discover -s tests -v
```

## 注意事项

1. **模型下载**：首次启动时会自动从 ModelScope 下载 `SenseVoiceSmall` 模型，请确保网络畅通。`docker-compose.yml` 已将 `./models` 挂载到容器内缓存目录，避免重复下载。
2. **GPU 兼容性**：部分老显卡可能不被 PyTorch 2.x 支持，如遇 CUDA 启动错误，建议优先使用 CPU 镜像。
3. **音频格式**：服务端接收 Wyoming `AudioChunk` 事件中的原始 PCM 数据，并在内部转换为 WAV 后送入 FunASR。

## 许可证

代码采用 [MIT License](LICENSE)。

SenseVoice 模型版权归 [Alibaba DAMO Academy](https://github.com/FunAudioLLM/SenseVoice) 所有。