智能问答引擎
智能问答引擎是问答服务的运行环境，包括可执行从多轮对话设计器导出的对话应用、基于常见问题集的知识库、意图识别和服务统计监控等模块。架构图
从部署拓扑结构上看，智能问答引擎的架构如下图所示：智能问答引擎架构
- superbrain：智能问答引擎核心服务节点，提供对外操作的Rest APIs，比如知识库管理、多轮对话管理和监控统计等。
- superbrain admin：智能问答引擎管理控制台，提供Web管理页面，方便企业IT人员或业务人员管理智能问答引擎。
- siamese：底层服务，知识库搜索时，文档和查询条件之间的相关度计算模块。
- Elasticsearch：底层服务，存储知识库数据的服务，在检索时，召回数据。
- intent：底层服务，提供意图识别能力。
- redis：底层服务，缓存数据和做定时任务。
- MongoDB：底层服务，superbrain数据的持久化数据库。
安装
获取服务镜像
当前，Chatopera智能问答引擎只面向企业做私有部署，有合作意向的企业联系下面邮箱，进行洽谈：联系方式：info@chatopera.com
洽谈内容包括：
- 概念验证
- 试用申请
- 其他商业合作
chatopera.superadmin.docker.v1.tgz
chatopera.superbrain.docker.v1.tgz
chatopera.siamese.docker.v1.tgz
chatopera.mongodb.docker.v1.tgz
chatopera.redis.docker.v1.tgz
chatopera.elasticsearch.docker.v1.tgz
依赖环境
智能问答引擎是使用docker镜像进行分发的，所以，只要是docker v12+ 版本支持的操作系统都可以运行智能问答引擎服务，对于更详细的操作系统的兼容列表，请参考Docker Community Edition (CE)。硬件方面，Chatopera推荐使用4Core CPU(Intel E5 or better)， 16GB Memory，128GB Disk运行服务。
智能问答引擎的docker镜像可以安装在docker服务中，或docker registry中。然后通过容器管理框架，比如kubernetes、Apache Mesos或docker compose。
在本文档中，介绍使用docker compose的方式部署和管理服务，docker compose是轻量级的docker服务编排方案。
- docker 版本
安装文档，注意：docker为开源码程序，本文档使用社区版本（Docker CE）。
- docker-compose
安装文档。
安装镜像
假设docker已经被安装好，并且其进程已经启动，在命令行终端，执行下面命令：docker load < chatopera.superadmin.docker.v1.tgz
docker load < chatopera.superbrain.docker.v1.tgz
docker load < chatopera.siamese.docker.v1.tgz
docker load < chatopera.mongodb.docker.v1.tgz
docker load < chatopera.redis.docker.v1.tgz
docker load < chatopera.elasticsearch.docker.v1.tgz
上述命令执行后，查看各个镜像已经安装成功，使用命令：
docker images
描述服务
在命令行终端，进入一个文件路径，智能问答引擎的服务的数据文件将保存在这个路径下，假设该路径为 /app/chatbot。- 创建服务描述文件 docker-compose.yml
version: '2'
services:
superadmin:
image: "registry.chatopera.com/ada/superadmin:develop"
restart: always
environment:
- SUPERBRAIN_API_URL=http://superbrain:8003/api/v1
superbrain:
image: "registry.chatopera.com/pintuan/superbrain:release"
restart: always
environment:
- PORT_NUMBER=8003
- SECRET_HASH=demo
- MONGO_DB_URI=mongodb://mongodb/superbrain-dev
- REDIS_HOST=redis
- REDIS_PORT=6379
- ELASTICSEARCH_HOST=http://elasticsearch:9200
# - ELASTICSEARCH_AUTH=
- ELASTICSEARCH_API_VERSION=5.2
ports:
- "8003:8003"
volumes:
- $PWD/superbrain/logs:/app/logs
command: "node app.js"
depends_on:
- redis
- mongodb
- elasticsearch
- siamese
siamese:
image: "registry.chatopera.com/pintuan/siamese:release"
restart: always
ports:
- "8012:8012"
volumes:
- $PWD/siamese/logs:/logs
environment:
- TXT_LOG_LVL=DEBUG
- SIAMESE_PORT=8012
- SIAMESE_THREADS=24
- SIAMESE_W2V_MODEL_EN=/word2vec/google-news-slim/GoogleNews-vectors-negative300-SLIM.bin.gz
mongodb:
image: "tutum/mongodb:3.2"
restart: always
volumes:
- $PWD/mongodb/data:/data/db
ports:
- "27017:27017"
- "27018:27018"
environment:
- AUTH=no
redis:
image: redis:latest
restart: always
command: redis-server --appendonly yes
volumes:
- $PWD/redis/data:/data
ports:
- "6379:6379"
elasticsearch:
image: "elasticsearch:5.2.0"
restart: always
environment:
- bootstrap.memory_lock=true
- "ES_JAVA_OPTS=-Xms512m -Xmx512m"
volumes:
- $PWD/elasticsearch/data:/usr/share/elasticsearch/data
- $PWD/elasticsearch/plugins:/usr/share/elasticsearch/plugins
ports:
- "9200:9200"
- "9300:9300"
ulimits:
memlock:
soft: -1
hard: -1
该描述文件采用的格式是YML，该描述文件声明了多个容器服务和它的配置，比如镜像、环境变量、映射的磁盘、日志管理等。拷贝右侧的代码为/app/chatbot/docker-compose.yml。
关于服务编排格式更多说明。
创建磁盘路径
Docker容器是一种管理计算资源的方式，它让开发运营软件的构建、分发和运行做到了标准化。对于在容器运行过程中，不慎被删除或崩溃，有可能造成数据丢失。一个解决方案是将Docker容器中应用产生的数据映射到宿主机器的磁盘上。在命令行终端中， 到/app/chatbot下，执行下面的命令：
mkdir -p mongodb/data # 存储 mongodb 数据
mkdir -p elasticsearch/data # 存储 elasticsearch 数据
mkdir -p elasticsearch/plugins # elasticsearch 插件程序
mkdir -p redis/data # 存储 redis 数据
mkdir -p superbrain/logs # 存储 superbrain 日志
启动服务
完成磁盘路径的创建后，就可以启动服务了。在命令行终端中， 到/app/chatbot下，执行下面的命令：
docker-compose up -d
这时，命令会立即退出，因为该命令告诉docker-compose在后台执行启动工作，服务启动需要1-2分钟，这取决于运行服务的硬件资源。
在命令行终端中， 到/app/chatbot下，执行下面的命令查看服务日志：
docker-compose logs -f
在服务启动的过程中，也可以看到相应日志。
关于docker-compose up的更多使用介绍，请查看文档。
在命令行终端中， 到/app/chatbot下，执行下面的命令查看服务启动状态：
docker-compose ps
在输出中，为多列描述的各服务的信息，其中State列为其中状态，在没有异常发生时，各服务的State均为Up，输出结果类似下面：
chatoperaio_elasticsearch_1 /docker-entrypoint.sh elas ... Up 0.0.0.0:9200->9200/tcp, 0.0.0.0:9300->9300/tcp
chatoperaio_intent_1 npm start Up 0.0.0.0:8027->8027/tcp
chatoperaio_mongodb_1 /run.sh Up 0.0.0.0:27017->27017/tcp, 0.0.0.0:27018->27018/tcp, 28017/tcp
chatoperaio_redis_1 docker-entrypoint.sh redis ... Up 0.0.0.0:6379->6379/tcp
chatoperaio_siamese_1 /root/venv-py2/bin/python2 ... Up 0.0.0.0:8012->8012/tcp
chatoperaio_superadmin_1 /bin/sh -c npm start Up 3000/tcp
chatoperaio_superbrain_1 node app.js Up 0.0.0.0:8003->8003/tcp
以上代表服务正常启动了，这时可以通过访问智能问答引擎控制台来管理聊天机器人。
http://服务器IP地址:8032
管理控制台
智能问答引擎管理控制台是为方便企业IT人员或业务人员管理智能问答引擎而设计的，在服务被正常启动后，管理控制台的URL地址是：http://{{IP}}:8032
注意: {{IP}}是docker容器运行的宿主机器IP地址。
使用浏览器打开该地址，即可使用管理控制台，主要功能包括：
- 聊天机器人增删改差
- 聊天机器人监控
- 聊天机器人多轮对话管理
- 聊天机器人知识库管理
聊天机器人管理
进入控制台，可以看到所有聊天机器人并管理。控制台
新建机器人
管理详情
聊天机器人监控
通过仪表盘可以查看机器人的使用情况。仪表盘
使用多轮对话设计器 设计对话应用并导出的程序包，程序包后缀名是.c66。导入可以看到对话列表，也可以设置各个对话的状态。
多轮对话
环境变量4
查看脚本
逻辑
知识库包括问答对和近义词，问答对支持批量导入，导入文件格式必须是UTF-8编码的CSV文件。
该CSV文件的每一行内容格式为： 是否启用，标准问,答案,扩展问1,扩展问2,扩展问3
CSV文件示例
true,钱款数据在哪查,微信商户支付平台里
false,怎么计算中奖呢,无法计算,中奖计算方法
true,没有二维码,刷新当前页,看不到二维码
常见问题
编辑一个问答对的标准问、扩展问、回复和状态。
问题编辑
近义词
API
智能问答引擎与其他服务集成的方式是暴露出来的Rest API接口，接口可以分为以下几类：| 资源 | 描述 | 路径前缀 |
| 聊天机器人 | 对象的增删改查 | /api/v1/chatbot |
| 多轮对话 | 查询，导入和状态管理 | /api/v1/chatbot/:ChatbotID/conversation |
| 多轮对话 | 问答的使用情况统计数据 | /api/v1/chatbot/:chatbotID/conversation/query/counts |
| 知识库FAQ问答对 | 增删改查和状态管理 | /api/v1/chatbot/:chatbotID/faq/database |
| 知识库近义词 | 增删改查 | /api/v1/chatbot/:ChatbotID/faq/synonyms |
| 知识库 | 问答的使用情况统计数据 | /api/v1/chatbot/:chatbotID/faq/query/counts |
| 意图识别 | 分析接口 | /api/v1/chatbot/:ChatbotID/intent/parse |
| 应用健康 | 状态查询接口 | /ping |
基本规范
在Rest API接口中，请求包括协议(http/https)，IP地址(Host)，HTTP头字段(Headers)，HTTP报文主体(Body 可选)。- 请求(Request)
Host: {{IP}}
Headers: Content-Type application/json
注意： 1. {{变量}}代表变量； 2. {{IP}}代表服务运行的宿主机器的IP地址。
- 响应(Response)
{
"rc": 0,
"data": ...
}
其中，rc代表请求是否被满足，0代表满足；rc非0时，代表有异常，不同的异常类型使用不同的数字，在每个API中介绍。
异常返回的一般形式：
{
"rc": 非0的正整数,
"error": ...,
"msg": ...
}
POST /api/v1/chatbot/:ChatbotID
cURL：创建聊天机器人curl --request POST \
--url 'http://{{IP}}:8003/api/v1/chatbot/{{chatbotID}}' \
--header 'Content-Type: application/json' \
--data '{
"name": "小叮当",
"primaryLanguage": "zh_CN"
}'
创建聊天机器人
BODY
{"name": "小叮当",
"primaryLanguage": "zh_CN"
}
| 字段 | 必须 | 类型 | 描述 |
| chatbotID | 是 | string | 机器人的唯一ID，是以字母开始的由[a-zA-Z0-9_]组成的字符串。 |
| name | 是 | string | 机器人的名称。 |
| primaryLanguage | 是 | string | 机器人的语言，现在支持两个选项：["zh_CN", "en_US"]，分别代表中文和英文。 |
| description | 否 | string | 机器人的描述 |
成功返回
{"rc": 0,
"data": {
"chatbotID": "{{chatbotID}}",
"name": "小叮当",
"fallback": "我不明白您的意思。",
"description": "智能问答和对话任务",
"welcome": "你好！我是机器人客服。",
"primaryLanguage": "zh_CN"
}
}
返回字段说明：
fallback：聊天机器人的兜底回复。
description：聊天机器人的描述。
welcome：欢迎语。
异常返回
{"rc":2,
"error":"already exists."
}
返回字段说明：
rc：非0正整数代表不同的异常类型，比如，当前rc是2，异常描述为“already exists.”，说明该{{chatbotID}}已经存在了。
PUT /api/v1/chatbot/:ChatbotID
cURL：更新聊天机器人curl -X PUT \
http://{{IP}}:8003/api/v1/chatbot/{{chatbotID}} \
-H 'Content-Type: application/json' \
-d '{
"fallback": "我不能理解您的意思。",
"description": "聊天机器人",
"welcome": "我的特长是聊天。"
}'
更新聊天机器人
BODY
{"fallback": "我不能理解您的意思。",
"description": "聊天机器人",
"welcome": "我的特长是聊天。"
}
| 字段 | 必须 | 类型 | 描述 |
| fallback | 否 | string | 机器人兜底回复，在多轮对话查询没有匹配到回复时使用。 |
| description | 否 | string | 描述该机器人。 |
| welcome | 否 | string | 欢迎语，保留字段，暂时未使用。 |
成功返回
{"rc": 0,
"data": {
"chatbotID": "{{chatbotID}}",
"fallback": ...,
"description": ...,
"welcome": ...
}
}
异常返回
{"rc": 1,
"error": ...
}
返回字段说明：
rc为正整数时，代表异常，异常描述为error。
GET /api/v1/chatbot/:ChatbotID
cURL：获取聊天机器人信息curl -X GET \
http://{{IP}}:8003/api/v1/chatbot/{{chatbotID}} \
-H 'Content-Type: application/json'
获取聊天机器人信息
BODY
null成功返回
{"rc": 0,
"data": {
"chatbotID": "{{chatbotID}}",
"name": "小叮当",
"fallback": "我不明白您的意思。",
"description": "智能问答和对话任务",
"welcome": "你好！我是机器人客服。",
"primaryLanguage": "zh_CN"
}
}
异常返回
{"rc": 3,
"error": "not exist."
}
返回字段说明：
rc为正整数时，代表异常，异常描述为error。
GET /api/v1/chatbot
cURL：获取聊天机器人列表curl -X GET \
'http://{{IP}}:8003/api/v1/chatbot?sortby=-created&q={"chatbotID": "department_1"}' \
-H 'Content-Type: application/json'
获取聊天机器人列表
QUERY
支持在URL中添加query信息来查询机器人和翻页等操作，比如 /api/v1/chatbot?page=1&limit=10&fields=chatbotID name&q={"name": "test"}，各参数介绍如下：| 属性 | 类型 | 描述 | 默认值 | 示例 |
| limit | number | 返回本页数据的条数 | 100 | 10 |
| page | number | 返回哪一页(可根据total进行判断) | 1 | 2 |
| fields | string | 返回哪些字段 | 除_id 和 __v之外的所有字段 | chatbotID name |
| sortby | string | 按照哪个字段进行排序 | 空 | -created (按照 created 降序) |
| q | string | 按照字段查询 | 空 | {"name": "test"} |
BODY
null成功返回
{"total": 1,
"rc": 0,
"current_page": 1,
"total_page": 1,
"data": [
{
"name": "小叮当",
"chatbotID": "{{chatbotID}}",
"primaryLanguage": "zh_CN",
"fallback": "我不明白您的意思。",
"welcome": "你好！我是机器人客服。",
"description": "智能问答和对话任务"
},
...
]
}
返回字段说明：
total代表聊天机器人数量。
current_page代表当前页，total_page代表总页数。
data是聊天机器人数据。
异常返回
{"rc": 1,
"error": ...
}
返回字段说明：
rc为正整数时，代表异常，异常描述为error。
DELETE /api/v1/chatbot/:ChatbotID
cURL：删除一个聊天机器人curl -X DELETE \
http://{{IP}}:8003/api/v1/chatbot/{{chatbotID}} \
-H 'Content-Type: application/json' \
删除一个聊天机器人
BODY
null成功返回
{"rc": 0,
"data": {
"message": "done."
}
}
异常返回
{"rc": 1,
"error": ...
}
返回字段说明：
rc为正整数时，代表异常，异常描述为error。
POST /api/v1/chatbot/:ChatbotID/faq/database
cURL：创建问答对curl -X POST \
http://{{IP}}:8003/api/v1/chatbot/{{chatbotID}}/faq/database \
-H 'Content-Type: application/json' \
-d '{
"post": "怎么开通微信支付?",
"reply": "登录微信公众号平台，点击左侧微信支付菜单栏，按照开通步骤开通微信支付",
"enabled": true
}'
创建问答对
BODY
{"post": "怎么开通微信支付?",
"reply": "登录微信公众号平台，点击左侧微信支付菜单栏，按照开通步骤开通微信支付",
"enabled": true
}
| 字段 | 必须 | 类型 | 描述 |
| post | 是 | string | 问答对的问题，也称“标准问” |
| reply | 是 | string | 问题对应的回复 |
| enabled | 是 | boolean | 是否“启用”，启用代表该问答对在检索时被使用；否则不被检索 |
成功返回
{"rc": 0,
"data": {
"id": "{{docId}}}"
}
}
返回字段说明：
docId代表该问答对的唯一标识。
异常返回
{"rc": 3,
"error": ...
}
返回字段说明：
rc为正整数时，代表异常，异常描述为error。
GET /api/v1/chatbot/:ChatbotID/faq/database/:docId
cURL：根据文档Id查询问答对详情curl -X GET \
http://{{IP}}:8003/api/v1/chatbot/{{chatbotID}}/faq/database/{{docId}} \
-H 'Content-Type: application/json'
根据文档Id查询问答对详情
BODY
null成功返回
{"rc": 0,
"data": {
"id": "{{docId}}",
"post": "怎么开通微信支付?",
"reply": "登录微信公众号平台，点击左侧微信支付菜单栏，按照开通步骤开通微信支付",
"enabled": true
}
}
异常返回
{"rc": 3,
"error": {
"msg": "Not Found"
}
}
返回字段说明：
rc为正整数时，代表异常，异常描述为error。
PUT /api/v1/chatbot/:ChatbotID/faq/database/:docId
cURL：根据文档ID更新问答对curl -X PUT \
http://{{IP}}:8003/api/v1/chatbot/{{chatbotID}}/faq/database/{{docId}} \
-H 'Content-Type: application/json' \
-d '{
"post": "怎么开通微信支付?",
"reply": "登录微信公众号平台，点击左侧微信支付菜单栏，按照开通步骤开通微信支付",
"enabled": true
}'
根据文档ID更新问答对
BODY
{"post": "怎么开通微信支付?",
"reply": "登录微信公众号平台，点击左侧微信支付菜单栏，按照开通步骤开通微信支付",
"enabled": true
}
| 字段 | 必须 | 类型 | 描述 |
| post | 否 | string | 问答对的问题，也称“标准问” |
| reply | 否 | string | 问题对应的回复 |
| enabled | 否 | boolean | 是否“启用”，启用代表该问答对在检索时被使用；否则不被检索 |
成功返回
{"rc": 0,
"data": {
"id": "{{docId}}"
}
}
异常返回
{"rc": 3,
"error": {
"msg": "Not Found"
}
}
返回字段说明：
rc为正整数时，代表异常，异常描述为error。
DELETE /api/v1/chatbot/:ChatbotID/faq/database/:docId
cURL：根据文档ID删除问答对curl -X DELETE \
http://{{IP}}:8003/api/v1/chatbot/{{chatbotID}}/faq/database/{{docId}} \
-H 'Content-Type: application/json'
根据文档ID删除问答对
BODY
null成功返回
{"rc": 0,
"message": "done"
}
异常返回
{"rc": 3,
"error": {
"msg": "Not Found"
}
}
返回字段说明：
rc为正整数时，代表异常，异常描述为error。
GET /api/v1/chatbot/:ChatbotID/faq/database
cURL：查询问答对列表，可根据字段查询，支持分页curl -X GET \
'http://{{IP}}:8003/api/v1/chatbot/{{chatbotID}}/faq/database?limit=30' \
-H 'Content-Type: application/json'
查询问答对列表，可根据字段查询，支持分页
QUERY
在url中，支持使用检索条件，比如 /api/v1/chatbot/{{chatbotID}}/faq/database?page=1&limit=10，各参数介绍如下：| 属性 | 类型 | 描述 | 默认值 | 示例 |
| limit | number | 返回本页数据的条数 | 5 | 10 |
| page | number | 返回哪一页(可根据total进行判断) | 1 | 2 |
BODY
null成功返回
{"total": 354,
"current_page": 1,
"total_page": 12,
"data": [
{
"post": "上架商品就不能修改了是吗？",
"is_original": true,
"reply": "没有订单产生时可以修改",
"enabled": true,
"id": "{{docId}}"
},
...
]
}
异常返回
{"rc": 3,
"error": {
"msg": "[index_not_found_exception] no such index
}
}
返回字段说明：
rc为正整数时，代表异常，异常描述为error。
POST /api/v1/chatbot/:chatbotID/faq/database/:docId/extend
cURL：创建扩展问curl -X POST \
http://{{IP}}:8003/api/v1/chatbot/{{chatbotID}}/faq/database/{{docId}}/extend \
-H 'Content-Type: application/json' \
-d '{
"post": "怎样支持微信支付?"
}
'
创建扩展问，扩展问关联一个问答对，扩展问是标准问的另一种问法。一个问答对可以关联多个扩展问。
扩展问可以使系统更智能，提高检索的准确率。
BODY
{"post": "怎样支持微信支付?"
}
| 字段 | 必须 | 类型 | 描述 |
| post | 是 | string | 与标准问意思一致的另一种问法，也称“扩展问”。 |
成功返回
{"rc": 0,
"data": {
"id": "{{extendId}}"
}
}
返回字段说明：
extendId是该扩展问的唯一标识。
异常返回
{"rc": 1,
"error": ...
}
返回字段说明：
rc为正整数时，代表异常，异常描述为error。
GET /api/v1/chatbot/:chatbotID/faq/database/:docId/extend
cURL：查询扩展问curl -X GET \
http://{{IP}}:8003/api/v1/chatbot/{{chatbotID}}/faq/database/{{docId}}/extend \
-H 'Content-Type: application/json'
查询扩展问
BODY
null成功返回
{"total": 1,
"current_page": 1,
"total_page": 1,
"data": [
{
"post": "怎样支持微信支付?",
"is_original": false,
"postId": "{{docId}}",
"enabled": true,
"id": "{{extendId}}"
},
...
],
"rc": 0
}
异常返回
{"rc": 3,
"error": ...
}
返回字段说明：
rc为正整数时，代表异常，异常描述为error。
PUT /api/v1/chatbot/:chatbotID/faq/database/:docId/extend/:extendId
cURL：更新扩展问curl -X PUT \
http://{{IP}}:8003/api/v1/chatbot/{{chatbotID}}/faq/database/{{docId}}/extend/{{extendId}} \
-H 'Content-Type: application/json' \
-d '{
"post": "怎样支持微信支付?"
}
'
更新扩展问
BODY
{"post": "怎样支持微信支付?"
}
| 字段 | 必须 | 类型 | 描述 |
| post | 是 | string | 与标准问意思一致的另一种问法，也称“扩展问”。 |
成功返回
{"rc": 0,
"data": {
"id": "{{extendId}}"
}
}
返回字段说明：
extendId是该扩展问的唯一标识。
异常返回
{"rc": 3,
"error": {
"msg": "Not Found"
}
}
返回字段说明：
rc为正整数时，代表异常，异常描述为error。
DELETE /api/v1/chatbot/:chatbotID/faq/database/:docId/extend/:extendId
cURL：删除扩展问curl -X DELETE \
http://{{IP}}:8003/api/v1/chatbot/{{chatbotID}}/faq/database/{{docId}}/extend/{{extendId}} \
-H 'Content-Type: application/json'
删除扩展问
BODY
null成功返回
{"rc": 0,
"message": "done"
}
异常返回
{"rc": 3,
"error": ...
}
返回字段说明：
rc为正整数时，代表异常，异常描述为error。
GET /api/v1/chatbot/:ChatbotID/faq/database/export
cURL：导出问答对数据curl -X GET \
http://{{IP}}:8003/api/v1/chatbot/{{chatbotID}}/faq/database/export \
-H 'Content-Type: application/json'
导出问答对数据
BODY
null成功返回
{"rc": 0,
"data": [
[
true,
"怎么开通微信支付?",
"登录微信公众号平台，点击左侧微信支付菜单栏，按照开通步骤开通微信支付",
"如何支持微信支付"
],
...
]
}
返回字段说明：
data是问答对的所有数据，每个元素代表一个问答对。 每个元素又是一个数组，按照顺序分别代表：[enabled，标准问，回复，0~多个扩展问]。
异常返回
{"rc": 1,
"error": ...
}
返回字段说明：
rc为正整数时，代表异常，异常描述为error。
POST /api/v1/chatbot/:ChatbotID/faq/synonyms
cURL：创建近义词curl -X POST \
http://{{IP}}:8003/api/v1/chatbot/{{chatbotID}}/faq/synonyms \
-H 'Content-Type: application/json' \
-d '{
"text": "番茄",
"neighbors": ["西红柿", "狼桃"]
}'
创建近义词，近义词可以进一步提高系统的智能水平。
BODY
{"text": "番茄",
"neighbors": ["西红柿", "狼桃"]
}
| 字段 | 必须 | 类型 | 描述 |
| text | 是 | string | 词汇 |
| neighbors | 是 | [string] | 与text意思相近的词汇 |
成功返回
{"rc": 0,
"data": {
"text": "番茄",
"chatbot": "{{chatbotID}}",
"neighbors": [
"西红柿",
"狼桃"
],
"id": "{{synonymsId}}"
}
}
返回字段说明：
synonymsId是该近义词组的唯一标识。
异常返回
{"rc": 1,
"error": ...
}
返回字段说明：
rc为正整数时，代表异常，异常描述为error。
GET /api/v1/chatbot/:ChatbotID/faq/synonyms/:synonymsId
cURL：使用synonymsId获取近义词详情curl -X GET \
http://{{IP}}:8003/api/v1/chatbot/{{chatbotID}}/faq/synonyms/{{synonymsId}} \
-H 'Content-Type: application/json'
使用synonymsId获取近义词详情
BODY
null成功返回
{"rc": 0,
"data": {
"text": "番茄",
"neighbors": [
"西红柿",
"狼桃"
]
}
}
异常返回
{"rc": 1,
"error": ...
}
返回字段说明：
rc为正整数时，代表异常，异常描述为error。
PUT /api/v1/chatbot/:ChatbotID/faq/synonyms/:synonymsId
cURL：更新近义词curl -X PUT \
http://{{IP}}:8003/api/v1/chatbot/{{chatbotID}}/faq/synonyms/{{synonymsId}} \
-H 'Content-Type: application/json' \
-d '{
"text": "番茄",
"neighbors": ["西红柿", "狼桃", "洋柿子"]
}'
更新近义词
BODY
{"text": "番茄",
"neighbors": ["西红柿", "狼桃", "洋柿子"]
}
成功返回
{"rc": 0,
"data": {
"text": "番茄",
"neighbors": [
"西红柿",
"狼桃",
"洋柿子"
]
}
}
异常返回
{"rc": 1,
"error": ...
}
DELETE /api/v1/chatbot/:ChatbotID/faq/synonyms/:synonymsId
cURL：删除近义词curl -X DELETE \
http://{{IP}}:8003/api/v1/chatbot/{{chatbotID}}/faq/synonyms/{{synonymsId}} \
-H 'Content-Type: application/json'
删除近义词
BODY
null成功返回
{"rc": 0,
"message": "done"
}
异常返回
{"rc": 1,
"error": ...
}
返回字段说明：
rc为正整数时，代表异常，异常描述为error。
GET /api/v1/chatbot/:ChatbotID/faq/synonyms
cURL：查询近义词列表，支持分页和按字段查询curl -X GET \
http://{{IP}}:8003/api/v1/chatbot/{{chatbotID}}/faq/synonyms \
-H 'Content-Type: application/json'
查询近义词列表，支持分页和按字段查询
BODY
null成功返回
{"total": 1,
"rc": 0,
"current_page": 1,
"total_page": 1,
"data": [
{
"text": "番茄",
"chatbot": "{{chatbotID}}",
"neighbors": [
"西红柿",
"狼桃",
"洋柿子"
],
"id": "{{synonymsId}}"
},
...
]
}
异常返回
{"rc": 1,
"error": ...
}
返回字段说明：
rc为正整数时，代表异常，异常描述为error。
POST /api/v1/chatbot/:ChatbotID/faq/query
cURL：根据查询句子查询答案, 返回答案列表，并带有分数curl -X POST \
http://{{IP}}:8003/api/v1/chatbot/{{chatbotID}}/faq/query \
-H 'Content-Type: application/json' \
-d '{
"query": "如何开通微信支付"
}'
根据查询句子查询答案, 返回答案列表，并带有分数
BODY
{"query": "如何开通微信支付"
}
| 字段 | 必须 | 类型 | 描述 |
| query | 是 | string | 从知识库中检索的目标 |
成功返回
{"rc": 0,
"data": [
{
"id": "{{docId}}",
"score": 0.647,
"post": "怎么开通微信支付?",
"reply": "登录微信公众号平台，点击左侧微信支付菜单栏，按照开通步骤开通微信支付"
}
]
}
返回字段说明：
data是一个数组，包含0～多个问答对，并且按照匹配程度降序，匹配程度就是该问答对的问题和query的相似度。
相似度是属于[0-1]区间的值，越大代表语义越相似。
异常返回
{"rc": 1,
"error": ...
}
返回字段说明：
rc为正整数时，代表异常，异常描述为error。
POST /api/v1/chatbot/:ChatbotID/faq/click
cURL：记录FAQ点击事件curl -X POST \
http://{{IP}}:8003/api/v1/chatbot/{{chatbotID}}/faq/click \
-H 'Content-Type: application/json' \
-d '{
"query": "如何开通微信支付",
"groundtruth": "如何支持微信支付",
"negatives": ["如何支持支付", "怎么取消微信支付"]
}'
记录FAQ点击事件：在客服人员点击建议问时，将访客的问题和客服点击的问题记录下来。
点击事件具有很重要的价值：
- 梳理业务，提高商业智能;
- 方便统计系统使用情况;
- 评估系统准确率;
- 优化系统准确率，比如训练更好的机器学习模型。
BODY
{"query": "如何开通微信支付",
"groundtruth": "如何支持微信支付",
"negatives": ["如何支持支付", "怎么取消微信支付"]
}
| 字段 | 必须 | 类型 | 描述 |
| query | 是 | string | 原始查询 |
| groundtruth | 是 | string | 准确答案 |
| negatives | 是 | [string] | 被展示为建议答案但是没有被选中的候选回复 |
成功返回
{"rc": 0,
"message": "done"
}
返回字段说明：
异常返回
{"rc": 1,
"error": ...
}
返回字段说明：
rc为正整数时，代表异常，异常描述为error。
POST /api/v1/chatbot/:chatbotID/intent/parse
cURL：意图识别服务curl -X POST \
http://{{IP}}:8003/api/v1/chatbot/{{chatbotID}}/intent/parse \
-H 'Content-Type: application/json' \
-d '{
"query": "can I have my cashback",
"clientId": "gmis"
}'
使用机器学习模型，分析意图和实体。
BODY
{"query": "我想取钱",
"clientId": "{{clientId}}"
}
| 字段 | 必须 | 类型 | 描述 |
| query | 是 | string | 待被分析意图的句子 |
| clientId | 是 | string | 客户唯一标识，目前意图识别模型依赖每个客户的数据，和客户的业务关系紧密，每个客户单独制作。 |
成功返回
{"rc": 0,
"data": {
"tag": "{{intentId}}",
"score": 2.515
}
}
返回字段说明：
如果rc为0，但是data中不包含tag和score时，代表程序未能识别出意图。
异常返回
{"rc": 1,
"error": ...
}
返回字段说明：
rc为正整数时，代表异常，异常描述为error。
GET /api/v1/chatbot/:ChatbotId/conversation
cURL：获得对话列表curl -X GET \
http://{{IP}}:8003/api/v1/chatbot/{{chatbotID}}/conversation \
-H 'Content-Type: application/json'
获得对话列表
BODY
null成功返回
{"rc": 0,
"total": 1,
"current_page": 1,
"total_page": 1,
"data": [
{
"chatbotID": "{{chatbotID}}",
"name": "{{conversationName}}",
"enabled": true,
"id": "{{conversationId}}"
},
...
]
}
返回字段说明：
异常返回
{"rc": 1,
"error": ...
}
返回字段说明：
rc为正整数时，代表异常，异常描述为error。
GET /api/v1/chatbot/:ChatbotId/conversation/:conversationId
cURL：获得对话详情curl -X GET \
http://{{IP}}:8003/api/v1/chatbot/{{chatbotID}}/conversation/{{conversationId}} \
-H 'Content-Type: application/json' \
获得对话详情
BODY
null成功返回
{"rc": 0,
"data": {
"chatbotID": "{{chatbotID}}",
"name": "course",
"modified": "2018-07-11T09:39:58.349Z",
"created": "2018-07-02T12:02:43.037Z",
"scriptBody": "+ _resolve_course_\n- 您好，我是小云，您的课程顾问，请问您家小孩多大了？\n\n+ 一年级老师\n- ^get_teachers(1)",
"enabled": true,
"id": "{{conversationId}}"
}
}
返回字段说明：
异常返回
{"rc": 1,
"error": ...
}
返回字段说明：
rc为正整数时，代表异常，异常描述为error。
PUT /api/v1/chatbot/:ChatbotId/conversation/:conversationId/enable
cURL：使对话处于"启用"状态curl -X PUT \
http://{{IP}}:8003/api/v1/chatbot/{{chatbotID}}/conversation/{{conversationId}}/enable
使对话处于"启用"状态
BODY
null成功返回
{"rc": 0,
"data": {
"name": "course",
"chatbotID": "{{chatbotID}}",
"enabled": true,
"id": "{{conversationId}}"
}
}
返回字段说明：
异常返回
{"rc": 1,
"error": ...
}
返回字段说明：
rc为正整数时，代表异常，异常描述为error。
PUT /api/v1/chatbot/:ChatbotId/conversation/:conversationId/disable
cURL：使对话处于"禁用"状态curl -X PUT \
http://{{IP}}:8003/api/v1/chatbot/{{chatbotID}}/conversation/{{conversationId}}/disable \
使对话处于"禁用"状态
BODY
null成功返回
{"rc": 0,
"data": {
"name": "course",
"chatbotID": "{{chatbotID}}",
"enabled": false,
"id": "{{conversationId}}"
}
}
返回字段说明：
异常返回
{"rc": 1,
"error": ...
}
返回字段说明：
rc为正整数时，代表异常，异常描述为error。
GET /api/v1/chatbot/:chatbotID/conversation/environment
cURL：获取环境变量curl -X GET \
http://{{IP}}:8003/api/v1/chatbot/{{chatbotID}}/conversation/environment \
获取环境变量
环境变量是多轮对话的在“设计阶段”和“部署阶段”不共享的变量。具体应用场景见多轮对话设计器：快速开始。
BODY
null成功返回
{"rc": 0,
"data": {
"USERNAME": "张三"
}
}
返回字段说明：
异常返回
{"rc": 1,
"error": ...
}
返回字段说明：
rc为正整数时，代表异常，异常描述为error。
PUT /api/v1/chatbot/:chatbotID/conversation/environment
cURL：更新环境变量curl -X PUT \
http://{{IP}}:8003/api/v1/chatbot/{{chatbotID}}/conversation/environment \
-H 'Content-Type: application/json' \
-d '{
"USERNAME": "李四",
"PASSWORD": "123456"
}'
更新环境变量
BODY
{"USERNAME": "李四",
"PASSWORD": "123456"
}
成功返回
{"rc": 0,
"msg": "done"
}
返回字段说明：
异常返回
{"rc": 1,
"error": ...
}
返回字段说明：
rc为正整数时，代表异常，异常描述为error。
POST /api/v1/chatbot/:ChatbotId/conversation/query
cURL：对话问答查询curl -X POST \
http://{{IP}}:8003/api/v1/chatbot/{{chatbotID}}/conversation/query \
-H 'Content-Type: application/json' \
-d '{
"fromUserId": "{{uid}}",
"textMessage": "北京今天天气怎么样",
"isDebug": false
}'
对话问答查询
BODY
{"fromUserId": "{{uid}}",
"textMessage": "北京今天天气怎么样",
"isDebug": false
}
成功返回
{"rc": 0,
"data": {
"state": "default",
"createdAt": 1531910247845,
"string": "白天天气多云，并且空气湿度偏大，在这种天气条件下，您会感到有些闷热，不很舒适。",
"topicName": "weather",
"subReplies": [],
"logic_is_fallback": false,
"botName": "小叮当"
}
}
返回字段说明：
state是一些业务需求的约定字段，比如，对话要完成“用户认证”，那么在完成认证后，state会返回auth_succ；认证失败时，返回auth_fail，该字段可通过对话脚本设定。
logic_is_fallback代表该回复是否是兜底。
topicName代表当前机器人正在聊的话题。
botName代表聊天机器人的名字。
异常返回
{"rc": 1,
"error": ...
}
返回字段说明：
rc为正整数时，代表异常，异常描述为error。
POST /api/v1/chatbot/:ChatbotId/conversation/droplet/import
cURL：导入对话应用文件ZIPFILE=小叮当-1.0.0-conversations.c66
set -x
curl -i -X POST -H "Content-Type: multipart/form-data" \
-F "droplet=@$ZIPFILE" \
-F "USERNAME=李四" \
-F "PASSWORD=123456" \
http://{{IP}}:8003/api/v1/chatbot/{{chatbotID}}/conversation/droplet/import
导入对话应用文件
对话应用文件示例详见天气查询机器人:多轮对话示例程序。
BODY
multipart表单，环境变量使用-F设定键值对，对话应用文件设置droplet的文件路径，参考cURL样例程序。成功返回
{"rc": 0,
"data": {
"msg": "Import is done successfully."
}
}
异常返回
{"rc": 1,
"error": ...
}
返回字段说明：
rc为正整数时，代表异常，异常描述为error。
GET /ping
cURL：获取应用健康状态curl -X GET \
http://{{IP}}:8003/ping \
-H 'Content-Type: application/json'
获取应用健康状态
BODY
null成功返回
{"timestamp": 1531918165514,
"uptime": 8783.43,
"application": {
"name": "superbrain",
"version": "1.0.0",
"pid": 1,
"title": "node",
"argv": [
"/usr/local/bin/node",
"/app/app.js"
],
"versions": {
"http_parser": "2.8.0",
"node": "8.11.3",
"v8": "6.2.414.54",
"uv": "1.19.1",
"zlib": "1.2.11",
"ares": "1.10.1-DEV",
"modules": "57",
"nghttp2": "1.32.0",
"napi": "3",
"openssl": "1.0.2o",
"icu": "60.1",
"unicode": "10.0",
"cldr": "32.0",
"tz": "2017c"
}
},
"resources": {
"memory": {
"rss": 369848320,
"heapTotal": 130859008,
"heapUsed": 108874240,
"external": 18007788
},
"loadavg": [
0.35302734375,
0.28759765625,
0.2412109375
],
"cpu": [
{
"model": "Intel(R) Xeon(R) CPU E5-2682 v4 @ 2.50GHz",
"speed": 2500,
"times": {
"user": 1586270600,
"nice": 0,
"sys": 1050236500,
"idle": 21709890800,
"irq": 0
}
},
{
"model": "Intel(R) Xeon(R) CPU E5-2682 v4 @ 2.50GHz",
"speed": 2500,
"times": {
"user": 1562807900,
"nice": 0,
"sys": 1015181800,
"idle": 21782348900,
"irq": 0
}
}
],
"disk": [
{
"filesystem": "overlay",
"size": 123721700,
"used": 94808660,
"available": 22605316,
"capacity": 0.81,
"mount": "/"
},
{
"filesystem": "tmpfs",
"size": 65536,
"used": 0,
"available": 65536,
"capacity": 0,
"mount": "/dev"
},
{
"filesystem": "tmpfs",
"size": 8216392,
"used": 0,
"available": 8216392,
"capacity": 0,
"mount": "/sys/fs/cgroup"
},
{
"filesystem": "/dev/vda1",
"size": 123721700,
"used": 94808660,
"available": 22605316,
"capacity": 0.81,
"mount": "/app/logs"
},
{
"filesystem": "shm",
"size": 65536,
"used": 0,
"available": 65536,
"capacity": 0,
"mount": "/dev/shm"
},
{
"filesystem": "tmpfs",
"size": 8216392,
"used": 0,
"available": 8216392,
"capacity": 0,
"mount": "/sys/firmware"
}
],
"nics": {
"lo": [
{
"address": "127.0.0.1",
"netmask": "255.0.0.0",
"family": "IPv4",
"mac": "00:00:00:00:00:00",
"internal": true,
"cidr": "127.0.0.1/8"
}
],
"eth0": [
{
"address": "172.19.0.15",
"netmask": "255.255.0.0",
"family": "IPv4",
"mac": "02:42:ac:13:00:0f",
"internal": false,
"cidr": "172.19.0.15/16"
}
]
}
},
"system": {
"arch": "x64",
"platform": "linux",
"type": "Linux",
"release": "4.4.0-62-generic",
"hostname": "29866b45ce71",
"uptime": 2453892,
"cores": 2,
"memory": 16827174912
}
}
返回字段说明：
描述应用和操作系统的各种数据。
