语义理解

语义理解NLP模块

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

NLP参数说明

NLP请求参数

NlpRequestConfig为语义理解请求参数，具体说明如下：

参数	类型	是否必须	说明
appStateBean	AppStateBean	否	当前的应用状态
codes	List	否	用户此次交互仅使用该参数中的应用 具体参考API技能说明
clientInfo	Map	否	客户端状态，协议扩展字段，可忽略
userInfo	Map	否	用户参数，协议扩展字段，可忽略
location	Map	否	天气技能所需字段
contentMessage	Map	否	content中的扩展参数，协议扩展字段，可忽略
robotSkills	Map>	否	用户应用自定义参数，协议扩展字段，可忽略

AppStateBean

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

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

通用operateState

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

• NlpRequestConfig可以设定此次语义请求使用的技能，以及可以传入一些扩展参数；

• 当不传入NlpRequestConfig时，此次NLP默认使用聊天技能，如果目标文字触发技能进入语，将会进入该技能。

NlpRequestConfig参数创建（具体参数可参考TuringSDKSample）

    NlpRequestConfig.Builder builder = new                                                                          NlpRequestConfig.Builder();
    //当不要特殊处理当前的上下文时，appStateBean该值可以省略
    builder.appStateBean(appStateBean);     
    //指定此次请求的技能Code，聊天对话时可以省略
    builder.codes(userCodes);
    //指定此次请求的自定义参数，没有自定义参数时省略
    builder.robotSkills(customParams);  

创建指定技能的请求参数：

    //指定技能，以全文翻译技能为例 1000018为全文翻译技能的code
    //该技能为定制技能，需要联系图灵商务开通
    NlpRequestConfig.Builder nlpbuilder = new NlpRequestConfig.Builder();
    List<Integer> userCodes = new ArrayList<>();
    userCodes.add(Integer.valueOf(1000018));
    nlpbuilder.codes(userCodes);
    NlpRequestConfig nlp = nlpbuilder.build();

NLP请求结果

TuringOSClientListener接口

该接口为语义理解请求结果回调接口（同其他模块的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：扩展输出字段，该模块暂时没有输出。

NLP调用

方法说明

 /** 
    * 
    * @param text 限定合法的最大长度为100个字符
    * @param requestConfig NlpRequestConfig
    * @param listener TuringOSClientListener
    */
   public void actionNlp(String text, NlpRequestConfig requestConfig,                   TuringOSClientListener listener)

   /** 
    * 
    * @param text 限定合法的最大长度为100字符
    * @param listener TuringOSClientListener
    */
   public void actionNlp(String text, TuringOSClientListener listener)

    //调用
    client.actionNlp(text, requestConfig, Listener)

NLP调用示例

1.不指定NlpRequestConfig

备注：当不传入NlpRequestConfig时，此次NLP默认使用聊天技能，如果目标文字触发特定技能，将会进入该技能。

    //输入：我要玩成语接龙（该文字会触发成语接龙技能）
    client.actionNlp("我要玩成语接龙",  Listener)

返回示例：

{
    "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":"欢迎进入“成语接龙”游戏，接不上了可以跟我说“提示”、 “换题”或“跳过”； 不想玩了可以对我说 “退出” 。来，让我验验你是学霸还是学酥。请接：江湖医生"
                }
            }
        ]
    }
}

2.指定NlpRequestConfig

例如需要翻译文字:

        NlpRequestConfig.Builder nlpbuilder = new NlpRequestConfig.Builder();
        List<Integer> userCodes = new ArrayList<>();
        //1000018为全文翻译技能的code
        userCodes.add(Integer.valueOf(1000018));
        nlpbuilder.codes(userCodes);
        NlpRequestConfig nlp = nlpbuilder.build();

        client.actionNlp(text, requestConfig, new TuringOSClientListener());

返回示例：

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

NLP输出

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已经给出大部分技能的解析实体类；

大部分技能公用实体对象SkillParameters：

