话务机器人_ 对话机器人服务 CBS_API参考_华为云

(1)

API 参考

文档版本 01

发布日期 2021-09-26

(2)

非经本公司书面许可，任何单位和个人不得擅自摘抄、复制本文档内容的部分或全部，并不得以任何形式传播。

商标声明

和其他华为商标均为华为技术有限公司的商标。

本文档提及的其他所有商标或注册商标，由各自的所有人拥有。

注意

您购买的产品、服务或特性等应受华为公司商业合同和条款的约束，本文档中描述的全部或部分产品、服务或特性可能不在您的购买或使用范围之内。除非合同另有约定，华为公司对本文档内容不做任何明示或暗示的声明或保证。

由于产品版本升级或其他原因，本文档内容会不定期进行更新。除非另有约定，本文档仅作为使用指导，本文档中的所有陈述、信息和建议不构成任何明示或暗示的担保。

(3)

1 ^{使用前必读}

1.1 概述

欢迎使用对话机器人服务 (Conversational Bot Service) 。对话机器人服务

(Conversational Bot Service) 是一款基于人工智能技术，针对企业应用场景开发的云服务，主要包括智能问答、智能质检和任务型对话等功能。

在调用对话机器人服务API之前，请确保已经充分了解对话机器人服务相关概念，详细信息请参见产品介绍。

1.2 调用说明

对话机器人服务提供了REST（Representational State Transfer）风格API，支持您通过HTTPS请求调用，调用方法请参见3 如何调用API。

1.3 终端节点

终端节点即调用API的请求地址，不同服务不同区域的终端节点不同，您可以从地区和终端节点中查询所有服务的终端节点。

目前对话机器人服务支持以下地区和终端节点：

表1-1 问答机器人

区域名称区域终端节点（Endpoint）协议类型

华北-北京一 cn-

north-1 cbs-ext.cn-

north-1.myhuaweicloud.com HTTPS 华北-北京四 cn-

north-4 cbs-ext.cn-

north-4.myhuaweicloud.com HTTPS

(6)

表1-2 话务机器人

区域名称区域终端节点（Endpoint）协议类型

华北-北京一 cn-

north-1 cbs-ext.cn-

north-1.myhuaweicloud.com HTTPS 华北-北京四 cn-

north-4 cbs-ext.cn-

north-4.myhuaweicloud.com HTTPS

1.4 约束与限制

您能创建的智能问答机器人默认配额是10个，智能话务机器人默认配额是5个。如果需要增加配额，联系华为云工程师。更详细的限制请参见具体API的说明和产品介绍约束与限制。

1.5 基本概念

● 账号

用户注册华为云时的账号，账号对其所拥有的资源及云服务具有完全的访问权限，可以重置用户密码、分配用户权限等。由于账号是付费主体，为了确保账号安全，建议您不要直接使用账号进行日常管理工作，而是创建用户并使用他们进行日常管理工作。

● 用户

用户是服务的使用人员，具有身份凭证（密码和访问密钥）。

在我的凭证下，您可以查看账号ID和用户ID。通常在调用API的鉴权过程中，您需要用到账号、用户和密码等信息。

● 区域（Region）

从地理位置和网络时延维度划分，同一个Region内共享弹性计算、块存储、对象存储、VPC网络、弹性公网IP、镜像等公共服务。Region分为通用Region和专属 Region，通用Region指面向公共租户提供通用云服务的Region；专属Region指只承载同一类业务或只面向特定租户提供业务服务的专用Region。

详情请参见区域和可用区。

● 可用区（AZ，Availability Zone）

一个AZ是一个或多个物理数据中心的集合，有独立的风火水电，AZ内逻辑上再将计算、网络、存储等资源划分成多个集群。一个Region中的多个AZ间通过高速光纤相连，以满足用户跨AZ构建高可用性系统的需求。

● 项目

华为云区域默认对应一个项目，这个项目由系统预置，用来隔离物理区域间的资源（计算资源、存储资源和网络资源），以默认项目为单位进行授权，用户可以访问您账号中该区域的所有资源。如果您希望进行更加精细的权限控制，可以在区域默认的项目中创建子项目，并在子项目中购买资源，然后以子项目为单位进行授权，使得用户仅能访问特定子项目中资源，使得资源的权限控制更加精确。

(7)

图1-1 项目隔离模型

(8)

2 ^{API 概览}

CBS服务提供了如下接口，方便用户使用对话机器人。

表2-1 接口说明

接口类型说明

问答机器人在线问答接口主要功能接口：问答请求、问答统计、问答会话（仅支持老用户）、获取问题提示、问答满意度评价、问答转人工、单轮问答（即将下线）的接口。

智能话务机器人接口会话管理接口：发起会话、结束会话、进行会话的接口。

(9)

3 ^{如何调用 API}

