本文介绍了自部署模型与边缘大模型网关集成的通信协议规范。该协议基于 OpenAI 标准协议构建，并针对特定场景进行了一系列功能扩充。下文将分别介绍各项主要服务的协议格式与交互细节。

自部署语音合成（TTS）模型接口协议

自部署的语音合成服务可通过 HTTP/HTTPS 或 WebSocket（WS）/WebSockets Secure（WSS）协议接入边缘大模型网关。

HTTP/HTTPS 接口协议详情

• 协议版本：HTTP/1.1 或更高版本，支持 HTTPS
• 请求方法：POST
• 请求路径：/audio/speech

HTTP 请求头

HTTP 请求头需包含以下字段：

HTTP 请求体

请求体为 JSON 格式，包含以下参数：

一个典型的 HTTP 请求体示例如下：

{
    "model": "your_model",
    "input": "The text to be generated",
    "voice": "alloy",
    "response_format": "pcm",
    "speed": 1.0,
    "sample_rate": 16000,
    "channel": 1,
    "extra_data": {
        "room_id": "123",
        "key_a": "value_a"
    }
}

HTTP 返回结果

服务成功处理请求后，将以 HTTP 分块传输编码（Chunked Transfer Encoding）的方式流式返回合成的音频数据。

• 成功响应：

  • 状态码：200 OK
  • 响应体：合成的音频数据流。
  • 响应头（可选）：服务可返回 X-Biz-Trace-Info 响应头，用以携带需要透传的元信息。边缘大模型网关在转发响应时将原样透传此响应头。

• 失败响应：返回相应的 HTTP 错误状态码及 JSON 格式的错误信息。

配置流程参考

详细的接入配置流程，请参见 调用自部署模型。

WebSocket 接口协议详情

自部署的语音合成服务也可以通过 WebSocket（WS）/WebSockets Secure（WSS）协议接入边缘大模型网关。客户端与服务端之间通过交换 JSON 格式的事件消息（以 WebSocket Text Frame 形式传输）实现双向实时通信。

• 协议版本：WebSocket (ws/wss)
• 请求路径：/realtime
• 请求头：

TTS WebSocket 事件列表

下表列出了客户端与服务端之间交互的主要事件类型及其说明：

客户端事件详解

初始化会话参数 - tts_session.update

客户端在建立 WebSocket 连接后，必须首先发送此事件来配置本次 TTS 会话的核心参数。

{
    "event_id": "event_123",
    "type": "tts_session.update",
    "session": {
        "voice": "xxx",
        "output_audio_format": "pcm",
        "output_audio_sample_rate": 16000,
        "output_audio_speed_rate": 0.0,
        "output_audio_volume": 1.0,
        "output_audio_pitch_rate": 0,
        "output_audio_channel": 1,
        "enable_subtitle": true
        "extra_data": {} // map
    }
}

字段说明

上报待合成文本 - input_text.append

客户端通过此事件向服务端流式发送待合成的文本内容。可以将一段长文本拆分为多个 input_text.append 事件分次发送。

{
    "event_id": "event_345",
    "type": "input_text.append",
    "delta": "待合成的文本片段"
}

字段说明：

• delta: 本次上报的文本片段。

文本上报结束 - input_text.done

当客户端完成所有文本片段的发送后，应发送此事件来通知服务端文本输入已结束。

{
    "event_id": "event_346",
    "type": "input_text.done"
}

服务端事件详解

会话参数确认 - tts_session.updated

服务端在成功处理客户端的 tts_session.update 请求后，会返回此事件，确认本次 TTS 会话的参数配置已生效。

{
    "event_id": "server_event_001",
    "type": "tts_session.updated",
    "session": {
        "voice": "your_voice_name",
        "output_audio_format": "pcm",
        "output_audio_sample_rate": 16000,
        "output_audio_speed_rate": 1.0,
        "output_audio_volume": 1.0,
        "output_audio_pitch_rate": 0.0,
        "output_audio_channel": 1,
        "enable_subtitle": false,
        "extra_data": {}
    }
}

字段说明：

• session: 包含已确认生效的会话参数，字段含义同客户端发送的 tts_session.update 事件。

增量音频数据 - response.audio.delta

