ASR 服务 API 文档

1. 概述

本文档描述 ASR 服务对外提供的 HTTP 与 WebSocket 接口规范，包括鉴权、模型查询、健康检查及实时语音识别能力。

服务地址示例：http://127.0.0.1:8250、ws://127.0.0.1:8250/ws/asr

---

2. 路由总览

HTTP

• POST /api/token 获取访问 Token
• POST /api/verify 验证 Token（从 Header 或 Query 取 Token）
• GET /api/models 获取支持的 ASR 服务类型及模型列表
• GET /health 健康检查

WebSocket

• GET /ws/asr ASR 双向流网关

---

3. 网关协议支持矩阵

链路	支持协议	说明
客户端 -> ASR 网关	HTTP/1.1, WebSocket	HTTP 用于 Token/模型/健康检查；WebSocket 用于实时语音流
ASR 网关 -> 上游识别服务	WebSocket (ws/wss)	根据配置 asr.services.<type>.ssl 选择 ws 或 wss

网关不提供 gRPC / SSE 接口。

---

4. HTTP 接口

GoFrame 已启用 MiddlewareHandlerResponse，HTTP 成功响应统一为：

{
  "code": 0,
  "message": "",
  "data": {}
}

失败时 code != 0，message 为错误信息。

4.1 获取 Token

• 方法：POST
• 路径：/api/token
• Content-Type：application/json

请求体：

字段	类型	必填	说明
api_key	string	是	与配置 security.apiKey 一致
user_id	string	是	业务用户标识
expires_in	int	否	秒；<=0 时回退配置 jwt.expire（默认 3600）

示例：

curl -X POST http://127.0.0.1:8250/api/token \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "ascjajwfjawjkfio2iiuudahha",
    "user_id": "user123",
    "expires_in": 3600
  }'

成功示例：

{
  "code": 0,
  "message": "",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "expires_in": 3600,
    "expires_at": "2026-05-15T10:30:00"
  }
}

4.2 验证 Token

• 方法：POST
• 路径：/api/verify

Token 提取顺序：

1. Authorization: Bearer <token>
2. Query 参数 token

成功示例：

{
  "code": 0,
  "message": "",
  "data": {
    "valid": true,
    "user_id": "user123",
    "expires_at": "2026-05-15T10:30:00"
  }
}

4.3 获取支持模型

• 方法：GET
• 路径：/api/models

返回内容按 asr_service_type 分组，当前仅提供 funasr。

响应示例：

{
  "code": 0,
  "message": "",
  "data": {
    "services": [
      {
        "asr_service_type": "funasr",
        "models": [
          {
            "code": "Fun-ASR-MLT-Nano-2512",
            "name": "多语言模型(Fun-ASR-MLT-Nano-2512)"
          },
          {
            "code": "SenseVoiceSmall",
            "name": "多语言模型(SenseVoiceSmall)"
          }
        ]
      }
    ]
  }
}

4.4 健康检查

• 方法：GET
• 路径：/health

示例：

{
  "code": 0,
  "message": "",
  "data": {
    "status": "healthy",
    "timestamp": "2026-05-15T09:30:00+08:00",
    "active_connections": 2
  }
}

---

5. WebSocket 接口

5.1 连接地址

ws://127.0.0.1:8250/ws/asr

连接示例：

wss://asr.iprtapp.com/ws/asr?asrServiceType=funasr&hotwordCacheId=hotword_label_daily_v1&language=zh-CN&model=SenseVoiceSmall&token=<JWT_TOKEN>

5.2 Query 参数

参数	必填	说明
token	是	JWT Token
model	否	模型编码，默认会回退
language	否	语言偏好（用于热词查询和自动映射到 svs_lang）
hotwordCacheId	否	热词缓存 ID（服务端按 ID+语言回源 DB 查热词）
asrServiceType	否	ASR 服务类型，固定为 funasr

5.3 参数回退与纠正规则

网关会对 asrServiceType 与 model 进行纠正：