/**
 * 部分技能字段
 * 儿童聊天(100000) 英文对话(100102) 成语接龙(10005)
 * 知识库(100302) 歌曲点播(200101) 故事点播(200201)
 * 曲艺点播(200201) 十万个为什么(200205) 绕口令(200207)
 * 维基百科(200209) 脑筋急转弯(200211) 顺口溜(200212)
 * 动物叫声(200301) 大自然声音(200302) 乐器声音(200303)
 * 诗词背诵(200401) 拍照(200501) 跳舞(200701)
 * 日期查询(200702) 时间查询(200702) 闹钟(200710)
 * 笑话(201204) 四则运算(201501) 中英互译(201711)
 * 谁在叫(404003) 休眠(900101) 屏幕亮度(900110)
 * 电量查询(900110) 音量控制(900110) 开机提示语(1000010)
 * 主动交互(1000011)
 *
 *
 **/
public class SkillParameters implements Serializable

天气技能实体WeatherParameters；

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

BaseResp字段说明

参数	类型	说明
code	int	请求响应Code，具体可参考Code说明
message	String	请求响应的消息描述
nlpResponse	NlpResponse（Object）	语义请求结果

• 当code=200表示NLP成功；
• 其他code表示识别异常，参考Code说明。

NlpResponse

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

NlpResponse-Intent

参数	类型	说明
code	Intent（Object）	此次请求命中的技能Code 具体参考API技能说明
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；

比如诗词点播：

client.actionNlp("我要听李白的诗", requestConfig, listener);

{
    "code":200,
    "globalId":"130626025540774001",
    "message":"success",
    "nlpResponse":{
        "intent":{
            "code":200401,
            "intentName":"read",
            "operateState":1100,
            "parameters":{
                "author":"李白",
                "name":"听蜀僧濬弹琴",
                "type":"诗",
                "years":"唐代",
                "content":"蜀僧抱绿绮，西下峨眉峰。为我一挥手，如听万壑松。客心洗流水，余响入霜钟。不觉碧山暮，秋云暗几重。"
            }
        },
        "results":[
            {
                "groupType":0,
                "resultType":"text",
                "values":{
                    "text":"听蜀僧濬弹琴 唐代 李白 蜀僧抱绿绮，西下峨眉峰。为我一挥手，如听万壑松。客心洗流水，余响入霜钟。不觉碧山暮，秋云暗几重。"
                }
            }
        ]
    }
}

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

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

特殊天气技能

调用示例

NlpRequestConfig.Builder builder = new NlpRequestConfig.Builder();
AppStateBean weather = new AppStateBean();
weather.setCode(201401);
Map<String, Object> weatherInfo = new HashMap<>();
weatherInfo.put("city", "深圳");
//城市和坐标可以二选一
weatherInfo.put("longitude", "114.062252");
weatherInfo.put("latitude", "22.559938");
builder.location(weatherInfo);
builder.appStateBean(weather);
NlpRequestConfig requestConfig = builder.build();

client.actionNlp("今天天气怎么样！", requestConfig, new listener);

备注

天气城市使用顺序：

1.最优先使用用户输入文本；

2.使用缓存；

3.使用用户输入的location信息。

开机提示语请求

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

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

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

返回示例：

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

主动交互请求

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

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


    client.actionAutoConversion(listener)

返回示例：

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

上传通讯录和应用

该接口返回返回结果BaseResp为空，需要单独解析。

    /**
     * 上传通讯录与APP列表
     *
     * @param appAndContactsBean    上传数据;数据封装在 {@link AppAndContactsBean}中
     * @param turingOSClientListener 网络请求回调 {@link TuringOSClientListener}
     */
    public void uploadAppsAndContacts(AppAndContactsBean appAndContactsBean, TuringOSClientListener turingOSClientListener)


    //调用示例
    AppAndContactsBean appAndContactsBean = new AppAndContactsBean();
    Map<String, String> appMap = new HashMap<>();
    //设备中的app名称与app包名放入Map中
    appMap.put("日历", "com.android.calendar");
    appMap.put("微信", "com.android.wechat");
    appMap.put("拨号", "com.android.phone");
    Map<String, String> contactMap = new HashMap<>();
    //设备中的通讯录中联系人名称与电话放入Map中
    for(int i = 0; i < 20; i++){
        contactMap.put("张三" + i ", "123 56 789" + i);
     }
    appAndContactsBean.setAppsMap(appMap);
    appAndContactsBean.setContactMap(contactMap);

    client.uploadAppsAndContacts(appAndContactsBean, turingOSClientListener)

返回示例：

{
    "ret":0,
    "text":"上传成功"
}

常见问题

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

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