145 lines
7.6 KiB
Markdown
145 lines
7.6 KiB
Markdown
# Realtime ASR WebSocket Optimization Demo
|
||
|
||
这是一个独立的实时 ASR WebSocket 验证项目，放在模型部署项目 `demo` 下，但不导入、不启动、也不调用仓库根目录的原始 `app/`。
|
||
|
||
## 验证目标
|
||
|
||
- 浏览器麦克风或按实时速度发送的 PCM/WAV 音频通过本项目 WebSocket 发送。
|
||
- 同一 `sentence_id` 的 partial、final 和后续更新覆盖同一条 raw segment。
|
||
- raw segment 与前端 display block 分离，避免把物理切段直接等同于展示换行。
|
||
- 小于 1.6 秒且带有 `short_attach` / `embedding_attach` 策略的实名结果降级为 pending。
|
||
- 不把 embedding 字段写入 demo 状态池。
|
||
- 只有相邻且身份可信的 segment 才合并；A→B→A 保持时间顺序。
|
||
- 记录 partial 首次延迟、final 延迟、partial 修订次数和服务端返回时间范围。
|
||
- 每个实时 turn 单独提交声纹特征，由辅助服务维护本 WebSocket session 的在线聚类中心。
|
||
|
||
本次修复、诊断状态和部署验收步骤见 [FIXES.md](FIXES.md)。ASR 继续使用已部署的独立 vLLM；已有 vLLM 服务时无需重复启动或下载模型。
|
||
|
||
当前 VLLM 端点提供的是同步 OpenAI 音频转写接口，没有暴露原生
|
||
`create_stream/feed_stream/finish_stream`。因此本项目仍然是真实 WebSocket
|
||
音频流：麦克风 PCM 到达后立即进入 VAD，按窗口调用 VLLM 生成 partial；它不会
|
||
等整段音频结束。`native_partial_supported=false` 只表示模型 HTTP 接口本身
|
||
不是原生 ASR stream，不伪造不存在的能力。
|
||
|
||
## 启动
|
||
|
||
需要启动两个模型服务和一个 WebSocket 页面：VLLM 只负责 ASR，辅助服务负责
|
||
VAD、CAM++ 声纹模型及在线聚类，WebSocket 只做音频流编排，不导入原项目代码。
|
||
|
||
先在 `demo` 目录下载 ASR 和辅助模型，并启动 VLLM：
|
||
|
||
```powershell
|
||
cd D:\github-project\ASR\Qwen-Asr\demo
|
||
python scripts\download_models.py
|
||
python scripts\serve.py
|
||
```
|
||
|
||
另一个终端启动辅助模型服务：
|
||
|
||
```powershell
|
||
cd D:\github-project\ASR\Qwen-Asr\demo
|
||
pip install -r requirements-auxiliary.txt
|
||
python scripts\auxiliary_server.py
|
||
```
|
||
|
||
另开一个终端启动 WebSocket 页面：
|
||
|
||
```powershell
|
||
cd D:\github-project\ASR\Qwen-Asr\demo\realtime_asr_optimization_demo
|
||
python -m venv .venv
|
||
.\.venv\Scripts\Activate.ps1
|
||
pip install -r requirements.txt
|
||
python server.py --no-browser
|
||
```
|
||
|
||
页面服务默认监听 `0.0.0.0:8082`，端口在 `server.py` 顶部的 `WEB_PORT` 内部变量中维护。
|
||
VLLM 默认地址为 `http://127.0.0.1:9950/v1`，辅助服务默认地址为
|
||
`http://127.0.0.1:8010`。可通过环境变量切换到远程服务：
|
||
|
||
```powershell
|
||
$env:MODEL_SERVICE_URL = 'http://127.0.0.1:9950/v1'
|
||
$env:AUXILIARY_SERVICE_URL = 'http://127.0.0.1:8010'
|
||
python server.py --no-browser
|
||
```
|
||
|
||
如果服务器端口已通过 VS Code Remote/端口转发映射到本机，保持上述两个
|
||
`127.0.0.1` 地址即可：本地 WebSocket 只负责编排，ASR 和 VAD/CAM++ 推理仍在
|
||
服务器 GPU 服务中完成。先访问 `http://127.0.0.1:9950/v1/models` 与
|
||
`http://127.0.0.1:8010/health`，分别确认 VLLM 模型和辅助模型服务可达且 `ready=true`。
|
||
|
||
服务器部署时使用 `--no-browser`，然后在客户端浏览器访问 `http://服务器IP:8082`。如需让启动日志显示服务器域名或 IP，可设置 `WEB_DISPLAY_HOST`；它只影响提示文本，不改变监听地址。
|
||
|
||
辅助服务启动后可用 `http://服务器IP:8010/health` 检查模型状态。WebSocket
|
||
收到聚类服务错误时仍会继续输出 ASR，但对应片段会显示“未知说话人”；详细的
|
||
`speaker_reason` 可将鼠标悬停在标签上查看，事件日志仍会显示 `speaker_warning`，
|
||
便于区分“模型未归类”和“ASR 失败”。
|
||
|
||
声纹服务的实时路径必须通过 ModelScope pipeline 的公开接口提取 embedding：
|
||
`pipeline([wav_path], output_emb=True)`。不能绕过 pipeline 预处理后直接调用
|
||
`pipeline.model`，否则采样率、声道和 waveform 预处理不会执行，部分 ModelScope
|
||
版本会直接抛异常，WebSocket 仍会继续输出 ASR 并把说话人保留为 pending。
|
||
更新辅助服务代码后需要重启 `python scripts/auxiliary_server.py`，仅重启页面
|
||
服务不会替换已经驻留在 GPU 中的旧辅助服务进程。
|
||
|
||
## 页面操作
|
||
|
||
1. 选择 Mic 或 File。
|
||
2. 点击开始，浏览器通过 `/ws` 建立本项目 WebSocket。
|
||
3. 页面展示腾讯 Demo 风格的气泡；麦克风或 PCM/WAV 文件按流式方式输入，partial 会在讲话过程中实时刷新。
|
||
4. VAD 检测到静音、或活跃 turn 内声纹窗口比对检出换人时提交当前 turn，先返回 pending，再异步更新说话人。
|
||
5. 停止会发送 `stop`，服务端完成当前 turn 和 speaker 队列后再发送 `end`。
|
||
6. `abort` 只取消会话，不提交当前片段。
|
||
|
||
## WebSocket 消息
|
||
|
||
客户端首条消息：
|
||
|
||
```json
|
||
{
|
||
"type": "start",
|
||
"source": "mic",
|
||
"model_service_url": "http://127.0.0.1:9950/v1",
|
||
"model": "Qwen/Qwen3-ASR-0.6B",
|
||
"speaker_diarization": 1,
|
||
"sentence_strategy": 0,
|
||
"enable_native_partial_stream": true,
|
||
"partial_interval_ms": 1200,
|
||
"max_segment_sec": 12,
|
||
"display_merge": true,
|
||
"speaker_window_ms": 1000,
|
||
"speaker_switch_similarity": 0.5
|
||
}
|
||
```
|
||
|
||
`speaker_window_ms` 与 `speaker_switch_similarity` 可省略，默认读取环境变量
|
||
`SPEAKER_TURN_WINDOW_MS`（1000）和 `SPEAKER_SWITCH_SIMILARITY`（0.5）。
|
||
|
||
随后持续发送 16kHz、单声道、PCM16 二进制音频；文件模式仅支持 PCM/WAV，结束发送 `{"type":"eof"}`，停止发送
|
||
`{"type":"stop"}`，取消发送 `{"type":"abort"}`。每个已完成 turn 会向辅助服务
|
||
发送一次 `/v1/speaker/resolve`，只包含当前 turn 音频和 session_id，不会重复上传整段会话。
|
||
换人强制切段产生的边界段会附带 `speaker_verified=0`：辅助服务仍返回匹配标签，
|
||
但不更新簇质心、不建立新簇。活跃 turn 内另有窗口比对请求 `/v1/speaker/embedding`
|
||
（multipart 音频，返回 `{"ok": true, "embedding": [...]}`），只出向量、零聚类副作用。
|
||
辅助服务 `speaker_protocol_version` 为 3；旧版辅助服务缺少窗端点时 WebSocket 侧
|
||
探测一次即自动停用切换感知切段并发送 `speaker_warning`，不影响 ASR。
|
||
|
||
服务端会发送 `start`、`sentences`、`display_state`、`metrics`、`speaker_warning`、`draining`、`end` 和 `error`。
|
||
页面用带 `revision` 的 `display_state` 渲染，以 `block_id` 标识展示块；`sentences` 保留原始片段及诊断状态。
|
||
停止后必须等待 `end`，其中包含完整 `sentences` 和 `display_blocks`，不能提前关闭连接。
|
||
`sentences` 中 `sentence_type=0` 是 partial，`sentence_type=1` 是 final；同一个
|
||
`sentence_id` 必须覆盖更新而不是追加。`sentence_strategy=0` 使用约 800ms
|
||
静音切句，`sentence_strategy=1` 使用约 1400ms 静音切段，更适合段落模式。
|
||
静音阈值之外还有说话人切换感知切段：活跃 turn 内每积累约 1 秒有声窗口就与
|
||
辅助服务比对一次声纹，与当前 turn 参考向量余弦低于阈值时在“停顿≥200ms 后的
|
||
首个起音”处强制切开，头段 final 的 `commit_reason` 为 `speaker_change`。这覆盖
|
||
上一位尾句与下一位间隔不足静音阈值（常见 200~600ms 换话停顿）被合成一句的问题。
|
||
|
||
## 目录
|
||
|
||
- `server.py`：本地 HTTP 页面和 WebSocket 会话编排。
|
||
- `model_service.py`：独立 VLLM OpenAI 音频接口适配层。
|
||
- `auxiliary_service.py`：独立辅助模型 HTTP 接口适配层。
|
||
- `speaker_assembler.py`：raw segment、speaker evidence 和 display block 状态机。
|
||
- `static/`：麦克风/文件测试页面。
|
||
- `tests/`：只测试本项目状态合并和音频转换逻辑。
|