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

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

自部署的语音合成服务可通过 HTTP/HTTPS 或 WebSocket/WebSockets Secure（WSS）协议接入边缘大模型网关。本节主要描述 HTTP/HTTPS 的接入方式。

HTTP/HTTPS 接口协议详情

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

HTTP 请求头

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

HTTP 请求体 (Body)

请求体为 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）的方式流式返回合成的音频数据（PCM 格式）。

• 成功响应：状态码 200 OK，响应体为音频流。
• 失败响应：返回相应的 HTTP 错误状态码及 JSON 格式的错误信息。

配置流程参考

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

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

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

WebSocket 接口协议详情

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

WebSocket 连接请求头

WebSocket 连接请求头需包含以下字段：

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",
    "delta": "base64_encoded_audio_data"
}

字段说明：

• event_id：客户端生成的唯一事件ID。
• item_id：客户端生成的唯一数据项ID，用于关联同一段音频流的不同数据块。
• delta：经过 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 事件。