3.1 构造请求

本节介绍REST API请求的组成，并以调用IAM服务获取用户Token接口说明如何调用 API，该API获取用户的Token，Token可以用于调用其他API时鉴权。

您还可以通过这个视频教程了解如何构造请求调用API：https://

bbs.huaweicloud.com/videos/102987 。

请求示例如下所示，一个请求主要由请求URL、请求方法、请求消息头和请求消息体几部分组成，各个部分将在下文详细解释。

图3-1 请求示例图

请求 URI

请求URI由如下部分组成。

{URI-scheme} :// {Endpoint} / {resource-path} ? {query-String}

尽管请求URI包含在请求消息头中，但大多数语言或框架都要求您从请求消息中单独传递它，所以在此强调。

(10)

表3-1 URI 中的参数说明

参数描述

URI-scheme 表示用于传输请求的协议，当前所有API均采用HTTPS协议。

Endpoint 指定承载REST服务端点的服务器域名或IP，不同服务不同区域的Endpoint不同，您可以从地区和终端节点中获取。例如对话机器人服务在“华北-北京四”区域的Endpoint为“cbs-ext.cn- north-4.myhuaweicloud.com”。

resource-path 资源路径，也即API访问路径。从具体API的URI模块获取，例如“问答机器人获取问题提示”API的resource-path为“/v1/

{project_id}/qabots/{qabot_id}/suggestions”。其中

{project_id}为项目编号，请参考获取项目ID获取，{qabot_id}

为智能问答机器人编号，可在CBS服务智能问答机器人首页获取。

query-String 查询参数，是可选部分，并不是每个API都有查询参数。查询参数前面需要带一个“？”，形式为“参数名=参数取值”，

例如“limit=10”，表示查询不超过10条数据。当前CBS服务未使用该参数。

例如，您需要获取“华北-北京四”区域的调用获取问题提示API，则需使用“华北-北京四”区域的Endpoint（cbs-ext.cn-north-4.myhuaweicloud.com），并在获取问题提示的URI部分找到resource-path（/v1/{project_id}/qabots/{qabot_id}/

suggestions），拼接起来如下所示。

https://cbs-ext.cn-north-4.myhuaweicloud.com/v1/{project_id}/qabots/{qabot_id}/suggestions

图3-2 URI 示意图

说明

为查看方便，在每个具体API的URI部分，只给出resource-path部分，并将请求方法写在一起。

这是因为URI-scheme都是HTTPS，而Endpoint在同一个区域也相同，所以简洁起见将这两部分省略。

请求方法

HTTPS方法（也称为操作或动词），它告诉服务您正在请求什么类型的操作。

表3-2 HTTPS 方法

方法说明

GET 请求服务器返回指定资源。

(11)

方法说明

PUT 请求服务器更新指定资源。

POST 请求服务器新增资源或执行特殊操作。

DELETE 请求服务器删除指定资源，如删除对象等。

HEAD 请求服务器资源头部。

PATCH 请求服务器更新资源的部分内容。

当资源不存在的时候，PATCH可能会去创建一个新的资源。

在-获取问题提示的URI部分，您可以看到其请求方法为“POST”，则其请求为：

POST https://cbs-ext.cn-north-1.myhuaweicloud.com/v1/{project_id}/qabots/{qabot_id}/suggestions

请求消息头

可选的附加请求头字段，如指定的URI和HTTPS方法所要求的字段。详细的公共请求消息头字段请参见表3-3，其中请求认证信息请参见认证鉴权。

表3-3 公共请求消息头

名称描述是否必选示例

Content-type 发送的实体的

MIME类型。是 application/json Content-Length 请求body长度，单

位为Byte。 POST/PUT请求为可选， GET不包含该字段。

3495

X-Auth-Token 用户Token。是 MIINRwYJKoZIhvc NAQcCoIINODCC DTQCAQExDTALB glghkgBZQMEAgE wgguVBgkqhkiG...

X-Language 请求语言类型。否，默认为zh-

cn。 en-us

说明

公有云API同时支持使用AK/SK认证，AK/SK认证是使用SDK对请求进行签名，签名过程会自动往请求中添加Authorization（签名认证信息）和X-Sdk-Date（请求发送的时间）请求头。

AK/SK认证的详细说明请参见AK/SK认证。

对于获取问题提示接口，由于需要认证，所以需要添加“Content-Type”和“X-Auth- Token”，添加消息头后的请求如下所示。

(12)

POST https://cbs-ext.cn-north-1.myhuaweicloud.com/v1/{project_id}/qabots/{qabot_id}/suggestions Content-Type: application/json

X-Auth-Token：MIIaBgYJKoZIhvcNAQcC……

请求消息体

请求消息体通常以结构化格式（如JSON或XML）发出，与请求消息头中Content-type 对应，传递除请求消息头之外的内容。若请求消息体中参数支持中文，则中文字符必须为UTF-8编码。

每个接口的请求消息体内容不同，也并不是每个接口都需要有请求消息体（或者说消息体为空），GET、DELETE操作类型的接口不需要消息体，消息体具体内容需要根据具体接口而定。

对于获取问题提示接口，您可以从接口的请求部分看到所需的请求参数及参数说明。

将消息体加入后的请求如下所示。

POST https://cbs-ext.cn-north-1.myhuaweicloud.com/v1/{project_id}/qabots/{qabot_id}/suggestions Content-Type: application/json

X-Auth-Token：MIIaBgYJKoZIhvcNAQcC……

{ "question":"桌面云", "top":2

}

到这里为止这个请求需要的内容就具备齐全了，您可以使用curl、Postman或直接编写代码等方式发送请求调用API。对于获取问题提示接口，您可以从响应消息部分看到返回参数及参数说明。

3.2 认证鉴权

调用接口有如下两种认证方式，您可以选择其中一种进行认证鉴权。

● Token认证：通过Token认证通用请求。

● AK/SK认证：通过AK（Access Key ID）/SK（Secret Access Key)加密调用请求。

Token 认证

Token在计算机系统中代表令牌（临时）的意思，拥有Token就代表拥有某种权限。

Token认证就是在调用API的时候将Token加到请求消息头，从而通过身份认证，获得操作API的权限。

说明

Token的有效期为24小时，需要使用一个Token鉴权时，可以先缓存起来，避免频繁调用。

调用CBS服务提供的API前，需要先获取Token，获取Token方式如下所示。

加粗的斜体字段需要根据实际值填写，其中

username

为用户名，

domainname

为用户所属的账号名称，

********

为用户登录密码。

一般，username和domainname保持一致。如果您是IAM用户，请登录“我的凭证”

页面，获取IAM用户名、账号名，填写至username、domainname参数处。

CBS服务开通区域为华北-北京四时，对应的projectname为cn-north-4。projectname 请依据实际开通区域进行填写，当前服务支持区域请参见终端节点。

POST https://iam.cn-north-4.myhuaweicloud.com/v3/auth/tokens

(13)

Content-Type: application/json { "auth": {

"identity": { "methods": [ "password"

],

"password": { "user": {

"name": "username", "password": "********", "domain": {

"name": "domainname"

} } } }, "scope": { "project": {

"name": "cn-north-4"

} } } }

如下图所示，返回的响应消息头中"x-subject-token"就是需要获取的用户Token。获取 Token之后，您就可以使用Token调用CBS服务API。如需了解更多获取Token方式，请参考获取用户Token。

图3-3 获取用户 Token 响应消息头

您还可以通过这个视频教程了解如何使用Token认证：https://

bbs.huaweicloud.com/videos/101333 。

AK/SK 认证

说明

AK/SK签名认证方式仅支持消息体大小12M以内，12M以上的请求请使用Token认证。

AK/SK认证就是使用AK/SK对请求进行签名，在请求时将签名信息添加到消息头，从而通过身份认证。

● AK(Access Key ID)：访问密钥ID。与私有访问密钥关联的唯一标识符；访问密钥 ID和私有访问密钥一起使用，对请求进行加密签名。

● SK(Secret Access Key)：与访问密钥ID结合使用的密钥，对请求进行加密签名，

可标识发送方，并防止请求被修改。

(14)

使用AK/SK认证时，您可以基于签名算法使用AK/SK对请求进行签名，也可以使用专门的签名SDK对请求进行签名。详细的签名方法和SDK使用方法请参见API签名指南。

如果之前没有生成过AK/SK，可登录“我的凭证”界面，选择“管理访问密钥 > 新增访问密钥”来获取。

须知

签名SDK只提供签名功能，与服务提供的SDK不同，使用时请注意。

3.3 返回结果

状态码

请求发送以后，您会收到响应，包含状态码、响应消息头和消息体。

状态码是一组从1xx到5xx的数字代码，表示了请求响应的状态，完整的状态码列表请参见状态码。

对于CBS服务接口，如果调用后返回状态码为“200”，则表示请求成功。

响应消息头

对应请求消息头，响应同样也有消息头，如“Content-type”，CBS服务响应消息头无特殊用途，可用于定位问题使用。

响应消息体

响应消息体通常以结构化格式返回，与响应消息头中Content-type对应，传递除响应消息头之外的内容。

对于获取问题提示接口，返回如下消息体，格式请具体参考获取问题提示响应消息部分。

{

"questions":[

"桌面云打不开", "桌面云无法登录"

] }

当接口调用出错时，会返回错误码及错误信息说明，错误响应的Body体格式如下所示。

{ "error_code": "CBS.0022",

"error_msg": "question can not be null"

}

