更新时间:2021-09-17 GMT+08:00
分享

问答机器人API

功能介绍

用户可通过调用该接口与机器人进行会话。旧版问答机器人API请参见问答会话API(仅支持老用户)

调试

您可以在API Explorer中调试该接口。

URI

POST /v1/{project_id}/qabots/{qabot_id}/chat

表1 路径参数

参数

是否必选

参数类型

描述

project_id

String

项目ID,用于资源隔离。请参见获取项目ID

qabot_id

String

机器人标识符,qabot编号,UUID格式。如:303a0a00-c88a-43e3-aa2f-d5b8b9832b02。

获取方法:

登录对话机器人服务控制台,在智能问答机器人列表中查看qabot_id。

请求参数

表2 请求Header参数

参数

是否必选

参数类型

描述

X-Auth-Token

String

用户Token。

Token认证就是在调用API的时候将Token加到请求消息头,从而通过身份认证,获得操作API的权限,响应消息头中X-Subject-Token的值即为Token。

表3 请求Body参数

参数

是否必选

参数类型

描述

extends

Extends object

扩展参数。

chat_enable

Boolean

默认false。

true:使用内部闲聊语料进行兜底。

false:不使用闲聊兜底。

user_id

String

用户id,在日志中用于标识不同用户,可以为任意String。

question

String

用户问题。如:查天气。长度为1~512。

session_id

String

会话标识符,UUID格式。如:c04e6f7b-61d7-4a2d-a0c8-f9ecd2f62359。

  1. 每次对话开启,机器人创建会话id,下次请求中传入该id表示继续该轮对话,每轮会话有效时间为2分钟。
  2. 若传入的会话id已过期或者为空,则机器人会重新创建新的会话id(重新创建会话id会消耗一定时间)。

query_types

Array of Integers

指定发送的机器人类型集合。

0 知识库问答。

1 技能问答。

2 闲聊问答。

3 图谱问答。

4 文档问答。

5 表格问答。

非必填字段。如果不填,会使用默认的机器人融合策略。

表4 Extends

参数

是否必选

参数类型

描述

tag_ids

Tag object

待匹配的答案标签信息。

domain_ids

Array of strings

问题类别id列表。一次最多可以传入10个。

只有属于这些问题类别的知识库问答对才会被匹配到。

获取domain_ids方法:

登录对话机器人服务控制台,在“问答机器人 > 知识库 > 问答管理”界面,鼠标指向问题类别,获取domain_ids。

source

String

问题来源。

支持用户自定义,最终体现在问答日志里。

return_all_answers

Boolean

是否返回所有类型的回答。

表5 Tags

参数

是否必选

参数类型

描述

should

Array of string

至少要包含列表中的一个答案标签id。

响应参数

状态码: 200

表6 响应Body参数

参数

参数类型

描述

reply_type

Integer

回复类型:

0 知识库回复。

1 技能回复。

2 闲聊回复。

3 图谱回复。

4 文档回复。

5 表格回复。

qabot_answers

QaBotAnswersNew object

知识库回复。

chat_answers

ChatAnswers object

闲聊回复。

taskbot_answers

TaskBotAnswers object

技能回复。只有专业版机器人有该回复。

docqa_answers

DocqaAnswers object

文档回复。只有专业版机器人有该回复。

tableqa_answers

TableQaAnswers object

表格回复。只有专业版机器人有该回复。

session_id

String

会话id,每次对话开启,机器人创建会话id,下次请求中传入该id表示继续该对话,每轮会话有效时间为2分钟。

kbqa_answers

KbqaAnswers object

图谱回复。只有专业版机器人有该回复。

request_id

String

请求ID。用来标记调用失败时,用来标记本次问答。

表7 QaBotAnswersNew

参数

参数类型

描述

answers

Array of QaBotAnswer objects

问答机器人回复。

recommend_answers

Array of RecomendAnswer objects

问答机器人推荐回复。

表8 QaBotAnswer

参数

参数类型

描述

qa_pair_id

String

问答对ID,UUID格式,如:305cd440-ab4f-4704-9b30-ffa4e82a5606。

st_question

String

标准问题,如:桌面云打不开。

answer

String

答案,如:桌面云打不开了。

score

Double

相似度得分,精确到小数点后3位。

