多模态实时交互服务架构

前提条件
开通服务并获取必要参数。
开通阿里云百炼实时多模交互应用,获取Workspace ID、APP ID和API Key。
环境依赖
运行环境要求:Go 1.18 及以上版本。
依赖安装方式:本SDK提供源码集成,请下载multimodal-go-sdk 并按照说明集成。完整示例可参考压缩包中examples。
音频格式说明
使用 Go SDK接入使用 websocket 传输协议。
-
WS 链路音频格式说明:
- 上行:支持 pcm (16k 采样率 16bit 单通道)和 opus 音频流。
- 下行:支持 pcm 和 mp3 音频流。
客户端调用的三种模式
对比项 | push2talk | tap2talk | duplex |
|---|---|---|---|
类型 | 客户端控制模式 | 点击模式 | 双工模式 |
音频上传方式 | 按需 | 持续 Listening状态超过20秒不上传音频即报错 | 持续 任何状态超过20秒不上传音频都报错 |
VAD检测方 | 客户端 | 服务端 | 服务端 |
打断方式 | RequestToSpeak消息打断 | RequestToSpeak消息打断 | 语音打断 |
使用场景 | 由用户控制开始/结束客户端语音发送和识别,适用于按键说话,松开停止说话的场景。 | 客户端需持续上传音频,服务端自动检测语音活动的场景。但不支持用户语音打断大模型输出,只能发送RequestToSpeak打断消息。 | 客户端需持续上传音频,服务端自动检测语音活动的场景。用户随时可以说话打断大模型输出。 |
接口说明
dashscope.MultiModalDialog
客户端请求(客户端 → 服务端)
主对话管理类,提供与服务端交互的所有方法。
1. NewMultiModalDialog
创建交互,设置回调。
2. Start
启动对话服务,返回 OnStarted 回调。注意 OnStarted 会回调 dialogID。
3. StartSpeech
通知服务端开始上传音频,注意需要在 LISTENING 状态才可以调用。
4. SendAudioData
发送语音数据。
5. StopSpeech
通知服务端结束上传音频。
6. Interrupt
通知服务端,客户端需要打断当前交互,开始说话。
7. LocalRespondingStarted
通知服务端,客户端开始播放 TTS 音频。
8. LocalRespondingEnded
通知服务端,客户端结束播放 TTS 音频。
9. Stop
结束当前轮次对话。
10. GetDialogState
获得当前对话服务状态,返回 DialogState 枚举。
11. RequestToRespond
请求服务端直接文本合成语音,或者发送指令给服务端。
请求参数
RequestParameters
字段 | 类型 | 描述 |
|---|---|---|
| *Upstream | 上行参数 |
| *Downstream | 下行参数 |
| *ClientInfo | 客户端信息 |
| *BizParams | 业务参数(可选) |
Upstream
字段 | 类型 | 必选 | 描述 |
|---|---|---|---|
| string | 否 | 音频格式,支持pcm,raw-opus,默认为pcm |
| string | 是 | 上行类型: AudioOnly 仅语音通话 AudioAndVideo 音视频通话 |
| string | 否 | 客户端使用的模式,默认tap2talk。 可选项:
|
| map | 否 | 其他参数通过透传方式传递 |
Downstream
字段 | 类型 | 必选 | 描述 |
|---|---|---|---|
| string | 否 | 合成语音的音色,支持范围取决于用户在管控台选择的语音合成模型 |
| int | 否 | 合成语音的采样率,支持范围:
默认为24000。 千问-TTS、千问3-TTS模型仅支持24000。 |
| string | 否 | 控制返回给用户哪些中间文本:
可以设置多种,以逗号分隔,默认为transcript |
| string | 否 | 音频格式,支持pcm,opus,mp3,raw-opus,默认为pcm。 千问-TTS模型仅支持pcm。 注意:opus 和 raw-opus的区别是opus格式的每一包数据都有额外ogg封装(RFC 7845) |
| int | 否 | 合成音频的音量,取值范围0-100,默认50 |
| int | 否 | 合成音频的声调,取值范围50-200,默认100 |
| int | 否 | 合成音频的语速,取值范围50-200,表示默认语速的50%-200%,默认100 |
| map | 否 | 其他参数通过透传方式传递 |
ClientInfo
字段 | 二级参数 | 类型 | 必选 | 描述 |
|---|---|---|---|---|
| string | 是 | 终端用户ID,客户根据自己业务规则生成,用来针对不同终端用户实现定制化功能。最大长度36个字符。 | |
|
| string | 否 | 客户端全局唯一的ID,需要用户自己生成并传入SDK,最大长度40个字符。一个终端用户可以有多个设备,那么每一个设备的uuid都不同,但user_id相同。 |
|
| string | 否 | 调用方公网IP |
|
| string | 否 | 调用方所在城市,指明客户端粗略位置 |
| string | 否 | 调用方纬度信息,在需要客户端精确位置的业务场景提交 | |
| string | 否 | 调用方经度信息,在需要客户端精确位置的业务场景提交 |
BizParams
字段 | 类型 | 必选 | 描述 |
|---|---|---|---|
| map | 否 | 设置需要透传给agent的参数,各类agent传递的参数参考调用官方Agent文档说明。可以在extra_config子节点中设置对话扩展参数,目前支持enable_web_search,表示是否开启联网搜索。这里的设置优先级更高,会覆盖管控台配置。 |
| map | 否 | 用于设置用户自定义prompt变量,由用户自定义设置json中的key和value。管控台上配置自定义prompt变量的方法参考应用配置-提示词 |
| map | 否 | 用于设置用户自定义对话变量,由用户自定义设置json中的key和value。管控台上配置自定义对话变量的方法参考应用配置-对话变量 |
| map | 否 | 其他参数通过透传方式传递 |
构建参数示例
MultiModalCallback 回调接口
服务端返回 (服务端 → 客户端)
回调接口,用于处理语音聊天过程中的各种事件。
对话状态说明(DialogState)
OnStateChanged接口回调的状态包括 LISTENING、THINKING、RESPONDING 三个状态:
- Listening:表示机器人正在监听用户输入,用户可以发送音频。
- Thinking:表示机器人正在思考。
- Responding:表示机器人正在生成语音或语音回复中。
调用交互时序图

