1. 需求背景与适用场景
1.1 需求背景
Smartbi AIChat 提供了多种使用方式,供用户自由选择。如果常用PC端,我们有基于PC浏览器的AIWeb页面;如果常用手机,我们有基于手机的App或者使用手机浏览器访问的AIChatView页面;我们还提供了基于钉钉、企微、飞书等IM的使用页面。但是,这些都是AIChat平台内置页面,页面样式和操作方式是基于产品内置好的。如果要把AIChat集成到客户自己的APP里,或者集成到其他平台中,Smartbi AIChat内置页面样式可能不符合要求。 为了让客户在使用AIChat的时候可以自定义前端页面,我们提供了 Restfull API 接口。本文主要就是介绍如何使用 AIChat 接口实现客户自己的前端页面。
1.2 适用场景
使用Smartbi AIChat 提供的API适合以下应用场景的开发:
- 觉得Smartbi AIChat内置对话界面不好看,可以使用Smartbi扩展包机制重新开发使用界面。
- 需要将对话嵌入到集团内部APP中,可以定制Android/IOS原生界面,或者嵌入自定义H5页面。
- 需要嵌入到其他的Web平台中,可以定制H5页面。
- 需要嵌入其聊天工具中(如钉钉、企业微信、飞书等),可以定制符合聊天工具要求的页面。
- 其他使用场景,可以咨询Smartbi客服团队,获取支持。
2. 技术架构
用户自定义对话界面的逻辑架构图如下。
- 用户自定义界面,可以脱离Smartbi AIChat,嵌入在第三方平台里面,包括:
- 第三方Web应用。
- 第三方Android应用。
- 第三方IOS应用。
- 如果第三方系统也是Web页面,推荐使用Smartbi扩展包方式开发集成页面,这样可以避免跨域问题。如果需要在第三方非Web应用中开发,需要对所有API做服务端转发。
3. 界面集成
可以把 Smartbi AIChat 对话界面,整体集成嵌入到第三方系统中。
值 | |
---|---|
URL路径 | /smartbi/vision/AIChatV3.html GET请求 示例:http://10.10.35.110:9070/smartbi/vision/AIChatV3.html |
集成说明 | 本地址必须登录后再使用。可以跳过登录步骤,直接打开v3的界面。 |
参数 | 无 |
4. API 接口说明
AIChat 提供的是标准 Restfull API 接口,登录后直接调用就可以了,在最简单情况下只需要两步就可以完成需要的操作。
示例代码请参考: DemoCodeDemoCode 、 示例程序下载
4.1 登录AIChat
- 接口说明
名称 | 值 |
---|---|
请求地址 | |
请求方式 | POST |
请求参数 | userName password smartbiServer casLoginUrl loginMethod |
- 接口参数说明
URL参数名 | 说明 | 是否必填 | |
---|---|---|---|
输入参数 | userName | 登录账号 | 必填 |
password | 登录密码 | 必填 | |
smartbiServer | Smartbi服务器地址。该AIChat服务器第一次登录Smartbi,必填;以后选填;不填则使用之前已经登录过的Smartbi服务器。 | 选填 | |
casLoginUrl | 如果Smartbi是使用CAS登录方式,则需要填入该值;该AIChat服务器第一次登录Smartbi,必填;以后选填;不填则使用之前已经登录过的CAS认证服务器。 | 选填 | |
loginMethod | 使用的登录方法,枚举值。普通登录使用login;如果是CAS登录则使用loginWithCas,默认情况下都可以不填。
| 选填 | |
返回值 | { |
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 | 查询类型:
| 建议使用: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 | 查询类型:
| 建议使用: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/#/testTool2?answerid=01fc76d5-7ec4-4fad-8216-d4b829ac740c | ||
接口说明 | 获取本次对话的详细查询步骤和内容 这个基本是前端接口,需要前端js辅助解析的,所以无法直接提供给第三方调用 | ||
接口参数 | id | 本次对话Id | |
返回内容 | 查询步骤说明html页面 |
4.9 获取当前用户可以使用的数据模型列表
名称 | 描述 | 默认值 | |
接口路径 | http://host:port/aiweb/proxy/aibus/get_using_themes | ||
接口说明 | 获取当前用户可以使用的数据模型列表 | ||
header | token | 登录key,使用login方法获取;login方法请参考:登录AIChat | |
接口参数 | |||
返回内容 | { code: 错误码(0 - 表示正确) message:错误描述 result:[{ "id": 数据模型themeID }]} |
4.10 获取当前用户会话历史
名称 | 描述 | 默认值 | |
接口路径 | http://host:port/aiweb/proxy/admin/v3/db/conv/get_list_by_user | ||
接口说明 | 获取当前用户可以使用的数据模型列表 | ||
header | token | 登录key,使用login方法获取;login方法请参考:登录AIChat | |
接口参数 | userName | 当前用户名 | |
返回内容 | { code: 错误码(0 - 表示正确) message:错误描述 result:[{ _id: 对话Id (convId), name: 对话名称, endTime: 对话结束时间(时间戳 – long) }]} |
4.11 打开对话历史
名称 | 描述 | 默认值 | |
接口路径 | http://host:port/aiweb/proxy/admin/v3/db/conv/get_by_convid | ||
接口说明 | 获取当前用户可以使用的数据模型列表 | ||
header | token | 登录key,使用login方法获取;login方法请参考:登录AIChat | |
接口参数 | convId | 会话Id | |
返回内容 | { code: 错误码(0 - 表示正确) message:错误描述 result:[{ id: 消息Id convId: 会话Id, name: 对话名称, answer:消息返回报文 – 主要是解析这个内容 beginTime:消息开始时间 endTime: 消息结束时间(时间戳 – long) ... }]} |
4.12 删除对话历史
名称 | 描述 | 默认值 | |
接口路径 | http://host:port/aiweb/proxy/admin/v3/db/conv/remove_by_convid | ||
接口说明 | 获取当前用户可以使用的数据模型列表 | ||
header | token | 登录key,使用login方法获取;login方法请参考:登录AIChat | |
接口参数 | convId | 会话Id | |
返回内容 | { code: 错误码(0 - 表示正确) message:错误描述 result:"" } |