Android SDK

本文介绍了如何使用阿里云智能语音服务提供的Android NUI SDK,包括SDK下载安装、关键接口及代码示例。

前提条件

  • 创建项目并获取项目Appkey。

    语音对话的项目类型选择语音识别 + 语音合成 + 语音分析,然后在服务管理与开通页面将其升级为商用版。

  • 获取Token

下载安装

下载SDK和示例代码

说明

请下载后在样例初始化代码中替换您的阿里云账号信息、AppkeyToken才可运行。

类别

兼容范围

系统

支持Android 4.0以上版本,API LEVEL 14。

架构

armeabi-v7a,arm64-v8a,x86,x86_64。

接口说明

  • createConversation:创建交互,设置回调。对应销毁接口为destroyConversation

    /**
     * 初始化SDK,SDK为单例,请先释放后再次进行初始化。请勿在UI线程调用,可能会引起阻塞。
     * @param callback:事件监听回调,参见下文具体回调。
     * @param parameters:json string形式的初始化参数,参见下方说明或接口说明:
     * @return:参见错误码
     */
    public synchronized int createConversation(final INativeConvCallback callback);

    其中INativeConvCallback类型包含如下回调:

    • onConvEventCallback:SDK事件回调。

      /**
       * SDK主要事件回调
       * @param event:回调事件,可通过调用其中具体方法获得事件及相关信息。具体方法见下方ConvEvent
       */
      void onConvEventCallback(ConvEvent event);
      • ConvEvent方法列表:

        方法名

        说明

        int getStatusCode();

        获得状态码/错误码,详情请参见SDK错误码

        String getErrorMessage();

        获得错误信息。

        String getDialogId();

        获得当前dialog_id。

        Constants.ConvEventType getEventType();

        获得当前事件类型,详情请参见下方ConvEventCode

      • ConvEventCode:

        SDK事件名称

        事件说明

        EVENT_CONVERSATION_STARTED

        AI登场。会话任务成功启动,建连成功。

        EVENT_CONVERSATION_FAILED

        会话任务发生错误,需要查看错误码及错误信息。收到此事件后需要根据错误信息判断如何处理,也可以使用此dialog_id重新连接,继续会话。

        EVENT_COVERSATION_COMPLETED

        AI退场。任务成功完成,执行断连操作。

        EVENT_SENTENCE_BEGIN

        HUMAN开始说话。PushToTalk模式按键则触发此事件,TapToTalkDuplex模式是用户开始说话触发此事件。

        EVENT_SENTENCE_END

        HUMAN说话结束。PushToTalk模式按键松开则触发此事件,TapToTalkDuplex模式是用户说话结束触发此事件。

        EVENT_DATA_OUTPUT_STARTED

        开始播放服务端TTS数据。

        EVENT_DATA_OUTPUT_COMPLETED

        服务端TTS数据合成完成。

        EVENT_INTERRUPT_ACCEPTED

        AI(服务端)接收按键请求(如打断)。

        EVENT_INTERRUPT_DENIED

        AI(服务端)拒绝按键请求(如打断)。

        EVENT_VOICE_INTERRUPT_ACCEPTED

        AI(服务端)接收语音请求(如打断)。

        EVENT_VOICE_INTERRUPT_DENIED

        AI(服务端)拒绝语音请求(如打断)。

        EVENT_HUMAN_SPEAKING_DETAIL

        ASR识别结果。

        EVENT_RESPONDING_DETAIL

        大模型返回的结果。

    • onConvStateChangedCallback:SDK状态回调。

      /**
       * SDK状态回调
       * @param state:回调事件,可通过调用其中具体方法获得事件及相关信息。具体方法见下方DialogState
       */
      void onConvStateChangedCallback(int state);
      
      public enum DialogState {
          DIALOG_IDLE(0),
          DIALOG_LISTENING(1),
          DIALOG_RESPONDING(2),
          DIALOG_THINKING(3),
      }

      DialogState:AI(服务端)处于的状态。

      名称

      说明

      DIALOG_IDLE

      当前处于空闲未工作状态。

      DIALOG_LISTENING

      AI(服务端)处于听状态,接收用户输入数据(如MIC音频数据)。

      DIALOG_RESPONDING

      AI(服务端)处于反馈状态,发送AI的数据(如TTS音频数据)。

      DIALOG_THINKING

      AI(服务端)处于思考阶段。

    • onConvDataReceivedCallback:收到返回的结果数据。

      /**
       * 获得返回数据(如音频)回调
       * @param buffer:返回的数据
       */
      int onConvDataReceivedCallback(byte[] buffer);
    • onConvSoundLevelCallback:获得的输入音频的音量级别。

      /**
       * 计算输入音频的音量级别,从低到高0-100,以及对应的db值
       * @param level:音频的音量级别,从低到高0-100
       * @param db:音频db值,-160 - 0
       */
      void onConvSoundLevelCallback(int level, float db);
    • onConvEventTrackCallback:获得关键埋点信息日志。

      /**
       * 日志埋点输出函数
       * @param level:输出日志的级别, 详见 ConvLogLevel
       * @param log:关键埋点信息日志
       */
      void onConvEventTrackCallback(int level, String log);
  • destroyConversation:销毁交互。对应创建接口为createConversation

    /**
     * 
     * @return:参见错误码
     */
    public synchronized int destroyConversation();
  • connect:与服务端建立链接。

    /**
     * 初始化SDK并连接AI服务。
     * @param parameters:json string形式的初始化参数,参见下方说明或接口说明:
     * @return:参见错误码
     */
    public synchronized int connect(String parameters);

    参数设置:

    参数

    类型

    是否必选

    说明

    appkey

    String

    项目Appkey。详情请参见创建项目

    token

    String

    鉴权信息。

    url

    String

    域名地址。生产环境网关URL:

    wss://nls-gateway-cn-beijing.aliyuncs.com/ws/v1

    workspace

    String

    资源为resources目录下的相关文件。

    例如以下示例工程中,通过拷贝aar包的资源文件,获得资源文件所处的路径,即为workspace。

    ConvUtils.copyAssetsData(this);
    ConvUtils.getModelPath(this);

    dialog_id

    String

    对话ID,空代表新的对话,传入则代表继续通话。格式为32位随机字符串。

    mode

    String

    运行模式。取值如下:

    • duplex(默认):在tap2talk的模式上提供语音打断能力,端侧具备移动端AEC算法处理能力。

    • tap2talk:语音起点由端侧VAD给出。

    • push2talk:按键语音交互,语音的起点和尾点由按键时间给出。

    user_agent

    String

    客户端userAgent,用来记录和鉴权。

    debug_path

    String

    日志和音频文件存储目录,不设置则在workspace下创建debug目录。

    save_log

    Boolean

    是否存储日志,默认false。

    save_wav

    Boolean

    是否存储音频,默认false。

    log_level

    String

    日志级别,取值范围:

    • verbose

    • debug

    • info(默认)

    • warn

    • warning

    • error

    device_id

    String

    设备唯一标识#utdid。

    dialog_attributes

    JSONObject

    AI角色属性。

    dialog_attributes.model_id

    String

    大模型ID(枚举,给出支持的列表)。

    dialog_attributes.prompt

    String

    大模型prompt,最长800个字符。

    dialog_attributes.voice

    String

    TTS音色(成品音色,比如 longxiaochun,或者客户克隆voiceName, 补充权限校验)。

    dialog_attributes.voice_detection_enabled

    Boolean

    是否开启语音检测,去掉开始和结束的静音,并且当句尾静音长度超过X(服务端控制)的时候认为指令结束。

    默认为true,push2talk模式可设为false。

    advanced_attributes

    JSONObject

    高级属性。

    advanced_attributes.context_depth

    String

    控制用户问题调大模型服务时附加多少历史对话,取值:

    • 0:表示不附加历史。

    • n:大于0的整数表示附加n轮问答历史,范围 [1, 10]。

    • all(默认):表示附加本次通话中所有历史。

    advanced_attributes.enable_search

    String

    是否开启LLM搜索增强,默认为false(不开启)。

    advanced_attributes.xingchen

    String

    model_idxingchen-model时表示调用星辰的模型,必传此内容。JSON格式字符串,JSON内容为:

    "{\"character_id\":\"xxxxx\",\"user_id\":\"xxxx\"}"

    character_iduser_id是星辰的参数,必传。

  • disconnect:断开链接。

    /**
     * @param force:true则内部快速关闭websocket,false则内部进行stopdisconnect.
     * @return:参见错误码
     */
    public synchronized int disconnect(boolean force);
  • interrupt:打断交互,使AI进入听状态。在PushToTalk模式下,在AI说和AI思考状态下打断返回空闲状态。

    /**
     * 打断交互,使AI进入听状态。
     * @return:返回打断结果,允许打断返回SUCCESS,拒绝打断返回REQUEST_DENIED
     */
    public synchronized int interrupt();
  • sendAudioData:推送实时采集的音频数据。

    /**
     * @return:参见错误码
     */
    public synchronized int sendAudioData(byte[] buffer, int len);
  • sendRefData:推送参考音频数据,在音频数据送给播放器时推送。

    /**
     * @return:参见错误码
     */
    public synchronized int sendRefData(byte[] buffer, int len);
  • sendResponseData:Listening/Idle状态下,通知服务端与用户主动交互,可以直接把上传的文本转换为语音下发,也可以上传文本调用大模型,返回的结果再转换为语音下发。

    /**
     * @param parameters:json string形式的初始化参数,参见下方说明或接口说明:
     * @return:参见错误码
     */
    public synchronized int sendResponseData(String parameters);

    参数设置:

    参数

    类型

    是否必选

    说明

    type

    String

    服务应该采取的交互类型。取值如下:

    • transcript:表示直接把文本转语音。

    • prompt:表示把文本送大模型回答。

    text

    String

    要处理的文本。

  • updateMessage:更新参数(例如rtc、p2t)。

    /**
     * 更新其他服务的参数。
     * @param parameters:json string形式的初始化参数,参见下方说明或接口说明:
     * @return:参见错误码
     */
    public synchronized int updateMessage(String parameters);
    • RTC相关命令

      RTC INIT:

      {
      	"type": "rtc",
      	"action": "INIT"
      }

      RTC设置:

      {
      	"type": "rtc",
      	"from_state": "2",
      	"seq_id": "1",
      	"to_state": "0"
      }
    • p2t模型相关命令

      p2t按下按钮时更新agent_chat,可填写zh、en、ja、ko。

      {"type":"update_nls_parameters","agent_chat":{"language_type":"zh","answer_language_type":"en"}}
      # 或
      {"type":"update_nls_parameters","SendSpeech_agent_chat":{"language_type":"zh","answer_language_type":"en"}}
      
      # SendSpeech_agent_chat 优先级高于 agent_chat
    • 更新其它参数命令。

      {"type":"update_nls_parameters","avatar":{}}
      
      {"type":"update_nls_parameters","client_info":{}}
      
      {"type":"update_nls_parameters","agent_chat":{}}
      
      {"type":"update_nls_parameters","SendSpeech_extra_info":"{\"prompt\":\"123\",\"sessionId\":\"456\"}"}
    • 更新参数万能方法

      用户自定义服务端交互参数,具体说明如下:

      参数字段

      说明

      "type": "update_custom_nls_parameters"

      表示使用用户自定义参数功能。

      nls_rule

      规定参数在协议中添加的位置,例如:

      • "payload": ["Start_custom2", "SendSpeech_custom3"]表示在向服务端发送"Start"协议时,payload中添加参数"custom2":{"test":2}

      • "header": ["Start_custom1"] 表示在向服务端发送"Start"协议时,header中添加参数"custom1":{"test":1}

      {
      	"type": "update_custom_nls_parameters",
      	"nls_rule": {
      		"header": ["Start_custom1"],
      		"payload": ["Sart_custom2", "SendSpeech_custom3"],
      		"context": ["Stop_custom4"]
      	},
      	"nls_params": {
      		"Start_custom1": {
      			"test": 1
      		},
      		"Sart_custom2": {
      			"test": 2
      		},
             "SendHumanSpeech_custom3": {
      			"test": 3
      		},
      		"Stop_custom4": {
      			"test": 4
      		}
      	}
      }
  • setAction:需要有一个音频(播放)开始/结束事件告知到SDK。

    /**
     * @return:参见错误码
     */
    public synchronized int setAction(ConvConstants.ConvAppAction action);
    
    public enum ConvAppAction {
        MIC_STARTED,
        MIC_STOPPED,
        PLAYER_STARTED,
        PLAYER_STOPPED,
        ENABLE_VOICE_INTERRUPT,
        DISABLE_VOICE_INTERRUPT,
        VOICE_MUTE,
        VOICE_UNMUTE,
        START_HUMAN_SPEECH,   /* 仅在push2talk模式有效, 表示用户开始说话 */
        STOP_HUMAN_SPEECH,    /* 仅在push2talk模式有效, 表示用户说话完毕 */
        CANCEL_HUMAN_SPEECH,  /* 仅在push2talk模式有效, 表示用户说话取消 */
        PULL_OUT_HEADPHONES;
    }
    
    • ConvAppAction

      名称

      说明

      MIC_STARTED

      MIC开始工作。

      MIC_STOPPED

      MIC停止录音。

      PLAYER_STARTED

      开始播放。

      PLAYER_STOPPED

      播放完毕。

      说明

      需确保播放器中缓存数据全部播放完毕后给出,否则会导致自打断或播放数据进入ASR。

      ENABLE_VOICE_INTERRUPT

      开启语音打断功能。

      DISABLE_VOICE_INTERRUPT

      关闭语音打断功能。

      VOICE_MUTE

      语音静音。若正在AI听阶段,则主动告知AI,用户已经说完话。

      VOICE_UNMUTE

      语音静音关闭。

      START_HUMAN_SPEECH

      仅在push2talk模式有效, 表示用户开始说话。

      STOP_HUMAN_SPEECH

      仅在push2talk模式有效,表示用户说话完毕。

      CANCEL_HUMAN_SPEECH

      仅在push2talk模式有效,表示用户说话取消。

      PULL_OUT_HEADPHONES

      拔耳机时调用,用于优化耳机切换的回声消除效果。

    • p2t模式按下按键代码示例。

      // 设置语种,即设置参数agent_chat
      JSONObject root_obj = new JSONObject();
      JSONObject agent_chat_obj = new JSONObject();
      agent_chat_obj.put("language_type", "zh");
      agent_chat_obj.put("answer_language_type", "en");
      root_obj.put("SendHumanSpeech_agent_chat", agent_chat_obj);
      root_obj.put("type", "update_nls_parameters");
      
      conv_instance.updateMessage(root_obj.toString());
      
      conv_instance.setAction(ConvConstants.ConvAppAction.START_HUMAN_SPEECH);
    • p2t模式松开按键代码示例。

      conv_instance.setAction(ConvConstants.ConvAppAction.STOP_HUMAN_SPEECH);
    • p2t模式取消用户说话代码示例。

      conv_instance.setAction(ConvConstants.ConvAppAction.CANCEL_HUMAN_SPEECH);
  • getState:获得当前各种状态。

    /**
     * @param param:
     * @return:根据ConvStateType,返回对应事件的枚举值的int值,需要转换对应枚举
     */
    public synchronized int getState(ConvConstants.ConvStateType state);
    
    public enum ConvStateType {
        DIALOG_STATE,
        MIC_STATE,
        PLAYER_STATE;
    }
    
    /**
     * 返回对应枚举
     */
    public enum DialogState {
        DIALOG_IDLE(0),
        DIALOG_LISTENING(1),
        DIALOG_RESPONDING(2),
        DIALOG_THINKING(3);
    }
    
    public enum ConvAppAction {
        MIC_STARTED,
        MIC_STOPPED,
        PLAYER_STARTED,
        PLAYER_STOPPED;
    }
    • ConvStateType

      名称

      说明

      DIALOG_STATE

      对话(AI)当前状态,枚举值为ConvConstants.DialogState。

      MIC_STATE

      MIC当前状态,枚举值为ConvConstants.ConvAppAction。

      PLAYER_STATE

      PLAYER当前状态,枚举值为ConvConstants.ConvAppAction。

    • DialogState

      名称

      说明

      DIALOG_IDLE

      当前处于空闲未工作状态。

      DIALOG_LISTENING

      AI(服务端)处于听状态,接收用户输入数据(如MIC音频数据)。

      DIALOG_RESPONDING

      AI(服务端)处于反馈状态,发送AI的数据(如TTS音频数据)。

      DIALOG_THINKING

      AI(服务端)处于思考阶段。

    • ConvAppAction

      名称

      说明

      MIC_STARTED

      MIC开始工作。

      MIC_STOPPED

      MIC停止录音。

      PLAYER_STARTED

      开始播放。

      PLAYER_STOPPED

      播放完毕。