更多SDK接口使用说明
VQA(图片问答)交互
VQA 是在对话过程中通过发送图片实现图片+语音的多模交互的功能。
核心过程是通过输入类似"看一下xxx"意图的语音,或者直接输入请求文本的方式触发 VQA,返回基于图片内容的问答结果。
-
通过语音请求的流程为:
- 语音说:"看一下前面有什么"。
- 通过回调函数
OnRespondingContent返回拍照意图 "visual_qa"。 - 客户端收到上述意图后,调用
RequestToRespond接口提交图片内容触发问答回复。
-
直接通过文本请求流程为:
- 客户端直接调用request_to_respond接口提交图片内容和请求文本,触发问答回复。
通过Websocket请求LiveAI(视频通话)
LiveAI(视频通话)是百炼多模交互提供的官方 Agent。通过 Go SDK 发送图片序列的方式,可以实现视频通话的功能。我们推荐您的服务端和客户端(网页或者 APP)通过 RTC 传输视频和音频,然后将服务端采集到的视频帧以 500ms/张 的速度发送给 SDK,同时保持实时的音频输入。
注意:LiveAI 发送图片只支持 base64 编码,每张图片的大小在 180K 以下。
- LiveAI调用时序

- 关键代码示例
文本合成TTS
SDK支持通过文本直接请求服务端合成音频。
您需要在客户端处于Listening状态下发送RequestToRespond请求。
若当前状态非Listening,需要先调用Interrupt 接口打断当前播报。
自定义提示词变量和传值
- 在管控台项目【提示词】配置自定义变量。
user_name字段代表用户昵称。并将变量user_name以占位符形式${user_name}插入到Prompt 中。

- 在代码中设置变量。
"user_name" = "大米"。
- 请求回复

使用文本请求对话结果
SDK支持通过文本直接请求返回 LLM 结果和语音合成数据。
您需要在客户端处于Listening状态下发送RequestToRespond请求。
SDK连接和状态管理
1. 资源管理
使用完毕后请调用 Cleanup() 方法释放所有资源:
2. 心跳保活
建议定期发送心跳以保持链接:
3. 状态监控
通过实现 MultiModalCallback 接口监控对话状态变化: