1.接口需求背景与适用场景

1.1 需求背景

Smartbi AIChat本身是提供了多种客户端供用户选择的。如果常用PC，我们有基于PC浏览器的AIWeb页面；如果常用手机，我们有基于手机的App或者使用手机浏览器访问的AIChatView页面；我们还提供了基于钉钉的使用页面。

但是，这些都是Smartbi AIChat平台内置的使用页面，页面样式和操作方式是基于产品内置好的。如果用户想把自然语言查询集成到用户自己的APP里面，或者集成到用户其他的平台里面，我们内置的页面样式可能不太符合用户的要求，集成起来就不自然。

为了让用户在使用Smartbi自然语言查询的时候，可以自定义前端页面，我们提供了基于Java语言实现的RestFul API接口。本文主要就是介绍如何使用Smartbi AIChat的接口实现自己的前端页面。

1.2 适用场景

使用Smartbi AIChat 提供的API适合以下场景开发：


2. 逻辑架构

【用户自定义对话界面-逻辑架构图】

说明：

如果是Web页面，推荐使用Smartbi扩展包方式开发集成页面。这样可以避免跨域问题。如果需要在第三方应用中开发，需要做对所有API做服务端转发。

3. API说明

Smartbi AIChat二次开发，提供的是标准Restful API。只需要登录后，执行查询就可以了。所以，只需要2个API就可以完成需要的操作。

4.接口说明

4.1 登录AIChat

4.1.1 接口说明

名称

值

请求地址

http://smartbi-AIChat-server:port/aiweb/api/v1/login

请求方式

POST

请求参数

userName

password

smartbiServer

casLoginUrl

loginMethod

4.1.2 接口参数说明


URL参数名

说明

是否必填

输入参数

userName

登录账号

必填

password

登录密码

必填

smartbiServer

Smartbi服务器地址；该AIChat服务器第一次登录Smartbi，必填；以后选填；不填则使用之前已经登录过的Smartbi服务器

选填

casLoginUrl

如果Smartbi是使用CAS登录方式，则需要填入该值；该AIChat服务器第一次登录Smartbi，必填；以后选填；不填则使用之前已经登录过的Cas认证服务器

选填

loginMethod

使用的登录方法；枚举值

login

loginWithCas

普通登录使用login；如果是Cas登录则使用loginWithCas

默认情况下都可以不填

选填

返回值

{

    "code": 0,

    "result": {

        "userId": "",

        "userName": "",

        "userAlias": "",

        "isAdmin":

    },

    "message": "",

    "token": ""

}


4.1.3 接口返回值说明

返回参数名

返回值说明

code

接口调用是否成功；0 - 表示成功；负数为错误码

message

错误描述，code=0 时，该内容为空

token

登录方法特有内容，这个非常重要，后续接口需要传递该值以验证登录

result

调用接口的返回内容，登录接口的返回内容说明如下：

"userId": "",                                                   Smartbi中的用户Id

"userName": "",                                             Smartbi中的用户名

"userAlias": "",                                               Smartbi中的用户中文名

"isAdmin":                                                     在Smartbi中是否是管理员

4.1.4 调用示例（PostMan调用截图）


4.2 查询接口（异步）


名称

描述

默认值

接口路径

http://host:port/aiweb/api/v3/conv/query

接口说明

V3版本查询方法 -- 异步方法 -- SSE请求

header

token

登录key，使用login方法获取；login方法请参考：登录AIChat

接口参数

convId

会话Id

datasetId

数据模型Id

question

用户问题


queryType

查询类型：

  • query（查询模式）

  • analysis（分析模式）

  • expert（专家模式）

建议使用：analysis

id

本次对话id

从外部传入才能做点赞点踩


need_inquiry

本次查询是否需要使用反问功能

default(true)

返回内容

返回SSE对象，前端处理

SSE返回报文样例：

{"role": "SimpleQuery", "response_status": "generating code", "response_message": " \"", "execution_result": "", "send_to": "Unknown", "response_type": "python"}

