ASR 服务（sherpa-asr-online-server）

服务定位

sherpa-asr-online-server 是一个 C++ WebSocket 流式 ASR 服务，使用 sherpa-onnx 的流式 zipformer + silero-vad。协议沿用 mod_audio_fork 子协议约定，因此可被 FreeSWITCH mod_audio_fork 直接当作 ASR 后端，也可被任意 WebSocket 客户端调用。

特性：

• HTTP GET /health 健康检查
• WebSocket /audio，子协议 audio.drachtio.org
• 客户端先发一帧 metadata 文本，再持续推 16kHz / mono / PCM16 二进制音频
• 服务端按 partial / final 返回 type=transcription 的 JSON 文本帧
• 客户端发送 0 长度二进制帧或关闭连接时，服务自动 flush 最后的识别结果
• 固定数量 I/O worker 线程 + select 事件循环
• 启动时预热 sessionPoolSize 个 ASR session

构建与运行

1
2
3
4
5

cd sherpa-asr-online-server
.\build.ps1
# 等价于：
# cmake -S . -B build -G "Visual Studio 17 2022" -A x64
# cmake --build build --config Release --target sherpa_asr_online_server

启动：

1
2
3
4

cd .\build\Release
.\sherpa_asr_online_server.exe
# 或显式指定配置：
# .\sherpa_asr_online_server.exe C:\path\to\config.json

健康检查：

1

curl http://127.0.0.1:10096/health

返回：

1
2
3
4
5
6
7
8

{
  "ok": true,
  "service": "sherpa-asr-online-server",
  "activeSessions": 3,
  "maxSessions": 16,
  "wsPath": "/audio",
  "ioWorkers": 4
}

WebSocket 协议

握手

1
2
3
4
5
6
7

GET /audio HTTP/1.1
Host: 127.0.0.1:10096
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Version: 13
Sec-WebSocket-Key: <base64-16>
Sec-WebSocket-Protocol: audio.drachtio.org

校验：

• 必须 Sec-WebSocket-Version: 13
• 必须 Upgrade: websocket + Connection: upgrade
• 若 wsSubprotocol 非空（默认 audio.drachtio.org），请求必须带对应 token
• 受 maxSessions 限流，超出返回 503

握手成功后服务端立即为连接绑定一个预热的 ASR session（recognizer + VAD 已就绪），日志 ws-<n> websocket session started on worker=<i>。

客户端 → 服务端

1. metadata 文本帧（第一帧）

任意 JSON 文本，服务端会尝试解析 uuid | channel_uuid | call_uuid | sessionId | session_id 任一字段作为日志和录音文件名的 channelUuid。mod_audio_fork 默认发：

1

{ "uuid": "fs-channel-uuid", "callerId": "10086", "direction": "inbound" }

后续 text frame 默认丢弃，debugLogTextFrames=true 时打印。

2. 二进制音频帧

16kHz / 单声道 / PCM16 little-endian 原始采样。

• 帧大小受 maxFrameBytes 限制（默认 4MB），超过即触发 1002 协议错误关闭
• 任意时刻发 0 长度二进制帧 = “flush”：服务端立刻 flush 当前 segment 并发出 final
• 服务端不做重采样，上游非 16kHz 会导致 partial 全错

3. 控制帧

• 0x8 Close：服务端先 flush final，再回 1000 bye close
• 0x9 Ping：原样回 Pong
• 0xA Pong：忽略
• 其他 opcode：发 error 后回 1003 unsupported opcode 并关闭
• 不支持分片帧（FIN=0 或 opcode=0x0），收到回 1002 protocol error

服务端 → 客户端

服务端通过文本帧下发 JSON 事件，按 type 分三类。

type=transcription

每次 partial 推送 / final 段完成 / 客户端 flush 都可能发一条：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

{
  "type": "transcription",
  "data": {
    "text": "你好世界",
    "isFinal": false,
    "utteranceIndex": 3,
    "speechStarted": true,
    "speechActive": true,
    "speechSegmentDetected": true,
    "speechSegmentCompleted": false,
    "endpointDetected": false,
    "serverSessionId": "ws-12",
    "channelUuid": "fs-channel-uuid",
    "metadataText": "{\"uuid\":\"fs-channel-uuid\",...}",
    "finalReason": "endpoint",
    "flushReason": "client-close"
  }
}

partial 节流：同一句话内，partial 最快每 partialMinIntervalMs ms 下发一次；文本未变化的事件不重发。

type=error

1

{ "type": "error", "data": { "message": "ASR accept failed: <reason>" } }

error 通常紧随 close：

• ASR AcceptPcm16 失败 → 1011 内部错误
• 协议错误（帧过大 / 不支持的 opcode）→ 1002 / 1003

type=disconnect

服务端主动断开前，可能先发：

1

{ "type": "disconnect", "data": { "reason": "<message>" } }

连接生命周期

1
2
3
4
5
6
7
8
9
10
11
12
13

client                       server
  |--- TCP connect --------->|
  |--- HTTP GET /audio ----->|
  |<-- 101 Switching Proto --|
  |--- TEXT metadata ------->|     (acquire session)
  |--- BIN PCM16 frame ----->|
  |<-- transcription partial-|
  |--- BIN PCM16 frame ----->|
  |<-- transcription final --|     (segment_completed / endpoint)
  |--- BIN zero-length ----->|     (flush)
  |<-- transcription final --|     (flushReason=zero-length-binary)
  |--- CLOSE frame --------->|
  |<-- CLOSE 1000 bye -------|

关闭路径：

关键配置

服务与 IO

Sherpa ASR / VAD

吞吐调优

• ioWorkers：每个 worker 受 FD_SETSIZE 约束（Windows 默认 1024，本进程编译期固定 1024，单 worker ~992 连接）
• sessionPoolSize：建议接近或等于 maxSessions，避免连接抖动反复冷启动 recognizer / VAD
• numThreads：ONNX 推理线程
• partialMinIntervalMs / decodeBatchMs：影响 partial 实时性 vs CPU 占用
• recordAudioEnabled：默认关闭，只在排查问题时打开

与 FreeSWITCH 集成

通过 uuid_audio_fork：

1

fs_cli -x "uuid_audio_fork <uuid> start ws://127.0.0.1:10096/audio mono 16k callflow_asr {}"

callflow-esl 默认配置：

1
2
3
4
5
6
7
8

{
  "audioFork": {
    "wsUrl": "ws://192.168.2.246:10096/audio",
    "bugName": "callflow_asr",
    "mixType": "mono",
    "sampleRate": "16k"
  }
}

业务通过 ctx.hear({...}) 或 ctx.callHear(...) 触发，runtime 内部负责 audio_fork 启停与 transcription 事件订阅。

排查识别问题

开启上行音频录制

1
2
3
4

{
  "recordAudioEnabled": true,
  "recordAudioDir": "recordings"
}

每个 WebSocket 会话会把 PCM16 二进制保存为 .wav：

1

asr-<YYYYMMDD-HHMMSS-mmm>-<serverSessionId>[-<channelUuid>].wav

放回 sherpa-demo/demo_online_asr.exe 复现，确认是模型问题还是网络问题。

调试日志

测试客户端

仓库内 request-asr.js 用原生 net + crypto 实现最小 WebSocket 客户端，按本协议发送 models/sherpa-onnx-sense-voice/test_wavs/zh_vad.wav 的 PCM16：

1

node .\request-asr.js

打印每条 JSON 事件。

局限

参考

• 协议详细描述：仓库 sherpa-asr-online-server/README.md
• mod_audio_fork 子协议：见 mod_audio_fork