本文介绍如何通过多模态处理网关（Multi\-Modal Process Gateway，MMPG），基于自有 Agent 实现 AI 音视频互动。 ## 适用场景本方案适合具备较强自研能力，需要对用户原始音频或视频截图做进一步分析，或使用 Realtime 模型直接生成音频的业务。典型场景包括： * 同时编排端到端语音模型与其他模型或业务能力，由自有 Agent 统一管理对话逻辑和回复音频。 * 已具备自研的实时音频理解能力，并希望将自研分析结果与 MMPG 提供的 ASR、VAD 等音视频处理信息结合，自主制定打断和判停策略。 * 需要获取视频截图并完成自定义视觉分析，再将分析结果与实时对话结合。 ## 技术架构 **数据流（客户端 \-\> 业务服务端）** 客户端采集的音频、视频数据经由 RTC / MMT 发送至MMPG，MMPG进行 ASR 识别、VAD 检测等处理后，通过 WebSocket 将结构化的事件（如 ASR 文本、用户音频数据）实时推送给您的业务服务端。 ![图片](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/a4d30dbcba674581a244510ee8ecc5bd~tplv-goo7wpa0wc-topic.webp) **数据流（业务服务端 \-\> 客户端）** 您的业务服务端可以根据接收到的事件，调用大模型生成回复内容，再将合成的音频流、字幕流或自定义消息通过 WebSocket 发送给 MMPG， MMPG 再通过 RTC / MMT通道下发给客户端。 ![图片](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/7e6b728325c44a3a8af52405e1b958ef~tplv-goo7wpa0wc-topic.webp) ## 快速接入 ### 准备工作 * **子账户授权**：若您使用的火山引擎子账户，请确保您的子账户拥有 RTCFullAccess 权限。可前往 [访问控制-用户](https://console.volcengine.com/iam/identitymanage/user)，按照界面提示为目标用户授权。 * **开通服务**：确保您已开通[实时音视频（RTC）](https://console.volcengine.com/rtc)和 **AI 音视频互动方案** 服务。 * **获取凭证**： * **RTC AppId**：在 [AI 音视频互动方案-应用管理](https://console.volcengine.com/conversational-ai/devTools/appIdManage) 获取。 * **RTC Token**：测试时可以在控制台生成临时 Token；生产环境必须由您的服务端签发 Token。详见[使用 Token 完成鉴权](https://www.volcengine.com/docs/6348/70121)。 * **访问密钥（AK/SK）** ：用于 WebSocket 连接的签名鉴权。请前往[访问控制-密钥管理](https://console.volcengine.com/iam/keymanage)获取。 * **准备业务服务器和自有 Agent**：准备能够访问公网的业务服务端和要接入的自有 Agent。需要向客户端返回语音时，还需准备能够输出受支持音频格式的 TTS 服务。 ### 步骤 1：实现客户端音视频通话在客户端应用中集成 RTC SDK，实现基础的音视频通话，为 AI 提供音视频交互的基础环境。 **快速实现** 根据您的客户端平台，集成 RTC SDK 实现音视频通话能力。 * **快速测试**：参考[跑通示例项目](https://www.volcengine.com/docs/6348/70124)，快速集成一个音视频通话 Demo。 * **集成到应用**：参考[实现音视频通话](https://www.volcengine.com/docs/6348/70123)。 **关键配置与注意事项** * **订阅或发布流**：推荐使用默认的自动发布和自动订阅音频设置。若需手动控制，可以在调用 `joinRoom` 时将 `isAutoPublish` 和 `isAutoSubscribeAudio` 设为 `false`，再通过 `subscribeStream` 和 `publishStream` 订阅或发布音频流。 * **优化音质**：对于移动端，若场景对音频质量有更高要求，例如需要播放音乐，可调用 `setAudioScenario` 设置合适的音频场景，使手机音量切换为[媒体音量](https://www.volcengine.com/docs/6348/651068?lang=zh)。 > **注意** > 对于 RTC SDK 3.60 及以上版本，可以将音频场景设置为 AI 对话场景。例如，Android 端可使用 `AICLIENT`；创建 RTC 引擎时，还需要通过 `parameters` 传入私有参数 `"rtc.fg_config":"aigc_media_360=true"`。 * **静音用户**：如需让用户静音，请使用 `muteAudioCapture` 静音麦克风，以降低切换延迟。不建议使用 `stopAudioCapture`，否则可能出现声音卡顿或变声。 ### 步骤 2：建立 WebSocket 连接在业务服务端向 MMPG 发起 WebSocket 连接请求。 |项目 |值 | |---|---| |请求地址 |`wss://interactai.volcvideo.com/api/v2/mmpg` | |请求方法 |`GET` | |地域 |`cn-north-1` | |签名服务名 |`rtc` | |鉴权方式 |使用 AK、SK 按火山引擎签名机制生成请求 Header | 以下 Python 示例演示如何签名并建立连接： ```Python import os from volcenginesdkcore.signv4 import SignerV4 from websockets.sync.client import connect PROTOCOL = "wss" HOST = "interactai.volcvideo.com" PATH = "/api/v2/mmpg" REGION = "cn-north-1" SERVICE = "rtc" def connect_to_mmpg(): ak = os.environ["VOLC_ACCESSKEY"] sk = os.environ["VOLC_SECRETKEY"] headers = {} SignerV4.sign( PATH, "GET", headers, "", None, {}, ak, sk, REGION, SERVICE, ) return connect( f"{PROTOCOL}://{HOST}{PATH}", additional_headers=headers, ) ``` 运行程序前，通过环境变量传入 AK 和 SK： ```Bash export VOLC_ACCESSKEY="YOUR_ACCESS_KEY" export VOLC_SECRETKEY="YOUR_SECRET_KEY" ``` ### 步骤 3：创建并初始化会话连接建立后，业务服务端需要在服务端规定的等待时间内发送 `session.create`，创建并初始化会话。请求包含以下字段： |字段 |说明 | |---|---| |`event_id` |本次请求的唯一标识，由业务服务端生成，用于关联请求、回调和错误日志。 | |`type` |事件类型，固定为 `session.create`。 | |`session` |会话配置，包括 `AgentConfig`、`AudioConfig`、`VisionConfig` 和 `ASRConfig`。完整参数说明参见 [session.create](https://docs.volcengine.com/docs/6348/2756798#session-create-parameters)[ 配置](https://docs.volcengine.com/docs/6348/2756798#session-create-parameters)。 | 发送 `session.create` 事件示例： ```JSON { "event_id": "event_create_001", "type": "session.create", "session": { "AgentConfig": { "TransmitConfig": { "Type": "rtc", "AppId": "YOUR_APP_ID", "RoomId": "YOUR_ROOM_ID", "UserId": "YOUR_AGENT_USER_ID", "TargetUserId": [ "YOUR_CLIENT_USER_ID" ] }, "IdleTimeout": 180, "TurnDetectionMode": 0, "SubtitleConfig": { "DisableRTSSubtitle": false, "UserTranscriptMode": 1 } }, "AudioConfig": { "AudioFormat": { "UserAudioFormat": "pcm16", "AssistantAudioFormat": "pcm24", "AnsMode": 0 }, "EnableUserAudio": false, "VADConfig": { "SilenceTime": 600, "ForceBeginThreshold": 200, "ForceEnd": false, "ExpireTime": 2500, "EnablePrefetch": true, "AIVAD": true } }, "ASRConfig": { "Provider": "volcano", "ProviderParams": { "Mode": "bigmodel", "VolcanoASRParameters": "{}", "Credential": { "ApiResourceId": "volc.seedasr.sauc.duration" }, "StreamMode": 2 } } } } ``` 参数校验通过后，MMPG 返回 `session.created`，表示会话创建成功，AI 用户将加入指定的 RTC 房间。收到 `session.created` 前，不要发送 AI 音频。 ### 步骤 4：处理 MMPG 事件会话创建后，每轮对话依次接收用户识别结果、执行自有 Agent 逻辑，再向 MMPG 发送回复音频。MMPG 将音频转发到 RTC 房间，并返回播放状态。该流程在会话期间循环执行。 #### 时序图 * 对话流程（关闭声纹降噪） ![图片](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/eb433bb56445450c9ae43941aafc8ba1~tplv-goo7wpa0wc-topic.webp) * 对话流程（开启声纹降噪） ![图片](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/2f30dec0ef9946bb989fdbace6dcf8f7~tplv-goo7wpa0wc-topic.webp) #### 1. 接收用户语音与识别结果会话创建成功后，MMPG 开始处理目标用户发布的音频，并通过 WebSocket 返回识别事件，您需要根据 `type` 进行分支处理。核心对话流程事件如下： * `user.conversation.created`：检测到用户开始说话。 * `user.audio.transcription.started`：ASR 识别到首个有效文字。 * `user.audio.transcription.segment`：ASR 的当前识别片段。需要开启 `EnablePrefetch`，可用于提前准备回复。 * `user.audio.transcription.done`：返回本轮最终识别结果，通常用于触发自有 Agent。完整事件说明，参见 [WebSocket 事件参考](https://docs.volcengine.com/docs/6348/2756798#websocket-events)。 #### 2. 执行自有 Agent 逻辑收到 `user.audio.transcription.done` 后，按以下步骤生成回复： 1. 将用户文本 `transcript` 发送给自有 Agent。 2. 自有 Agent 可以结合会话上下文调用 LLM、工具或业务系统生成回复。 3. 需要向客户端返回语音时，再调用 TTS 将回复合成为音频（如 PCM 格式）。 > 示例中的 `call_your_agent` 和 `call_your_tts` 需要由您根据自有 Agent 和 TTS 服务实现。 ```python def handle_user_transcript(websocket, user_text): answer = call_your_agent(user_text) audio_chunks = call_your_tts(answer, sample_rate=24000) send_audio_response(websocket, audio_chunks, next(response_ids)) ``` #### 3. 向客户端发送 AI 音频完整的事件列表及数据结构，参见 [WebSocket 事件参考](https://docs.volcengine.com/docs/6348/2756798#websocket-events)。 **发送 PCM 数据** 将 TTS 输出切成连续的小块，对每个音频块进行 Base64 编码，再通过 `assistant.audio.delta` 发送。`AssistantAudioFormat` 必须与 TTS 实际输出格式一致。示例如下： ```JSON { "event_id": "your_unique_event_id_456", "type": "assistant.audio.delta", "resp_id": 1, "payload": "Base64EncodedAudioChunk", "done": false } ``` **关键参数说明：** * `resp_id`：同一轮回复的唯一标识。需要打断当前播报并开始新一轮播报时，发送一个 `resp_id` 更大的 `assistant.audio.delta`。 * `payload`：Base64 编码的 PCM 音频数据块。 * `done`：最后一块音频数据设为 `true`。 **发送 Ogg Opus 数据** 如果需要直接发送 Ogg Opus 数据，在 `session.create` 的 `AudioConfig.AudioFormat` 中声明输出格式和处理方式： ```JSON { "AssistantAudioFormat": "ogg_opus", "AssistantAudioProcessMode": "demux" } ``` `assistant.audio.delta` 中的 `payload` 仍为 Base64 字符串。Base64 解码后的各数据块必须按顺序组成连续的 Ogg Opus logical stream。 ```JSON { "type": "assistant.audio.delta", "resp_id": 101, "payload": "T2dnUwAC...", "done": false } ``` * `demux`：默认模式。MMPG 仅对 Ogg 容器解封装，并将 Opus 数据发送给客户端。 * `decode`：MMPG 将 Ogg Opus 解码为 24 kHz、16\-bit、单声道 PCM 后发送给客户端。 ### 步骤 5：结束会话对话结束后，为避免产生不必要的计费，建议主动结束会话。 1. **业务服务端**：向 MMPG 发送 `session.close`。 ```JSON { "event_id": "event_unique_id_789", "type": "session.close" } ``` 2. **客户端**：调用 RTC SDK 的 `leaveRoom` 和 `destroyRTCEngine` 接口，让用户离开房间并释放客户端资源。 ## 进阶使用 ### 处理用户打断在语音对话中，用户随时可能在 AI 说话时插话。根据您在 `session.create` 中是否开启了声纹降噪，打断的控制逻辑严格遵循以下时序： * **关闭声纹降噪（追求极速响应）** 1. 当 AI 正在播放音频（业务方已持续发送 `assistant.audio.delta`），用户突然说话。 2. 一旦收到 `user.audio.transcription.started`（ASR 识别到首字），可以发送 `assistant.audio.cancel` 指令（或直接发送一个 `resp_id` 更大的新音频包），立即清空正在播放和等待播放的 AI 音频。 * **开启声纹降噪（防干扰模式）** 收到 `user.audio.transcription.started` 后不要立即打断。等待 `user.audio.speaker.verification` 确认说话人匹配后，再取消播报。如果收到 `user.conversation.canceled`，且原因为 `speaker_mismatch`，应忽略这次发言，让原回复继续播放。 ### 收发自定义消息会话存续期间，业务服务端与客户端可以随时收发自定义消息。 * **服务端发送**：业务服务端可以通过 MMPG 向客户端发送自定义消息： ```JSON { "event_id": "event_msg_001", "type": "assistant.message", "payload": "{\"action\":\"show_image\",\"url\":\"https://example.com/img.png\"}" } ``` * **客户端接收**：客户端通过 RTC SDK 的 [onRoomBinaryMessageReceived](https://www.volcengine.com/docs/6348/70081#IRTCRoomEventHandler-onroombinarymessagereceived) 回调接收消息。 * **客户端发送**：客户端调用 RTC SDK 的 [sendUserBinaryMessage](https://www.volcengine.com/docs/6348/70080?lang=zh#senduserbinarymessage) 向 AI 用户发送消息。 * **服务端接收**：业务服务端收到 `user.message` 后，解析 `payload` 获取客户端传递的内容。 ```JSON { "event_id": "event_msg_002", "type": "user.message", "payload": "{\"feedback\":\"user_clicked_button_A\"}" } ``` ### 发送欢迎语 MMPG 不支持通过 `AgentConfig.WelcomeMessage` 配置欢迎语。欢迎语应由业务服务端生成，并通过 `assistant.audio.delta` 发送。建议使用以下时序，避免客户端漏播开头内容： 1. 客户端加入 RTC 房间并成功订阅 AI 音频流。 2. 客户端通过自定义消息通知业务服务端已准备播放。 3. 业务服务端生成欢迎语音频，并按正常 AI 回复流程发送。 ## 配置与协议参考 ### `session.create` 配置 `session.create` 的请求由 `event_id`、`type` 和 `session` 组成。`event_id` 由业务服务端生成，用于日志追踪；`type` 固定为 `session.create`；`session` 包含以下配置。 #### 完整参数结构 ```JSON { "event_id": "unique_request_id_001", "type": "session.create", "session": { "AgentConfig": { "TransmitConfig": { "Type": "rtc", "AppId": "...", "RoomId": "...", "UserId": "...", "TargetUserId": ["..."], "BusinessId": "..." }, "IdleTimeout": 180, "TurnDetectionMode": 0, "SubtitleConfig": { "DisableRTSSubtitle": false, "UserTranscriptMode": 1 } }, "AudioConfig": { "AudioFormat": { "UserAudioFormat": "pcm16", "AssistantAudioFormat": "pcm24", "AnsMode": 0 }, "EnableUserAudio": false, "VADConfig": { "SilenceTime": 600, "ForceBeginThreshold": 200, "ForceEnd": false, "ExpireTime": 2500, "EnablePrefetch": true, "AIVAD": true }, "VoicePrint": { "Mode": 1, "EnableSV": true, "VoiceDuration": 30, "IdList": [], "Score": 50 }, "VolumeGain": 0.3, "FarfieldConfig": { "Enable": false, "Level": "Medium", "Threshold": 0, "FixedSource": false } }, "VisionConfig": { "Enable": false, "SnapshotConfig": { "StreamType": 0, "Height": 360, "Interval": 1000, "ImagesLimit": 2, "AutoSelect": true } }, "ASRConfig": { "Provider": "volcano", "ProviderParams": { "Mode": "bigmodel", "VolcanoASRParameters": "...", "StreamMode": 2, "ContextHistoryLength": 3 } } } } ``` #### 参数说明 |参数名称 |类型 |必填 |参数含义 | |---|---|---|---| |event_id |String |是 |每个事件的唯一标识，由业务方自行生成，用于日志追踪。 | |type |String |是 |事件类型。在此接口下固定取值为：`session.create`。 | |session |Object |是 |会话配置对象，定义了 AI 智能体在本次通话中的核心能力。 | |智能体配置 |||| |└ AgentConfig |Object |是 |智能体基础行为与传输配置。 | |└─ TransmitConfig |Object |是 |RTC 传输协议与身份配置。 | |└── Type |String |是 |传输协议类型。当前固定取值为：`rtc`。 | |└── AppId |String |是 |火山引擎 AI 音视频互动方案的应用 AppId，需与客户端加入 RTC 房间时使用的 AppId 保持一致。 | |└── RoomId |String |是 |RTC 房间的 ID。需与真人用户进入的房间号保持一致。 | |└── UserId |String |是 |AI 智能体在房间内的唯一标识 ID。由您自定义，不能与 `TargetUserId` 相同。

