协议契约与接口说明文档 (funasr-asr-server)

本文档详细说明 funasr-asr-server 对外暴露的 10099 端口 WebSocket 流式协议 与 10094 端口 HTTP 离线转写协议，并提供调试测试客户端的使用方法。

---

1. WebSocket 流式推流接口 (端口 10099)

1.1 连接与握手

• URL: ws://<host>:10099/audio（或 ws://<host>:10099/）
• Subprotocol（子协议）: audio.drachtio.org（完全兼容 FreeSWITCH mod_audio_fork 与 drachtio 生态）
• 握手响应: 返回 101 Switching Protocols 并回显 Sec-WebSocket-Protocol: audio.drachtio.org。如果当前并发会话达到 concurrency.maxSessions，直接返回 503 Service Unavailable 拒绝连接。

1.2 客户端入站推流帧规范

客户端在建立连接后，按照如下时序发送数据帧：

1. 首帧（可选）：JSON 格式元数据

   {
     "uuid": "channel-uuid-12345",
     "sample_rate": 16000,
     "channels": 1,
     "turnId": 1
   }

   服务端会解析其中的 uuid 作为日志追踪标识，并在下发的事件中回显 metadata。
2. 后续帧：PCM16 音频二进制数据包 (Binary Frame)
   • 格式：16kHz 采样率、16-bit 线性定点数、Little-Endian（低位在前）、单声道 PCM；
   • 节奏：推荐按照真实语音流时间戳推送（例如每 20ms 发送一包，每包 320 个采样点 = 640 字节）；
3. 结束帧：零长度二进制帧 (Zero-length Binary Frame)
   • 发送一个 byte[0] 的空二进制包，通知服务端此段音频结束，促使服务端触发终态定稿（Final）并关闭当前会话。

1.3 服务端出站事件帧规范 (JSON 格式)

服务端实时向下游推送 JSON 文本帧。帧结构严格对齐平台标准 transcription 事件：

{
  "event": "transcription",
  "text": "你好我想咨询一下业务",
  "isFinal": false,
  "serverSessionId": "ws-1",
  "utteranceIndex": 1,
  "speechStarted": false,
  "speechActive": true,
  "speechSegmentDetected": true,
  "speechSegmentCompleted": false,
  "snippetTime": 0.02
}

关键字段含义

字段名	类型	说明
event	string	固定为 "transcription"
text	string	识别文字内容（Partial 阶段为当前流式字，Final 阶段为带标点的整句定稿）
isFinal	boolean	false 表示流式增量中间结果；true 表示本句终结定稿结果
speechStarted	boolean	瞬时上升沿标记。当前语音段首次开嗓时为 true（下游可凭此打断 TTS 播报）
speechActive	boolean	当前帧是否为人声活动
speechSegmentCompleted	boolean	瞬时下降沿标记。检测到本句语音结束切句时为 true
serverSessionId	string	服务端生成的唯一会话标识（如 ws-1）
snippetTime	number	当前处理音频包的物理时长（秒，如 0.02 代表 20ms）

---

2. HTTP 离线与 Whisper 接口 (端口 10094)

2.1 健康检查探针

• 请求: GET http://<host>:10094/health
• 响应 (200 OK):

  {
    "ok": true,
    "service": "fanasr-asr-offline-server",
    "active_profile": "funasr-2pass",
    "active_model": "funasr-2pass",
    "description": "FunASR unified HTTP offline ASR server in pure Rust",
    "total_requests": 128
  }

2.2 标准离线转写接口

• 请求: POST http://<host>:10094/asr（或 POST /recognize）
• 请求体:
  • 支持 multipart/form-data（表单字段名为 file 上传 wav/mp3 音频文件）；
  • 或直接发送 application/octet-stream（原始 PCM16 二进制音频数据）。
• 响应 (200 OK):

  {
    "ok": true,
    "text": "你好，我想咨询一下业务。",
    "duration": 2.45,
    "latencyMs": 142
  }

2.3 OpenAI Whisper 规范兼容接口

• 请求: POST http://<host>:10094/v1/audio/transcriptions
• 请求头: Content-Type: multipart/form-data
• 表单参数:
  • file: 上传的音频文件（支持 wav, mp3, m4a, flac 等，服务内部自动调用 FFmpeg 转换为 16kHz PCM16）；
  • model: 选填，模型名称；
  • response_format: 选填，支持 json 或 text。
• 响应 (200 OK):

  {
    "text": "你好，我想咨询一下业务。"
  }

---

3. 本地验证与联调测试工具

项目自带了完整的 Node.js 测试客户端脚本，位于项目根目录下：

3.1 真实 WAV 文件流式推流测试

# 按真实通话节奏（每 20ms 推一包）推流识别：
bun run ./onnx-platform/funasr-asr-server/request-ws.js "path/to/test.wav"

测试脚本会自动完成：

1. 校验并提取 WAV 头；
2. 若采样率不是 16kHz 或非单声道，自动重采样重整；
3. 按照 20ms 间隔逐步推送，实时打印终端返回的 Partial 与 Final 结果。

3.2 极速推流模式

# 以不限流极速推流模式测试服务并发性能与解码吞吐：
bun run ./onnx-platform/funasr-asr-server/request-ws.js "path/to/test.wav" --fast

3.3 静音防误打断回归测试

# 发送 3 秒全零 PCM 静音数据，断言绝不产生虚假文字或误触发 VAD：
bun run ./onnx-platform/funasr-asr-server/request-ws.js --silence

3.4 HTTP 离线识别测试

# 标准接口测试
curl -X POST http://127.0.0.1:10094/asr -F "file=@test.wav"

# OpenAI 兼容接口测试
curl -X POST http://127.0.0.1:10094/v1/audio/transcriptions -F "file=@test.wav"