1. 需求背景与适用场景

1.1 需求背景

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

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

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

1.2 适用场景

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

觉得Smartbi内置的对话界面不好看，可以使用Smartbi扩展包机制重新开发使用界面
需要将对话嵌入到集团内部APP中，可以定制Android/IOS原生界面，或者嵌入自定义H5页面
需要嵌入到其他的Web平台中，可以定制H5页面
需要嵌入其聊天工具中（如：钉钉、微信等），可以定制符合聊天工具要求的页面
其他使用场景，可以咨询Smartbi客服团队，获取支持

2. 逻辑架构

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

说明：

用户自定义界面，可以脱离Smartbi，嵌入在第三方平台里面，包括：
- 第三方Web应用
- 第三方Android应用
- 第三方IOS应用

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

3. API说明

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

3.1 登录AIChat

通过账号密码登陆AIChat

3.1.1 接口说明

名称	值
请求地址	http://smartbi-AIChat-server:port/aiweb/api/v1/login
请求方式	POST
请求参数	userName password smartbiServer casLoginUrl loginMethod

3.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": "" }

3.1.3 接口返回值说明

返回参数名	返回值说明
code	接口调用是否成功；0 - 表示成功；负数为错误码
message	错误描述，code=0 时，该内容为空
token	登录方法特有内容，这个非常重要，后续接口需要传递该值以验证登录
result	调用接口的返回内容，登录接口的返回内容说明如下： "userId": "", Smartbi中的用户Id "userName": "", Smartbi中的用户名 "userAlias": "", Smartbi中的用户中文名 "isAdmin": 在Smartbi中是否是管理员

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

3.2 查询数据模型清单、推荐问句

3.2.1 接口说明

名称	值
请求地址	http://smartbi-AIChat-server:port/aiweb/integration/api/v1/get_using_theme
请求方式	POST
请求参数	token

3.2.2 接口参数说明

URL参数名

说明

是否必填

输入参数

token

登陆AIChat返回获得的token

必填

返回值

{

"code": 0,

"result": [

{

"id": "I8a80818c0191262b262b26b0019126c8d71a****",

"name": "****NLA-绩效考核-20240806",

"title": "****NLA-绩效考核-20240806",

"desc": "**证券NLA-绩效考核-20240806包含了年月、年、指标名称、指标口径、指标大类、指标负责人、指标细类、分支机构考核类别、所属考核组织类型、分支机构分组等字段",

"type": "augmentedDataset",

"recommendQuestion": [

"每年指标名称排名",

"每年得分",

"近5年指标名称得分",

"排名按年份排序，线图显示",

"排名的合计"

],

"lastBuildTime": "2024/08/09 16:11:00"

}

],

"message": null,

"token": "717261E64AEC5D904AA2410D127BFB27"

}

3.2.3 接口返回说明

返回参数名	返回值说明
code	接口调用是否成功；大于等于0 - 表示成功；负数为错误码
message	错误描述，code=0 时，该内容为空
token	登录方法特有内容，这个非常重要，后续接口需要传递该值以验证登录
result	调用接口的返回内容，登录接口的返回内容说明如下： "id": 数据模型themeID "name": 数据模型名称 "title": 数据模型名称别名 "desc"：数据模型概览 "type": 数据类型 "recommendQuestion": 推荐问句 "lastBuildTime": 最近构建时间 ... 其他返回值可以忽略

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

3.3 维度指标树-详细版

3.3.1 接口说明

名称	值
请求地址	http://smartbi-AIChat-server:port/aiweb/integration/api/v1/get_theme_tree
请求方式	POST
请求参数	token themeId type

3.3.2 接口参数说明

	URL参数名	说明	是否必填
输入参数	token	登陆AIChat两种方式返回获得的token	必填
	themeId	数据模型ID	必填
	type	传入参数值：augmentedDataset	必填
返回值	{ "code": 0, "result": [ { "id": "MEASURE", "parentId": null, "path": "/度量", "value": "MEASURE", "label": "度量", "dataType": "MEASURE_FOLDER", "fieldType": null, "timeLevel": null, "hasChild": "true", "defaultCheck": "false", "children": [ ] } ] }, { "id": "DIMENSION", "parentId": null, "path": "/维度", "value": "DIMENSION", "label": "维度", "dataType": "DIMENSION_FOLDER", "fieldType": null, "timeLevel": null, "hasChild": "true", "defaultCheck": "false", "children": [ ] } ] } ], "message": null, "token": "A381D523DD9C96754C2F40BA6365542F" }

3.3.3 接口返回说明