命名规则：

* 支持由大小写字母（A\-Z、a\-z）、数字（0\-9）、下划线（_）、短横线（\-）、句点（.）和 @ 组成，最大长度为 128 个字符。

* 同一 AppId 下 UserId 全局唯一。若同一 AppId 下不同房间内 AI Bot 名称相同，会导致使用服务端回调的功能异常，如字幕、Function Calling 和状态回调功能。

* UserId 的值不能与 AgentConfig.TargetUserId（真人用户 ID）相同。 | |└── TargetUserId |String[] |是 |需使用客户端 SDK 进房的真人用户的 UserId。仅支持传入一个 UserId，即单个房间内，仅支持一个用户与AI Bot 一对一通话。 | |└── BusinessId |String |否 |业务标识 ID，用于区分不同的业务逻辑或统计维度。 | |└─ IdleTimeout |Integer |否 |空闲等待超时时间（秒）。当房间内无真人用户时，AI 自动退出的等待时长。默认值为 180。 | |└─ TurnDetectionMode |Integer |否 |新一轮对话的触发方式。

* `0`：自动触发。服务端检测到静音后自动开启 ASR 判定。

* `1`：不自动触发。需通过业务逻辑控制，调用 RTC SDK 的 sendUserBinaryMessage 接口发送特定格式的二进制消息，触发新一轮对话。参见[判停与对话触发](https://docs.volcengine.com/docs/6348/1544164)。

默认值为 `0`。 | |└─ SubtitleConfig |Object |否 |字幕下发配置。 | |└── DisableRTSSubtitle |Boolean |否 |是否关闭房间内客户端的二进制字幕回调。

* `false`：开启。开启后，还需在客户端实现监听 [onRoomBinaryMessageReceived](https://www.volcengine.com/docs/6348/70081#IRTCRoomEventHandler-onroombinarymessagereceived)（以 Android 为例），并解析字幕。

* `true`：关闭。

默认值为 `false`。 | |└── UserTranscriptMode |Integer |否 |是否通过 WebSocket 向业务服务端推送流式识别字幕。

* `0`（默认）：不接收。

* `1`：通过 `user.audio.transcription.delta` 接收。 | |音频与 VAD 算法 |||| |└ AudioConfig |Object |是 |音频算法与编解码处理配置。 | |└─ AudioFormat |Object |是 |音频流格式定义。 | |└── UserAudioFormat |String |是 |指定 `user.audio.delta` 的音频格式。目前仅支持 `pcm16`（16 kHz、16\-bit、单声道 PCM）。 | |└── AssistantAudioFormat |String |是 |指定业务服务端发送的 `assistant.audio.delta` 音频格式。支持格式：

* PCM

* 可选值：`pcm16`（16 kHz）、`pcm24`（24 kHz）、`pcm32`（32 kHz）、`pcm48`（48 kHz）。

* 必须为 16\-bit、单声道 PCM。

* Opus

* 可选值：`ogg_opus`

* 必须为单声道，编码帧长为 20 ms，采样率必须为 48 kHz。 | |└── AnsMode |Integer |否 |AI 降噪。对音频进行智能降噪处理，适用于不具备或不便开启端侧 AI 降噪能力的终端。例如：若物联网、智能硬件设备算力有限，无法运行复杂的端侧降噪算法的场景。

可根据实际噪声环境选择不同级别的降噪模式：

* 0（默认值）：禁用 AI 降噪。

* 1：轻度降噪。适用于抑制微弱、平稳的背景噪声。

* 2：中度降噪。适用于抑制中度平稳噪声，如空调声、风扇声。

* 3：重度降噪。适用于抑制嘈杂、非平稳的动态噪音，如键盘敲击声、物体碰撞声、动物叫声等。 | |└─ EnableUserAudio |Boolean |否 |是否通过 `user.audio.delta` 返回用户音频，默认值为 `false`。返回格式为 16 kHz、16\-bit、单声道 PCM。 | |└─ VADConfig |Object |否 |语音活动检测（VAD）相关参数。 | |└── SilenceTime |Integer |否 |判停静音时长阈值（毫秒）。当用户静音超过该值时判定本轮说话结束。默认 600，范围 [500, 3000)。 | |└── ForceBeginThreshold |Integer |否 |首帧打断阈值（毫秒）。

当 AI 正在播报时，若系统（基于 VAD）检测到用户语音持续时长达到该设定值，AI 立即停止播报。此过程不完全依赖 ASR 识别具体文字。

* 取值范围： [0, 1000]。

* 默认值：0，即禁用此功能。

> 在嘈杂环境下，设置过小的阈值可能导致 AI 被环境噪音误打断（如突然的关门声、咳嗽声）。 | |└── ForceEnd |Boolean |否 |是否开启辅助 VAD 强制判停。

开启后，一旦用户静音时长达到 SilenceTime，系统会立即判定用户发言结束，并终止本轮 ASR 识别。适用于对响应速度要求极高，且用户说话节奏较快的场景。此过程基于 VAD 实现，不依赖 ASR 判停。

* false（默认值）：关闭。

* true：开启。 | |└── ExpireTime |Integer |否 |强制判停兜底时长（毫秒）。从 ASR 识别到最后一段文字起，若经过 ExpireTime 时长仍未触发静音判停（即 SilenceTime），则强制判定用户本轮说话已结束。

适用于背景噪声大、环境干扰严重（导致 VAD/ASR 无法准确判断静音）时，进行兜底强制判停。

建议设置为 SilenceTime 的 1.5 倍。 | |└── EnablePrefetch |Boolean |否 |是否启用 ASR 预取（Prefetch）。开启后才能收到 `user.audio.transcription.segment` 句中识别事件。默认 `true`。 | |└── AIVAD |Boolean |否 |是否开启智能语义判停。启用后，当用户静音时长达到 SilenceTime 时，系统会引入 AI 模型来分析用户语义是否完整；如果语义完整，系统才判定用户本轮发言结束。该功能有效提升在复杂对话场景下（如长句、思考停顿）判停的准确性，避免将一句完整的话错误地拆分为多轮对话。

* true：开启。

* false（默认值）：关闭。

> AIVAD 功能目前在限时免费公测阶段。 | |└─ VoicePrint |Object |否 |声纹识别与声纹降噪配置。 | |└── Mode |Integer |否 |声纹模式。

* `0`：关闭。

* `1`：声纹降噪（增强目标人声，抑制背景人声）。

* `2`：声纹识别。

默认 `0`。 | |└── EnableSV |Boolean |否 |声纹降噪模式下（Mode=1），是否验证说话人身份：

* false（默认值）：关闭。

* true：开启。系统会实时提取说话人的声纹特征，并与 IdList 中预注册或自动注册的声纹比对。仅当匹配成功时，才将 ASR 识别结果送入 LLM；否则将丢弃该段语音，不触发后续业务逻辑，从而避免背景人声误触发 AI。 | |└── VoiceDuration |Integer |否 |声纹降噪模式下（Mode=1且 IdList 为空），自动注册声纹时所需的有效语音时长。单位为秒。

* 取值范围：[4, 33]。

* 默认值：12。 | |└── IdList |String[] |否 |预注册的声纹 ID 列表。模式为降噪时限 1 个，模式为识别时支持 1~3 个。 | |└── Score |Integer |否 |声纹识别模式下（Mode = 2 且 IdList 有值），声纹的置信度阈值。可用于判断当前说话人是否为目标用户。

配置后，系统会计算实时语音与预注册声纹的“相似度分数”。只有当分数不低于设定阈值时，才会判定说话人为目标用户。

* 取值范围：[1, 100]。

* 推荐值：40 ~ 60。

* 默认值：50（不传或传 0 时均生效）。 | |└─ VolumeGain |Float |否 |采集音量增益系数。默认值 1.0，推荐设为 0.3 以减少环境噪音误识别。 | |└─ FarfieldConfig |Object |否 |通过抑制距离麦克风 3\-5 米以外的背景人声，解决远场场景下的 AI 误触发、误识别及判停延迟等问题。该功能适用于耳机、手机等收音效果较好的设备。

> 由于不同硬件设备的收音特性差异较大，必须根据实际设备类型和应用场景选择合适的 Level 或 Threshold。若参数设置不当（如抑制过强），可能会导致正常用户的声音也被抑制，影响收音质量。建议根据实际业务场景进行细致调试。 | |└── Enable |Boolean |否 |是否开启远场抑制功能。默认 `false`。 | |└── Level |String |否 |噪声抑制强度，系统将根据环境底噪自动动态调整过滤门槛。可取值如下：

* High：强抑制，过滤效果最强，适用于极其嘈杂或远场人声干扰严重的场景。

* Medium（默认值）：中抑制，在抑制干扰与保留微弱人声之间取得平衡。

* Low：弱抑制，过滤效果最弱，保留更多音频细节，适用于相对安静的环境。

若 Threshold \> 0 ，本配置失效。 | |└── Threshold |Integer |否 |自定义噪声抑制阈值。

* 取值范围：[0, 127]，数值越小抑制越强，127 接近静音。

* 默认值： 0，表示不启用自定义噪声抑制，由 Level 抑制噪声。

若此值 \> 0，则 Level 配置失效。不同硬件设备的阈值可能存在差异，建议优先使用 Level 参数。 | |└── FixedSource |Boolean |否 |音源位置是否固定。`true`：位置固定（如手机听筒模式）。`false`：位置不固定（如扬声器模式）。 | |视觉理解 |||| |└ VisionConfig |Object |否 |AI 视觉理解与抽帧配置。

回调时机：user.audio.transcription.segment、user.audio.transcription.done之前 | |└─ Enable |Boolean |是 |是否开启视觉理解功能。`true`：开启。`false`：关闭。默认 `false`。 | |└─ SnapshotConfig |Object |否 |抽帧截图详细配置。 | |└── StreamType |Integer |否 |截图来源流类型。

* 0：主流。指来自摄像头的实时视频画面。

* 1：屏幕共享流。指用户共享的设备屏幕内容（如桌面、应用窗口、PPT 等）。

默认值为 0。 | |└── Height |Integer |否 |截图视频帧高度，取值范围为 [0, 1792]，单位为像素。

不填或传 0 时自动修改为 360。

视频帧宽度自动按传入高度进行比例计算。 | |└── Interval |Integer |否 |相邻截图之间的时间间隔（毫秒）。

* 不设置callbackMode：非必填，取值范围 [100, 5000]，默认 1000。

* 设置callbackMode为周期回调：必填，不小于 1000。 | |└── ImagesLimit |Integer |否 |单次回调的最大截图数量。非必填

* 不设置callbackMode：范围 [0, 50]，默认 2。

* 设置callbackMode为周期回调：固定为1，不需要设置。 | |└── AutoSelect |Boolean |否 |是否启用自动选帧。启用后，系统会自动输入的视频中选取质量较高的帧，解决因移动抖动或失焦导致的识别不准问题。

* true：启用。

* false（默认值）：关闭。

> 启用后，截图间隔 Interval 固定为 166ms（每秒采样 6 张图片），用户自定义的 Interval会失效。 | |└── CallbackMode |String |否 |图片回调模式。

* 空值或未配置：默认行为，在user.audio.transcription.segment、user.audio.transcription.done前回调图片。

* `periodic_session`：在整个 WebSocket 会话期间，按 `Interval` 周期回调图片。

* `periodic_conversation`：在每轮 `user.conversation.created` 至 `user.conversation.done` 期间，按 `Interval` 周期回调图片。 | |语音识别配置（透传） |||| |└ ASRConfig |Object |是 |语音识别（ASR）引擎配置。 | |└─ Provider |String |是 |ASR 服务提供商，当前支持 `volcano`。 | |└─ ProviderParams |Object |否 |ASR 引擎的详细参数配置。填Provider=`volcano`时，必填 | |└── Mode |String |是 |模型类型。该参数固定取值：bigmodel，表示火山引擎语音识别大模型。 | |└── VolcanoASRParameters |String |否 |VolcanoASRParameters 是一个经过压缩并转义后的 JSON 字符串，用于透传火山引擎语音识别大模型 ASR 服务的 [原生 API 参数](https://www.volcengine.com/docs/6561/1354869)。

* 如何配置：

* 基础用法：若您不需要进行任何自定义配置，接受平台所有默认行为，可将该字段值设为空的 JSON 对象，即 `VolcanoASRParameters: "{}"`。

* 高级用法：若您需要判停、热词等功能，则需要通过此参数传入对应的参数配置。

1. 根据需求，参考文档 [大模型流式语音识别API](https://www.volcengine.com/docs/6561/1354869) 选取您需要的参数构建一个 JSON 对象，然后将该对象压缩并转义为 JSON 字符串。

2. 将该 JSON 对象压缩并转义为字符串后，作为 VolcanoASRParameters 的值传入。例如，要将静音判停阈值设为 500 毫秒，则为 `"{\"request\":{\"end_window_size\":500}}"`。

* 可透传的参数：

* 支持的参数：[大模型流式语音识别API](https://www.volcengine.com/docs/6561/1354869) 中的请求参数（即发送 full client request 表格下的参数），但需排除下方无需透传的参数列表中由平台管理的参数。

* 无需透传的参数：

以下参数由平台统一管理，您的字符串中不可包含这些字段：

```Plain Text```
``` * user```
``` * request.show_speech_rate```
``` * request.show_volume```
``` * request.enable_lid```
``` * request.enable_emotion_detection```
``` * request.enable_gender_detection```
``` * request.show_utterances```
``` * request.result_type```
``` * request.model_name```
``` * request.force_to_speech_time```
``` * audio.format```
``` * audio.codec```
``` * audio.rate```
``` * audio.bits```
``` ```
| |└── Credential |Object |否 |指定要使用的流式语音识别大模型版本，默认 1.0 版本。 | |└─── ApiResourceId |String |否 |指定要使用的流式语音识别大模型版本：

* volc.bigasr.sauc.duration（默认值）：流式语音识别大模型 1.0。

* volc.seedasr.sauc.duration：流式语音识别大模型 2.0。 | |└── StreamMode |Integer |否 |语音识别结果返回模式：

* 0（默认值）：流式输入流式输出。识别结果会分段、实时地返回。该模式下识别速度更快，适用于对实时性要求高的场景，如实时字幕。

* 1：流式输入非流式输出。即在完整接收并处理完整个语音片段后，一次性返回最终的识别结果。该模式下识别准确率更高，适用于对实时性要求不高的场景，如会议录音转写。

* 2（推荐）：双向流式优化版。在流式输入和流式输出的基础上，支持对检测到的完整语句片段进行二次非流式识别，兼顾实时性与准确性。

> * 要启用二次识别，您必须在 VolcanoASRParameters 参数中透传 "enable_nonstream": true。

> * 使用流式语音识别大模型 2.0 版本时，StreamMode 取值只能为 1 或 2，推荐用 2。 | |└── ContextHistoryLength |Integer |否 |上下文轮次。将最近指定轮数会话内容送入流式语音识别大模型，辅助模型理解当前对话的背景，从而提升大模型识别准确性。

取值范围为 [0, 20]，默认为 0 表示不开启该功能。 | #### 与 StartVoiceChat 的配置差异 RTC、ASR、VAD、声纹、远场人声抑制和视觉截图中的同名参数，可以参考 [开启 AI 对话 StartVoiceChat](https://docs.volcengine.com/docs/6348/2123348) 的说明和取值。两种接入方式的字段层级不同，不要直接复制 `StartVoiceChat` 请求体。以下 `StartVoiceChat` 配置不适用于 MMPG： * `ASRConfig.InterruptConfig`。请通过 `assistant.audio.cancel` 或递增 `resp_id` 控制打断。 * `AgentConfig.WelcomeMessage`。请由业务服务端生成并发送欢迎语音频。 * `AgentConfig.EnableConversationStateCallback`、`AgentConfig.ServerMessageURLForRTS` 和 `AgentConfig.ServerMessageSignatureForRTS`。MMPG 通过当前 WebSocket 连接返回事件。 * `VisionConfig.SnapshotConfig.ImageDetail` 和 `VisionConfig.StorageConfig`。MMPG 不支持图片精细度配置，也不支持通过该配置将截图存储到 TOS。 * LLM、TTS、函数调用、联网问答和记忆等 Agent 能力由业务服务端实现，不在 `session.create` 中配置。 ### `session.update` 配置会话创建后，可以通过 `session.update` 更新 `AudioConfig.VoicePrint` 和 `AudioConfig.FarfieldConfig`。当前不支持更新其他配置。更新成功后，MMPG 返回 `session.updated`；更新失败时返回 `error`。 #### 更新 VoicePrint `VoicePrint.Enable` 和 `VoicePrint.VoiceDuration` 仅在实时无感声纹场景生效。修改 `VoiceDuration` 时，需要同时将 `Enable` 设为 `true`。注册状态通过 `user.audio.speaker.voiceprint` 返回，新声纹从下一轮 ASR 开始生效。 ```JSON { "event_id": "event_update_voiceprint_001", "type": "session.update", "session": { "AudioConfig": { "VoicePrint": { "Enable": true, "VoiceDuration": 15 } } } } ``` #### 更新 FarfieldConfig * `FarfieldConfig` 仅在使用火山引擎流式语音识别大模型时生效，更新时需要传入完整配置，不支持只传入其中一部分字段。 * 由于不同硬件设备的收音特性差异较大，必须根据实际设备类型和应用场景选择合适的 Level 或 Threshold。若参数设置不当（如抑制过强），可能会导致正常用户的声音也被抑制，影响收音质量。建议根据实际业务场景进行细致调试。示例如下： ```JSON { "event_id": "event_update_farfield_001", "type": "session.update", "session": { "AudioConfig": { "FarfieldConfig": { "Enable": true, "Level": "Low", "Threshold": 0, "FixedSource": false } } } } ``` ### WebSocket 事件参考 #### 网关 \-\> 业务服务端每个事件都包含 `event_id` 和 `type`。涉及对话轮次的事件还会包含 `conv_id`，涉及 AI 回复音频的事件会包含 `resp_id`。部分事件还包含以下字段： * `user.conversation.canceled.reason`：本轮对话取消原因。例如，`speaker_mismatch` 表示声纹验证不匹配。 * `user.audio.transcription.started.start_ms`：首个有效文字的时间，单位为毫秒。 * `user.audio.transcription.started.sv_active`：当前声纹验证是否已生效。 * `user.audio.transcription.segment`、`user.audio.transcription.done` 中的 `vp_id`、`vp_name`：声纹识别结果。 * `user.image.delta` 中的 `image_id`、`fragment_id`、`is_partial`：图片及分片标识。按 `fragment_id` 排序并拼接 Base64 解码后的数据，可还原 JPEG 图片。 |**Event Type** |**描述** |**数据结构示例** | |---|---|---| |**session.created****session.updated** |`session.create` 或 `session.update` 成功后的回调。 |```JSON```
```{```
``` "event_id": "event_session_001",```
``` "type": "session.created"```
```}```
| |**user.conversation.created** |检测到用户开始说话，新一轮对话开始。 |```JSON```
```{```
``` "event_id": "event_conversation_001",```
``` "type": "user.conversation.created",```
``` "conv_id": "conversation_001"```
```}```
| |**user.conversation.done** |本轮用户对话结束。 |```JSON```
```{```
``` "event_id": "event_conversation_002",```
``` "type": "user.conversation.done",```
``` "conv_id": "conversation_001"```
```}```
| |**user.conversation.canceled** |本轮对话被取消，例如未识别到有效文字或声纹验证失败。 |```JSON```
```{```
``` "event_id": "event_conversation_003",```
``` "type": "user.conversation.canceled",```
``` "conv_id": "conversation_001",```
``` "reason": "speaker_mismatch"```
```}```
| |**user.audio.delta** |用户原始音频。需要将 `AudioConfig.EnableUserAudio` 设为 `true`。音频为 16 kHz、16\-bit、单声道 PCM。 |```JSON```
```{```
``` "event_id": "event_audio_001",```
``` "type": "user.audio.delta",```
``` "conv_id": "conversation_001",```
``` "payload": "BASE64_ENCODED_AUDIO"```
```}```
| |**user.audio.transcription.started** |ASR 识别到首个有效文字。 |```JSON```
```{```
``` "event_id": "event_transcription_001",```
``` "type": "user.audio.transcription.started",```
``` "conv_id": "conversation_001",```
``` "start_ms": 2000,```
``` "sv_active": false```
```}```
| |**user.audio.transcription.delta** |流式识别结果。需要将 `UserTranscriptMode` 设为 `1`。 |```JSON```
```{```
``` "event_id": "event_transcription_002",```
``` "type": "user.audio.transcription.delta",```
``` "conv_id": "conversation_001",```
``` "transcript": "你好"```
```}```
| |**user.audio.transcription.segment** |用户说话停顿时返回当前识别片段。需要开启 `EnablePrefetch`。 |```JSON```
```{```
``` "event_id": "event_transcription_003",```
``` "type": "user.audio.transcription.segment",```
``` "conv_id": "conversation_001",```
``` "transcript": "你好，请介绍一下",```
``` "vp_id": "voiceprint_001",```
``` "vp_name": "user_001"```
```}```
| |**user.audio.transcription.done** |返回本轮最终识别结果，通常用于触发自有 Agent。 |```JSON```
```{```
``` "event_id": "event_transcription_004",```
``` "type": "user.audio.transcription.done",```
``` "conv_id": "conversation_001",```
``` "end_ms": 5000,```
``` "transcript": "你好，请介绍一下今天的天气。",```
``` "vp_id": "voiceprint_001",```
``` "vp_name": "user_001"```
```}```
| |**user.audio.speaker.verification** |声纹验证成功，仅声纹降噪场景发送。 |```JSON```
```{```
``` "event_id": "event_voiceprint_001",```
``` "type": "user.audio.speaker.verification",```
``` "conv_id": "conversation_001"```
```}```
| |**user.audio.speaker.voiceprint** |返回声纹生成状态，仅动态无感声纹场景需要关注。 |```JSON```
```{```
``` "event_id": "event_voiceprint_002",```
``` "type": "user.audio.speaker.voiceprint",```
``` "status": 1```
```}```
| |**user.image.delta** |JPEG 格式的视频截图分片。需要开启 `VisionConfig`。 |```JSON```
```{```
``` "event_id": "event_image_001",```
``` "type": "user.image.delta",```
``` "conv_id": "conversation_001",```
``` "format": "jpeg",```
``` "compress": "base64",```
``` "image_id": "image_001",```
``` "fragment_id": 1,```
``` "payload": "BASE64_ENCODED_IMAGE",```
``` "is_partial": false```
```}```
| |**user.message** |收到客户端通过 RTC SDK 发送的自定义消息。 |```JSON```
```{```
``` "event_id": "event_message_001",```
``` "type": "user.message",```
``` "payload": "custom message"```
```}```
| |**assistant.audio.started** |MMPG 开始向客户端发送指定 `resp_id` 的音频。 |```JSON```
```{```
``` "event_id": "event_playback_001",```
``` "type": "assistant.audio.started",```
``` "resp_id": 1```
```}```
| |**assistant.audio.done** |指定 `resp_id` 的音频已全部发送给客户端。 |```JSON```
```{```
``` "event_id": "event_playback_002",```
``` "type": "assistant.audio.done",```
``` "resp_id": 1```
```}```
| |**assistant.audio.canceled** |指定 `resp_id` 的待播音频已被清空。 |```JSON```
```{```
``` "event_id": "event_playback_003",```
``` "type": "assistant.audio.canceled",```
``` "resp_id": 1```
```}```
| |**error** |会话建立或执行过程中发生错误。请记录完整事件，并结合关联请求和服务日志排查。 |```JSON```
```{```
``` "event_id": "event_error_001",```
``` "type": "error",```
``` "message": "request failed"```
```}```
| #### 业务服务端 \-\> 网关 |**Event Type** |**描述** |**数据结构示例** | |---|---|---| |**session.create** |创建会话并绑定 RTC 房间。每条 WebSocket 连接首先发送该事件。完整配置参见前文 `session.create` 示例。 |```JSON```
```{```
``` "event_id": "event_create_001",```
``` "type": "session.create",```
``` "session": {```
``` "AgentConfig": {```
``` "TransmitConfig": {```
``` "Type": "rtc",```
``` "AppId": "your_app_id",```
``` "RoomId": "your_room_id",```
``` "UserId": "your_agent_user_id",```
``` "TargetUserId": ["your_user_id"]```
``` }```
``` }```
``` }```
```}```
| |**session.update** |更新声纹或远场人声抑制配置。更新时传入对应模块的完整配置。 |```JSON```
```{```
``` "event_id": "event_update_001",```
``` "type": "session.update",```
``` "session": {```
``` "AudioConfig": {```
``` "VoicePrint": {```
``` "Enable": true,```
``` "VoiceDuration": 15```
``` }```
``` }```
``` }```
```}```
| |**session.close** |结束会话并释放资源。 |```JSON```
```{```
``` "event_id": "event_close_001",```
``` "type": "session.close"```
```}```
| |**assistant.audio.delta** |流式发送 Base64 编码的 AI 音频。最后一个音频数据包需要将 `done` 设为 `true`。 |```JSON```
```{```
``` "event_id": "event_audio_001",```
``` "type": "assistant.audio.delta",```
``` "resp_id": 1,```
``` "payload": "BASE64_ENCODED_AUDIO",```
``` "done": false```
```}```
| |**assistant.audio.cancel** |清空正在播放和等待播放的 AI 音频。 |```JSON```
```{```
``` "event_id": "event_cancel_001",```
``` "type": "assistant.audio.cancel"```
```}```
| |**assistant.message** |向客户端发送自定义消息。 |```JSON```
```{```
``` "event_id": "event_message_001",```
``` "type": "assistant.message",```
``` "payload": "custom message"```
```}```
| ### 音频格式 > 音频格式必须与 `session.create` 中声明的 `AssistantAudioFormat` 一致，否则可能出现无声、变速或音调异常。 |`AssistantAudioFormat` |音频要求 | |---|---| |`pcm16` |16 kHz、16\-bit、单声道 PCM。 | |`pcm24` |24 kHz、16\-bit、单声道 PCM。 | |`pcm32` |32 kHz、16\-bit、单声道 PCM。 | |`pcm48` |48 kHz、16\-bit、单声道 PCM。 | |`ogg_opus` |单声道 Ogg Opus，编码帧长必须为 20 ms，采样率必须为 48 kHz。使用 Ogg Opus 时，同一个 `resp_id` 的音频流建议封装为一条独立的 Ogg，不同 `resp_id` 的音频数据不能封装在同一个 Ogg 中。 | 使用 `ogg_opus` 时，可以通过 `AudioConfig.AudioFormat.AssistantAudioProcessMode` 选择处理方式： * `demux`：默认模式。MMPG 仅对 Ogg 容器解封装，并将 Opus 数据发送给客户端。 * `decode`：MMPG 将 Ogg Opus 解码为 24 kHz、16\-bit、单声道 PCM 后发送给客户端。无论使用哪种处理方式，`assistant.audio.delta.payload` 都是 Base64 字符串。Base64 解码后的各数据块必须按顺序组成连续的 Ogg Opus logical stream。