服务端通过此事件，以流式方式增量返回合成的音频数据。

{
    "event_id": "event_wQp5vyn4VloVTOcrQS6bo",
    "type": "response.audio.delta",
    "item_id": "item_ezC2f0aiYLtsTILllMIXe",
    "delta": "base64_encoded_audio_chunk"
}

字段说明：

• delta: 经过 Base64 编码的 PCM 音频数据片段。

音频合成结束 - response.audio.done

当服务端完成所有音频的合成与发送后，会发送此事件，标志着本次 TTS 请求处理完毕。

{
    "event_id": "event_zh366ItZEWdcnSOiTPR2N",
    "type": "response.audio.done",
    "item_id": "item_ezC2f0aiYLtsTILllMIXe"
}

字幕信息 - response.audio_subtitle.delta

如果客户端在初始化时设置了 enable_subtitle 为 true，服务端将通过此事件推送与合成音频同步的字幕信息。

{
    "event_id": "event_2122",
    "type": "response.audio_subtitle.delta",
    "item_id": "msg_003",
    "subtitles": {
        "text": "你好",
        "words": [{
          "start": 0.0,
          "end": 1.319999933242798,
          "word": "你"
        },{
        "start": 1.319999933242798,
          "end": 2.6,
          "word": "你"
        }],
    ...
  }
}

字段说明：

• subtitles.text: 当前字幕片段对应的完整文本。
• subtitles.words: 一个数组，包含当前片段中每个词汇及其在音频流中的起始时间（start）和结束时间（end），单位为秒。

自部署语音识别（ASR）模型接口协议

自部署的语音识别（ASR）服务通过 WebSocket（WS）/WebSockets Secure（WSS）协议接入边缘大模型网关。客户端与服务端之间通过交换 JSON 格式的事件消息（以 WebSocket Text Frame 形式传输）实现双向实时通信。

WebSocket 接口协议详情

• 协议版本：WebSocket（ws/wss）
• 请求路径：/realtime
• 请求头：

ASR WebSocket 事件列表

下表列出了客户端与服务端之间交互的主要事件类型及其说明：

客户端事件详解

初始化会话参数 - transcription_session.update

此事件用于客户端向服务端传递本次 ASR 会话所需的各项参数。

{
  "type": "transcription_session.update",
  "session": {
    "input_audio_format": "pcm",
    "input_audio_codec": "raw",
    "input_audio_sample_rate": 16000,
    "input_audio_bits": 16,
    "input_audio_channel": 1,
    "extra_data": {}
  }
}

字段说明：

• session.input_audio_format：音频容器格式，例如 pcm。
• session.input_audio_codec：音频编码格式，例如 raw（表示未压缩的原始音频数据）。
• session.input_audio_sample_rate：音频采样率（Hz）。
• session.input_audio_bits：每个采样点的位数，例如 16（表示16-bit）。
• session.input_audio_channel：音频声道数。
• session.extra_data：（可选）JSON 对象，用于承载特定 ASR 服务提供商所需的自定义参数。网关会将此部分数据原样透传给后端自部署的 ASR 模型。

音频数据上报 - input_audio_buffer.append

客户端通过此事件持续向服务端流式发送经过 Base64 编码的音频数据。对于支持连续流式识别的场景，通常无需发送 input_audio_buffer.commit 事件，服务端会根据接收到的音频流实时返回识别结果。

{
    "event_id": "event_wQp5vyn4VloVTOcrQS6bo",
    "type": "input_audio_buffer.append",
    "item_id": "item_ezC2f0aiYLtsTILllMIXe",
    "audio": "base64_encoded_audio_data"
}

字段说明：

• event_id：客户端生成的唯一事件ID。
• item_id：客户端生成的唯一数据项ID，用于关联同一段音频流的不同数据块。
• audio：经过 Base64 编码的音频数据片段。

音频上报结束通知 - input_audio_buffer.commit（可选）

此事件用于明确告知服务端，客户端已完成当前一段完整音频的上报。网关在收到此事件后，会确保与后端模型的连接在处理完已接收音频前保持有效。