SDK错误码

状态码

状态消息

说明

11

MEM_ALLOC_ERROR

内存分配失败。

50

INIT_FAILED

初始化为不支持的模式。

51

NOT_CONNECTED

链接失败,如联网超时等。

52

ENGINE_NULL

交互引擎未创建,不可使用。

53

ILLEGAL_PARAM

设置参数非法。

54

ILLEGAL_INIT_PARAM

初始化参数非法。

55

INVALID_STATE

当前交互状态无法调用此接口。

56

HAS_INVOKED

已经调用了此接口。

57

NOT_CREATE_CONVERSATION

还未创建会话即未调用createConversation就开始操作。

58

SKIP_SEND_DATA

当前交互状态忽略此次音频。

59

SEND_DATA_FAILED

发送音频失败。

60

INVALID_AUDIO_DATA

无效音频。

61

STOP_FAILED

stop()失败,如超时。

62

CANCEL_FAILED

cancel()失败,如超时。

63

INVOKE_TIMEOUT

接口调用超时。

64

REQUEST_DENIED

打断请求拒绝。

65

REQUEST_ACCEPTED

允许打断请求。

100

INTERNAL_ENGINE_INIT_FAILED

内部引擎初始化失败,常发生于connect()时。

101

INTERNAL_ENGINE_SET_PARAM_FAILED