1. asrServiceType 未传或非法时，回退为 funasr。
2. model 未传或非法时，回退为 SenseVoiceSmall。
3. 网关对外 asr_service_type 固定返回 funasr。
4. 网关内部按 model 路由到对应 host/port： SenseVoiceSmall -> asr.services.funasr-sensevoice； Fun-ASR-MLT-Nano-2512 -> asr.services.funasr。

客户端应显式传 model 和 asrServiceType，避免依赖回退逻辑。

5.4 握手阶段失败响应（HTTP）

以下情况发生在 WS 升级前，返回普通 JSON：

• 连接数超限：{"error":"服务器连接数已满","code":503}
• 缺少 token：{"error":"缺少token参数","code":401}
• token 无效：{"error":"Token无效或已过期","code":401}

5.5 连接成功消息（网关 -> 客户端）

固定字段：

字段	类型	说明
type	string	固定为 connected
user_id	string	用户标识
language	string	连接语言参数
model	string	连接模型参数
hotword_cache_id	string	热词缓存 ID
asr_service_type	string	服务类型，固定为 funasr
message	string	固定为 连接成功

{
  "type": "connected",
  "user_id": "user123",
  "language": "zh-CN",
  "model": "SenseVoiceSmall",
  "hotword_cache_id": "12345",
  "asr_service_type": "funasr",
  "message": "连接成功"
}

5.6 客户端发送消息

网关识别两类消息：

• 文本帧（JSON）：透传前会补充/覆盖部分字段
• 二进制帧：视为音频数据直接转发给上游

文本帧固定字段（网关转发给上游）：

字段	类型	必填	默认值	说明
mode	string	否	offline	识别模式
wav_name	string	否	audio	音频标识
is_speaking	bool	否	true	语音状态；false 时触发结束信号
wav_format	string	否	pcm	音频格式
audio_fs	int	否	16000	采样率
chunk_size	array	否	[5,10,5]	分块参数
itn	bool	否	true	ITN 开关
hotwords	string	否	""	热词 JSON 字符串
svs_lang	string	否	""/auto映射	SenseVoice 语种
retain_asr_record	bool	否	false	是否保留本次识别记录（设备级开关）；当该字段为 true 或配置 asr.recording.globalEnabled=true 时，网关会在停止帧或断开连接时写入 b_asr_record，并上传录音到在线存储后写入 b_file（业务类型：recording，支持 oss/s3）

文本帧示例：

{
  "mode": "offline",
  "wav_name": "mic",
  "is_speaking": true,
  "chunk_size": [5, 10, 5],
  "wav_format": "pcm",
  "audio_fs": 16000,
  "itn": true
}

文本帧处理规则：

1. 若 is_speaking=false，网关不会透传原 JSON，而是向上游发送结束信号 {"is_speaking":false}。
2. 若消息带 hotwords，网关将其标准化后缓存到连接上下文。
3. 若未带 hotwords 且有 hotwordCacheId，首帧时网关会尝试从本地缓存/数据库回填热词。
4. language 优先级：连接 URL 参数 language -> 首帧 language 覆盖连接值。
5. 文本帧会被标准化为上表固定字段集合后再转发。
6. Query 参数 model 仅用于连接级模型选择，不会回填到文本帧消息体。
7. 若消息未带 svs_lang 且连接有 language，网关会自动映射： zh/en/ja/ko/yue/fr/de/es/pt/ru/ar/th/vi/id/it 其余回退 auto。

二进制帧发送规范（依据首帧配置）：

1. 首帧文本消息发送完成后，再开始发送二进制音频帧。
2. 网关对二进制帧不做内容解析，按原样转发到上游 ASR 服务。
3. 二进制帧的发送方式由首帧参数决定，重点字段为：mode、wav_format、audio_fs、chunk_size。

