sherpa-asr-online-server

基于 sherpa-onnx 的 C++17 流式 ASR WebSocket 服务。它接收 16kHz、单声道、PCM16 音频， 结合在线 Zipformer 与 Silero VAD 返回 partial / final 文本事件，主要供 FreeSWITCH mod_audio_fork 使用。

专题导航

• 配置参考
• WebSocket 协议
• 集成与排障
• 全仓服务目录

目录结构

sherpa-asr-online-server/
├── src/                               # HTTP/WebSocket、会话与工作线程
├── sherpa_asr_vad_online_bridge.*     # 与主服务解耦的识别桥接层
├── config.json                        # 外置配置
├── request-asr.js                     # 本地音频验证客户端
├── build.ps1 / build.sh               # Windows / Linux 构建入口
├── build/                              # 构建目录，不提交
└── target/                             # 可运行安装目录，不提交

模型从 onnx-platform/models/ 解析；sherpa-onnx SDK 来自同级 onnx-platform/sherpa-onnx/。不要随意移动模型或 SDK 文件。

构建

Windows PowerShell：

.\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

Linux x64：

./build.sh

修改服务代码或 bridge 后至少重新构建对应平台。

运行

仓库根目录：

bun run dev:asr

也可进入安装目录直接运行：

cd target\win_x64
.\sherpa_asr_online_server.exe

服务默认读取模块根目录 config.json；安装目录中的可执行文件也会携带外置配置和所需运行库。 监听端口、健康路径与 WebSocket 地址以服务目录和实际配置为准。

配置

启动前至少校准：

• server：监听地址、健康路径、WebSocket 路径与子协议。
• concurrency / socket：会话、线程、队列与帧大小限制。
• recording / logging：调试录音和日志开关。
• asr.activeModel / asr.models：在线模型 profile 与模型文件。
• asr：采样率、partial 节流、解码、热词和空闲 final。
• vad：Silero VAD 模型与分段阈值。

完整字段、模型切换与吞吐建议见配置参考。

健康检查

先启动服务，再请求服务目录列出的健康 URL。成功响应应表明服务 就绪并包含当前监听、模型和容量信息。健康检查成功只代表模型已加载，不代表音频格式或 WebSocket 客户端协议正确。

最小 WebSocket 验证

使用仓库测试客户端发送本地 16kHz 单声道 PCM16 / WAV 音频：

bun run .\request-asr.js <audio-file>

客户端升级、控制消息、二进制帧和服务端事件格式见 WebSocket 协议。FreeSWITCH 接入和识别问题定位见 集成与排障。

协议

本节已迁移到WebSocket 协议，原 README 路由继续作为快速入口。

调用示例

Node / Bun 客户端与 mod_audio_fork 配置示例见 集成与排障。

排查识别问题

按健康状态、升级握手、音频格式、VAD、模型路径和日志顺序检查，详见 集成与排障。

日志

关键会话、识别状态和调试开关见集成与排障。

注意事项

服务没有鉴权，建议只在可信网络运行；任务中启动的服务必须在结束前停止。