本文介绍了如何使用边缘大模型网关平台预置的语音对话智能体。

能力介绍 #

边缘大模型网关平台预置了一个语音对话智能体。该智能体适用于语音对话场景，具备以下能力：

• 中文、英文语音输入与输出。
• 保留最多 10 轮对话历史。
• 未收到语音时返回语音应答。
• 对话支持打断。

  说明

  对话打断只适用于单独使用语音对话智能体场景。对于组合使用语音对话智能体与您自己的 Coze 智能体场景，暂不支持对话打断。

• 与第三方智能体组合使用。
• 支持 WebSocket 连接保活。

使用流程 #

语音对话智能体支持两种使用模式：单独使用、与您在 Coze 平台搭建的智能体组合使用。

场景1：单独使用语音对话智能体 #

1. 参考调用平台预置智能体创建一个网关访问密钥，并为该密钥绑定 语音对话智能体。
2. 参考查看密钥（API Key），获取网关访问密钥的 API key。
3. 调用 Realtime API 实现与智能体进行语音对话。关于 API 的说明，请参见 Realtime API。

场景2：组合使用语音对话智能体和您自己的 Coze 智能体 #

1. 完成第三方智能体调用准备工作，具体包括：

   1. 关联智能体：将您在 Coze 平台搭建的智能体添加到边缘大模型网关。
      在该步骤中，需要提供 Coze Bot ID。
   2. 创建调用渠道：创建一个用来访问您的 Coze 智能体的调用渠道。
      支持通过 个人访问令牌 和 OAuth 访问令牌 方式向边缘大模型网关授予您的 Coze 智能体的访问权限。不同授权方式下需提供的鉴权配置不同。

2. 创建一个网关访问密钥。在 模型选择 中同时选择：

   • 您的 Coze 智能体（渠道类型 为 自有三方智能体）
     

   • 平台预置的 语音对话智能体（渠道类型 为 平台预置智能体）
     

   完成创建后，该网关访问密钥可用于调用您的 Coze 智能体和平台预置的语音对话智能体。

3. 参考查看密钥（API Key），获取网关访问密钥的 API key。

4. 调用 Realtime API 实现与智能体进行语音对话。关于 API 的说明，请参见 Realtime API。

Realtime API #

Realtime API 是一个有状态的、基于事件的 API，通过 WebSocket 进行通信。您可以使用 Realtime API 与边缘大模型网关的预置语音对话智能体构建语音对话。目前，Realtime API 支持音频作为输入和输出。

与 Realtime API 建立 WebSocket 连接需要以下参数：

• 单独使用语音对话智能体（后端为内置的豆包语言大模型）
  • URL：wss://ai-gateway.vei.volces.com/v1/realtime
  • 查询参数：?model=AG-voice-chat-agent
  • 请求头：Authorization: Bearer $YOUR_API_KEY

    说明

    $YOUR_API_KEY 需要替换成绑定了 语音对话智能体 的网关访问密钥的 API key。详情请参见使用流程。

• 组合使用语音对话智能体和您自己的 Coze 智能体（后端为您的 Coze 智能体）
  • URL: wss://ai-gateway.vei.volces.com/v1/realtime
  • 查询参数: ?model=AG-voice-chat-agent&ag-coze-bot-id=<Coze Bot ID>
  • 请求头:
    • Authorization: Bearer $YOUR_API_KEY
    • X-Conversation-Id: sess_xxxx （可选字段）

    说明

    • $YOUR_API_KEY 需要替换成绑定您的 Coze 智能体和 语音对话智能体的网关访问密钥的 API key。详情请参见使用流程。
    • X-Conversation-Id：用于将服务端返回的 session.created 中的 session id 保存下来以继续之前的会话。

在基于 JavaScript 的 Websocket 连接请求中使用子协议认证 #

针对浏览器 JavaScript 环境发起的 websocket 请求，由于不支持添加请求头，参照 OpenAI 示例 采用了在 Sec-WebSocket-Protocol 请求头中添加子协议的方式来实现认证。该认证体现在语音对话智能体的 JavaScript 示例代码，如下图所示。

WebSocket 连接保活 #

语音对话智能体支持通过心跳包（ping/pong 帧）来维持 WebSocket 连接的活跃状态，防止因长时间无数据传输导致连接被超时中断。
具体机制如下：

• 服务端在 2 分钟内未收到 ping 帧和任何语音包则断开连接。
• 服务端收到 ping 帧时，回复 pong 帧并将连接延长 2 分钟。
• 服务端在 60 分钟内未收到任何语音包则断开连接。

API 定义 #

Realtime API 兼容 OpenAI 的 Realtime 接口，支持的事件如下表所示。

客户端事件 #

session.update

将此事件发送以更新会话的默认配置。如需更新配置，客户端必须在创建会话的一开始就发送该消息（发送音频之前），服务器将以 session.updated 事件响应，显示完整的有效配置。

• event_id: string
  可选字段，由客户端生成的事件 ID。
• type: string
  事件类型，取值为 session.update。