domain

String

所属领域,如:桌面云。

top_score_question

String

最高评分的扩展问或标准问。具体见表4

表9 RecomendAnswer

参数

参数类型

描述

qa_pair_id

String

问答对ID,UUID格式,如:305cd440-ab4f-4704-9b30-ffa4e82a5606。

st_question

String

标准问题,如:桌面云打不开。

score

Double

相似度得分,精确到小数点后3位。

domain

String

所属领域,如:桌面云。

top_score_question

String

最高评分的扩展问或标准问。具体见表4

表10 ChatAnswers

参数

参数类型

描述

answer

String

答案,如:美好的一天祝您一切顺利。

score

Float

闲聊的置信度,范围:[0.0,1.0 ]。0.0表示兜底回复。

表11 TaskBotAnswers

参数

参数类型

描述

answer

String

答案, 如:请问您需要查询哪里的天气?

skill_id

String

技能标识符,UUID格式。如:9eece064-bdb5-43cb-8e0f-8c19a929e25c。

skill_responses

Array of SkillResponse objects

技能回复信息。

表12 SkillResponse

参数

参数类型

描述

skill_id

String

输入问题,不能为空,UUID格式,如:9eece064-bdb5-43cb-8e0f-8c19a929e25c。

skill_version

String

skill的版本。

frame

Frame object

命中意图。

candidate

CandidateIntention object

候选意图。

locked

Boolean

技能是否被锁定,默认是false。

related_intenions

Array of RelatedIntention objects

相关意图信息。

表13 Frame

参数

参数类型

描述

intention

String

意图。

confidence

Double

命中意图置信度。

current_slots

Array of CurrentSlot objects

当前槽位列表。

history_slots

Array of HistorySlot objects

历史槽位列表。

reply

String

机器人回复。

task_complete

Boolean

任务是否完成。

flow_complete

Boolean

对话流程是否结束。

candidate_words

Array of Strings

候选词。

intention_alias

String

意图名称。

表14 CurrentSlot

参数

参数类型

描述

slot_id

String

槽位ID,UUID格式,如:9eece064-bdb5-43cb-8e0f-8c19a929e25c。

slot_name

String

槽位名称。

slot_values

Array of SlotValue objects

槽位值。

slot_identification

String

用户设置的槽位标识。

表15 SlotValue

参数

参数类型

描述

word

String

词。

norm_word

String

通用词。

begin_position

Integer

词的起始位置。

end_position

Integer

词的结束位置。

表16 HistorySlot

参数

参数类型

描述

slot_name

String

槽位名称。

slot_values

Array of HistorySlotWord objects

槽信息。

slot_identification

String

用户设置的槽位标识。

表17 HistorySlotWord

参数

参数类型

描述

word

String

词。

norm_word

String

归一化后的词。

表18 CandidateIntention

参数

参数类型

描述

candidate_intention

String

候选意图。

candidate_confidence

Double

候选技能置信度。

表19 RelatedIntention

参数

参数类型

描述

intention

String

意图名称。

confidence

Double

意图置信度。

表20 DocqaAnswers

参数

参数类型

描述

answer

String

答案。

score

Double

文档问答回复的得分。

question

String

问题。

answer_detail

DocQueryAnswerDetail object

文档回复的详细信息。

details

Array of DocQueryAnswerDetail objects

文档回复的topN答案。

表21 DocQueryAnswerDetail

参数

参数类型

描述

answer

String

答案。

doc_id

String

文档ID。

end_index

Integer

答案结束下标。

paragraph_score

Double

段落评分。

paragraph_text

String

段落文字。

phrase_score

Double

文档问答阅读理解评分。

start_index

Integer

答案开始下标。

total_score

Double

文档问答总评分。

paragraph_number

Integer

段落在文档中的编号。

表22 TableQaAnswers

参数

参数类型

描述

table_id

String

表格ID。

answer

String

表格问答答案。

score

Double

评分。

表23 KbqaAnswers

参数

参数类型

描述

answer

String

图谱问答的答案。

score

Double

评分。

状态码: 400

表24 响应Body参数

参数

参数类型

描述

error_code

String

调用失败时的错误码。 调用成功时无此字段。

error_msg

String

调用失败时的错误信息。 调用成功时无此字段。