其中，error_code表示错误码，error_msg表示错误描述信息。

(15)

4 ^{问答机器人}

4.1 问答机器人 API

功能介绍

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

（仅支持老用户）。

调试

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

URI

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

表4-1 路径参数

参数是否必选参数类型描述

project_id 是 String 项目ID，用于资源隔离。请参见获取项目 ID。

qabot_id 是 String 机器人标识符，qabot编号，UUID格式。

如：303a0a00-c88a-43e3-aa2f- d5b8b9832b02。

获取方法：

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

(16)

请求参数

表4-2 请求 Header 参数

X-Auth-Token 是 String 用户Token。

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

表4-3 请求 Body 参数

参数是否必

选

参数类型描述

extends 否 Extends

object 扩展参数。

chat_enabl

e 否 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_type

s 否 Array of

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

0 知识库问答。

1 技能问答。

2 闲聊问答。

3 图谱问答。

4 文档问答。

5 表格问答。

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

(17)

表4-4 Extends

参数是否必

选

参数类型描述

tag_ids 否 Tag

object 待匹配的答案标签信息。

domain_ids 否 Array of

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

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

获取domain_ids方法：

登录对话机器人服务控制台，在“问答机器人

> 知识库 > 问答管理”界面，鼠标指向问题类别，获取domain_ids。

source 否 String 问题来源。

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

return_all_a

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

表4-5 Tags

参数是否必

选

参数类型描述

should 否 Array of

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

响应参数

状态码： 200

(18)

表4-6 响应 Body 参数

参数参数类型描述

reply_type Integer 回复类型：

0 知识库回复。

1 技能回复。

2 闲聊回复。

3 图谱回复。

4 文档回复。

5 表格回复。

qabot_answers QaBotAnswers

New object 知识库回复。

chat_answers ChatAnswers

object 闲聊回复。

taskbot_answe

rs TaskBotAnswers

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

docqa_answers DocqaAnswers

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

tableqa_answe

rs TableQaAnswer

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

session_id String 会话id，每次对话开启，机器人创建会话id，

下次请求中传入该id表示继续该对话，每轮会话有效时间为2分钟。

kbqa_answers KbqaAnswers

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

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

表4-7 QaBotAnswersNew

answers Array of QaBotAnswer objects

问答机器人回复。

recommend_a

nswers Array of

RecomendAnswe r objects

问答机器人推荐回复。

(19)

表4-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_que

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

表4-9 RecomendAnswer

top_score_que

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

表4-10 ChatAnswers

answer String 答案，如：美好的一天祝您一切顺利。

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

表4-11 TaskBotAnswers

answer String 答案，如：请问您需要查询哪里的天气？

skill_id String 技能标识符，UUID格式。如：9eece064- bdb5-43cb-8e0f-8c19a929e25c。

(20)

参数参数类型描述 skill_response

s Array of SkillRespons e objects

技能回复信息。

表4-12 SkillResponse

skill_id String 输入问题，不能为空，UUID格式，如：9eece064- bdb5-43cb-8e0f-8c19a929e25c。

skill_version String skill的版本。

frame Frame

object 命中意图。

candidate CandidateIn tention object

候选意图。

locked Boolean 技能是否被锁定，默认是false。

related_inteni

ons Array of RelatedInte ntion objects

请求示例

● 请求示例

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();

(25)

} }

响应示例

状态码：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":{

(26)

"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"

}

状态码

状态码请参见状态码。

错误码

错误码请参见错误码。

4.2 问答统计 API

4.2.1 问答统计

功能介绍

获取指定时间范围内的问题答复统计，支持按周期统计。

调试

URI

GET /v1/{project_id}/qabots/{qabot_id}/requests/reply-rates?

start_time={start_time}&end_time={end_time}&interval={interval}&time_zone={ti me_zone}&domain={domian}

(27)

表4-25 路径参数

project_id 是 String 项目ID，用于资源隔离。请参见获取项目ID。

qabot_id 是 String qabot编号，UUID格式，如：

303a0a00-c88a-43e3-aa2f- d5b8b9832b02。

获取方法：

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

表4-26 Query 参数

domain 否 String 所属领域。

end_time 否 String 查询的结束时间，long，UTC时间，默认值为当前时间的毫秒数。

interval 否 String 统计周期目前支持year，

month，week，day。

start_time 否 String 查询的起始时间，long，UTC时间，默认值为0。

time_zone 否 String 请求所在时区，例如：中国东八区为"+08:00"；美国西五区为

"-05:00"；默认为"UTC"。

(28)

请求参数

响应参数

状态码： 200

startutc Long 统计开始时间。调用失败时无此字段。

endutc Long 统计结束时间。调用失败时无此字段。

interval String 统计周期目前支持year、month、week、day。