返回参数名	返回值说明
code	接口调用是否成功；大于等于0 - 表示成功；负数为错误码
message	错误描述，code=0 时，该内容为空
token	登录方法特有内容，这个非常重要，后续接口需要传递该值以验证登录
result	调用接口的返回内容，登录接口的返回内容说明如下： "id": 维度或者度量 "children": 对应id下得维度/指标信息，数组得形式存储 ... 其他返回值可以忽略

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

3.4 维度指标树-精简版、推荐问句

3.4.1 接口说明

名称	值
请求地址	http://smartbi-AIChat-server:port/aiweb/integration/api/v1/get_data_set_info_summary
请求方式	POST
请求参数	token themeId

3.4.2 接口参数说明

	URL参数名	说明	是否必填
输入参数	token	登陆AIChat返回获得的token	必填
输入参数	themeId	数据模型ID	必填
返回值	{ "code": 0, "result": { "id": "I8a8085ba0190fa36fa36ed470191065c84e70006", "name": "证券NLA-考核-20240731", "alias": "证券NLA-考核-20240731", "dimensions": { "考核日期维度": [ "年月", "年" ], "分支机构维": [ "所属考核组织类型", "所属分公司代码（考核）", "分公司名称", "所属分公司名称（考核）", "分组", "分支机构代码（实际）", "分支机构代码（考核）", "分支机构级别", "分支机构名称（实际）", "分支机构名称（考核）" ], "绩效考核指标": [ "c_rank" ], "指标信息维": [ "指标名称", "指标口径", "指标负责人", "指标细类" ] }, "measures": { "绩效考核指标": [ "排名", "得分", "完成值新", "完成值" ] }, "recommendQuestions": null }, "message": null, "token": "A381D523DD9C96754C2F40BA6365542F" }

3.4.3 接口返回说明

返回参数名	返回值说明
code	接口调用是否成功；大于等于0 - 表示成功；负数为错误码
message	错误描述，code=0 时，该内容为空
token	登录方法特有内容，这个非常重要，后续接口需要传递该值以验证登录
result	调用接口的返回内容，登录接口的返回内容说明如下： "id": 数据模型themeID "name": 数据模型名称 "alias": 数据模型名称别名 "dimensions" NLA模型中所有维度 "measures" NLA模型中所有度量 "recommendQuestions" 推荐问句 ... 其他返回值可以忽略

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

3.5 执行查询

3.5.1 接口说明

名称	值
请求地址	http://smartbi-AIChat-server:port/aiweb/integration/api/v1/query
请求方式	POST
请求参数	token txt themeId chartType

3.5.2 接口参数说明

	URL参数名	说明	是否必填
输入参数	token	AIChat登陆方法返回的token	必填
	txt	用户的查询问句，比如：今年的合同额	必填
	themeId	Smartbi数据模型Id	必填
	chartType	图形类型；默认使用系统选项中定义的图形类型	选填
返回值	{ "code": 0, "result": { "currentRows": "", "currentPage": "", "rowsPerPage": "", "portletType":"", "html":"", "nl2sql":"", "llm":"", ... }, "message": "", "token": "" }

3.5.3 接口返回值说明

返回参数名	返回值说明
code	接口调用是否成功；大于等于0 - 表示成功；负数为错误码
message	错误描述，code=0 时，该内容为空
token	登录方法特有内容，这个非常重要，后续接口需要传递该值以验证登录
result	调用接口的返回内容，登录接口的返回内容说明如下： "currentRows": 当前页行数 "currentPage": 当前页码 "rowsPerPage": 每页行数 "portletType"：显示类型（表格、图形等） "html": 如果是表格，为html，如果是图形为Echarts Options "nl2sql": 查询定义 "llm": 是否大模型接口 ... 其他返回值可以忽略

3.5.4 PortletType说明

中文名	PortletType / chartType
汇总表	TABLE_LIST
清单表	TABLE_DETAIL_LIST
交叉表	TABLE_CROSS
柱图	ECHARTS_BAR
横条图	ECHARTS_BAR__HORIZONTAL
线图	ECHARTS_LINE
饼图	ECHARTS_PIE
圆环图	ECHARTS_PIE__DONUT
散点图	ECHARTS_SCATTER
泡泡图	ECHARTS_SCATTER__BUBBLE

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

【表格返回】

【图形返回】

3.6 点赞点踩

3.6.1 接口说明

名称	值
请求地址	http://smartbi-AIChat-server:port/aiweb/integration/api/v1/feedback
请求方式	POST
请求参数	tag uuid feedbackText token

