本文介绍了如何使用阿里云百炼大模型服务提供的实时多模交互移动端 Android SDK,包括SDK下载安装、关键接口及代码示例。
多模态实时交互服务架构

前提条件
- 开通阿里云百炼实时多模交互应用,获取Workspace ID、APP ID和API Key。
- 下载SDK和 Demo并配置必要的环境、依赖。
- 导入示例代码,按照调用流程接入SDK。
- 您可以直接运行压缩包中的 APK 测试程序,填入上方三个必要参数,即可进行测试。
Package | Version |
1.0.6.7 |
SDK接入
交互数据链路说明
SDK使用WebSocket协议与服务端交互,支持AudioOnly和AudioAndVideo 两种模式:
- 音频交互:仅支持音频和文本对话功能。
- 音视频交互:在交互中通过指令方式进入视频通话模式,客户端持续向服务端发送图片序列,实现端到端的音视频多模交互能力。
交互模式说明
SDK支持 Push2Talk、 Tap2Talk和Duplex(全双工)三种交互模式。
- Push2Talk: 长按说话,抬起结束的收音方式。
- Tap2Talk: 点击开始说话,自动判断用户说话结束的收音方式。
- Duplex: 全双工交互,连接开始后支持任意时刻开始说话,支持语音打断。
调用说明
SDK及其调用Demo。
SDK引用
导入依赖库。
-
app/src/main/libs
- convsdk-release_*.aar //阿里云VoiceChatSDK
- multimodal_dialog_sdk.aar // 阿里云多模对话SDK
- multimodal_dialog_tongyimetathings.aar //使用 License 模式接入服务使用的鉴权 SDK
-
其他Demo APP 引入的依赖:
参考
app/build.gradle
关键参数
参数名称 | 是否必须 | 值 | 说明 |
url | 是 | String | 请求的服务端地址。 WebSocket 链路地址:wss://dashscope.aliyuncs.com/api-ws/v1/inference |
api_key | 是 | String | 百炼服务接入API Key。请您在百炼平台创建API_KEY,移动端为了安全考虑,您也可以在服务端接入短时Token,并下发给客户端使用。 |
workspace_id | 是 | String | 百炼管控台,业务空间 ID。 |
app_id | 是 | String | 您在管控台创建的应用 ID。 |
chain_mode | 是 | String | WebSocket。 |
Demo简介
-
EntranceActivity 入口页面,需要修改url/api_key/app_id等信息。
- 可以通过页面选择对话使用Tap2Talk或者Duplex等模式。
- 使用 License 模式,请参考子文档【使用 License 模式接入Android SDK】。
-
MultimodalDialogActivity,对话交互实现类。
- Demo页面中引用TYAudioRecorder 作为录音输入,您可以替换为自己的实现。
- Demo页面使用AudioPlayer作为音频播放输出,您可以选择使用自己的实现类。
-
Demo在音频交互模式下,支持VQA(图生文)功能,即通过语音说"拍照识别xxx",触发服务下发拍照意图。之后:
- 您可以将本地拍照并上传OSS(或其他内容服务生成公共链接),触发单张图片的识别和对话。
- 您也可以直接上传图片的 base64 数据,向服务请求图片识别对话结果。
- Demo在VideoAndAudio音视频交互模式下,目前通过外部采集的方式输入图像序列,方便眼镜等IoT设备的采集和视频对话接入。
接口设计
MultimodalDialog 对话入口类
- MultiModalDialog 初始化对话类,传入必要的全局参数。
- createConversation 创建会话。
- start 开始对话。
- stop 结束对话。
- destroy
- setConversationTimeout 设置超时时间。
- interrupt 打断交互。
- startSpeech 通知服务端开始上传音频,注意需要在Listening状态才可以调用。只需要在Push2Talk模式下调用。
- sendAudioData 通知服务端上传音频。
- stopSpeech 通知服务端结束上传音频。只需要在Push2Talk模式下调用。
- requestToRespond 请求服务端回答指定问题或做TTS播放出来。
- 其他接口。
关键参数枚举
参数 | 值 | 说明 |
ChainMode | WebSocket | 支持AudioOnly和AudioAndVideo两种交互 |
DialogMode | TAP2TALK | 手动开始,自动结束 |
PUSH2TALK | 手动开始,手动结束 | |
DUPLEX | 全双工交互 |
MultiModalRequestParam 端云交互参数详情
Start - Input Message 请求开始会话消息。服务收到Start消息后,向客户端发送Started消息。一级参数 | 二级参数 | 类型 | 是否必选 | 说明 |
|---|---|---|---|---|
task_group | string | 是 | 任务组名称,固定为"aigc",请直接复制使用 | |
task | string | 是 | 任务名称,固定为"multimodal-generation",请直接复制使用 | |
function | string | 是 | 调用功能,固定为"generation",请直接复制使用 | |
model | string | 是 | 阿里云百炼模型名称,固定为"multimodal-dialog",请直接复制使用 | |
input | directive | string | 是 | 指令名称:Start |
workspace_id | string | 是 | 客户在阿里云百炼业务空间ID(Workspace ID),可在多模态交互开发套件控制台,点击左下角业务空间名称,"业务空间详情"中查看,目前仅支持主账号默认业务空间。 | |
app_id | string | 是 | 客户创建的应用ID(APP ID),可在多模态交互开发套件控制台的"我的应用"页面查看。 | |
dialog_id | string | 否 | 对话ID,默认不填时是开启新会话,服务端会自动生成并在事件中下发,格式示例:"12345678-1234-1234-1234-1234567890ab",共36个字符。当希望继续之前的对话时,把当时服务端下发的dialog_id在这里传入 | |
parameters | upstream | object | 是 | 参数说明参考下方 parameters.upstream的参数说明表格 |
downstream | object | 否 | 参数说明参考下方 parameters.downstream的参数说明表格 | |
client_info | object | 是 | 参数说明参考下方 parameters.client_info的参数说明表格 | |
biz_params | object | 否 | 参数说明参考下方 parameters.biz_params的参数说明表格 |
一级参数 | 类型 | 是否必选 | 说明 |
|---|---|---|---|
type | string | 是 | 上行类型: AudioOnly 仅语音通话 |
mode | string | 否 | 客户端使用的模式,默认tap2talk。 可选项:
三种模式的对比可以参考下方的客户端使用的三种模式对比表格。 |
audio_format | string | 否 | 音频格式,支持pcm,raw-opus,默认为pcm |
sample_rate | int | 否 | 语音识别的采样率,支持范围:
默认为16000 |
vocabulary_id | string | 否 | 热词id,设置该参数时会覆盖管控台热词配置。当管控台提供的热词不能满足客户需求时,可以考虑用Open API程序化管理热词,参见热词API文档。 |
language | string | 否 | 语音识别语种,默认和控制台选择的语言保持一致。 |
一级参数 | 类型 | 是否必选 | 说明 |
|---|---|---|---|
voice | string | 否 | 合成语音的音色,支持范围取决于用户在管控台选择的语音合成模型 |
sample_rate | int | 否 | 合成语音的采样率,支持范围:
默认为24000。 千问-TTS、千问3-TTS模型仅支持24000。 |
audio_format | string | 否 | 音频格式,支持pcm,opus,mp3,raw-opus,默认为pcm。 千问-TTS模型仅支持pcm。 注意:opus 和 raw-opus的区别是opus格式的每一包数据都有额外ogg封装(RFC 7845) |
frame_size | int | 否 | 合成音频的帧大小,取值范围:
默认值为60,单位ms 只在合成音频格式为opus或raw-opus时生效 |
volume | int | 否 | 合成音频的音量,取值范围0-100,默认50 |
speech_rate | int | 否 | 合成音频的语速,取值范围50-200,表示默认语速的50%-200%,默认100 |
pitch_rate | int | 否 | 合成音频的声调,取值范围50-200,默认100 |
bit_rate | int | 否 | 合成音频的比特率,取值范围:6~510kbps,默认值为32,单位kbps,只在合成音频格式为mp3, opus或raw-opus时生效 |
intermediate_text | string | 否 | 控制返回给用户哪些中间文本:
可以设置多种,以逗号分隔,默认为transcript |
word_timestamp_enabled | boolean | 否 | 是否下发tts合成音频对应的时间戳。如果设置为true,会在RespondingContent.extra_info下返回时间戳信息,用于客户端显示字幕等,默认为false。 必须在intermediate_text有指定dialog的情况下才会返回; 只有CosyVoice音色列表中表明支持时间戳的音色和复刻音色才会返回。 |
transmit_rate_limit | int | 否 | 下发音频发送速率限制,单位:字节每秒 |
incremental_response | boolean | 否 | 是否增量返回大模型结果,true为增量,false为全量。默认为false,全量下发 |
instruction | string | 否 | 设置指令,用于控制方言、情感等合成效果。该功能适用的模型以及在不同模型的格式要求请参见指令控制。 |
language | string | 否 | 语音合成语种,默认和控制台选择的语言保持一致。 |
一级参数 | 二级参数 | 类型 | 是否必选 | 说明 |
|---|---|---|---|---|
user_id | string | 是 | 终端用户ID,客户根据自己业务规则生成,用来针对不同终端用户实现定制化功能。最大长度36个字符。 | |
device | uuid | string | 否 | 客户端全局唯一的ID,需要用户自己生成并传入SDK,最大长度40个字符。一个终端用户可以有多个设备,那么每一个设备的uuid都不同,但user_id相同。 |
network | ip | string | 否 | 调用方公网IP |
location | latitude | string | 否 | 调用方纬度信息,在需要客户端精确位置的业务场景提交 |
longitude | string | 否 | 调用方经度信息,在需要客户端精确位置的业务场景提交 | |
city_name | string | 否 | 调用方所在城市,指明客户端粗略位置 |
一级参数 | 类型 | 是否必选 | 说明 |
|---|---|---|---|
user_defined_params | json object | 否 | 设置需要透传给agent 和 mcp 服务的参数,各类agent传递的参数参考调用官方Agent文档说明, mcp 传递参数依照 mcp 服务本身所需的参数。可以在extra_config子节点中设置对话扩展参数,目前支持:1. enable_web_search,表示是否开启联网搜索。这里的设置优先级更高,会覆盖管控台配置;2. agent_timeout,表示agent连接超时的时间,传值范围是10秒到120秒。如果不传,则默认为10秒。 |
user_prompt_params | json object | 否 | 用于设置用户自定义prompt变量,由用户自定义设置json中的key和value。管控台上配置自定义prompt变量的方法参考应用配置-提示词 |
user_query_params | json object | 否 | 用于设置用户自定义对话变量,由用户自定义设置json中的key和value。管控台上配置自定义对话变量的方法参考应用配置-对话变量 |
对比项 | push2talk | tap2talk | duplex |
|---|---|---|---|
类型 | 客户端控制模式 | 点击模式 | 双工模式 |
音频上传方式 | 按需 | 持续 Listening状态超过20秒不上传音频即报错 | 持续 任何状态超过20秒不上传音频都报错 |
VAD检测方 | 客户端 | 服务端 | 服务端 |
打断方式 | RequestToSpeak消息打断 | RequestToSpeak消息打断 | 语音打断 |
使用场景 | 由用户控制开始/结束客户端语音发送和识别,适用于按键说话,松开停止说话的场景。 | 客户端需持续上传音频,服务端自动检测语音活动的场景。但不支持用户语音打断大模型输出,只能发送RequestToSpeak打断消息。 | 客户端需持续上传音频,服务端自动检测语音活动的场景。用户随时可以说话打断大模型输出。 |
IConversationCallback (回调接口)
onConvEventCallback AI对话 Response详情
-
EVENT_HUMAN_SPEAKING_DETAIL
语音识别内容
SpeechContent - response
一级参数
二级参数
三级参数
类型
是否必选
说明
output
event
string
是
事件名称:SpeechContent
dialog_id
string
是
对话 ID。
text
string
是
用户语音识别出的文本,流式全量输出
finished
bool
是
输出是否结束
-
EVENT_RESPONDING_DETAIL
大模型的返回文本
示例:output
finished
bool
是
输出是否结束
dialog_id
string
是
对话 ID。
event
string
是
消息类型
text
string
否
大模型返回的文本结果。
spoken
string
否
大模型返回的播放内容的文本,可能跟 text 字段有所不同。
extra_info
object
否
其他扩展信息,目前支持:
commands: 命令字符串
agent_info: 智能体信息
tool_calls: 插件返回的信息
dialog_debug: 对话debug信息
timestamps: 链路中各节点时间戳
异常处理
onErrorReceived - response
通用错误码
如遇报错问题,请参见多模态交互套件-错误码进行排查。
若问题仍未解决,请联系技术支持,反馈遇到的问题,并提供完整的request_id和dialog_id,以便进一步排查问题。
调用时序
全双工交互

半双工交互

更多SDK接口使用说明
双工交互
移动端Android SDK支持Duplex 双工交互模式。 在双工交互模式下,SDK支持在播放语音合成回复的同时,输入录音数据。当用户在此时说话时,服务会自动打断当前播报数据返回 (客户端播放器缓存需要应用层处理),并开始新的回复。
双工交互需要实现回声消除(AEC,Acoustic Echo Cancellation),Android SDK内置了回声消除算法。当您需要使用双工交互时,仍需要您进行必要的配置。
- 输入麦克风录音音频
- 输入参考通道音频
VQA交互
VQA 是在对话过程中通过发送图片实现图片+语音的多模交互的功能。
核心过程是语音或者文本请求拍照意图触发"visual_qa"拍照指令。
当客户端通过回调函数onConvEventCallback收到拍照指令后, 发送图片链接或者base64数据(支持小于 180 KB 的图片)。
- 处理"visual_qa" command和上传拍照。
通过 WebSocket 链路请求LiveAI
LiveAI (视频通话)是百炼多模交互提供的官方Agent。通过Android 全功能版本SDK, 您也可以在 WebSocket 链路中通过自行录制视频帧的方式来调用视频通话功能。
注意:通过 WebSocket 调用 LiveAI发送图片只支持base64编码,每张图片的大小在 180 KB 以下。
- LiveAI调用时序

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

ASR结果即时纠错
在对话过程中,ASR 识别结果有可能出现错误或者非预期的结果。 除了配置热词之外,您也可以通过即时纠错功能接口上传词表进行实时干预。
- 参数说明。
参数 | 一级参数 | 二级参数 | 类型 | 说明 |
|---|---|---|---|---|
AsrPostProcessing | Object | ASR 纠错词表 | ||
ReplaceWord[] | List | 词表列表,每个ReplaceWord 对应一组词的替换规则 | ||
source | String | 需要被替换的文本 | ||
target | String | 替换目标文本 | ||
match_mode | String | 匹配模式,默认为exact: exact:整句精确匹配,只有文本与source完全相同才匹配成功 partial:部分匹配,文本中部分字符与source相同即匹配成功 |