调用失败时无此字段。

time_zone String 所在时区，例如：中国东八区为"+08:00"；美国西五区为"-05:00";默认为"UTC"。调用失败时无此字段。

total ReplyRatesT

otal object 总计答复率统计数据。调用失败时无此字段。

intervals ReplyRatesI ntervals object

按时间间隔答复率统计数据。调用失败时无此字段。

表4-29 ReplyRatesTotal

question_count Long 用户提问总数。

direct_count Long 直接回答个数。

recommend_co

unt Long 推荐回答个数。

(29)

参数参数类型描述 notmatch_coun

t Long 未匹配个数。

direct_rate Double 直接回答比率，保留小数点后三位。

recommend_rat

e Double 推荐回答比率，保留小数点后三位。

notmatch_rate Double 未匹配比率，保留小数点后三位。

dialog_count Long 多轮对话次数。

dialog_rate Double 多轮对话比例。

invalid_count Long 无效问题次数。

invalid_rate Double 无效问题比例。

chat_count Long 闲聊匹配次数。

chat_rate Double 闲聊比例。

表4-30 ReplyRatesIntervals

名称参数类型说明

start String 间隔周期开始时间。

question_count Long 间隔周期用户提问总数。

direct_count Long 间隔周期直接回答个数。

recommend_co

unt Long 间隔周期推荐回答个数。

notmatch_coun

t Long 间隔周期未匹配个数。

invalid_count Long 间隔周期无效问题个数。

chat_count Long 间隔周期闲聊匹配个数。

direct_rate Double 间隔周期直接回答比率，保留小数点后三位。

recommend_rat

e Double 间隔周期推荐回答比率，保留小数点后三位。

notmatch_rate Double 间隔周期未匹配比率，保留小数点后三位。

chat_rate Double 间隔周期闲聊匹配比率，保留小数点后三位。

invalid_rate Double 间隔周期无效问题比率，保留小数点后三位。

dialog_count Long 多轮会话次数。

dialog_rate Double 多轮会话比例。

(30)

状态码： 400

请求示例

● 请求示例

GET https://cbs-ext.cn-north-4.myhuaweicloud.com/v1/{project_id}/qabots/{qabot_id}/requests/reply- rates?interval=day&time_zone=%2B08%3A00

Request Header:

import requests

url = "https://{endpoint}/v1/{project_id}/qabots/{qabot_id}/requests/reply-rates?

start_time={start_time}&end_time={end_time}&interval={interval}&time_zone={time_zone}"

response = requests.get(url, headers=headers, json=body, verify=False) print(response.text)

//endpoint、projectId、qabot_id等需要替换成实际信息。

URL url = new URL("https://{endpoint}/v1/{project_id}/qabots/{qabot_id}/requests/reply-rates?

start_time={start_time}&end_time={end_time}&interval={interval}&time_zone={time_zone}");

connection.setRequestMethod("GET");

connection.setDoOutput(false);

}

(31)

}

CBSDemo.cbsDemo();

} }

响应示例

{ "interval":"day",

"startutc":1613059200000, "endutc":1613720547615, "time_zone":"+08:00", "total":

{

"question_count":179, "direct_count":86, "recommend_count":4, "notmatch_count":85, "chat_count":0, "invalid_count":2, "dialog_count":2, "direct_rate":0.480, "recommend_rate":0.022, "notmatch_rate":0.475, "dialog_rate":0.011, "chat_rate":0.000, "invalid_rate":0.011 },

"intervals":[

{

"start":"2021-02-14", "question_count":28, "direct_count":7, "recommend_count":0, "notmatch_count":21, "chat_count":0, "invalid_count":0, "dialog_count":0, "direct_rate":0.250, "recommend_rate":0.000, "notmatch_rate":0.750, "dialog_rate":0.000, "chat_rate":0.000, "invalid_rate":0.000 },

{

"start":"2021-02-15", "question_count":2, "direct_count":0, "recommend_count":0, "notmatch_count":2, "chat_count":0, "invalid_count":0, "dialog_count":0, "direct_rate":0.000, "recommend_rate":0.000, "notmatch_rate":1.000, "dialog_rate":0.000, "chat_rate":0.000, "invalid_rate":0.000 },

{

(32)

"start":"2021-02-19", "question_count":149, "direct_count":79, "recommend_count":4, "notmatch_count":62, "chat_count":0, "invalid_count":2, "dialog_count":2, "direct_rate":0.530, "recommend_rate":0.027, "notmatch_rate":0.416, "dialog_rate":0.013, "chat_rate":0.000, "invalid_rate":0.013 }

] }

{ "error_code":"CBS.0021",

"error_msg":"request parameter error"

}

状态码

错误码

4.2.2 访问统计

功能介绍

获取用户会话统计信息。

调试

URI

