移动端Android SDK

MultiModalDialog SDK是阿里云通义团队提供的支持音视频端到端多模实时交互的SDK。通过SDK对接通义大模型以及后端多种Agent，能够支持用户接入语音对话、天气、音乐、新闻等多种能力，并支持视频和图像的大模型对话能力。

前提条件

• 开通阿里云百炼实时多模交互应用，获取Workspace ID、APP ID和API Key。

• 下载SDK和 Demo bailian-multi-modal-android-sdk-1.0.4.1.zip并配置必要的环境、依赖。

• 导入示例代码，按照调用流程接入SDK。

• 您可以直接运行压缩包中的 APK 测试程序，填入上方三个必要参数，即可进行测试。

SDK接入

交互数据链路说明

SDK支持Websocket和RTC 两个链路与服务端交互，多模交互支持AudioOnly和AudioAndVideo 两种模式：

• 音频交互：推荐使用Websocket 连接，连接速度较快，性能要求较低。

  • WS 链路音频格式说明：

    • 上行：支持 pcm 和 opus 格式音频进行语音识别。

    • 下行：支持 pcm 和 mp3 音频流。

• 音视频交互：仅支持RTC 传输方式连接进行交互，提供端到端的音视频多模交互能力。

  • RTC 链路音频格式说明：

    • 上行：支持 pcm 传入 SDK，传输采用 opus 格式。

    • 下行：支持从 SDK 获取 pcm，传输采用 opus 格式。

交互模式说明

SDK支持 Push2Talk、 Tap2Talk和Duplex（全双工）三种交互模式。

• Push2Talk: 长按说话，抬起结束的收音方式。

• Tap2Talk: 点击开始说话，自动判断用户说话结束的收音方式。

• Duplex: 全双工交互，连接开始后支持任意时刻开始说话，支持语音打断。

调用说明

SDK及其调用Demo。

SDK引用

导入依赖库。

• app/src/main/libs

  • convsdk-release_*.aar //阿里云VoiceChatSDK

  • multimodal_dialog_sdk.aar // 阿里云多模对话SDK

  • com.aliyun.aio:AliVCSDK_ARTC // 阿里云RTC SDK

• 其他DemoAPP引入的依赖：

  参考app/build.gradle

  implementation libs.androidbootstrap
  implementation libs.okhttp
  implementation libs.okio //Android OKHttp3应用要增加一个收入IO的okio包
  implementation libs.http.logging.interceptor
  implementation libs.core.ktx
  //导入视频云sdk
  implementation libs.alivcsdk.artc

关键参数

Demo简介

• EntranceActivity 入口页面，需要修改url/api_key/app_id等信息。

  • 可以通过页面选择使用RTC或者Websocket请求链路。

  • 可以通过页面选择对话使用Tap2Talk或者Duplex等模式。

• MultimodalDialogActivity，对话交互实现类。

  • Demo页面中引用TYAudioRecorder 作为录音输入，您可以替换为自己的实现。

  • Demo页面使用AudioPlayer作为音频播放输出，您可以选择使用自己的实现类。

  • Demo在音频交互模式下，支持VQA（图生文）功能，即通过语音说“拍照识别xxx”，触发服务下发拍照意图。之后：

    • 您可以将本地拍照并上传OSS（或其他内容服务生成公共链接），触发单张图片的识别和对话。

    • 您也可以直接上传图片的base64请求服务或者图片的对话结果。

  • Demo在VideoAndAudio音视频交互模式下，目前通过外部采集的方式输入图像序列，方便眼镜等IoT设备的采集和视频对话接入。

接口设计

MultimodalDialog 对话入口类

1. MultiModalDialog

   初始化对话类，传入必要的全局参数。

   /**
        * 初始化     
        * @param context: 上下文
        * @param url: 服务器地址
        * @param chainMode: 链路模式
        * @param workspaceId: 工作空间id
        * @param appId: 应用id
        * @param dialogMode: 对话模式
        * */
       fun MultiModalDialog(
           context: Context,
           url: String?,
           chainMode: ChainMode?,
           workspaceId: String?,
           appId: String?,
           dialogMode: DialogMode?
       )

2. createConversation

   创建会话。

   /**
        * 初始化成功后，启动对话流程
        * @param params 初始化参数
        * @param chatCallback 主回调，除了初始化过程的所有消息，都会从这里透出给上层
        */
       fun createConversation(@NonNull MultiModalRequestParam params,chatCallback: IConversationCallback)

3. start

   开始对话。

   /**
        * 连接,启动对话
        */
       fun start()

4. stop

   结束对话。

   /**
        * 断开,结束对话
        */
       fun stop()

5. destroy

       /**
        * 销毁实例
        */
       fun destroy()

6. setConversationTimeout

   设置超时时间。

       /**
        * 设置对话超时时间,当服务未在指定时间内检出用户说话，上报timeout事件
        * @param timeout 超时时间,单位ms
        */
       fun setConversationTimeout(timeout: Long)

7. interrupt

   打断交互。

       /**
        * 打断AI说话
        */
       fun interrupt()

8. startSpeech

   通知服务端开始上传音频，注意需要在Listening状态才可以调用。只需要在Push2Talk模式下调用。

   /**
    * 通知服务端开始上传音频，注意需要在Listening状态才可以调用。
    * 只需要在Push2Talk模式下调用。
    */
   fun startSpeech()

9. sendAudioData

   通知服务端上传音频。

   /**
    * 通知服务端上传音频。
    * @param audioData 音频帧数据
    */
   fun sendAudioData(audioData: ByteArray?)

10. stopSpeech

    通知服务端结束上传音频。只需要在Push2Talk模式下调用。

    /**
     * 通知服务端结束上传音频。只需要在Push2Talk模式下调用。
     * Push2Talk 用户结束说话
     */
    fun stopSpeech()

11. requestToRespond

    请求服务端回答指定问题or做TTS播放出来。

    /**
         * 请求服务端回答指定问题or做TTS播放出来
         * @param type: transcript 表示直接把文本转语音，prompt 表示把文本送大模型回答
         * @param text：对应的文本
         * @param params: 额外参数
         */
        fun requestToRespond(type: String, text: String, params: JSONObject)

12. 其他接口。

        /**
         * 当前配置是否是全双工模式
         */
        fun isDuplexMode(): Boolean
    
        /**
         * Push2Talk 用户取消说话
         */
        fun cancelSpeech()
    
        /**
         * 发送语音回复结束
         * */
        fun sendResponseEnded()
        
        /**
         * 发送语音回复开始
         * */
        fun sendResponseStarted()
    
        /**
         * 推送视频帧
         *
         * @param videoFrame 视频帧
         * @param callback: 送帧结果回调
         */
        fun sendVideoFrame(videoFrame: TYVideoFrame,callback: IVideoChatPushFrameCallback)
    
    
        

关键参数枚举

MultiModalRequestParam 端云交互参数详情

{
    "header": {
        "action":"run-task",
        "task_id": "9B32878******************3D053",
        "streaming":"duplex"
    },
    "payload": {
        "task_group":"aigc",
        "task":"multimodal-generation",
        "function":"generation",
        "model":"multimodal-dialog",
        "input":{
          "directive": "Start",
          "workspace_id": "llm-***********",
          "app_id": "****************"
        },
        "parameters":{
          "upstream":{
            "type": "AudioOnly",
            "mode": "duplex"
          },
          "downstream":{
            "voice": "longxiaochun_v2",
            "sample_rate": 24000
          },
          "client_info":{
            "user_id": "bin********207",
            "device":{
              "uuid": "432k*********k449"
            },
            "network":{
              "ip": "10.0.0.9"
            },
            "location":{
              "city_name": "北京市"
            }
          },
          "biz_params":{
            "user_defined_params": {
                "agentIdA": {
                    "name": "value"
                }
            },
            "user_prompt_params": {
                "name": "value"
            },
            "user_query_params": {
                "name": "value"
            }
          }
        }
    }
}

IConversationCallback （回调接口）

    /**
     * 对话启动结果，鉴权、客户端加入通道成功后，会回调该消息
     */
    fun onStartResult(isSuccess: Boolean, errorInfo: TYError?)

    /**
     * 主动打断的回调，包括手动打断和语音打断
     */
    fun onInterruptResult(isSuccess: Boolean, errorInfo: TYError?)

    /**
     * 对话准备完成，多端（客户端/VoiceChat/视频理解）均加入通道后，会回调该消息，此时才能调用业务接口
     */
    fun onReadyToSpeech()

    /**
     * 状态切换回调
     * 包含DIALOG_IDLE，DIALOG_LISTENING，DIALOG_RESPONDING，DIALOG_THINKING
     */
    fun onConvStateChangedCallback(state: DialogState)

    /**
     * 音量强度回调
     * @param audioType 参考 {@link Constant.TYVolumeSourceType}
     * @param audioLevel 0-100
     */
    fun onConvSoundLevelCallback(audioLevel: Float, audioType: Constant.TYVolumeSourceType)

    /**
     * 超出用户有效输入超时时间的超时时间，收到此事件，用户需要重新启动或者结束对话
     * @param timeout 超时时间
     */
    fun onSpeechTimeout(timeout: Long)

    /**
     * 回路音频，用于客户端AEC回声消除
     * @param bytes 音频数据
     */
    fun onPlaybackAudioData(bytes: ByteArray)

    /**
     * 对话过程中的异常信息
     * @param errorInfo 异常信息
     */
    fun onErrorReceived(errorInfo: TYError)

    /**
     * 对话过程中的事件信息
     * @param errorInfo 事件信息
     */
    fun onConvEventCallback(var1: ConvEvent?)

    /**
     * 运行过程中回调关键日志信息给上层
     * @param level 日志级别，参考Android.Log
     * @param type 日志类型
     * @param debugInfo 日志信息
     */
    fun onDebugInfoTrack(level: Int, type: Constant.TYDebugInfoType, debugInfo: String)

onConvEventCallback AI对话 Response详情

• EVENT_HUMAN_SPEAKING_DETAIL

  语音识别内容

  SpeechContent - response

  一级参数	二级参数	三级参数	类型	是否必选	说明
  output	event		string	是	事件名称：SpeechContent
  	dialog_id		string	是	对话id
  	text		string	是	用户语音识别出的文本，流式全量输出
  	finished		bool	是	输出是否结束

  {
      "header": {
          "request_id": "9B32878******************3D053",
          "service_id": "368208df",
          "status_code": 200,
          "status_name": "Success",
          "status_message": "Success.",
          "attributes":{
            "user_id":"1234557879x"
          }
      },
      "payload": {
          "output":{
            "event": "SpeechContent",
            "dialog_id": "b39398c9dd8147********35cdea81f7",
            "text": "一二三",
            "finished": false
          },
          "usage":{
            "invoke":10,
            "model_x":10
          }
      }
  }

• EVENT_RESPONDING_DETAIL

  大模型的返回文本

  output	finished		bool	是	输出是否结束
  	dialog_id		string	是	对话id
  	event		string	是	消息类型
  	text		string	否	LLM大模型返回的文本结果
  	spoken		string	否	LLM大模型返回的播放内容的文本，可能跟 text 字段有所不同。
  	extra_info		object	否	其他扩展信息，目前支持： commands: 命令字符串 agent_info: 智能体信息 tool_calls: 插件返回的信息 dialog_debug: 对话debug信息 timestamps: 链路中各节点时间戳

  示例：

  {
      "header": {
          "event":"result-generated",
          "task_id": "9B32878******************3D053"
      },
      "payload": {
          "output":{
            "event": "RequestAccepted",
            "dialog_id": "b39398c9dd8147********35cdea81f7",
            "text": "您输入了数字序列“12345”。如果您有关于这些数字的问题或者需要我用它们来完成某项任务，请告诉我更多的细节，我会尽力帮助您。",
            "spoken": "您输入了数字序列“12345”。如果您有关于这些数字的问题或者需要我用它们来完成某项任务，请告诉我更多的细节，我会尽力帮助您。",
            "finished": true,
          "extra_info": {
            "commands": "[{\"name\":\"VOLUME_SET\",\"params\":[{\"name\":\"series\",\"normValue\":\"70\",\"value\":\"70\"}]}]",
            "tool_result": [{
              "id": "",
              "type": "function",
              "function": {
                "name": "function_name",
                "arguments": "{\"id\": \"123\", \"name\": \"test\"}",
                "outputs": "函数调用结果",
                "status": {
                  "code": 200,
                  "message": "Success."
                }
              }
            }]
          }
          },
          "usage":{
            "invoke":10,
            "model_x":10
          }
      }
  }

异常处理

onErrorReceived - response

调用时序

全双工交互

半双工交互

multiModalDialog.sendAudioData(data);

multiModalDialog.sendRefData(data);