3.6.2 接口参数说明

	URL参数名	说明	是否必填
输入参数	tag	1-为正确，0-为错误	必填
	uuid	query接口查询的问句返回的uuid唯一标识	必填
	feedbackText	人工输入，反馈内容	必填
	token	AIChat登陆方法返回的token	必填
返回值	{ "code": 0, "result": null, "message": null, "token": "A381D523DD9C96754C2F40BA6365542F" }

接口调用成功后，会将点赞点踩相关信息写入AIChat的数据库服务中对应表中：

3.6.3 接口返回说明

返回参数名	返回值说明
code	接口调用是否成功；大于等于0 - 表示成功；负数为错误码
message	错误描述，code=0 时，该内容为空
token	登录方法特有内容，这个非常重要，后续接口需要传递该值以验证登录

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

3.7 切换图形

3.7.1 接口说明

名称	值
请求地址	http://smartbi-AIChat-server:port/aiweb/integration/api/v1/query_with_nl2sql
请求方式	POST
请求参数	table nl2sql chartType token

3.7.2 接口参数说明

	URL参数名	说明	是否必填
输入参数	table	数据模型themeId	必填
	nl2sql	query接口查询的问句返回的nl2sql的value值；注：需要将value值中转义符\剔除	必填
	chartType	执行查询接口中附注的PortletType值；举例：ECHARTS_BAR	必填
	token	AIChat登陆方法返回的token	必填
返回值	{ "code": 0, "result": { "intentionType": null, "queryRecordIndex": null, "multiRecordSessionId": null, "uuid": null, "rowsCount": 0, "currentRows": 0, "currentPage": 0, "rowsPerPage": 50, "headers": null, "values": null, "realValues": null, "warnings": null, "html": "{"yAxis":{"fieldFormat":{"date":"","prefix":"","name":"<整型-默认值>","viewType":"TNUMBER","scale":1.0,"time":"","type":"INTEGER","suffix":"","decimal":0},"axisLabel":{"show":true},"type":"value"},"xAxis":{"fieldFormat":{"date":"","prefix":"","name":"<字符串-默认值>","viewType":"NONE","scale":1.0,"time":"","type":"STRING","suffix":"","decimal":0},"axisLabel":{"show":true},"data":["沪世纪"],"type":"category"},"color":["rgba(149,162,255,1)","rgba(250,128,128,1)","rgba(60,185,252,1)","rgba(255,192,118,1)","rgba(250,231,104,1)","rgba(135,232,133,1)","rgba(115,171,245,1)","rgba(203,155,255,1)","rgba(67,67,72,1)","rgba(144,237,125,1)","rgba(247,163,92,1)","rgba(128,133,233,1)"],"advanced":{"rowNotEmpty":true},"series":[{"fieldFormat":{"date":"","prefix":"","name":"<整型-默认值>","viewType":"TNUMBER","scale":1.0,"time":"","type":"INTEGER","suffix":"","decimal":0},"groupName":"GLOBAL_MARK","data":[{"displayValue":["沪世纪","813"],"tooltipInfo":[{"realValue":"沪世纪","fieldGroupType":"cols","realValueString":"沪世纪","label":"分支机构名称（考核）","value":"沪世纪","uniqueId":"8c4e629e045a44e3b3a79d69b34aafd2"},{"realValue":813,"fieldGroupType":"rows","realValueString":"813","label":"排名","value":"813","uniqueId":"3cfa25d8e1a74b7da592a7860c6efcda"}],"colIndex":1,"rowIndex":[0,0],"value":[0,813]}],"name":"排名","type":"bar","markLine":{"symbol":"none"},"yAxisIndex":0}],"tooltip":{"trigger":"item"},"seriesConfig":{"global":{"stack":false,"step":false,"smooth":false}},"chartEx":{"clasifyName":[{"data":"排名"}],"drillableFields":[],"outputRows":1000}}", "nl2sql": null, "nl2sqlDuration": 0, "nl2mdx": null, "portletType": "ECHARTS_BAR", "queryType": "PageQuery", "clientId": "fd768e86c2ff43a4ae663da42f38066b", "combinedQueryClientId": null, "question": null, "themeId": "I8a8085ba0190fa36fa36ed470191065c84e70006", "intentionParams": null, "resultTips": null, "interActionItems": null, "processing": null, "pageBO": null, "subTable": null, "llmReviseQuestion": null, "measureDescriptions": null, "nl2sqlStatus": null, "nl2sqlRecommendInfo": null, "intentionRecommendInfo": null, "jsonResult": null, "gptMql": null, "prompt": null, "llm": false, "num": false }, "message": null, "token": "717261E64AEC5D904AA2410D127BFB27" }