GET /v1/{project_id}/qabots/{qabot_id}/requests/session-stats?

start_time={start_time}&end_time={end_time}&interval={interval}&time_zone={ti me_zone}

表4-32 路径参数

(33)

qabot_id 是 String qabot_id，UUID格式，如：

303a0a00-c88a-43e3-aa2f- d5b8b9832b02。

获取方法：

参数是否必选描述

start_time 否查询的起始时间，long，UTC时间，默认值为 0。

end_time 否查询的结束时间，long，UTC时间，默认值为当前时间的毫秒数。

interval 是统计周期目前支持month、week、day。

time_zone 否请求所在时区，例如：中国东八区为"+08:00"；

美国西五区为"-05:00"；默认为"UTC"。（注意 +-:符号需要经过urlEncoder加码）

请求参数

响应参数

状态码： 200

(34)

interval String 统计周期目前支持year、month、week、day。

time_zone String 所在时区，默认为"utc"。例如：中国东八区为

"+08:00"；美国西五区为"-05:00"。

total SessionStatsT

otal object 会话总计统计数据。调用失败时无此字段。

intervals Array of SessionStatsI ntervals objects

会话间隔统计数据。调用失败时无此字段。

startutc Long 统计开始的utc时间。调用失败时无此字段。

endutc Long 统计结束的utc时间。调用失败时无此字段。

表4-36 SessionStatsTotal

session_count Long 会话总数。

user_count Long 独立用户个数。

avg_request_co

unt Double 平均会话轮数，保留小数点后三位。

avg_session_tim

e Double 平均会话时长，保留小数点后三位。

表4-37 SessionStatsIntervals

start String 间隔周期开始时间。

session_count Long 间隔周期会话总数。

user_count Long 间隔周期独立用户个数。

avg_request_co

unt Double 间隔周期平均会话轮数，保留小数点后三位。

avg_session_tim

e Double 间隔周期平均会话时长，保留小数点后三位。

状态码： 400

(35)

请求示例

● 请求示例

GET https://cbs-ext.cn-north-4.myhuaweicloud.com/v1/{project_id}/qabots/{qabot_id}/requests/

session-stats?interval=day&time_zone=%2B08%3A00 Request Header: Content-Type: application/json

X-Auth-Token:MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDTALBglghkgBZQMEAgEwgguVBgkqhkiG...

import requests

url = "https://{endpoint}/v1/{project_id}/qabots/{qabot_id}/requests/session-stats?

start_time={start_time}&end_time={end_time}&interval={interval}&time_zone={time_zone}"

URL url = new URL("https://{endpoint}/v1/{project_id}/qabots/{qabot_id}/requests/session- stats?start_time={start_time}&end_time={end_time}&interval={interval}&time_zone={time_zone}");

}

} }

CBSDemo.cbsDemo();

} }

(36)

响应示例

{ "interval":"day", "total":{

"session_count":122, "user_count":4,

"avg_request_count":1.467, "avg_session_time":23909.836 },"intervals":[

{ "start":"2021-02-14", "session_count":8, "user_count":1,

"avg_request_count":3.500, "avg_session_time":157500.000 },

"avg_request_count":2.000, "avg_session_time":2000.000 },

"avg_request_count":1.319, "avg_session_time":14646.018 }

], "startutc":1613059200000, "endutc":1613720965417, "time_zone":"+08:00"

}

{

"error_code":"CBS.0021",

}

状态码

错误码

4.2.3 热点问题统计

功能介绍

获取热点问题列表。

(37)

默认按标准问被用户问及的频率降序排列。

调试

URI

GET /v1/{project_id}/qabots/{qabot_id}/qa-pairs/hots?

start_time={start_time}&end_time={end_time}&top={top}&domain_id={domain_id }&domain={domain}

表4-39 路径参数

303a0a00-c88a-43e3-aa2f- d5b8b9832b02。

获取方法：

domain 否热点问题所属领域。

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

获取domain_id方法：

登录对话机器人服务控制台，在“问答机器人 >

知识库 > 问答管理”界面，鼠标指向问题类别，

获取domain_id。

(38)

start_time 否查询的起始时间，long，utc时间，默认值为0。

end_time 否查询的结束时间，long，utc时间，默认值为当前时间的毫秒数。

exclude 否 true:根据问答对信息展示热点问题（如：热点问题对应的问答对“你好”发生了修改，变成了

“你好啊”，此时热点问题也将返回 “你好啊”；但是如果这个问题对被删除，则“你好”

不会被展示在热点问中）

false: 不根据问答对信息展示热点问题。

top 否热点问题最多显示的个数，默认值为10，取值范

围1-20。

请求参数

响应参数

状态码： 200

表4-42 响应参数

questions Array of HotQuestion Count

objects

指定时间范围内，热点问题列表。

