# myasr

**Repository Path**: null_500_7265/myasr

## Basic Information

- **Project Name**: myasr
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-26
- **Last Updated**: 2026-09-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# myasr · 实时语音转写服务

基于 [whisper.cpp](https://gitee.com/mirrors/whisper.cpp) 的局域网实时语音转文字（ASR）服务，支持**中英文混合输入**。浏览器采集麦克风 → WebSocket 推流 → 服务器 C++ 推理 → 文字实时回传。

面向低功耗 x86 小主机（开发实测：i5-1335U / 16GB / Ubuntu 24.04，纯 CPU 推理，无独显）。

## 架构

```
浏览器（web/index.html）                服务器（server/src）
┌──────────────────────────┐           ┌─────────────────────────────┐
│ getUserMedia 麦克风       │           │ ws_server  libwebsockets    │
│  → AudioWorklet/SP 采集  │  binary   │   ├─ IO 线程（lws 事件循环） │
│  → 16kHz mono Int16 PCM  │ ────────► │   └─ 推理线程（单 worker）   │
│ 灰字 partial / 黑字 final │ ◄──────── │ session   能量VAD状态机      │
│ 波形电平条 + 延迟显示      │  JSON     │ asr_engine whisper.cpp 封装 │
└──────────────────────────┘           │   · silero VAD 裁剪非语音    │
                                       │   · opencc 繁→简            │
                                       │   · beam search（final 可选）│
                                       └─────────────────────────────┘
```

**双引擎架构**（`--engine` 切换）：
- **sensevoice（默认）**：阿里 SenseVoice-small ONNX（sherpa-onnx C API），RTF≈0.04，中文准确率高、自带标点和 ITN。快到 partial 直接全量解码（1.5s 节流），灰字即完整句子、无窗口失真，final 断句后毫秒级出结果
- **whisper**：whisper.cpp（greedy/beam search），英文更稳，partial 用滑窗 + 上下文裁剪控成本

**双引擎路由（whisper 模式）**：灰字预览（partial）可用小模型 + 3 秒节流（求快、控 CPU）；断句后的黑字定稿（final）用主模型 + beam search（求准）。避免低功耗 CPU 持续满载导致热降频。

**断句策略**：会话级能量 VAD（自适应阈值 + 起始去抖）检测说话状态，静音 0.7s 自动断句；partial 只解码最近 12s 音频（头部 4s 作上下文、文本裁掉），成本恒定。

## 开机自启（systemd）

服务单元文件在 `deploy/myasr.service`，一键部署：

```bash
./scripts/install-service.sh    # 内部会按实际仓库路径/用户名修正单元文件
```

实现原理：
- `systemctl enable` 在 `/etc/systemd/system/multi-user.target.wants/` 建软链接，开机进入多用户模式时 systemd 自动拉起服务
- `Restart=on-failure` + `RestartSec=3`：进程异常退出 3 秒后自动重启
- `After=network.target`：等网络栈就绪后再启动（避免端口绑定过早失败）
- 日志进 journald：`journalctl -u myasr -f`（`./scripts/logs.sh` 已封装）

手动等价操作：

```bash
sudo cp deploy/myasr.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now myasr
```

## 目录结构

```
server/    C++ WebSocket ASR 服务（libwebsockets + whisper.cpp 联编）
web/       单文件浏览器客户端（双击即用，file:// 自动降级 ScriptProcessor）
tools/     ws_test.py 端到端推流测试脚本
scripts/   服务器运维脚本（见下）与 install-service.sh（systemd 一键部署）
deploy/    systemd 服务单元（开机自启）
docs/      设计与各阶段报告（P0 benchmark / P1 / P2）
```

## 服务器快捷脚本

在服务器上日常操作用 `scripts/` 里的脚本（建议配合 ~/.bashrc 别名 `myasr-*`）：

| 命令 | 作用 |
|---|---|
| `scripts/build.sh` | 增量编译服务端 |
| `scripts/restart.sh` | 重启 systemd 服务并确认 |
| `scripts/status.sh` | 服务状态 + CPU 占用 + 最近解码记录 |
| `scripts/logs.sh` | 实时日志（`logs.sh -j` 只看解码耗时行） |
| `scripts/test.sh` | 端到端回归测试（推中英混合测试音频） |
| `scripts/update.sh` | 一条龙：git pull → 编译 → 重启 → 回归测试 |

## 快速开始

### 1. 获取 whisper.cpp

gitee 镜像 `git clone` 易断流，建议 zip 包：

```bash
mkdir -p third_party && cd third_party
curl -sL -o whisper.zip 'https://gitee.com/mirrors/whisper.cpp/repository/archive/master.zip'
unzip -q whisper.zip && mv whisper.cpp-master whisper.cpp
```

### 2. 下载模型（国内走 hf-mirror）

```bash
mkdir -p models/sensevoice && cd models/sensevoice
B=https://hf-mirror.com/csukuangfj/sherpa-onnx-sense-voice-zh-en-ja-ko-yue-2024-07-17/resolve/main
curl -sLO $B/model.int8.onnx && curl -sLO $B/tokens.txt   # SenseVoice 默认引擎（~229MB）

# 可选：whisper 引擎模型
mkdir -p ../models && cd ../models
BASE=https://hf-mirror.com/ggerganov/whisper.cpp/resolve/main
curl -sLO $BASE/ggml-small-q5_1.bin      # whisper final（~515MB）
curl -sLO $BASE/ggml-base-q5_1.bin       # whisper partial（~60MB）
curl -sLO https://hf-mirror.com/ggml-org/whisper-vad/resolve/main/ggml-silero-v5.1.2.bin
```

注意：whisper small/base 的量化版是 **q5_1**（medium/large 才是 q5_0），文件名写错会 404。

### 3. 编译

sherpa-onnx 动态库无需源码编译，从 `pip install sherpa-onnx` 的轮子里提取（lib/ 内含
libsherpa-onnx-c-api.so 与 libonnxruntime.so），与 c-api.h 一起放到
`third_party/sherpa-onnx-dist/{lib,include/sherpa-onnx/c-api/}`，CMake 自动检测启用；
未放置时仅编译 whisper 引擎，功能不受影响。

```bash
cd server
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)
```

依赖：cmake ≥3.16、g++、libwebsockets-dev（`sudo apt install libwebsockets-dev`）、可选 libopencc-dev（繁转简，未装也能跑）。

### 4. 启动

```bash
# SenseVoice（默认，推荐）
server/build/myasr --engine sensevoice \
  --sensevoice-model models/sensevoice/model.int8.onnx \
  --sv-threads 4 --port 9000

# whisper（英文更稳时切换）
server/build/myasr --engine whisper \
  --model models/ggml-small-q5_1.bin \
  --vad-model models/ggml-silero-v5.1.2.bin \
  --threads 6 --beam 3 --port 9000
```

浏览器打开 `web/index.html`（双击即可），填服务器地址 `IP:9000`，点「🎤 开始」说话。

### 5. systemd（可选，开机自启）

```ini
# /etc/systemd/system/myasr.service
[Unit]
Description=myasr - whisper.cpp realtime ASR (WebSocket)
After=network.target

[Service]
User=YOUR_USER
WorkingDirectory=/home/YOUR_USER/work/gitee/myasr
ExecStart=/home/YOUR_USER/work/gitee/myasr/server/build/myasr --model models/ggml-small-q5_1.bin --partial-model models/ggml-base-q5_1.bin --vad-model models/ggml-silero-v5.1.2.bin --port 9000 --threads 6 --partial-threads 4 --beam 3
Restart=on-failure

[Install]
WantedBy=multi-user.target
```

日志：`journalctl -u myasr -f`，每个任务记录「音频时长 → 解码耗时」。

## 命令行参数

| 参数 | 默认 | 说明 |
|---|---|---|
| `--engine` | sensevoice | `sensevoice` / `whisper` |
| `--sensevoice-model` | models/sensevoice/model.int8.onnx | SenseVoice ONNX 模型（tokens.txt 同目录自动加载） |
| `--sv-threads` | 4 | SenseVoice 推理线程数 |
| `--model` | （whisper 必填） | whisper final 模型 |
| `--partial-model` | 复用主模型 | whisper partial 小模型 |
| `--vad-model` | 不启用 | silero VAD 模型（whisper 解码前裁非语音） |
| `--threads` | 6 | whisper final 推理线程数（15W CPU 建议 6，防热降频） |
| `--beam` | 0 | whisper final beam search（更准，beam3 实测不比 greedy 慢） |
| `--language` | zh | 默认语言，可被客户端 start 指令覆盖 |
| `--vad-threshold` | 0.004 | 会话级能量 VAD 阈值下限（随噪声底自适应） |
| `--port` | 9000 | WebSocket 监听端口 |

## WebSocket 协议

**客户端 → 服务端**：
- 二进制帧：16kHz / 单声道 / Int16 LE PCM 裸流
- 文本帧：`{"cmd":"start","language":"zh"}` 开始、`{"cmd":"stop"}` 强制断句

**服务端 → 客户端**：
- `{"type":"status","model":"..."}` 连接后报告模型信息
- `{"type":"partial","text":"...","ms":1234}` 实时预览（灰字，不保证准确）
- `{"type":"final","text":"...","ms":1234}` 断句定稿（黑字，最终结果）

## 实测性能（i5-1335U，15.4s 中英混合音频）

| 引擎 | 解码耗时 | RTF | 备注 |
|---|---|---|---|
| **SenseVoice-small int8** | **0.54s** | **0.04** | ✅ 默认引擎，中文全对、自带标点/ITN |
| whisper small-q5_1 beam3 | 5.0s | 0.32 | 英文术语拼写更稳（Artificial Intelligence 全对） |
| whisper large-v3-turbo q5_0 | — | 1.32 | ❌ CPU 实时无望 |
| whisper medium q5_0 | — | 0.88 | 仅适合离线整段转写 |

两个引擎的英文能力各有胜负：SenseVoice 快 10 倍且中文更强，whisper 英文拼写更稳；
英文误拼（如 mine learning）规划用 LLM 后纠错修复（P3.2）。

## 已知限制

- 首字延迟约 1s：伪流式架构（VAD + 滑窗）的固有开销
- SenseVoice 引擎语言在启动时固定为自动检测（`language=""`），不支持运行时强制
- 能量 VAD 在极嘈杂环境下可能误触发（自适应阈值已缓解，silero 会话级替换在计划中）
- whisper 引擎的繁简漂移由 initial_prompt + opencc 双保险处理