{
    "event_id": "event_wQp5vyn4VloVTOcrQS6bo",
    "type": "input_audio_buffer.commit",
    "item_id": "item_ezC2f0aiYLtsTILllMIXe"
}

适用场景：
主要针对那些需要显式结束指令的 ASR 服务提供商。若服务端或自部署模型开启了语音活动检测（VAD）功能，则通常由服务端判断语音结束，客户端无需发送此事件。

服务端事件详解

会话参数确认 - transcription_session.updated

服务端在成功处理客户端的初始化请求并建立 WebSocket 连接后，会返回此事件，确认本次 ASR 会话所采用的参数配置。

{
  "type": "transcription_session.updated",
  "session": {
    "input_audio_format": "pcm",
    "input_audio_codec": "raw",
    "input_audio_sample_rate": 16000,
    "input_audio_bits": 16,
    "input_audio_channel": 1,
    "result_type": 0
    "extra_data": {}
  }
}

字段说明：

• session 内各字段含义同客户端发送的 transcription_session.update 事件中的定义。
• session.result_type：（重要）标识后端 ASR 模型返回识别结果的模式：
  • 0：增量输出（服务端将使用 conversation.item.input_audio_transcription.delta 事件返回新增识别片段）。
  • 1：全量输出（服务端将使用 conversation.item.input_audio_transcription.result 事件返回截止到当前的完整识别结果）。

增量识别结果 - conversation.item.input_audio_transcription.delta

当 ASR 模型配置为增量输出模式（即 result_type 为 0）时，服务端会通过此事件实时推送最新识别出的文本片段。

{
  "type": "conversation.item.input_audio_transcription.delta",
  "event_id": "event_001",
  "item_id": "item_001",
  "content_index": 0,
  "delta": "Hello",
  "start": 0.0,
  "end": 3.319999933242798
}

字段说明：

• event_id：服务端生成的唯一事件ID。
• item_id：对应客户端上报音频时的 item_id。
• content_index：内容索引，用于处理可能的并发或多段内容。
• delta：最新识别出的文本片段。
• start：该识别文本片段在原始音频流中的起始时间点（单位：秒）。
• end：该识别文本片段在原始音频流中的结束时间点（单位：秒）。

累计识别结果 - conversation.item.input_audio_transcription.result

当 ASR 模型配置为全量输出模式（即 result_type 为 1）时，服务端会通过此事件实时推送截至当前时间点的完整累计识别结果。

以下示例展示了两次连续的 result 事件，体现了识别结果的逐步累积：

{
  "type": "conversation.item.input_audio_transcription.result",
  "event_id": "event_001",
  "item_id": "item_001",
  "transcript": "Hello, how?"
}

{
  "type": "conversation.item.input_audio_transcription.result",
  "event_id": "event_002",
  "item_id": "item_001",
  "transcript": "Hello, how are you?"
}

字段说明：

• transcript：截至当前时间点的完整识别文本。

最终识别结果 - conversation.item.input_audio_transcription.completed

当一段完整的语音输入处理完毕后（例如客户端发送了 input_audio_buffer.commit 事件，或服务端通过 VAD 检测到语音结束），服务端会发送此事件，返回该段语音的最终完整识别结果。

{
    "event_id": "event_2122",
    "type": "conversation.item.input_audio_transcription.completed",
    "item_id": "msg_003",
    "content_index": 0,
    "transcript": "Hello, how are you?",
    "words": [
        {
          "start": 0.0,
          "end": 1.319999933242798,
          "word": "Hello"
        },
    ...
  ]
}

字段说明：

• transcript：该段语音的最终完整识别文本。
• words：（可选）一个数组，包含了每个识别出的词汇及其对应的时间戳信息（start，end，word），有助于进行更细致的分析或后续处理。

关于结束判断：

• 如果后端 ASR 服务不具备 VAD 功能，则需要客户端在音频流结束后发送 input_audio_buffer.commit 事件。服务端在接收到此指令并完成对已缓存音频的识别后，会返回 conversation.item.input_audio_transcription.completed 事件。
• 如果后端 ASR 服务支持 VAD 功能，则服务端能够自动检测语音段的结束，并主动推送 conversation.item.input_audio_transcription.completed 事件，此时客户端无需发送 commit 事件。