智能问答引擎

智能问答引擎

智能问答引擎是问答服务的运行环境，包括可执行从多轮对话设计器导出的对话应用、基于常见问题集的知识库、意图识别和服务统计监控等模块。

架构图

从部署拓扑结构上看，智能问答引擎的架构如下图所示：
智能问答引擎架构

• superbrain：智能问答引擎核心服务节点，提供对外操作的Rest APIs，比如知识库管理、多轮对话管理和监控统计等。
• superbrain admin：智能问答引擎管理控制台，提供Web管理页面，方便企业IT人员或业务人员管理智能问答引擎。
• siamese：底层服务，知识库搜索时，文档和查询条件之间的相关度计算模块。
• Elasticsearch：底层服务，存储知识库数据的服务，在检索时，召回数据。
• intent：底层服务，提供意图识别能力。
• redis：底层服务，缓存数据和做定时任务。
• MongoDB：底层服务，superbrain数据的持久化数据库。

在企业使用过程中，只需要访问superbrain的REST APIs和superbrain admin的Web页面，底层服务的接口并不需要直接访问。同时，上面的七个服务，都是以docker镜像的形式分发，以docker容器的形式运行。

安装

获取服务镜像

当前，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 version 18.03.1-ce, build 9ee9f40
安装文档，注意：docker为开源码程序，本文档使用社区版本（Docker CE）。

• docker-compose

docker-compose version 1.21.1, build 5a3f1a3
安装文档。

安装镜像

假设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

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,没有二维码,刷新当前页,看不到二维码
常见问题 在问答对管理页面，也支持导出问答对为CSV文件，检索问答对等操作。
编辑一个问答对的标准问、扩展问、回复和状态。
问题编辑 为提高准确性，支持自定义近义词。
近义词

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)

在智能问答引擎服务启动后，通过 http 协议处理请求，如无特殊说明，每个接口都有如下设置：
Host: {{IP}}
Headers: Content-Type application/json
注意： 1. {{变量}}代表变量； 2. {{IP}}代表服务运行的宿主机器的IP地址。

• 响应(Response)

如无特殊说明，返回值都是JSON数据格式，在正常返回下，格式符合如下形式：
{
  "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	欢迎语，保留字段，暂时未使用。

对于机器人的chatbotID，name和primaryLanguage都是在创建时设定的，设定后不能变更。

成功返回

{
    "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=-createdq={"chatbotID": "department_1"}' \
  -H 'Content-Type: application/json'
获取聊天机器人列表

QUERY

支持在URL中添加query信息来查询机器人和翻页等操作，比如 /api/v1/chatbot?page=1limit=10fields=chatbotID nameq={"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=1limit=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点击事件：在客服人员点击建议问时，将访客的问题和客服点击的问题记录下来。
点击事件具有很重要的价值：

1. 梳理业务，提高商业智能;
2. 方便统计系统使用情况;
3. 评估系统准确率;
4. 优化系统准确率，比如训练更好的机器学习模型。

所以，该接口应保证尽可能调用。

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
    }
}
返回字段说明：
描述应用和操作系统的各种数据。