本文介绍 Fun-ASR-Realtime 实时语音识别服务中客户端通过 WebSocket 发送给服务端的客户端事件,包括 run-task(启动任务)、finish-task(结束任务)等指令的数据结构与字段含义。
run-task
启动语音识别任务,设置模型、音频格式、采样率等参数。
发送时机:建立 WebSocket 连接后立即发送。
响应事件:服务端返回 task-started 事件后才能发送音频。
| 参数 | 类型 | 说明 |
|---|---|---|
| header | object | (必选) |
| header.action | string | (必选) 指令类型,固定为 run-task。 |
| header.task_id | string | (必选) 客户端生成的任务 ID(UUID 格式),用于关联后续事件。 |
| header.streaming | string | (必选) 固定为 duplex。 |
| payload | object | (必选) |
| payload.task_group | string | (必选) 任务组,固定为 audio。 |
| payload.task | string | (必选) 任务类型,固定为 asr。 |
| payload.function | string | (必选) 功能类型。固定为recognition。 |
| payload.model | string | (必选) 模型名称。 |
| payload.input | object | (必选) 输入对象。不携带上下文时传入{}。 提示: 仅 fun-asr-realtime 模型支持上下文。 |
| payload.input.context | array(object) | (可选) 对话上下文,用于辅助识别、提升专有词汇的识别准确率。使用方法详见上下文增强。 提示: 上下文消息(input_text 和 text 类型)各最多 5 条,超出时保留最近的 5 条。每轮上下文文本总长度(user 和 assistant 的 text 字段长度之和)不超过 400 个字符(按字符数计算,每个字符计为 1),超出部分从末尾截断。 提示: 携带上下文时,context 中的消息顺序有要求:上下文消息必须按对话轮次排列,每轮中 user(input_text 类型)必须在对应的 assistant(text 类型)之前。 |
| payload.input.context.role | string | (必选) 消息角色。取值范围:
|
| payload.input.context.content | array(object) | (必选) 消息内容列表。 |
| payload.input.context.content.type | string | (必选) 内容类型。取值范围:
|
| payload.input.context.content.text | string | (必选) 文本内容。当 type 为 input_text 时,填入前几轮用户语音的识别结果或领域相关的词表;当 type 为 text 时,填入前几轮大语言模型的回复内容。 |
| payload.parameters | object | (必选) 语音识别参数。 |
| payload.parameters.format | string | (必选) 音频格式。 取值范围:
|
| payload.parameters.sample_rate | integer | (必选) 采样率(Hz)。 取值范围:8k模型仅支持 8000 Hz,其他模型支持任意采样率。 |
| payload.parameters.vocabulary_id | string | (可选) 预编译热词列表 ID。 需预先调用创建热词列表接口生成,识别时传入该 ID 即可使用列表中的热词。 适用于词汇已知且相对稳定、需要跨请求复用同一词表的场景。 使用方法请参见预编译热词。 |
| payload.parameters.language_hints | array[string] | (可选) 待识别音频语种。无默认值,不设置时模型自动识别。 仅支持设置 1 个值,设置多个时仅第一个生效。
|
| payload.parameters.max_sentence_silence | integer | (可选) VAD 断句静音阈值(ms)。当一段语音后的静音时长超过该阈值时,系统会判定该句子已结束。 默认值:1300。 取值范围:[200, 6000]。 |
| payload.parameters.multi_threshold_mode_enabled | boolean | (可选) 是否启用多阈值模式。启用后可防止 VAD 断句切割过长。 默认值:false。 |
| payload.parameters.heartbeat | boolean | (可选) 是否启用心跳包。 默认值:false。
|
| payload.parameters.speech_noise_threshold | float | (可选) 语音与噪音的判定阈值,用于调整语音活动检测(VAD)的灵敏度。 取值范围:[-1.0, 1.0]。 取值说明:
|
| payload.parameters.special_word_filter | string | (可选) 敏感词过滤规则,用于将识别结果中的指定词汇替换为等长的星号,或从结果中移除。值为规则对象序列化后的 JSON 字符串。最多可设置 32 个敏感词;未传入该参数时不进行过滤。
|
finish-task
通知服务端音频发送完毕,请求结束任务。
发送时机:所有音频数据发送完毕后。
响应事件:服务端返回 task-finished 事件。
| 参数 | 类型 | 说明 |
|---|---|---|
| header | object | (必选) |
| header.action | string | (必选) 指令类型,固定为 finish-task。 |
| header.task_id | string | (必选) 客户端生成的任务 ID(UUID 格式),需与run-task事件中的 task_id 保持一致。 |
| header.streaming | string | (必选) 固定为 duplex。 |
| payload | object | (必选) |
| payload.input | object | (必选) 固定为{}。 |