机器人技能的Android SDK接入文档

文档修订记录

文档版本号	修订日期	修订原因
V1.0	2023.04.20	创建文档
V1.1	2023.10.23	优化文档

概述

NLP模块为语义理解，包含图灵API的所有技能。需要使用不同的技能可以指定参数请求使用或进入该技能。

权限声明

网络权限 - 使用过程中，会有https与wss请求、网络状态检测

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />

存储权限 - 使用过程中，会写入日志文件（debug），请在清单中指定以下内容。

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />   
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<!-- android10 以上需要额外添加-->
<uses-permission android:name="android.permission.MANAGE_EXTERNAL_STORAGE" />

在android10及以上需要在application标签下添加如下配置

android:requestLegacyExternalStorage="true"

配置文件

将turing_config.json配置文件放在main/assets文件夹下

{
  "authorization": {
    "apikey": "您的apikey",
    "secret": "您的secret"
  },
  "ability": {
    "nlp": {
      "codes": [],
      "robotSkills": {
      }
    }
  }
}

接口说明

public interface TuringNlpInterface {

    /**
     * 语义理解
     *
     * @param text        目标文本，限定合法的最大长度为100字符
     * @param isAssignNlp 是否指定Nlp参数
     * @param listener    TuringOSClientListener
     */
    public void actionNlp(String text, boolean isAssignNlp, TuringOSClientListener listener);

    /**
     * @param text             目标文本，限定合法的最大长度为100字符
     * @param nlpRequestConfig nlp请求参数，如设置为空，则使用Turing_config.json中的nlp配置，如没有nlp配置，则使用默认值
     * @param listener         接口回调
     */
    public void actionNlp(String text, NlpRequestConfig nlpRequestConfig, TuringOSClientListener listener);

    /**
     * 请求打招呼接口,一般用于开机或机器人的第一次交互,返回的结果可以在图灵平台进行配置
     *
     * @param listener 接口回调
     */
    void actionFirstConversion(TuringOSClientListener listener);

    /**
     * 请求主动交互,用于让机器人主动发起交互的场景,返回的结果可以在图灵平台进行配置
     *
     * @param listener 接口回调
     */
    void actionAutoConversion(TuringOSClientListener listener);

    /**
     * 释放资源
     */
    void release();
}

使用说明

功能使用

实例化

val turingNlp:TuringNlpInterface = TuringNlp.getInstance(this)

NLP调用

方法一：使用全局配置文件Turing_config.json中的参数，需配置nlp参数

//输入：我要玩成语接龙（该文字会触发成语接龙技能）
turingNlp.actionNlp("我要玩成语接龙",true,object :TuringOSClientListener{
            override fun onResult(
                code: Int,
                result: String?,
                baseResp: BaseResp?,
                extension: String?
            ) {
                TODO("Not yet implemented")
            }

            override fun onError(code: Int, msg: String?) {
                TODO("Not yet implemented")
            }

        })

返回示例：

{
    "code":200,
    "globalId":"115417187981503001",
    "message":"success",
    "nlpResponse":{
        "intent":{
            "code":10005,
            "operateState":1100
        },
        "results":[
            {
                "groupType":0,
                "resultType":"text",
                "values":{
                    "ttsUrl":[
                        "http://turing-iot.oss-cn-beijing.aliyuncs.com/tts/tts-c8162cf54ada46bf883c0c19c8eba0de-20fcbe842c4746949d8db99192c10d7e.mp3"
                    ],
                    "text":"欢迎进入“成语接龙”游戏，接不上了可以跟我说“提示”、 “换题”或“跳过”； 不想玩了可以对我说 “退出” 。来，让我验验你是学霸还是学酥。请接：江湖医生"
                }
            }
        ]
    }
}

方法二：使用NlpRequestConfig参数

//指定特定技能
val nlpConfig = NlpRequestConfig.Builder().codes(mutableListOf(1000018)).build()
turingNlp.actionNlp("明天吃什么",nlpConfig,object :TuringOSClientListener{
            override fun onResult(
                code: Int,
                result: String?,
                baseResp: BaseResp?,
                extension: String?
            ) {
                TODO("Not yet implemented")
            }

            override fun onError(code: Int, msg: String?) {
                TODO("Not yet implemented")
            }

        })

