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
6

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

构建目录保留在 build\win_x64\，**可运行的发布产物安装到 target\win_x64\**（仅含可执行文件、
config.json 与运行时 DLL）。bun run dev / bun run dev:asr 即从这里启动它。

启动：

1
2
3
4

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

从 target\win_x64\ 启动时优先改该目录下的 config.json；重新构建不会自动覆盖已有的 target\win_x64\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 默认丢弃，logging.debugTextFrames=true 时打印。

2. 二进制音频帧

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

• 帧大小受 socket.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 -------|

关闭路径：

关键配置

config.json 按域分组：server / concurrency / socket / logging /
recording / asr / vad（与仓库 onnx-platform/sherpa-asr-online-server/README.md 一致）。

server — 监听

concurrency — 并发

socket — 套接字缓冲

logging — 日志

recording — 录音

asr — 识别

ASR 模型采用 asr.activeModel + asr.models profile 表结构：在 asr.models 下
声明多个模型 profile，用 asr.activeModel 指定当前加载哪一个。切换模型只改
asr.activeModel，无需改动各 profile 的文件路径。默认配置声明两个 profile：中文
int8 流式 zipformer（默认）与中英双语。

asr.models 每个 profile 的 modelDir 相对仓库 onnx-platform/models/ 解析，绝对路径
原样使用；profile 内的模型文件路径相对 modelDir 解析。

vad — 语音活动检测（强制启用，无开关）

VAD 强制启用，没有 enableVad 开关；endpoint 检测走 sherpa 默认，不在配置中暴露
enableEndpoint / endpointRule* 字段。旧版扁平字段 asrModelName / asrEncoder /
asrDecoder / asrJoiner / asrTokens / asrBpeVocab / asrModelType / asrModelingUnit /
vadModel / listenHost / listenPort / recordAudioEnabled / recordAudioDir /
enableVad / enableEndpoint / endpointRule* 已移除，迁移时改写为上述分组结构。完整字段见仓库
onnx-platform/sherpa-asr-online-server/README.md。

吞吐调优

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

与 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
5
6

{
  "recording": {
    "enabled": true,
    "dir": "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 事件。

局限

参考

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