...

SSE 接口会返回很多条这样的报文；具体原理请自行查询百度。

请手工拼接返回报文 "response_message" 和 "execution_result" 部分内容；response_type 表示当前这条报文的返回内容是啥。


4.3 查询接口（同步）


名称

描述

默认值

接口路径

http://host:port/aiweb/api/v3/conv/query_sync

接口说明

V3版本查询方法 -- 同步方法

header

token

登录key，使用login方法获取；login方法请参考：登录AIChat

接口参数

convId

会话Id

datasetId

数据模型Id

question

用户问题


queryType

查询类型：

  • query（查询模式）

  • analysis（分析模式）

  • expert（专家模式）

建议使用：analysis

id

本次对话id

从外部传入才能做点赞点踩


need_inquiry

本次查询是否需要使用反问功能

default(true)

返回内容

返回查询结果（JSON），前端处理

{

"code": 0,

"result": "[\"[{\\\"年月\\\":\\\"2019-01\\\",\\\"销量\\\":132912,\\\"销量环比增长率\\\":\\\"-6.06%\\\",\\\"_销量占比\\\":\\\"8.8272%\\\"},...]",

"message": null

}

code=0，表示返回正确（result是返回结果）；否则message就是错误提示。


4.4 中断查询


名称

描述

默认值

接口路径

http://host:port/aiweb/api/v3/conv/stop_stream

接口说明

异步query方法情况下，中断当前查询

header

token

登录key，使用login方法获取；login方法请参考：登录AIChat

接口参数

convId

会话Id

返回内容

{

code: 错误码（0 - 表示正确）

message：错误描述

result：方法执行返回结果 -- 服务端无返回则为空

}


4.5 新建查询对话


名称

描述

默认值

接口路径

http://host:port/aiweb/api/v3/conv/new

接口说明

新建查询对话

header

token

登录key，使用login方法获取；login方法请参考：登录AIChat

接口参数

convId

会话Id

返回内容

{

code: 错误码（0 - 表示正确）

message：错误描述

result：方法执行返回结果 -- 服务端无返回则为空

}


4.6 关闭查询对话


名称

描述

默认值

接口路径

http://host:port/aiweb/api/v3/conv/close

接口说明

关闭查询对话 -- 结束本次多轮对话

header

token

登录key，使用login方法获取；login方法请参考：

接口参数

convId

会话Id

返回内容

{

code: 错误码（0 - 表示正确）

message：错误描述

result：方法执行返回结果 -- 服务端无返回则为空

}

4.7 获取本次对话推荐数据模型


名称

描述

默认值

接口路径

http://host:port/aiweb/api/v3/conv/recommend_dataset

接口说明

获取本次对话推荐数据模型

header

token

登录key，使用login方法获取；login方法请参考：登录AIChat

接口参数

convId

会话Id

question

用户提问


datasetId

当前数据模型id


返回内容

{

code: 错误码（0 - 表示正确）

message：错误描述

result：获取推荐的数据模型列表

}


4.8 获取本次对话的详细查询步骤和内容


名称

描述

默认值

接口路径

http://host:port/aiweb/#/testTool?answerid=${id}


GET请求


示例：

http://10.10.35.110:9070/aiweb/#/testTool?answerid=01fc76d5-7ec4-4fad-8216-d4b829ac740c

接口说明

获取本次对话的详细查询步骤和内容


这个基本是前端接口，需要前端js辅助解析的，所以无法直接提供给第三方调用

接口参数

id

本次对话Id

返回内容

查询步骤说明html页面


5.界面集成


名称

描述

默认值

URL路径

/smartbi/vision/AIChatV3.html


GET请求


示例：

http://10.10.35.110:9070/smartbi/vision/AIChatV3.html

集成说明

本地址为bi里面的地址，必须登录bi后再使用。可以跳过登录步骤，直接打开v3的界面

参数

无