请求示例

  • 请求示例
    POST https://{endpoint}/v1/{project_id}/qabots/{qabot_id}/chat
    
    Request Header:
    Content-Type: application/json
    X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDTALBglghkgBZQMEAgEwgguVBgkqhkiG...
    Request Body:
    {
        "question": "桌面云打不开了"
    }
  • Python语言请求代码示例
    import requests
    url = "https://{endpoint}/v1/{project_id}/qabots/{qabot_id}/chat"
    token = "用户获取得到的实际token值"
    headers = {'Content-Type': 'application/json', 'X-Auth-Token': token}
    body = {"question": "用户问"}
    
    response = requests.post(url, headers=headers, json=body, verify=False)
    print(response.text)
  • Java语言请求代码示例
    import java.io.BufferedReader;
    import java.io.InputStream;
    import java.io.InputStreamReader;
    import java.io.OutputStreamWriter;
    import java.net.HttpURLConnection;
    import java.net.URL;
    
    public class CBSDemo {
    
        public void cbsDemo() {
            try {
                //endpoint、projectId、qabot_id需要替换成实际信息。
                URL url = new URL("https://{endpoint}/v1/{project_id}/qabots/{qabot_id}/chat");
                String token = "用户获取得到的实际token值";
                HttpURLConnection connection = (HttpURLConnection) url.openConnection();
                connection.setRequestMethod("POST");
                connection.setDoInput(true);
                connection.setDoOutput(true);
                connection.addRequestProperty("Content-Type", "application/json");
                connection.addRequestProperty("X-Auth-Token", token);
    
                //输入参数
                String body = "{\"question\": \"用户问\"}";
    
                OutputStreamWriter osw = new OutputStreamWriter(connection.getOutputStream(), "UTF-8");
                osw.append(body);
                osw.flush();
                InputStream is = connection.getInputStream();
                BufferedReader br = new BufferedReader(new InputStreamReader(is, "UTF-8"));
                while (br.ready()) {
                    System.out.println(br.readLine());
                }
            } catch (Exception e) {
                e.printStackTrace();
            }
        }
    
        public static void main(String[] args) {
            CBSDemo CBSDemo = new CBSDemo();
            CBSDemo.cbsDemo();
        }
    }

响应示例

状态码:200

成功响应示例

{
   "reply_type":0,
   "qabot_answers":{
      "request_id":"0a1b12ad-8448-4c95-8c13-fb199762f4511583841605901",
      "answers":[
         {
            "score":1,
            "answer":"桌面云打不开了",
            "domain":"桌面云",
            "qa_pair_id":"305cd440-ab4f-4704-9b30-ffa4e82a5606",
            "st_question":"桌面云打不开"
         }
      ]
   }
}

{
   "reply_type":1,
   "taskbot_answers":{
      "answer":"请问您需要查询哪里的天气?",
          "skill_id":"b7b16fc3-0946-46f7-8c70-b954b4fdb736",
      "skill_responses":[
         {
            "frame":{
               "intention":"weather_query",
               "confidence":0.9339861716638148,
               "reply":"请问您需要查询哪里的天气?",
               "candidate_words":[

               ],
               "task_complete":false,
               "current_slots":[

               ],
               "history_slots":[

               ]
            },
            "candidate":{
               "candidate_confidence":0
            },
            "skill_id":"b7b16fc3-0946-46f7-8c70-b954b4fdb736",
            "skill_version":"v8"
         },
         {
            "frame":{
               "confidence":0,
               "reply":"对不起,我没明白,请再多教我一些吧",
               "candidate_words":[

               ],
               "task_complete":true,
               "current_slots":[

               ],
               "history_slots":[

               ]
            },
            "candidate":{
               "candidate_confidence":0
            },
            "skill_id":"9eece064-bdb5-43cb-8e0f-8c19a929e25c",
            "skill_version":"v13"
         }
      ]
   }
}

{
   "reply_type":2,
   "chat_answers":{
      "answer":"美好的一天祝您一切顺利"
   }
}

状态码:400

失败响应示例

{
    "error_code":"CBS.0011",
    "error_msg":"auth failed"
}

状态码

状态码请参见状态码

错误码

错误码请参见错误码

分享:

    相关文档

    相关产品

close