• session: object
  包含以下字段：
  • modalities: array
    目前支持配置为 ["text", "audio"]或 ["audio"]。当为 ["audio"] 时服务器只不会返回 response.audio_transcript 中的文本消息。
  • instructions: string
    配置智能体的人物设定。示例：你是一个玩具对话智能体，你的名字叫豆包，你的回答要尽量简短。该字段对后端为 Coze 不生效。
  • voice: string
    目前只支持在 语音技术 - 音色列表 通用场景 中 包含中文语种且以 zh_ 开头 的音色。默认为 zh_female_tianmeixiaoyuan_moon_bigtts。
  • input_audio_format: string
    输入音频的格式。目前只支持 pcm16。
  • output_audio_format: string
    输出音频的格式。目前只支持 pcm16。
  • output_audio_sample_rate: int
    输出音频的采样率（Hz）。可选值：8000、16000、22050、24000、32000、44100、48000。默认值：16000。
  • silent_on_unrecognized_input: bool
    这是一个可选配置项，用于控制语音对话智能体在未能识别用户语音输入（即无法将其转换为文本）时的响应行为。默认值为 false 。
    • 当设置为 false（默认值）：
      如果智能体无法识别用户的语音输入，它会根据当前的对话语言环境给出提示。例如：
      • 在中文语境下，智能体会回复：“抱歉，我没有听到你说的话”。
      • 在英文语境下，智能体会回复：“Sorry, I didn't hear you clearly.”
    • 当设置为 true：
      如果智能体无法识别用户的语音输入，它将不会返回上述的提示语音，而是直接结束当前轮次的对话。
  • input_audio_transcription: object
    通过配置此项来将用户语音输入的文本转录发送给客户端。配置为空表示关闭此功能。
    包含以下字段：
    • model: string
      配置为 "model": "any" 来打开此功能。
  • turn_detection: object
    暂不支持，设置为空。
  • tools: array of object
    调用的工具。包含以下字段：
    • type: string
      工具类型。取值为 function，表示函数。
    • name: string
      函数名称。示例：get_weather。
    • description: string
      函数描述。
    • parameters: object
      函数的参数对象，使用 JSON Schema 格式。

      说明

      如果后端为您自己的 Coze 智能体，那么 tools 字段不生效。实际生效的是您在 Coze 智能体中定义的端插件。

  • tool_choice: string
    暂不支持。
  • temperature: number
    暂不支持。
  • max_response_output_tokens: integer or "inf"
    暂不支持。

示例：

{
   "type": "session.update",
   "session": {
      "modalities": ["audio"],
      "instructions": "你的名字叫豆包，你是一个智能助手，你的回答要尽量简短。",
      "voice": "zh_female_tianmeiyueyue_moon_bigtts",
      "input_audio_format": "pcm16",
      "output_audio_format": "pcm16",
      "input_audio_transcription": {
         "model": "any"
      },
      "tools": [{
         "type": "function",
         "name": "get_weather",
         "description": "获取当前天气",
         "parameters": {
            "type": "object",
            "properties": {
               "location": {
                  "type": "string"
               }
            },
            "required": ["location"]
         }
      }],
      "temperature": 0.8
   }
}

input_audio_buffer.append

发送此事件以将音频字节追加到输入音频缓冲区。音频缓冲区是临时存储，您可以在其中写入数据并稍后进行提交。

• event_id: string
  可选字段，由客户端生成的事件 ID。
• type: string
  事件类型，取值为 input_audio_buffer.append。
• audio: string
  Base64 编码的 audio bytes。目前只支持 pcm16 格式。

示例：

{
    "type": "input_audio_buffer.append",
    "audio": base64_audio
}

input_audio_buffer.commit

发送此事件以提交用户输入的音频缓冲区。提交输入音频缓冲区将触发音频转录，但不会生成模型的响应。服务器将以 input_audio_buffer.committed 事件进行响应。

• event_id: string
  可选字段，由客户端生成的事件 ID。
• type: string
  事件类型，取值为 input_audio_buffer.commit。

示例：

{
    "type": "input_audio_buffer.commit"
}

conversation.item.create

向对话的上下文中添加一个新项目，包括消息、函数调用响应。新增消息时，消息文本将直接作为输入发送到大模型以产生应答，此时无需再上报语音消息。如果成功，服务器将响应一个 conversation.item.created 事件，否则将发送错误事件。

• event_id: string
  可选字段，由客户端生成的事件 ID。
• type: string
  事件类型，取值为 conversation.item.create。
• previous_item_id: string
  暂不支持。
• item: object
  对话的 Item。包含以下字段：
  • id: string
    可选字段，客户端生成的 Item ID。
  • object: string
    可选字段，取值为 realtime.item。
  • type: string
    Item 的类型。取值为 function_call_output（新增函数调用响应）和 message（新增消息）。
  • call_id: string
    当 type 为 function_call_output 时需要传入，表示函数调用的 ID。如果在 function_call_output 项中传递，服务器将检查对话历史中是否存在具有相同 ID 的 function_call。
  • output: string
    当 type 为 function_call_output 时需要传入，表示函数调用响应。
  • role: string
    当 type 为 message 时需要传入。目前取值只支持 user。
  • content：list
    当 type 为 message 时需要传入。目前只支持包含一个元素的 list