private void executeCmd(String cmd,String dialogId,String taskId){
  String cmdName = null;
  String cmdParamValue = null;
  try {
    cmdName = new JSONArray(cmd).getJSONObject(0).getString("name");
  }catch (Exception ex) {
    ex.printStackTrace();
  }
  switch (cmdName){
     case "visual_qa":
       JSONObject extraObject = new JSONObject();
       extraObject.put("images", imagesArray);
       multimodalConversation.requestToRespond(type, text, extraObject.toString());
       break:
  ......
}

//上传拍照
public static JSONArray getMockOSSImage() {
    JSONObject imageObject = new JSONObject();
    JSONArray images = new JSONArray();
    try{
      if (vqaUseUrl){
        imageObject.put("type", "url");
        imageObject.put("value", "https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/7043267371/p909896.png");
      }else {
        imageObject.put("type", "base64");
        imageObject.put("value", getLocalImageBase64());
      }
      images.put(imageObject);

    }catch (Exception e){
      e.printStackTrace();
    }
    return images;
  }

//1. 设置交互类型为AudioAndVideo
MultiModalRequestParam.UpStream.builder().mode("duplex").type("AudioAndVideo").build();

//2. 在建联后发送voicechat_video_channel 请求
private void startVideoMode() {
    if (isVideoMode) return;

    try {
        MultiModalRequestParam updateParams = MultiModalRequestParam.builder().build();
        JSONObject videoObj = new JSONObject();
        videoObj.put("action", "connect");
        videoObj.put("type", "voicechat_video_channel");

        List<JSONObject> videos = new ArrayList<>();
        videos.add(videoObj);

        updateParams.setBizParams(MultiModalRequestParam.BizParams.builder()
                .videos(videos).build());

        multiModalDialog.requestToRespond("prompt", "", updateParams.getParametersAsJson());
        multiModalDialog.setVideoContainer(videoContainer, uiHandler);

        isVideoMode = true;
        runOnUiThread(() -> videoContainer.setVisibility(View.VISIBLE));

    } catch (JSONException e) {
        Log.e(TAG, "启动视频模式失败", e);
    }
}

//3. 开始音视频交互。处理交互流程。注意 demo 中Constant.ChainMode.RTC 类型的处理。
private void handleOutputStarted() {
    if (!isRtcUseInternalAudio()) {
        audioPlayer.pause(true);
        audioPlayer.play();
    }
    if (authParams.getChainMode() == Constant.ChainMode.RTC) {
        //RTC 模式下，tts 合成数据速度为正常比例
        multiModalDialog.sendResponseStarted();
    }
}

private void handleOutputCompleted() {
    Log.d(TAG, "输出完成");
    if (authParams.getChainMode() != Constant.ChainMode.RTC) {
        multiModalDialog.sendResponseEnded();
        audioPlayer.isFinishSend(true);
    }
}

//1. 设置交互类型为AudioAndVideo
MultiModalRequestParam.UpStream.builder().mode("duplex").type("AudioAndVideo").build();

//2. 在建联后发送voicechat_video_channel 请求
private void startVideoMode() {
    if (isVideoMode) return;

    try {
        MultiModalRequestParam updateParams = MultiModalRequestParam.builder().build();
        JSONObject videoObj = new JSONObject();
        videoObj.put("action", "connect");
        videoObj.put("type", "voicechat_video_channel");

        List<JSONObject> videos = new ArrayList<>();
        videos.add(videoObj);

        updateParams.setBizParams(MultiModalRequestParam.BizParams.builder()
                .videos(videos).build());

        multiModalDialog.requestToRespond("prompt", "", updateParams.getParametersAsJson());
        multiModalDialog.setVideoContainer(videoContainer, uiHandler);

        isVideoMode = true;
        runOnUiThread(() -> videoContainer.setVisibility(View.VISIBLE));

    } catch (JSONException e) {
        Log.e(TAG, "启动视频模式失败", e);
    }
}

//3. 每 500ms 提交一张视频帧照片数据，注意图片尺寸小于 180KB。
/**
 * DEMO 流程未调用。演示在 websocket 链路中实现 liveAI
 * 启动视频帧流，每 500ms 发送一次图片帧
 */
private void startVideoFrameStreaming() {
    Thread videoStreamingThread = new Thread(() -> {
        try {
            while ( !Thread.currentThread().isInterrupted()) {
                Thread.sleep(500);

                JSONObject extraObject = new JSONObject();
                extraObject.put("images", getMockOSSImage());

                multiModalDialog.updateInfo(extraObject);
                }
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        } catch (JSONException e) {
            throw new RuntimeException(e);
        }
    });

    videoStreamingThread.setDaemon(true);
    videoStreamingThread.setName("LiveAI-VideoStreaming");
    videoStreamingThread.start();

}

/**
 * build images list request
 * */
private static JSONArray getMockOSSImage() {
    JSONObject imageObject = new JSONObject();
    JSONArray images = new JSONArray();
    try{

        imageObject.put("type", "base64");
        imageObject.put("value", getLocalImageBase64());

        images.put(imageObject);

    }catch (Exception e){
        e.printStackTrace();
    }
    return images;
}

//read local image to base64
private static String getLocalImageBase64(){
    return "";
}

conversation.requestToRespond("transcript","幸福是一种技能，是你摒弃了外在多余欲望后的内心平和。",null);

//在请求参数构建中传入biz_params.user_prompt_params
HashMap<String, String> userPromptParams = new HashMap<>();
userPromptParams.put("user_name", "大米");
        MultiModalRequestParam.BizParams bizParams = MultiModalRequestParam.BizParams
                .builder()
                .userPromptParams(userPromptParams)
                .build();