3.7.3 接口返回说明

返回参数名	返回值说明
code	接口调用是否成功；大于等于0 - 表示成功；负数为错误码
message	错误描述，code=0 时，该内容为空
token	登录方法特有内容，这个非常重要，后续接口需要传递该值以验证登录
result	调用接口的返回内容，登录接口的返回内容说明如下： "html": 切换后的图表的html "portletType": 切换后的图标的类型 ... 其他返回值可以忽略

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

3.8 查询结果设置输出行数

3.8.1 接口说明

名称	值
请求地址	http://smartbi-AIChat-server:port/aiweb/integration/api/v1/set_rows_per_page
请求方式	POST
请求参数	token clientId pageSize dataSource queryType

3.8.2 接口参数说明

	URL参数名	说明	是否必填
输入参数	token	login 方法返回的token	必填
	clientId	用户的查询问句的clientId（可以从执行查询接口获取）	必填
	pageSize	设置每页输出大小	必填
	dataSource	数据来源，通常固定为smartbiproxy	必填
	queryType	用户的查询问句的queryType（可以从执行查询接口获取）	必填
返回值	{ "code": 0, "result": "", "message": "", "token": "" }

3.8.3 接口返回值说明

返回参数名	返回值说明
code	接口调用是否成功；0 - 表示成功；负数为错误码
message	错误描述，code=0 时，该内容为空
token	登录方法特有内容，这个非常重要，后续接口需要传递该值以验证登录
result	调用接口的返回内容

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

3.9 查询结果分页

3.9.1 接口说明

名称	值
请求地址	http://smartbi-AIChat-server:port/aiweb/integration/api/v1/query_with_page
请求方式	POST
请求参数	token clientId page dataSource queryType

3.9.2 接口参数说明

	URL参数名	说明	是否必填
输入参数	token	login 方法返回的token	必填
	clientId	用户的查询问句的clientId（可以从执行查询接口获取）	必填
	page	设置翻页，第几页	必填
	dataSource	数据来源，通常固定为smartbiproxy	必填
	queryType	用户的查询问句的queryType（可以从执行查询接口获取）	必填
返回值	{ "code": 0, "result": { "intentionType": "", "queryRecordIndex": "", "multiRecordSessionId": "", "uuid": "", "rowsCount":"", "currentRows":"", "currentPage":"", "rowsPerPage":"", ... }, "message": "", "token": "" }

3.9.3 接口返回值说明

返回参数名	返回值说明
code	接口调用是否成功；0 - 表示成功；负数为错误码
message	错误描述，code=0 时，该内容为空
token	登录方法特有内容，这个非常重要，后续接口需要传递该值以验证登录
result	调用接口的返回内容，登录接口的返回内容说明如下： "currentRows": 当前页行数 "currentPage": 当前页码 "rowsPerPage": 每页行数 "portletType"：显示类型（表格、图形等） "html": 如果是表格，为html，如果是图形为Echarts Options "nl2sql": 查询定义 "llm": 是否大模型接口 ...

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

3.10 清除对话历史（开启新对话）

Smartbi AIChat 是可以启用“多轮对话”和“单轮对话”的，具体操作方法在系统选项中配置，这里不详细描述。在启用多轮对话的时候，有时需要清空对话历史（也就是开启新的对话）。开启新对话需要使用该API实现。

3.10.1 接口说明

名称	值
请求地址	http://smartbi-AIChat-server:port/aiweb/integration/api/v1/close_query
请求方式	POST
请求参数	token

3.10.2 接口参数说明

URL参数名

说明

是否必填

输入参数

token

login 方法返回的token

必填

返回值

{

"code": 0,

"result": null,

"message": "",

"token": ""

}

3.10.3 接口返回值说明

返回参数名	返回值说明
code	接口调用是否成功；0 - 表示成功；负数为错误码
message	错误描述，code=0 时，该内容为空
token	登录方法特有内容，这个非常重要
result	空

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

3.11 页面集成

3.11.1 页面集成方式一

名称

值

请求地址

http://smartbi-AIChat-server:port/smartbi/vision/AIChatView2.html?question=今年各城市销量&userName=admin&password=admin

参数说明

question：问句，可以选填

userName：用户名

password：密码

请求URL：http://smartbi-AIChat-server:port/smartbi/vision/AIChatView2.html?userName=admin&password=admin

3.11.2 页面集成方式二

名称

值