返回示例：

{
    "code":200,
    "globalId":"115340674635503001",
    "message":"success",
    "nlpResponse":{
        "intent":{
            "code":1000018,
            "operateState":1010
        },
        "results":[
            {
                "groupType":0,
                "resultType":"text",
                "values":{
                    "text":"What to eat tomorrow"
                }
            }
        ]
    }
}

开机提示语请求

需要现在图灵机器人开放平台增加开机提示语。

//调用示例
turingNlp.actionFirstConversion(listener);

返回示例：

{
    "code":200,
    "globalId":"130470788369483001",
    "message":"success",
    "nlpResponse":{
        "intent":{
            "code":1000010,
            "operateState":2001
        },
        "results":[
            {
                "groupType":1,
                "resultType":"text",
                "values":{
                    "text":"你好，我是图灵机器人！"
                }
            }
        ]
    }
}

主动交互请求

主动交互可以返回机器人主动发起对话的结果，返回的对话内容需要在图灵机器人开放平台配置。

turingNlp.actionAutoConversion(listener)

返回示例：

{
    "code":200,
    "globalId":"130519772800774001",
    "message":"success",
    "nlpResponse":{
        "intent":{
            "code":1000011,
            "operateState":2001
        },
        "results":[
            {
                "groupType":1,
                "resultType":"text",
                "values":{
                    "text":"你都不理人家！"
                }
            }
        ]
    }
}

参数说明

输入参数

NlpRequestConfig

对应turing_config.json中的nlp参数

参数	类型	是否必须	取值范围	说明
appState	AppState	N		前的应用状态
userInfo	Map	N		用户参数，协议扩展字段，可忽略
robotSkills	Map>	N		用户应用自定义参数，协议扩展字段
clientInfo	Map	N		客户端状态，协议扩展字段，可忽略
binaryDetail	Map	N		默认无需配置
codes	List	N	-	用户此次交互仅使用该参数中的应用，具体参考（http://docs.turingos.cn/api/apiV2/#turingos）
location	Map	N	-	可设置城市和经纬度查询天气如： "location": { "city": "深圳", "latitude": "22.547", "longitude": "114.085947" }

AppStateBean

参数	类型	默认值	说明
code	int	0	应用code（具体参考图灵API）
operateState	int	0	应用状态值

当不要特殊处理当前的上下文时，appStateBean该值可以省略。

通用operateState

code	说明
1000	主动退出
1010	无上下文结束
1100	启动
1200	暂停
1300	继续
1400	等待重启

userInfo

key	value	说明
requestIp	IP地址如：180.149.130.13	可设置IP地址查询该地址的天气

回调接口

TuringOSClientListener：文字输入方式时，对话结果使用该接口回调，接口信息与其他模块一致，使用方式参考文字输入方式的方法说明；

public interface TuringOSClientListener {
    /**
     * 请求成功结果
     * @param code          请求Code
     * @param result        请求结果 JSON
     * @param baseResp      请求结果 BaseResp，只包含基础字段
     * @param extension     扩展信息
     */
    void onResult(int code, String result, BaseResp baseResp, String extension);

    /**
     * 请求失败
     * @param code          请求失败Code，参考错误码
     * @param msg           请求失败信息
     */
    void onError(int code, String msg);
}

每一次独立的NLP请求会返回onResult或onError；
请求成功的结果json字符串对应result；
BaseResp：参考NLP输出说明；
extension：扩展输出字段，该模块暂时没有输出。

输出参数

TuringOSClientListener接口的onResult方法同时返回json数据和BaseResp对象。

json示例如下：

{
    "code":200,
    "globalId":"98412738103000000",
    "message":"success",
    "nlpResponse":{
        "intent":{
            "code":100000,
            "operateState":1010
        },
        "results":[
            {
                "groupType":0,
                "resultType":"text",
                "values":{
                    "emotionId":0,
                    "sentenceId":201,
                    "text":"你好呀，乖宝宝。"
                }
            }
        ]
    }
}