调用失败时无此字段。

(39)

表4-43 HotQuestionCount

qa_pair_id String 问答对Id。

st_question String 标准问题。

domain String 标准问题所属领域。

状态码： 400

请求示例

● 请求示例

GET https://cbs-ext.cn-north-4.myhuaweicloud.com/v1/{project_id}/qabots/{qabot_id}/qa-pairs/hots Request Header:

import requests

url = "https://{endpoint}/v1/{project_id}/qabots/{qabot_id}/qa-pairs/hots?

start_time={start_time}&end_time={end_time}&top={top}&domain={domain}"

URL url = new URL("https://{endpoint}/v1/{project_id}/qabots/{qabot_id}/qa-pairs/hots?

start_time={start_time}&end_time={end_time}&top={top}&domain_id={domain_id}");

(40)

}

} }

CBSDemo.cbsDemo();

} }

响应示例

{ "questions":

[ {

"qa_pair_id"："xxxxxxxxxxx", "st_question"："桌面云打不开", "domain"："桌面云"

}, {

"qa_pair_id"："xxxxxxxxxxx", "st_question"："桌面云无法登陆", "domain"："桌面云"

} ]}

}

状态码

错误码

4.2.4 关键词统计

功能介绍

用户问关键词统计。

(41)

调试

URI

GET /v1/{project_id}/qabots/{qabot_id}/requests/keywords?

top={top}&start_time={start_time}&end_time={end_time}

表4-45 路径参数

303a0a00-c88a-43e3-aa2f- d5b8b9832b02。

获取方法：

top 否用户问题关键词列表显示的个数。默认值为10，

取值范围[1-50]。

start_time 否查询的起始时间，long，UTC时间，默认值为 0。

end_time 否查询的结束时间，long，UTC时间，默认值为当前时间的毫秒数。

(42)

请求参数

响应参数

状态码： 200

表4-48 响应参数

keywords Array of KeyWordsSt at objects

指定时间范围内，用户问关键词列表。调用失败时无此字段。

表4-49 KeyWordsStat

keyword String 关键词。

freq Long 关键词频次。

状态码： 400

请求示例

● 请求示例

GET https://cbs-ext.cn-north-4.myhuaweicloud.com/v1/{project_id}/qabots/{qabot_id}/requests/

keywords

(43)

Request Header:

import requests

url = "https://{endpoint}/v1/{project_id}/qabots/{qabot_id}/requests/keywords?

top={top}&start_time={start_time}&end_time={end_time}"

URL url = new URL("https://{endpoint}/v1/{project_id}/qabots/{qabot_id}/requests/keywords?

top={top}&start_time={start_time}&end_time={end_time}");

}

} }

CBSDemo.cbsDemo();

} }

响应示例

{ "keywords": [ {

"keyword":"桌面云", "freq":15

}, {

(44)

"keyword":"弹性云服务器", "freq":15

} ] }

}

状态码

错误码

4.3 问答会话 API（仅支持老用户）

4.3.1 开启会话

功能介绍

问答会话API由开启会话、处理会话、关闭会话三个接口组成。用户可通过调用该接口创建会话。该接口仅支持老用户，新用户请优先使用问答机器人API接口进行调用。

调试

URI

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

表4-51 路径参数

(45)

qabot_id 是 String 机器人标识符，qabot编号，

UUID格式。如：303a0a00- c88a-43e3-aa2f-

d5b8b9832b02。

进入问答机器人的Console界面，在“机器人名称/ID”列显示对应的qabot_id。

请求参数

响应参数

状态码： 200

参数类型描述

session_id String 会话标识符，UUID格式。如：

c04e6f7b-61d7-4a2d-a0c8-f9ecd2f62359。

每轮会话有效时间为2分钟，若2分钟内无响应则session_id失效。

具体获取方式请参见开启会话章节。

greeting String 机器人问候语。如：你好，我是你配置的机器人，现在可以跟我说话啦。

状态码： 400

(46)

请求示例

● 请求示例

POST http://{endpoint}/v1/{project_id}/qabots/{qabot_id}/sessions Request Header:

/** * 此demo仅供测试使用，建议使用sdk

*/public class CBSDemo {

public void cbsDemo() { try {

//endpoint、projectId、qabot_id需要替换成实际信息。

URL url = new URL("https://{endpoint}/v1/{project_id}/qabots/{qabot_id}/sessions");

connection.setRequestMethod("POST");

connection.setDoOutput(true);

}

} }

CBSDemo.cbsDemo();

} }

响应示例

{"session_id": "c04e6f7b-61d7-4a2d-a0c8-f9ecd2f62359",

(47)

"greeting": "你好, 我是你配置的机器人，现在可以跟我说话啦"

}

{"error_msg": "RESOURCE_NOT_EXIST_EXCEPTION",

"error_code": "CBS.3254"

}

