您当前的位置是:  首页 > 新闻 > 国内 >
 首页 > 新闻 > 国内 >

Chatopera 智能问答引擎

2018-08-01 14:05:54   作者:   来源:CTI论坛   评论:0  点击:


智能问答引擎

智能问答引擎

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

架构图

从部署拓扑结构上看,智能问答引擎的架构如下图所示:
智能问答引擎架构
  • 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中。然后通过容器管理框架,比如kubernetesApache Mesosdocker 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=-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点击事件:在客服人员点击建议问时,将访客的问题和客服点击的问题记录下来。
点击事件具有很重要的价值:
  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
    }
}
返回字段说明:
描述应用和操作系统的各种数据。
【免责声明】本文仅代表作者本人观点,与CTI论坛无关。CTI论坛对文中陈述、观点判断保持中立,不对所包含内容的准确性、可靠性或完整性提供任何明示或暗示的保证。请读者仅作参考,并请自行承担全部责任。

专题

博评网