BaseResp说明

BaseResp只解析基础字段，技能的实体内容字段需要自行实现实体类来解析，TuringSDKSample已经给出大部分技能的解析实体类；

其他特殊技能可根据具体返回的Json自行实现具体的实体类。

参数	类型	说明
code	int	请求响应Code，具体可参考Code说明
done	boolean	此次对话是否结束状态，如果是最终结果则是true，否则是false
globalId	String	此次对话的唯一标识
message	String	请求响应的消息描述
nlpResponse	NlpResponse	语义请求结果

NlpResponse

参数	类型	说明
intent	Intent（Object）	语义理解结果的实体内容
results	List（Object）	语义理解结果的提示语和播放内容集合

NlpResponse-Intent

参数	类型	说明
code	Intent（Object）	此次请求命中的技能Code 具体参考技能说明
operateState	int	此次技能的状态值，可参考OperateState说明

注意：该对象内不包含其他字段值，开发者需要根据不同的技能返回的JSON来编写解析不同的实体类，TuringSDKSample已经给出大部分技能的解析实体类，仅供参考，以实际返回的JSON数据为主。

通用operateState

code	说明
1000	主动退出
1010	无上下文结束
1100	启动
1200	暂停
1300	继续
1400	等待重启

NlpResponse-List-Results

参数	类型	说明
groupType	int	组类型(普通接入可忽略该参数): 0为独立输出; 大于0时可能包含同组相关内容
resultType	String	输出类型：当 resultType=text 时：表示文本当 resultType=voice 时：表示音频 url 当 resultType=image 时：表示图片 url 当 resultType=video 时：表示视频 url
values	Values（Object）	输出内容（必会包含 resultType 对应的 key，其他会根据具体应用场景进行字段扩充）

例如：

当resultType="voice"时，values必会包含voice对应的key；

{
    //其他字段省略
    "groupType":0,
    "resultType":"voice",
    "values":{
        "voice":{
        "http://turing-iot.oss-cn-beijing.aliyuncs.com/tts/tts-c8162cf54ada46bf883c0c19c8eba0de-20fcbe842c4746949d8db99192c10d7e.mp3"
        }

    }
}

解析示例：

TuringSDKSample已经给出解析示例

Path：com.turing.sample.ai.chat.ChatActivity
Method：handlerResult

注意

语音对话中，语义理解输出的文字结果以及附加的播放内容集合主要在NlpResponse-List-Results中；

语义理解的技能实体内容主要NlpResponse-Intent中，具体参考返回的Json；

{
    "code":200,
    "globalId":"130635831624483001",
    "message":"success",
    "nlpResponse":{
        "intent":{
            "code":200101,
            "intentName":"play_music",
            "operateState":1100,
            "parameters":{
                "singer":"周杰伦",
                "name":"夜曲"
            }
        },
        "results":[
            {
                "groupType":0,
                "resultType":"text",
                "values":{
                    "ttsUrl":[
                        "http://turing-iot.oss-cn-beijing.aliyuncs.com/tts/tts-c8162cf54ada46bf883c0c19c8eba0de-3b4770ca7db84f38a04a9637f77d717f.mp3"
                    ],
                    "text":"好的，请听我唱周杰伦的夜曲。"
                }
            },
            {
                "groupType":0,
                "resultType":"voice",
                "values":{
                    "voice":"http://iot-cdn.turingapi.com/202012242027/292a437efe852f713c464197a401b553/media/audio/20180524/8930b3635cb04f0cbb769c9c277f9acc.mp3"
                }
            }
        ]
    }
}

Results：返回了语义理解结果的文本等内容；

NlpResponse-Intent-parameters：返回诗词技能的详细信息。

常见问题

1.语义理解结果没有播放文本的链接

NLP模块中会返回语义理解结果的文本，但是不一定返回文本对应的音频，可能在一些技能场景中会有返回附加音频，所以当语义理解场景中需要播放语义理解的内容，可以使用语音聊天模块，具体参考语音对话模块介绍；