状态码

错误码

4.3.2 处理会话

功能介绍

问答会话API由开启会话、处理会话、关闭会话三个接口组成。用户可通过调用该接口与机器人进行会话。该接口即将下线，请优先使用问答机器人API接口进行调用。

调试

URI

POST /v1/{project_id}/qabots/{qabot_id}/sessions/{session_id}

表4-55 路径参数

qabot_id 是 String 机器人标识符，qabot编号，

UUID格式。如：303a0a00- c88a-43e3-aa2f-

d5b8b9832b02。

进入问答机器人的Console界面，在“机器人名称/ID”列显示对应的qabot_id。

session_id 是 String 会话标识符，UUID格式。如：

c04e6f7b-61d7-4a2d-a0c8- f9ecd2f62359。

具体获取方式请参见开启会话章节。

(48)

请求参数

表4-57 请求 Body 参数

参数是否必

选

参数类型描述

extends 否 SessionEx tends object

扩展参数。

chat_enabl

e 否 Boolean 默认true。

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

false：不使用闲聊兜底。

user_id 否 String 用户id，在日志中用于标识不同用户，可以为任意String, 长度1~64。

question 是 String 用户问题。如：查天气。长度为1~64。

表4-58 SessionExtends

参数是否必

选

参数类型描述

tag_ids 否 Tag

object 待匹配的答案标签信息。

(49)

参数是否必选

参数类型描述

domain_ids 否 Array of

string 问题类别id列表。

获取domain_ids方法：

登录对话机器人控制台，在“问答机器人 >

知识库 > 问答管理”界面，鼠标指向问题类别，获取domain_ids。

source 否 String 问题来源。

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

表4-59 Tag

参数是否必

选

参数类型描述

should 否 Array of

strings 必须要包含其中之一的答案标签id列表。

响应参数

状态码： 200

reply_type Integer 回复类型：

0 知识库回复。

1 技能回复。

2 闲聊回复。

qabot_answers QaBotAnswers

object 知识库回复。

chat_answers ChatAnswers

object 闲聊回复。

taskbot_answe

rs TaskBotAnswers

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

(50)

request_id String 请求ID。调用失败时无此字段。

表4-61 QaBotAnswers

answers Array of QaBotAnswer objects

问答机器人回复。

request_id String 请求ID。调用失败时无此字段。

表4-62 QaBotAnswer

answer String 知识库中的语料答案，包含该字段时，为直接回答；不包含时，为推荐答案。

top_score_que

stion String 最高评分的扩展问或标准问。

表4-63 ChatAnswers

answer String 答案，如：美好的一天祝您一切顺利。

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

表4-64 TaskBotAnswers

answer String 答案，如：请问您需要查询哪里的天气？

(51)

skill_id String 技能标识符，UUID格式。如：9eece064- bdb5-43cb-8e0f-8c19a929e25c。

skill_response

s Array of SkillRespons e objects

技能信息。

表4-65 SkillResponse

skill_id String 输入问题，不能为空，UUID格式，如：9eece064- bdb5-43cb-8e0f-8c19a929e25c。

skill_version String skill的版本。

frame Frame

object 命中意图。

candidate object 候选意图，具体参见表4-71。

locked Boolean 技能是否被锁定，默认是false related_inteni

ons Array of RelatedInte ntion objects

话务机器人_ 对话机器人服务 CBS_API参考_华为云

API 参考

目 录

1 使用前必读... 1

2 API 概览... 4

3 如何调用 API...5

4 问答机器人...11

5 话务机器人...70

6 数据结构...80

7 附录... 82

8 修订记录...87

1 使用前必读

1.1 概述

1.2 调用说明

1.3 终端节点

1.4 约束与限制

1.5 基本概念

2 API 概览

3 如何调用 API

3.1 构造请求

请求 URI

请求方法

请求消息头

请求消息体

3.2 认证鉴权

Token 认证

username

domainname

********

AK/SK 认证

3.3 返回结果

状态码

响应消息头

响应消息体

4 问答机器人

4.1 问答机器人 API

功能介绍

调试

URI

请求参数

响应参数

请求示例

响应示例

状态码

错误码

4.2 问答统计 API

4.2.1 问答统计

功能介绍

调试

URI

请求参数

响应参数

请求示例

响应示例

状态码

错误码

4.2.2 访问统计

功能介绍

调试

URI

请求参数

响应参数

请求示例

响应示例

状态码

错误码

4.2.3 热点问题统计

功能介绍

调试

URI

请求参数

响应参数

请求示例

响应示例

状态码

错误码

4.2.4 关键词统计

功能介绍

调试

URI

目录

1 ^{使用前必读}

2 ^{API 概览}

3 ^{如何调用 API}

4 ^{问答机器人}