首帧 mode	二进制帧发送方式	结束方式
offline	可连续发送完整音频内容（可分片发送）	发送文本帧 {"is_speaking": false}
online	按小块持续发送流式音频（建议固定块大小）	发送文本帧 {"is_speaking": false}
2pass	与 online 相同，按流式分块发送	发送文本帧 {"is_speaking": false}

二进制音频内容说明：

• wav_format=pcm：发送裸 PCM 数据（通常不含文件头）。
• wav_format=wav/mp3/mp4/flac...：按对应编码后的音频字节流发送。
• audio_fs 表示音频采样率（例如 16000）。
• chunk_size 用于上游流式处理参数，推荐与实际二进制分片节奏保持一致。

5.7 结果消息（网关 -> 客户端）

网关会把上游结果转为统一结构：

{
  "type": "result",
  "mode": "2pass-online",
  "text": "识别文本",
  "is_final": false,
  "asr_service_type": "funasr",
  "model": "SenseVoiceSmall",
  "timestamp": [[0, 120], [120, 260]],
  "detected_language": "en",
  "emotion": "neutral",
  "event": "speech"
}

上游若返回带标签文本，例如： "<|zh|><|NEUTRAL|><|Speech|> 牛排。" 网关会清洗为：

• text: "牛排。"
• detected_language: "zh-CN"

固定字段：

字段	类型	说明
type	string	固定为 result
mode	string	上游模式，缺省补 2pass
text	string	识别文本
is_final	bool	最终结果标识
asr_service_type	string	服务类型，固定为 funasr
model	string	连接模型
timestamp	array/null	时间戳
detected_language	string	上游识别语种（标准化，如 zh -> zh-CN）
language	string	连接语种回传
emotion	string/null	情绪信息
event	string/null	事件信息

错误消息示例：

固定字段：

字段	类型	说明
type	string	固定为 error
error	string	错误信息
asr_service_type	string	服务类型，固定为 funasr
model	string	连接模型

{
  "type": "error",
  "error": "错误描述",
  "asr_service_type": "funasr",
  "model": "SenseVoiceSmall"
}

---

6. 音频与连接约束（默认配置）

• 最大并发连接数：1000（websocket.maxConnections）
• 单连接超时：300s（websocket.timeout）
• 建议采样率：16000
• 建议音频块大小：8000 bytes

---

7. ASR Gateway 配置（config.yaml）

以下配置用于 ASR 服务自身，在线存储配置按本地配置文件读取，不依赖数据库在线存储配置表。

asr:
  defaultServiceType: "funasr"
  hotwordCache:
    # 热词缓存仅使用进程内本地缓存，不依赖 Redis
    localExpireSeconds: 1800
  recording:
    # 全局录制开关：true 时，默认录制所有会话
    globalEnabled: false
    defaultDealerId: "system"
    defaultOwnerId: "system"
    storage:
      # 存储服务类型：oss 或 s3
      providerType: "oss"
      # 对象键规则：{basePath}/asr/{dealerId}/{yyyy-MM-dd}/{filename}
      # 路径规则与 ByteOne 主项目文件存储规则保持一致
      basePath: "byteone"
      oss:
        endpoint: "oss-cn-xxxx.aliyuncs.com"
        region: "cn-xxxx"
        accessKeyId: "REPLACE_WITH_OSS_ACCESS_KEY_ID"
        accessKeySecret: "REPLACE_WITH_OSS_ACCESS_KEY_SECRET"
        bucket: "your-oss-bucket-name"
      s3:
        # 至少配置一个 endpoint；internalEndpoint 优先用于服务内部访问
        internalEndpoint: "s3.internal.example.com"
        externalEndpoint: "s3.amazonaws.com"
        region: "us-east-1"
        accessKeyId: "REPLACE_WITH_S3_ACCESS_KEY_ID"
        secretAccessKey: "REPLACE_WITH_S3_SECRET_ACCESS_KEY"
        bucket: "your-s3-bucket-name"

---

8. 版本信息

• 文档版本：v3.1
• 更新日期：2026-06-02