内部引擎配置参数失败。

111

INTERNAL_ENGINE_RESOURCE_NOT_FOUND

内部引擎因为找不到资源文件而初始化失败,请检查资源文件是否完备,且是最新版本

112

INTERNAL_ENGINE_VAD_INVALID_PARAM

内部vad引擎的初始化参数非法。

113

INTERNAL_ENGINE_VAD_INVALID_STATE

内部vad引擎运行处于异常状态,比如vad已经释放。

114

INTERNAL_ENGINE_VAD_PROCESS_FAILED

内部VAD引擎在异常状态送入数据。

115

INTERNAL_ENGINE_VAD_CREATE_FAILED

内部vad引擎初始化失败,一般是由于资源文件缺失或者不兼容的旧版本。

200

EMPTY_CONV_EVENT

非法ConvEvent。

201

INVALID_CONV_EVENT_MSG_TYPE

非法的ConvEvent事件类型。

301

SERVER_NOT_ACCESS

链接服务端失败,比如服务端不可链接,DNS不可解析等。

311

JSON_FORMAT_ERROR

接收到服务端返回的消息不符合JSON格式。

312

SSL_ERROR

SSL失败,比如握手失败。

313

SSL_CONNECT_FAILED

SSL链接失败。

351

NLS_INVOKE_TIMEOUT

向服务端发送请求操作超时。

352

NLS_START_FAILED

向服务端发送建立会话请求失败,常为网络问题。

353

NLS_STOP_FAILED

向服务端发送停止会话请求失败,常为网络问题。

354

NLS_CANCEL_FAILED

向服务端发送停止会话请求失败,常为网络问题。

355

NLS_START_INBOUND_FAILED

向服务端发送启动对话任务请求失败,常为网络问题。

358

NLS_CANCEL_BOUND_FAILED

向服务端发送停止对话任务请求失败,常为网络问题。

359

NLS_SET_PARAMS_FAILED

设置请求参数错误,比如设置token无效。

360

NLS_SEND_AUDIO_FAILED

向服务端发送音频数据失败,常为网络问题

时序图说明

duplex

image

push2talk

image

tap2talk

image

常见问题

语音对话支持哪些LLM?

目前只支持通义千问大模型(包括Qwen_turbo、Qwen_plus等),不支持替换其他大模型。通义大模型支持列表,详情请参见通义千问大语言模型介绍

是否支持RAG?

支持。如果您有业务需求,请提交工单进行咨询。