主题

AI 对话 ​

AI 对话说明 ​

AI 对话定义 ​

一个用户下面，有很多个对话（conversations），每个对话有很多个回合（chats），每个回合包含用户问题（prompt）、问题之外的衡石对象相关信息（userConfig 和 autoConfig）和 ai 的文本回答（answer）、生成的 chart 等信息。userConfig 由对话的客户端根据用户所在的产品功能点来设置。 后端主要分成 AgentManager 和具体 Agent 两大模块。AgentManager 根据 chat 的 prompt 和 userConfig，判断应该使用哪个 Agent 来执行任务返回结果，并根据需要设置 autoConfig。

数据结构 ​

AgentType ​

状态值意义
SUGGEST_QUESTIONS_AGENT根据 userConfig 中图表信息，生成当前用户适宜的推荐问题
HQL_AGENT根据 userConfig 中数据集信息和用户问题，生成即时查询结果
METRIC_SELECT_AGENT根据 userConfig 中数据集信息和用户问题，生成指标查询结果
PROHIBITED_QUESTION_AGENT用户问题为禁止问的问题，返回固定的回答

ProcessStatus ​

状态值意义
PENDING在等待队列中，所有 agent 类型适用
ANALYZE_REQUEST正在分析请求，所有 agent 类型适用
GENERATE_METRIC_QUERY生成指标查询，只有 METRIC_SELECT_AGENT 适用
DOING_METRIC_QUERY执行指标查询，只有 METRIC_SELECT_AGENT 适用
HQL_SELECT_FIELDS执行即时查询字段选择，只有 HQL_AGENT 适用
HQL_SELECT_FUNCTIONS执行即时查询函数例子选择，只有 HQL_AGENT 适用
GENERATE_HQL_QUERY生成即时查询，只有 HQL_AGENT 适用
DOING_HQL_QUERY执行即时查询，只有 HQL_AGENT 适用
DOING_SUMMARY执行总结，HQL_AGENT 和 METRIC_SELECT_AGENT 适用
DOING_QUESTION_SUGGESTING执行问题推荐，HQL_AGENT 和 METRIC_SELECT_AGENT,SUGGEST_QUESTIONS_AGENT 适用
DONE执行完成，所有 agent 类型适用
FAILED执行失败，所有 agent 类型适用
CANCELLED执行取消，所有 agent 类型适用

Conversation ​

字段类型描述
idINTEGER一个对话的唯一 id
titleSTRING一个对话的标题，默认是对话开头的用户提问
createdAtDATETIME创建的时间
createdByINTEGER创建用户的 id
updatedAtDATETIME最后更新的时间
updatedByINTEGER最后修改用户的 id
isDeleteBOOL后端软删除使用

Chat ​

字段类型描述
conversationIdINTEGERchat 所属对话的 id
uidSTRING一个问答回合的唯一标识
createdAtDATETIME创建的时间
createdByINTEGER创建用户的 id
updatedAtDATETIME最后更新的时间
updatedByINTEGER最后修改用户的 id
responseAtDATETIME最后响应的时间
promptSTRING一个问答回合的用户问题
answerSTRING一个问答回合的 ai 文本回答
chartsOBJECT ARRAY一个问答回合的 ai 生成的 chart，可能有多个
suggestQuestionsSTRING ARRAY一个问答回合的 ai 下一步的推荐问题
isContextEndBOOL是否结束话题切换新话题，计算时忽略本回合和之前的对话内容
statusListSTRING ARRAYProcessStatus 中当前选择的 agent 已经完成的步骤
modelSTRING使用的 ai 模型
temperatureDOUBLE模型的 temperature 设置
userConfigOBJECT用户问题当前所处的衡石对象上下文信息，比如数据集信息
userConfig.appIdINTEGER(不推荐使用)用户问题当前所处的衡石图表对象的应用 id
userConfig.chartIdINTEGER(不推荐使用)用户问题当前所处的衡石图表对象 id，与 userConfig.appId 配对使用以确定具体的图表对象
userConfig.dataAppIdINTEGER(不推荐使用)用户问题当前所处的衡石数据集对象的数据包 id
userConfig.datasetIdINTEGER(不推荐使用)用户问题当前所处的衡石数据集对象的数据集 id，与 userConfig.dataAppId 配对使用以确定具体的数据集对象
userConfig.dataSourcesOBJECT ARRAY用户问题针对的数据源信息，支持多个
userConfig.dataSources[i].dataAppIdINTEGER用户问题针对的数据源信息，跟同级的datasetId搭配使用，表示问题针对的数据集
userConfig.dataSources[i].datasetIdINTEGER用户问题针对的数据源信息，跟同级的dataAppId搭配使用，表示问题针对的数据集
userConfig.dataSources[i].datasetNameINTEGER用户问题针对的数据源信息，表示问题针对的数据集的名字
userConfig.dataSources[i].subjectIdINTEGER用户问题针对的数据源信息，表示问题针对的业务指标主题 id
userConfig.dataSources[i].subjectNameINTEGER用户问题针对的数据源信息，表示问题针对的业务指标主题的名字
autoConfigOBJECTAgentManager 和执行过程自动设置的一些信息，比如选择的 agent 等
autoConfig.agentTypeSTRINGAgentManager 判定应该使用的 agent
likedBOOL赞或者踩
likedMsgSTRING赞或者踩的具体内容
isDeleteBOOL后端软删除使用
isCurrentBOOL在重新回答的回合中，被用户使用的回合是 true，其他回合是 false
parentUidSTRING在重新回答的回合中，第一次回答的 parentUid 是 null，其他次的 parentUid 是第一次回答的 uid
subChatsOBJECT ARRAYChat 对象的数组，有重新回答的情况才有，包括第一次回答和其他次回答的 Chat
usageOBJECT ARRAY本次对话回合调用大模型 api 消耗的 token 情况，每次 api 调用对应一个统计 OBJECT
refineQuestionSTRING大模型根据上下文信息补齐并重新表述的具体的问题
favoriteBOOL是否已经被收藏，true 表示收藏，false 表示没收藏
favoriteAddTimeDATETIME对话回合被收藏的时间
favoriteUseTimeDATETIME对话回合被收藏后最近一次再次使用这个收藏的时间，第一次收藏的时候等于 favoriteAddTime
favoriteSourceSTRING使用收藏的时候会重新生成一个回合，这个时候，新的回合的来源就是被收藏的回合的 uid

ChatLog ​

字段类型描述
uidSTRING一个问答回合的唯一标识
logsOBJECT ARRAY一个问答回合的日志
logs[i].typeSTRING日志类型，包括 ASSISTANT,USER,PROCESS,ERROR
logs[i].contentSTRING日志内容
logs[i].timestampDATETIME日志时间
createdAtDATETIME创建的时间
createdByINTEGER创建用户的 id
updatedAtDATETIME最后更新的时间
updatedByINTEGER最后修改用户的 id

接口设计 ​

创建对话 ​

请求URL ​

http
POST /api/conversations HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数 ​

URL 参数 ​
字段类型是否必须说明
Request Body 参数 ​

见Conversation 结构说明。主要是 title 字段，如果为空，默认生成 Conversation YYYY-mm-DD HH:MM:SS 为对话标题

返回对象的格式说明 ​

字段类型说明
versionSTRING当前系统版本哈希值
dataOBJECT对话信息，包括 id 和标题等
msgSTRINGhttp code 不是200的话，返回具体的错误信息

接口示例: ​

http
POST /api/conversations HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

// Request Body:
{
  "title": "去分析1",
  ...
}
http
HTTP/1.1 200 Ok
Content-Type: application/json

{
  "data": {
    "id":1,
    "title":"去分析1",
    ...
  }
  ...
}

删除对话 ​

请求URL ​

http
DELETE /api/conversations/${conversationId} HTTP/1.1

请求参数 ​

URL 参数 ​
字段类型是否必须说明
conversationIdINTEGER是对话 id
Request Body 参数 ​

返回对象的格式说明 ​

字段类型说明
versionSTRING当前系统版本哈希值
msgSTRINGhttp code 不是200的话，返回具体的错误信息

接口示例: ​

http
DELETE /api/conversations/1 HTTP/1.1
http
HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  ...
}

获取对话列表 ​

请求URL ​

http
GET /api/conversations HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数 ​

URL 参数 ​
字段类型是否必须说明
offsetINTERGER否偏移的值
limitINTERGER否查询的最大个数
orderBySTRING否排序字段名，比如 id，title，createdAt， updatedAt 等
orderTypeSTRING否排序规则，asc 或者 desc
returnChatsBOOL否是否把对话下面的所有回合都获取并放入 chats 字段中一起返回
Request Body 参数 ​

返回对象的格式说明 ​

字段类型说明
versionSTRING当前系统版本哈希值
dataOBJECT ARRAY对话列表
msgSTRINGhttp code 不是200的话，返回具体的错误信息
totalHitsINTEGER所有结果列表总数
offsetINTEGER本次分页结果偏移量

接口示例: ​

http
GET /api/conversations HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...
http
HTTP/1.1 200 Ok
Content-Type: application/json

{
  "data": [
    {
      "id":1,
      "title":"去分析1",
      ...
    },
    ...
  ]
  ...
}

修改对话 ​

请求URL ​

http
PUT /api/conversations/${conversationId} HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数 ​

URL 参数 ​
字段类型是否必须说明
conversationIdINTEGER是对话 id
Request Body 参数 ​

见Conversation 结构说明。主要是 title 字段，用于修改标题

返回对象的格式说明 ​

字段类型说明
versionSTRING当前系统版本哈希值
dataOBJECT对话信息，包括 id 和标题等
msgSTRINGhttp code 不是200的话，返回具体的错误信息

接口示例: ​

http
PUT /api/conversations/1 HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

// Request Body:
{
  "title": "去分析11",
  ...
}
http
HTTP/1.1 200 Ok
Content-Type: application/json

{
  "data": {
    "id":1,
    "title":"去分析11",
    ...
  }
  ...
}

获取一个对话 ​

请求URL ​

http
GET /api/conversations/${conversationId} HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数 ​

URL 参数 ​
字段类型是否必须说明
conversationIdINTEGER是对话 id
Request Body 参数 ​

返回对象的格式说明 ​

字段类型说明
versionSTRING当前系统版本哈希值
dataOBJECT对话信息，包括 id 和标题等
msgSTRINGhttp code 不是200的话，返回具体的错误信息

接口示例: ​

http
GET /api/conversations/1 HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...
http
HTTP/1.1 200 Ok
Content-Type: application/json

{
  "data": {
    "id":1,
    "title":"去分析11",
    ...
  }
  ...
}

创建一个对话下的回合 ​

请求URL ​

http
POST /api/conversations/${conversationId}/chats HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数 ​

URL 参数 ​
字段类型是否必须说明
conversationIdINTEGER是对话 id，如果是专门获取推荐问题，对话内容不展示给用户，用固定的 id 0
syncBOOL否如果为 true，会等待结果然后才返回
timeoutINTEGER否sync 为 true 的时候，表示最大等待时间，默认是60000，也就是1分钟
Request Body 参数 ​

见对话回合 chat 结构说明。主要包括 prompt 和 userConfig，prompt 是用户的本回合对话内容，userConfig 配置当前用户所针对的衡石实体，目前只支持数据集或图表。

返回对象的格式说明 ​

字段类型说明
versionSTRING当前系统版本哈希值
dataOBJECT对话回合信息，包括 uid 和 ai 的回答等信息，详见对话回合 chat 结构说明
msgSTRINGhttp code不是200的话，返回具体的错误信息

接口示例1 创建即时查询对话回合: ​

http
POST /api/conversations/1/chats HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

// Request Body:
{
  "prompt": "每个short_name的最大的latitude是多少？",
  "userConfig":{
    "dataSources": [
      {
        "dataAppId": 130535,
        "datasetId": 2
      }
    ]
  }
}
http
HTTP/1.1 200 Ok
Content-Type: application/json

{
  "data": {
    "conversationId":1,
    "uid": "a6137043-4074-4e00-a2ff-6ece1dbdabbf",
    "createdAt": "2023-12-13 17:26:55",
    "charts": [],
    "answer": "",
    "responseAt": "",
    "prompt": "每个short_name的最大的latitude是多少？",
    "suggestQuestions":[],
    "statusList": ["ANALYZE_REQUEST"],
    "userConfig":{
      "dataSources": [
        {
          "dataAppId": 130535,
          "datasetId": 2
         }
      ]
      },
    "autoConfig":{}
  }
  ...
}

接口示例2 创建图表推荐问题对话回合: ​

http
POST /api/conversations/0/chats HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

// Request Body:
{
  "prompt": "请根据图表字段推荐问题",
  "userConfig":{
    "dataSources": [
      {
        "appId": 130535,
        "chartId": 2
      }
    ]
  }
}
http
HTTP/1.1 200 Ok
Content-Type: application/json

{
  "data": {
    "conversationId": 0,
    "uid": "1814fd1a-cbdd-43eb-83f7-014404241234",
    "createdAt": "2023-11-27 14:21:35",
    "charts": [],
    "answer": "",
    "responseAt": "",
    "prompt": "请根据图表字段推荐问题",
    "suggestQuestions":[],
    "statusList": ["ANALYZE_REQUEST"],
    "userConfig":{
      "dataSources": [
        {
          "appId": 130535,
          "chartId": 2
        }
      ]
      },
    "autoConfig":{}
  }
  ...
}

接口示例3 使用收藏的回合创建新对话回合: ​

http
POST /api/conversations/1/chats HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

// Request Body:
{
  "favoriteSource": "a6137043-4074-4e00-a2ff-6ece1dbdabbf"
}
http
HTTP/1.1 200 Ok
Content-Type: application/json

{
  "data": {
    "conversationId":1,
    "uid": "a7137043-4074-4e00-a2ff-6ece1dbdabbf",
    "createdAt": "2023-12-13 17:26:55",
    "charts": [],
    "answer": "",
    "responseAt": "",
    "prompt": "每个short_name的最大的latitude是多少？",
    "suggestQuestions":[],
    "statusList": ["ANALYZE_REQUEST"],
    "userConfig":{
      "dataSources": [
        {
          "dataAppId": 130535,
          "datasetId": 2
        }
      ]
      },
    "autoConfig":{},
    "favoriteSource": "a6137043-4074-4e00-a2ff-6ece1dbdabbf"
  }
  ...
}

删除一个对话下的一个回合 ​

请求URL ​

http
DELETE /api/conversations/${conversationId}/chats/${uid} HTTP/1.1

请求参数 ​

URL 参数 ​
字段类型是否必须说明
conversationIdINTEGER是对话 id
uidSTRING是对话回合的唯一标识
Request Body 参数 ​

返回对象的格式说明 ​

字段类型说明
versionSTRING当前系统版本哈希值
msgSTRINGhttp code 不是200的话，返回具体的错误信息

接口示例: ​

http
DELETE /api/conversations/1/chats/550e8400-e29b-41d4-a716-446655440000 HTTP/1.1
http
HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  ...
}

删除一个对话下的所有回合 ​

请求URL ​

http
DELETE /api/conversations/${conversationId}/chats HTTP/1.1

请求参数 ​

URL 参数 ​
字段类型是否必须说明
conversationIdINTEGER是对话 id
Request Body 参数 ​

返回对象的格式说明 ​

字段类型说明
versionSTRING当前系统版本哈希值
msgSTRINGhttp code 不是200的话，返回具体的错误信息

接口示例: ​

http
DELETE /api/conversations/1/chats HTTP/1.1
http
HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  ...
}

获取一个对话下的回合列表 ​

请求URL ​

http
GET /api/conversations/${conversationId}/chats HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数 ​

URL 参数 ​
字段类型是否必须说明
conversationIdINTEGER是对话 id
offsetINTERGER否偏移的值
limitINTERGER否查询的最大个数
orderByString否排序字段名，比如 id，title，createdAt， updatedAt 等
orderTypeString否排序规则，asc 或者 desc
Request Body 参数 ​

返回对象的格式说明 ​

字段类型说明
versionSTRING当前系统版本哈希值
dataOBJECT ARRAY对话回合列表
msgSTRINGhttp code 不是200的话，返回具体的错误信息
totalHitsINTEGER所有结果列表总数
offsetINTEGER本次分页结果偏移量

接口示例: ​

http
GET /api/conversations/1/chats HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...
http
HTTP/1.1 200 Ok
Content-Type: application/json

{
  "data": [
    {
      "conversationId":1,
      "uid": "a6137043-4074-4e00-a2ff-6ece1dbdabbf",
      "createdAt": "2023-12-13 17:26:55",
      "charts": [
        {
          "appId": 130535,
          "datasetId": 2,
          "options": {
            "axes": [
              {
                "op": "{{2}}.{short_name}",
                "uid": "uid1",
                "fieldName": "short_name",
                "kind": "formula",
                "datasetId": 2,
                "labelOrigin": "short_name",
                "label": "short_name",
                "isAggregate": false,
                "value": "{{china_map_province1}}.{short_name}",
                "dataset": 2,
                "fieldType": "string"
              },
              {
                "op": "max({{2}}.{latitude})",
                "uid": "uid2",
                "fieldName": "latitude",
                "kind": "formula",
                "datasetId": 2,
                "labelOrigin": "latitude",
                "label": "latitude",
                "isAggregate": true,
                "value": "max({{china_map_province1}}.{latitude})",
                "dataset": 2,
                "fieldType": "number"
              }
            ],
            "limit": 100
          },
          "dataAppId": 130535,
          "datasetIds": [
            2
          ]
        }
      ],
      "answer": "根据提供的数据，我们可以看到每个short_name（这里指的是中国的各个省份、直辖市和特别行政区）对应的最大纬度值。例如，\"内蒙古\"的最大纬度是40.8182330000，\"湖北\"的最大纬度是30.5462220000，\"海南\"的最大纬度是20.0186390000，以此类推。从数据中我们可以看出，纬度最大的是\"黑龙江\"，纬度为45.7422530000，纬度最小的是\"海南\"，纬度为20.0186390000。这些数据可以帮助我们了解中国各地区的地理位置分布。",
      "responseAt": "2023-12-13 17:27:20",
      "prompt": "每个short_name的最大的latitude是多少？",
      "suggestQuestions":["哪个short_name的latitude最大？","哪个short_name的latitude最小？"],
      "statusList": ["ANALYZE_REQUEST","HQL_SELECT_FIELDS","GENERATE_HQL_QUERY","DOING_HQL_QUERY","DOING_SUMMARY","DONE"],
      "userConfig":{
        "dataSources": [
          {
            "dataAppId": 130535,
            "datasetId": 2
          }
        ]
        },
      "autoConfig":{
        "agentType":"HQL_AGENT"
        }
    },
    {
      "conversationId": 1,
      "uid": "1814fd1a-cbdd-43eb-83f7-014404241379",
      "createdAt": "2023-11-27 14:21:35",
      "charts": [
        {
          "appId": 130535,
          "datasetId": 3，
          "options": {
            "axes": [
              {
                "op": "c38",
                "uid": "uid1",
                "fieldName": "c38",
                "kind": "measure",
                "datasetId": 3，
                "labelOrigin": "咨询量",
                "label": "咨询量",
                "isAggregate": true,
                "dataset": 3，
                "fieldType": "number"
              }
            ],
            "limit": 100
          },
          "dataAppId": 130535，
          "datasetIds": [
            3
          ]
        }
      ],
      "answer": "根据你的问题和提供的数据，这个数字369可能代表的是\"服务咨询量\"。这意味着在特定的时间段内，有369次服务咨询的记录。这个指标可以帮助我们了解客户对我们的服务有多大的需求，以及我们的服务是否能满足客户的需求。如果服务咨询量持续增长，那么可能意味着我们的服务有很大的市场需求，或者我们的服务有待改进以更好地满足客户的需求。",
      "responseAt": "2023-11-27 14:22:05",
      "prompt": "服务咨询量",
      "suggestQuestions":["成交量","成交率"],
      "statusList": ["ANALYZE_REQUEST","GENERATE_METRIC_QUERY","DOING_METRIC_QUERY","DOING_SUMMARY","DONE"],
      "userConfig":{
        "dataSources": [
          {
             "dataAppId": 130535,
             "datasetId": 3
           }
        ]
        },
      "autoConfig":{
        "agentType":"METRIC_SELECT_AGENT"
        }
    },
    ...
  ]
  ...
}

修改一个对话下的回合 ​

请求URL ​

http
PUT /api/conversations/${conversationId}/chats/${uid} HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数 ​

URL 参数 ​
字段类型是否必须说明
conversationIdINTEGER是对话 id
uidSTRING是对话回合的唯一标识
Request Body 参数 ​

见Chat 结构说明。主要用于更新 liked，likedMsg，isContextEnd，favorite，分别表示点赞和点踩，具体踩信息，是否结束对话上下文，是否收藏。

返回对象的格式说明 ​

字段类型说明
versionSTRING当前系统版本哈希值
dataOBJECT对话回合信息，参考Chat 结构说明
msgSTRINGhttp code 不是200的话，返回具体的错误信息

接口示例: ​

http
PUT /api/conversations/1/chats/1814fd1a-cbdd-43eb-83f7-014404241379 HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

// Request Body:
{
  "liked": "false",
  "likedMsg":"总结不是很好"
  ...
}
http
HTTP/1.1 200 Ok
Content-Type: application/json

{
  "data": {
    "conversationId": 1,
    "uid": "1814fd1a-cbdd-43eb-83f7-014404241379",
    "createdAt": "2023-11-27 14:21:35",
    "charts": [
      {
        "appId": 130535,
        "datasetId": 3，
        "options": {
          "axes": [
            {
              "op": "c38",
              "uid": "uid1",
              "fieldName": "c38",
              "kind": "measure",
              "datasetId": 3，
              "labelOrigin": "咨询量",
              "label": "咨询量",
              "isAggregate": true,
              "dataset": 3，
              "fieldType": "number"
            }
          ],
          "limit": 100
        },
        "dataAppId": 130535，
        "datasetIds": [
          3
        ]
      }
    ],
    "answer": "根据你的问题和提供的数据，这个数字369可能代表的是\"服务咨询量\"。这意味着在特定的时间段内，有369次服务咨询的记录。这个指标可以帮助我们了解客户对我们的服务有多大的需求，以及我们的服务是否能满足客户的需求。如果服务咨询量持续增长，那么可能意味着我们的服务有很大的市场需求，或者我们的服务有待改进以更好地满足客户的需求。",
    "responseAt": "2023-11-27 14:22:05",
    "prompt": "服务咨询量",
    "suggestQuestions":["成交量","成交率"],
    "statusList": ["ANALYZE_REQUEST","GENERATE_METRIC_QUERY","DOING_METRIC_QUERY","DOING_SUMMARY","DONE"],
    "userConfig":{
      "dataSources": [
        {
          "dataAppId": 130535,
          "datasetId": 3
        }
      ]
      },
    "autoConfig":{
      "agentType":"METRIC_SELECT_AGENT"
      }，
    "liked": "false",
    "likedMsg":"总结不是很好"
  }
  ...
}

获取一个对话下的回合 ​

请求URL ​

http
GET /api/conversations/${conversationId}/chats/${uid} HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数 ​

URL 参数 ​
字段类型是否必须说明
conversationIdINTEGER是对话 id，如果是专门获取推荐问题，对话内容不展示给用户，用固定的 id 0
uidSTRING是对话回合的唯一标识
Request Body 参数 ​

返回对象的格式说明 ​

字段类型说明
versionSTRING当前系统版本哈希值
dataOBJECT对话回合信息，包括状态和结果等，参考Chat 结构说明
msgSTRINGhttp code 不是200的话，返回具体的错误信息

接口示例1 获取即时查询结果: ​

http
GET /api/conversations/1/chats/a6137043-4074-4e00-a2ff-6ece1dbdabbf HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...
http
HTTP/1.1 200 Ok
Content-Type: application/json

{
  "data": {
    "conversationId":1,
    "uid": "a6137043-4074-4e00-a2ff-6ece1dbdabbf",
    "createdAt": "2023-12-13 17:26:55",
    "charts": [
      {
        "appId": 130535,
        "datasetId": 2,
        "options": {
          "axes": [
            {
              "op": "{{2}}.{short_name}",
              "uid": "uid1",
              "fieldName": "short_name",
              "kind": "formula",
              "datasetId": 2,
              "labelOrigin": "short_name",
              "label": "short_name",
              "isAggregate": false,
              "value": "{{china_map_province1}}.{short_name}",
              "dataset": 2,
              "fieldType": "string"
            },
            {
              "op": "max({{2}}.{latitude})",
              "uid": "uid2",
              "fieldName": "latitude",
              "kind": "formula",
              "datasetId": 2,
              "labelOrigin": "latitude",
              "label": "latitude",
              "isAggregate": true,
              "value": "max({{china_map_province1}}.{latitude})",
              "dataset": 2,
              "fieldType": "number"
            }
          ],
          "limit": 100
        },
        "dataAppId": 130535,
        "datasetIds": [
          2
        ]
      }
    ],
    "answer": "根据提供的数据，我们可以看到每个short_name（这里指的是中国的各个省份、直辖市和特别行政区）对应的最大纬度值。例如，\"内蒙古\"的最大纬度是40.8182330000，\"湖北\"的最大纬度是30.5462220000，\"海南\"的最大纬度是20.0186390000，以此类推。从数据中我们可以看出，纬度最大的是\"黑龙江\"，纬度为45.7422530000，纬度最小的是\"海南\"，纬度为20.0186390000。这些数据可以帮助我们了解中国各地区的地理位置分布。",
    "responseAt": "2023-12-13 17:27:20",
    "prompt": "每个short_name的最大的latitude是多少？",
    "suggestQuestions":["哪个short_name的latitude最大？","哪个short_name的latitude最小？"],
    "statusList": ["ANALYZE_REQUEST","HQL_SELECT_FIELDS","GENERATE_HQL_QUERY","DOING_HQL_QUERY","DOING_SUMMARY","DONE"],
    "userConfig":{
      "dataSources": [
        {
          "dataAppId": 130535,
          "datasetId": 2
        }
      ]
      },
    "autoConfig":{
      "agentType":"HQL_AGENT"
      }
  }
  ...
}

接口示例2 获取指标查询结果: ​

http
GET /api/conversations/1/chats/1814fd1a-cbdd-43eb-83f7-014404241379 HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...
http
HTTP/1.1 200 Ok
Content-Type: application/json

{
  "data": {
    "conversationId": 1,
    "uid": "1814fd1a-cbdd-43eb-83f7-014404241379",
    "createdAt": "2023-11-27 14:21:35",
    "charts": [
      {
        "appId": 130535,
        "datasetId": 3，
        "options": {
          "axes": [
            {
              "op": "c38",
              "uid": "uid1",
              "fieldName": "c38",
              "kind": "measure",
              "datasetId": 3，
              "labelOrigin": "咨询量",
              "label": "咨询量",
              "isAggregate": true,
              "dataset": 3，
              "fieldType": "number"
            }
          ],
          "limit": 100
        },
        "dataAppId": 130535，
        "datasetIds": [
          3
        ]
      }
    ],
    "answer": "根据你的问题和提供的数据，这个数字369可能代表的是\"服务咨询量\"。这意味着在特定的时间段内，有369次服务咨询的记录。这个指标可以帮助我们了解客户对我们的服务有多大的需求，以及我们的服务是否能满足客户的需求。如果服务咨询量持续增长，那么可能意味着我们的服务有很大的市场需求，或者我们的服务有待改进以更好地满足客户的需求。",
    "responseAt": "2023-11-27 14:22:05",
    "prompt": "服务咨询量",
    "suggestQuestions":["成交量","成交率"],
    "statusList": ["ANALYZE_REQUEST","GENERATE_METRIC_QUERY","DOING_METRIC_QUERY","DOING_SUMMARY","DONE"],
    "userConfig":{
      "dataSources": [
        {
          "dataAppId": 130535,
          "datasetId": 3
        }
      ]
      },
    "autoConfig":{
      "agentType":"METRIC_SELECT_AGENT"
      }
  }
  ...
}

接口示例3 获取图表推荐问题: ​

http
GET /api/conversations/0/chats/1814fd1a-cbdd-43eb-83f7-014404241234 HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...
http
HTTP/1.1 200 Ok
Content-Type: application/json

{
  "data": {
    "conversationId": 0,
    "uid": "1814fd1a-cbdd-43eb-83f7-014404241234",
    "createdAt": "2023-11-27 14:21:35",
    "charts": [],
    "answer": "",
    "responseAt": "2023-11-27 14:22:05",
    "prompt": "请根据图表字段推荐问题",
    "suggestQuestions":["各省份的经纬度分布情况是怎样的？","哪个short_name的latitude最大？"],
    "statusList": ["ANALYZE_REQUEST","DOING_QUESTION_SUGGESTING","DONE"],
    "userConfig":{
      "dataSources": [
        {
          "appId": 130535,
          "chartId": 2
        }
      ]
      },
    "autoConfig":{
      "agentType":"SUGGEST_QUESTIONS_AGENT"
      }
  }
  ...
}

获取一个对话下的一个回合的执行日志 ​

请求URL ​

http
GET /api/conversations/${conversationId}/chats/${uid}/logs HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数 ​

URL 参数 ​
字段类型是否必须说明
conversationIdINTEGER是对话 id
uidSTRING是对话回合的唯一标识
Request Body 参数 ​

返回对象的格式说明 ​

字段类型说明
versionSTRING当前系统版本哈希值
dataOBJECT ARRAY对话回合的日志信息，参考ChatLog 结构说明下的 logs 字段
msgSTRINGhttp code 不是200的话，返回具体的错误信息

接口示例: ​

http
GET /api/conversations/1/chats/a6137043-4074-4e00-a2ff-6ece1dbdabbf/logs HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...
http
HTTP/1.1 200 Ok
Content-Type: application/json

{
  "data": [
  {
    "type": "PROCESS",
    "content": "begin to prepare base info",
    "timestamp": "2023-12-13 17:26:55"
  },
  {
    "type": "PROCESS",
    "content": "llm chain build completed:[ContextLLM, HQLLLM, VisualizeLLM, SummaryLLM]",
    "timestamp": "2023-12-13 17:26:55"
  },
  {
    "type": "PROCESS",
    "content": "LLM ContextLLM begin to analyze",
    "timestamp": "2023-12-13 17:26:55"
  },
  {
    "type": "PROCESS",
    "content": "ai answer [{\"datasetId\":2,\"fields\":[\"short_name\",\"latitude\"],\"computation_fields\":[\"latitude\"]}]",
    "timestamp": "2023-12-13 17:26:57"
  },
  {
    "type": "PROCESS",
    "content": "chat answer validateResult is true with message {\"value\":\"[{\\\"datasetId\\\":2,\\\"fields\\\":[\\\"short_name\\\",\\\"latitude\\\"],\\\"computation_fields\\\":[\\\"latitude\\\"]}]\"}",
    "timestamp": "2023-12-13 17:26:57"
  },
  {
    "type": "ASSISTANT",
    "content": "[{\"datasetId\":2,\"fields\":[\"short_name\",\"latitude\"],\"computation_fields\":[\"latitude\"]}]",
    "timestamp": "2023-12-13 17:26:57"
  },
  {
    "type": "PROCESS",
    "content": "LLM HQLLLM begin to analyze",
    "timestamp": "2023-12-13 17:26:57"
  },
  {
    "type": "PROCESS",
    "content": "ai answer {\"axes\":[{\"op\":\"{short_name}\",\"uid\":\"uid1\"},{\"op\":\"max({latitude})\",\"uid\":\"uid2\"}]}",
    "timestamp": "2023-12-13 17:27:08"
  },
  {
    "type": "PROCESS",
    "content": "LLM VisualizeLLM begin to analyze",
    "timestamp": "2023-12-13 17:27:09"
  },
  {
    "type": "PROCESS",
    "content": "LLM SummaryLLM begin to analyze",
    "timestamp": "2023-12-13 17:27:09"
  },
  {
    "type": "PROCESS",
    "content": "ai answer 根据提供的数据，我们可以看到每个short_name（这里指的是中国的各个省份、直辖市和特别行政区）对应的最大纬度值。例如，\"内蒙古\"的最大纬度是40.8182330000，\"湖北\"的最大纬度是30.5462220000，\"海南\"的最大纬度是20.0186390000，以此类推。从数据中我们可以看出，纬度最大的是\"黑龙江\"，纬度为45.7422530000，纬度最小的是\"海南\"，纬度为20.0186390000。这些数据可以帮助我们了解中国各地区的地理位置分布。",
    "timestamp": "2023-12-13 17:27:20"
  }
  ]
  ...
}

让ai重新回答一个对话下的一个回合 ​

请求URL ​

http
GET /api/conversations/${conversationId}/chats/${uid}/regenerate HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数 ​

URL 参数 ​
字段类型是否必须说明
conversationIdINTEGER是对话 id
uidSTRING是对话回合的唯一标识
Request Body 参数 ​

返回对象的格式说明 ​

字段类型说明
versionSTRING当前系统版本哈希值
dataSTRING回合 uid
msgSTRINGhttp code 不是200的话，返回具体的错误信息

接口示例: ​

http
GET /api/conversations/1/chats/a6137043-4074-4e00-a2ff-6ece1dbdabbf/regenerate HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...
http
HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  "code": 0,
  "msg": "success",
  "data": "a6137043-4074-4e00-a2ff-6ece1dbdabbf",
  "chartDataStartTimeMillis": 0
}

设置一个对话下的回合的多次运行结果为选定答案 ​

请求URL ​

http
POST /api/conversations/${conversationId}/chats/${uid}/is-current HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数 ​

URL 参数 ​
字段类型是否必须说明
conversationIdINTEGER是对话 id，如果是专门获取推荐问题，对话内容不展示给用户，用固定的 id 0
uidSTRING是对话回合的唯一标识
Request Body 参数 ​

为空就行

返回对象的格式说明 ​

字段类型说明
versionSTRING当前系统版本哈希值
dataOBJECT对话回合信息，包括 uid 和 ai 的回答等信息，详见对话回合 chat 结构说明
msgSTRINGhttp code 不是200的话，返回具体的错误信息

接口示例: ​

http
POST /api/conversations/1/chats/a6137043-4074-4e00-a2ff-6ece1dbdabbf/is-current HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

// Request Body:
{
}
http
HTTP/1.1 200 Ok
Content-Type: application/json

{
  "data": {
    "conversationId":1,
    "uid": "a6137043-4074-4e00-a2ff-6ece1dbdabbf",
    "isCurrent": true,
    "createdAt": "2023-12-13 17:26:55",
    "charts": [],
    "answer": "",
    "responseAt": "",
    "prompt": "每个short_name的最大的latitude是多少？",
    "suggestQuestions":[],
    "statusList": ["ANALYZE_REQUEST"],
    "userConfig":{
      "dataSources": [
        {
          "dataAppId": 130535,
          "datasetId": 2
        }
      ]
      },
    "autoConfig":{}
  }
  ...
}

根据一个对话下的回合及其上下文补齐并重新表述生成具体的问题 ​

请求URL ​

http
POST  /api/conversations/${conversationId}/chats/refine-question HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数 ​

URL 参数 ​
字段类型是否必须说明
conversationIdINTEGER是对话 id
Request Body 参数 ​

见对话回合 chat 结构说明。主要包括 prompt 和 userConfig，prompt 是用户的本回合对话内容，userConfig 配置当前用户所针对的衡石实体，目前只支持数据集或图表。

返回对象的格式说明 ​

字段类型说明
versionSTRING当前系统版本哈希值
dataOBJECT包括优化后问题和执行日志
data.refineQuestionSTRING重新表述生成具体的问题
data.logsOBJECT ARRAY执行优化过程的日志，参考ChatLog 结构说明下的 logs 字段
msgSTRINGhttp code不是200的话，返回具体的错误信息

接口示例 ​

假设上一个问题问了今年的销售额，并获取了结果。

http
POST /api/conversations/1/chats/refine-question HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

// Request Body:
{
  "prompt": "去年的呢？",
  "userConfig":{
    "dataSources": [
      {
        "dataAppId": 130535,
        "datasetId": 2
      }
    ]
  }
}
http
HTTP/1.1 200 Ok
Content-Type: application/json

{
  "data":{
    "refineQuestion":"去年的销售额呢？",
    "logs":[]
  },
  ...
}

对话回合搜索接口 ​

请求URL ​

http
GET /api/conversations/search-chats HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数 ​

URL 参数 ​
字段类型是否必须说明
favoriteBOOL否true 或者 false 表示搜索收藏过的或者没收藏过的
dataAppIdINTERGER否要查询的数据源所属的数据包 id
datasetIdINTERGER否要查询的数据集 id
qSTRING否搜索 prompt 条件
offsetINTERGER否偏移的值
limitINTERGER否查询的最大个数
orderBySTRING否排序字段名，比如 id，title，createdAt，updatedAt，favoriteUseTime 等
orderTypeSTRING否排序规则，asc 或者 desc
Request Body 参数 ​

返回对象的格式说明 ​

字段类型说明
versionSTRING当前系统版本哈希值
dataOBJECT ARRAY对话回合列表
msgSTRINGhttp code 不是200的话，返回具体的错误信息
totalHitsINTEGER所有结果列表总数
offsetINTEGER本次分页结果偏移量

接口示例1 根据数据源获取相关的对话回合: ​

http
GET /api/conversations/search-chats?favorite=true&dataAppId=1&datasetId=1&offset=0&limit=10&orderBy=favoriteUseTime&orderType=desc HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...
http
HTTP/1.1 200 Ok
Content-Type: application/json

{
  "data": [
    {
      "conversationId":1,
      "uid": "a6137043-4074-4e00-a2ff-6ece1dbdabbf",
      "createdAt": "2023-12-13 17:26:55",
      "charts": [
        {
          "appId": 130535,
          "datasetId": 2,
          "options": {
            "axes": [
              {
                "op": "{{2}}.{short_name}",
                "uid": "uid1",
                "fieldName": "short_name",
                "kind": "formula",
                "datasetId": 2,
                "labelOrigin": "short_name",
                "label": "short_name",
                "isAggregate": false,
                "value": "{{china_map_province1}}.{short_name}",
                "dataset": 2,
                "fieldType": "string"
              },
              {
                "op": "max({{2}}.{latitude})",
                "uid": "uid2",
                "fieldName": "latitude",
                "kind": "formula",
                "datasetId": 2,
                "labelOrigin": "latitude",
                "label": "latitude",
                "isAggregate": true,
                "value": "max({{china_map_province1}}.{latitude})",
                "dataset": 2,
                "fieldType": "number"
              }
            ],
            "limit": 100
          },
          "dataAppId": 130535,
          "datasetIds": [
            2
          ]
        }
      ],
      "answer": "根据提供的数据，我们可以看到每个short_name（这里指的是中国的各个省份、直辖市和特别行政区）对应的最大纬度值。例如，\"内蒙古\"的最大纬度是40.8182330000，\"湖北\"的最大纬度是30.5462220000，\"海南\"的最大纬度是20.0186390000，以此类推。从数据中我们可以看出，纬度最大的是\"黑龙江\"，纬度为45.7422530000，纬度最小的是\"海南\"，纬度为20.0186390000。这些数据可以帮助我们了解中国各地区的地理位置分布。",
      "responseAt": "2023-12-13 17:27:20",
      "prompt": "每个short_name的最大的latitude是多少？",
      "suggestQuestions":["哪个short_name的latitude最大？","哪个short_name的latitude最小？"],
      "statusList": ["ANALYZE_REQUEST","HQL_SELECT_FIELDS","GENERATE_HQL_QUERY","DOING_HQL_QUERY","DOING_SUMMARY","DONE"],
      "userConfig":{
        "dataSources": [
          {
            "dataAppId": 130535,
            "datasetId": 2
          }
        ]
        },
      "autoConfig":{
        "agentType":"HQL_AGENT"
        },
        "favorite":true,
        "favoriteUseTime": "2023-12-13 18:27:20"
    },
    {
      "conversationId": 1,
      "uid": "1814fd1a-cbdd-43eb-83f7-014404241379",
      "createdAt": "2023-11-27 14:21:35",
      "charts": [
        {
          "appId": 130535,
          "datasetId": 3，
          "options": {
            "axes": [
              {
                "op": "c38",
                "uid": "uid1",
                "fieldName": "c38",
                "kind": "measure",
                "datasetId": 3，
                "labelOrigin": "咨询量",
                "label": "咨询量",
                "isAggregate": true,
                "dataset": 3，
                "fieldType": "number"
              }
            ],
            "limit": 100
          },
          "dataAppId": 130535，
          "datasetIds": [
            3
          ]
        }
      ],
      "answer": "根据你的问题和提供的数据，这个数字369可能代表的是\"服务咨询量\"。这意味着在特定的时间段内，有369次服务咨询的记录。这个指标可以帮助我们了解客户对我们的服务有多大的需求，以及我们的服务是否能满足客户的需求。如果服务咨询量持续增长，那么可能意味着我们的服务有很大的市场需求，或者我们的服务有待改进以更好地满足客户的需求。",
      "responseAt": "2023-11-27 14:22:05",
      "prompt": "服务咨询量",
      "suggestQuestions":["成交量","成交率"],
      "statusList": ["ANALYZE_REQUEST","GENERATE_METRIC_QUERY","DOING_METRIC_QUERY","DOING_SUMMARY","DONE"],
      "userConfig":{
        "dataSources": [
          {
            "dataAppId": 130535,
            "datasetId": 3
          }
        ]
        },
      "autoConfig":{
        "agentType":"METRIC_SELECT_AGENT"
        },
        "favorite":true,
        "favoriteUseTime": "2023-11-27 15:22:05"
    },
    ...
  ]
  ...
}

异步导出对话回合PNG/PDF ​

请求URL ​

http
GET /api/conversations/{conversationId}/chats/{uid}/async-export HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数 ​

URL 参数 ​
字段类型是否必须说明
conversationIdINTEGER是对话 id
uidSTRING是对话回合的唯一标识
typeSTRING否传png或者pdf，默认png
timeoutINTEGER否导出超时时间，单位毫秒，默认是550000，timeout内完成，直接返回二进制流下载，timeout未完成或出现异常，返回json信息，0表示等待到完成为止，相当于变成同步导出
widthINTEGER是必填， 渲染宽度
heightINTEGER否可选填，指定图表渲染的高度，默认是 width 的 四分之三
metaSTRING否可选填，'question', 'refineQuestion', 'answer', 'chart', 'chartConfig' ,五个字符串的任意组合，以逗号(',')分割，默认是 'chart'
requestIdSTRING是请求id，在异步导出的时候，需要根据这个请求id来轮询
Request Body 参数 ​

返回对象的格式说明 ​

如果导出任务没有完成，返回PENDING状态；若任务已完成，返回png/pdf格式文件流下载，文件名是用户问题

接口示例1: 导出对话回合png ​

http
GET /api/conversations/1/chats/a6137043-4074-4e00-a2ff-6ece1dbdabbf/async-export?type=png&timeout=0&width=400&requestId=rq1234 HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

轮询导出对话回合PNG/PDF ​

请求URL ​

http
GET /api/conversations/{conversationId}/chats/{uid}/poll-export HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数 ​

URL 参数 ​
字段类型是否必须说明
originRequestIdSTRING是异步导出时的requestId，所以要求必须先请求 async-export，并且该请求还没返回结果，这个时候才需要调用本接口
Request Body 参数 ​

返回对象的格式说明 ​

如果导出任务没有完成，返回PENDING状态；若任务已完成，返回png/pdf格式文件流下载，文件名是用户问题

接口示例1: 轮询对话回合png ​

http
GET /api/conversations/1/chats/a6137043-4074-4e00-a2ff-6ece1dbdabbf/poll-export?originRequestId=rq1234 HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

从用户问题到获得数据的完整API调用例子 ​

下面的例子没用使用真实的认证信息，API调用的认证方式请参考文档来使用： https://api.hengshi.com/v5.3/client_credentials.html

1. 新建对话 ​

http
POST https://ai.hengshi.com/api/conversations?requestId=01J7357BP9WPKD7JQA62Q0MAJX HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

// Request Body:
{
  "title":"测试对话1"
}
http
HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "5.3-SNAPSHOT@d0554f2#dace9f3",
  "code": 0,
  "msg": "success",
  "data": {
    "id": 172,
    "title": "测试对话1",
    "createdBy": 844,
    "createdAt": "2024-09-06 16:00:18",
    "updatedBy": 844,
    "updatedAt": "2024-09-06 16:00:18"
  },
  "chartDataStartTimeMillis": 0
}

可以获得对话id为172，实际使用时，可以根据需要复用已有的对话或者新建对话。

2. 对话下新建对话回合 ​

对话回合会返回文本的回答和具体的图表对象

http
POST https://ai.hengshi.com/api/conversations/172/chats?requestId=01J7357BRK334EFMJX4148S2PP&sync=true&timeout=60000 HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

// Request Body:
{
  "prompt":"广东省能量饮料各品牌排名",
  "userConfig":{
    "dataSources": [
      {
        "dataAppId":2938,
        "datasetName":"商品销售信息表",
        "datasetId":3
      }
    ]
  }
}
http
HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "5.3-SNAPSHOT@d0554f2#dace9f3",
  "code": 0,
  "msg": "success",
  "data": {
    "conversationId": 172,
    "prompt": "广东省能量饮料各品牌排名",
    "answer": "广东省能量饮料各品牌排名为：\n\n1. 东鹏特饮\n2. 红牛(华彬)\n3. 红牛(天丝)\n4. NA\n5. 魔爪",
    "model": "gpt-4o",
    "uid": "61e761e7-227f-4066-80b9-4ef81b65bda2",
    "temperature": 0.0,
    "createdBy": 844,
    "createdAt": "2024-09-06 16:14:26",
    "updatedBy": 844,
    "updatedAt": "2024-09-06 16:14:26",
    "responseAt": "2024-09-06 16:14:42",
    "isDelete": false,
    "isContextEnd": false,
    "suggestQuestions": [
      "请帮我查找指 标 总销售额",
      "每个 一级类目 的 销量 总和是多少？",
      "每个 省份 的 折算销量 总和占比是多少？"
    ],
    "statusList": [
      "PENDING",
      "ANALYZE_REQUEST",
      "HQL_SELECT_FIELDS",
      "HQL_SELECT_FUNCTIONS",
      "GENERATE_HQL_QUERY",
      "DOING_HQL_QUERY",
      "DOING_SUMMARY",
      "DOING_QUESTION_SUGGESTING",
      "DONE"
    ],
    "userConfig": {
      "dataSources": [
        {
          "datasetName": "商品销售信息表",
          "datasetId": 3,
          "dataAppId": 2938
        }
      ]
    },
    "autoConfig": {
      "agentType": "HQL_AGENT"
    },
    "isCurrent": true,
    "usage": [
      {
        "completion_tokens": 128,
        "prompt_tokens": 2152,
        "total_tokens": 2280
      }
    ],
    "chartCreatedAt": "2024-09-06 16:14:38",
    "refineQuestion": "广东省能量饮料各品牌排名",
    "favorite": false,
    "charts": [
      {
        "appId": 2938,
        "datasetId": 3,
        "options": {
          "axes": [
            {
              "op": "{{3}}.{brand_name}",
              "uid": "uid1",
              "fieldName": "brand_name",
              "sourceInfoList": [
                {
                  "targetIdString": "{{3}}.{brand_name}",
                  "sourceString": "{{3}}.{品牌}",
                  "sourceIndex": [
                    0,
                    0
                  ]
                }
              ],
              "kind": "formula",
              "datasetId": 3,
              "labelOrigin": "品牌",
              "label": "品牌",
              "isAggregate": false,
              "value": "{{3}}.{品牌}",
              "dataset": 3,
              "fieldType": "string"
            },
            {
              "op": "{{3}}.{province_name}",
              "uid": "uid2",
              "fieldName": "province_name",
              "sourceInfoList": [
                {
                  "targetIdString": "{{3}}.{province_name}",
                  "sourceString": "{{3}}.{省份}",
                  "sourceIndex": [
                    0,
                    0
                  ]
                }
              ],
              "kind": "formula",
              "datasetId": 3,
              "labelOrigin": "省份",
              "label": "省份",
              "isAggregate": false,
              "value": "{{3}}.{省份}",
              "dataset": 3,
              "fieldType": "string"
            },
            {
              "op": "{{3}}.{cls_4}",
              "uid": "uid3",
              "fieldName": "cls_4",
              "sourceInfoList": [
                {
                  "targetIdString": "{{3}}.{cls_4}",
                  "sourceString": "{{3}}.{四级类目}",
                  "sourceIndex": [
                    0,
                    0
                  ]
                }
              ],
              "kind": "formula",
              "datasetId": 3,
              "labelOrigin": "四级类目",
              "label": "四级类目",
              "isAggregate": false,
              "value": "{{3}}.{四级类目}",
              "dataset": 3,
              "fieldType": "string"
            },
            {
              "op": "{{3}}.{c0}",
              "uid": "uid4",
              "fieldName": "c0",
              "sourceInfoList": [
                {
                  "targetIdString": "{{3}}.{c0}",
                  "sourceString": "{销售额}",
                  "sourceIndex": [
                    0,
                    0
                  ]
                }
              ],
              "kind": "formula",
              "datasetId": 3,
              "labelOrigin": "销售额",
              "label": "销售额",
              "isAggregate": true,
              "value": "{销售额}",
              "dataset": 3,
              "fieldType": "number"
            },
            {
              "op": "calculate(rank() OVER (PARTITION BY {{3}}.{province_name}, {{3}}.{cls_4} ORDER BY {{3}}.{c0} DESC))",
              "uid": "uid5",
              "fieldName": "province_name",
              "sourceInfoList": [
                {
                  "targetIdString": "{{3}}.{province_name}",
                  "sourceString": "{{3}}.{省份}",
                  "sourceIndex": [
                    35
                  ]
                },
                {
                  "targetIdString": "{{3}}.{cls_4}",
                  "sourceString": "{{3}}.{四级类目}",
                  "sourceIndex": [
                    46
                  ]
                },
                {
                  "targetIdString": "{{3}}.{c0}",
                  "sourceString": "{销售额}",
                  "sourceIndex": [
                    68
                  ]
                }
              ],
              "kind": "formula",
              "datasetId": 3,
              "labelOrigin": "省份",
              "label": "广东省能量饮料品牌排名",
              "isAggregate": true,
              "value": "calculate(rank() over(partition by {{3}}.{省份},{{3}}.{四级类目} order by {销售额} desc))",
              "dataset": 3,
              "fieldType": "string"
            }
          ],
          "name": "Table",
          "limit": 100,
          "where": [
            {
              "op": "{{3}}.{province_name} = '广东省'",
              "fieldName": "province_name",
              "sourceInfoList": [
                {
                  "targetIdString": "{{3}}.{province_name}",
                  "sourceString": "{{3}}.{省份}",
                  "sourceIndex": [
                    0
                  ]
                }
              ],
              "kind": "formula",
              "datasetId": 3,
              "labelOrigin": "省份",
              "label": "省份",
              "value": "{{3}}.{省份}='广东省'",
              "dataset": 3,
              "fieldType": "string"
            },
            {
              "op": "{{3}}.{cls_4} = '能量饮料'",
              "fieldName": "cls_4",
              "sourceInfoList": [
                {
                  "targetIdString": "{{3}}.{cls_4}",
                  "sourceString": "{{3}}.{四级类目}",
                  "sourceIndex": [
                    0
                  ]
                }
              ],
              "kind": "formula",
              "datasetId": 3,
              "labelOrigin": "四级类目",
              "label": "四级类目",
              "value": "{{3}}.{四级类目}='能量饮料'",
              "dataset": 3,
              "fieldType": "string"
            }
          ],
          "sort": [
            {
              "op": "uid5",
              "kind": "reference",
              "direction": "asc"
            },
            {
              "op": "uid1",
              "kind": "reference",
              "direction": "asc"
            },
            {
              "op": "uid2",
              "kind": "reference",
              "direction": "asc"
            },
            {
              "op": "uid3",
              "kind": "reference",
              "direction": "asc"
            },
            {
              "op": "uid4",
              "kind": "reference",
              "direction": "asc"
            }
          ]
        },
        "dataAppId": 2938,
        "datasetIds": [
          3
        ]
      }
    ]
  },
  "chartDataStartTimeMillis": 0
}

其中 data.charts[0] 是一个图表对象，可以通过调用图表接口获取数据：https://api.hengshi.com/v5.3/chart.html#在应用内使用自定义图表配置获取图表数据

3. 根据图表对象获取数据 ​

其中appId是图表对象中的appId字段值，body就是整个图表对象。返回json中，data.data是一行行数据，每行数据的表头对应post的图表对象的options.axes[i].label

http
POST 'https://ai.hengshi.com/api/apps/2938/chart-data' HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

// Request Body:
{
  "appId": 2938,
  "datasetId": 3,
  "options": {
    "axes": [
      {
        "op": "{{3}}.{brand_name}",
        "uid": "uid1",
        "fieldName": "brand_name",
        "sourceInfoList": [
          {
            "targetIdString": "{{3}}.{brand_name}",
            "sourceString": "{{3}}.{品牌}",
            "sourceIndex": [
              0,
              0
            ]
          }
        ],
        "kind": "formula",
        "datasetId": 3,
        "labelOrigin": "品牌",
        "label": "品牌",
        "isAggregate": false,
        "value": "{{3}}.{品牌}",
        "dataset": 3,
        "fieldType": "string"
      },
      {
        "op": "{{3}}.{province_name}",
        "uid": "uid2",
        "fieldName": "province_name",
        "sourceInfoList": [
          {
            "targetIdString": "{{3}}.{province_name}",
            "sourceString": "{{3}}.{省份}",
            "sourceIndex": [
              0,
              0
            ]
          }
        ],
        "kind": "formula",
        "datasetId": 3,
        "labelOrigin": "省份",
        "label": "省份",
        "isAggregate": false,
        "value": "{{3}}.{省份}",
        "dataset": 3,
        "fieldType": "string"
      },
      {
        "op": "{{3}}.{cls_4}",
        "uid": "uid3",
        "fieldName": "cls_4",
        "sourceInfoList": [
          {
            "targetIdString": "{{3}}.{cls_4}",
            "sourceString": "{{3}}.{四级类目}",
            "sourceIndex": [
              0,
              0
            ]
          }
        ],
        "kind": "formula",
        "datasetId": 3,
        "labelOrigin": "四级类目",
        "label": "四级类目",
        "isAggregate": false,
        "value": "{{3}}.{四级类目}",
        "dataset": 3,
        "fieldType": "string"
      },
      {
        "op": "{{3}}.{c0}",
        "uid": "uid4",
        "fieldName": "c0",
        "sourceInfoList": [
          {
            "targetIdString": "{{3}}.{c0}",
            "sourceString": "{销售额}",
            "sourceIndex": [
              0,
              0
            ]
          }
        ],
        "kind": "formula",
        "datasetId": 3,
        "labelOrigin": "销售额",
        "label": "销售额",
        "isAggregate": true,
        "value": "{销售额}",
        "dataset": 3,
        "fieldType": "number"
      },
      {
        "op": "calculate(rank() OVER (PARTITION BY {{3}}.{province_name}, {{3}}.{cls_4} ORDER BY {{3}}.{c0} DESC))",
        "uid": "uid5",
        "fieldName": "province_name",
        "sourceInfoList": [
          {
            "targetIdString": "{{3}}.{province_name}",
            "sourceString": "{{3}}.{省份}",
            "sourceIndex": [
              35
            ]
          },
          {
            "targetIdString": "{{3}}.{cls_4}",
            "sourceString": "{{3}}.{四级类目}",
            "sourceIndex": [
              46
            ]
          },
          {
            "targetIdString": "{{3}}.{c0}",
            "sourceString": "{销售额}",
            "sourceIndex": [
              68
            ]
          }
        ],
        "kind": "formula",
        "datasetId": 3,
        "labelOrigin": "省份",
        "label": "广东省能量饮料品牌排名",
        "isAggregate": true,
        "value": "calculate(rank() over(partition by {{3}}.{省份},{{3}}.{四级类目} order by {销售额} desc))",
        "dataset": 3,
        "fieldType": "string"
      }
    ],
    "name": "Table",
    "limit": 100,
    "where": [
      {
        "op": "{{3}}.{province_name} = '广东省'",
        "fieldName": "province_name",
        "sourceInfoList": [
          {
            "targetIdString": "{{3}}.{province_name}",
            "sourceString": "{{3}}.{省份}",
            "sourceIndex": [
              0
            ]
          }
        ],
        "kind": "formula",
        "datasetId": 3,
        "labelOrigin": "省份",
        "label": "省份",
        "value": "{{3}}.{省份}='广东省'",
        "dataset": 3,
        "fieldType": "string"
      },
      {
        "op": "{{3}}.{cls_4} = '能量饮料'",
        "fieldName": "cls_4",
        "sourceInfoList": [
          {
            "targetIdString": "{{3}}.{cls_4}",
            "sourceString": "{{3}}.{四级类目}",
            "sourceIndex": [
              0
            ]
          }
        ],
        "kind": "formula",
        "datasetId": 3,
        "labelOrigin": "四级类目",
        "label": "四级类目",
        "value": "{{3}}.{四级类目}='能量饮料'",
        "dataset": 3,
        "fieldType": "string"
      }
    ],
    "sort": [
      {
        "op": "uid5",
        "kind": "reference",
        "direction": "asc"
      },
      {
        "op": "uid1",
        "kind": "reference",
        "direction": "asc"
      },
      {
        "op": "uid2",
        "kind": "reference",
        "direction": "asc"
      },
      {
        "op": "uid3",
        "kind": "reference",
        "direction": "asc"
      },
      {
        "op": "uid4",
        "kind": "reference",
        "direction": "asc"
      }
    ]
  },
  "dataAppId": 2938,
  "datasetIds": [
    3
  ]
}
http
HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "5.3-SNAPSHOT@d0554f2#dace9f3",
  "code": 0,
  "msg": "success",
  "data": {
    "data": [
      [
        "东鹏特饮",
        "广东省",
        "能量饮料",
        0.561721205652720,
        1
      ],
      [
        "红牛(华彬)",
        "广东省",
        "能量饮料",
        0.323624519820257,
        2
      ],
      [
        "红牛(天丝)",
        "广东省",
        "能量饮料",
        0.070889082390944,
        3
      ],
      [
        "NA",
        "广东省",
        "能量饮料",
        0.011996121692754,
        4
      ],
      [
        "魔爪",
        "广东省",
        "能量饮料",
        0.008819958034765,
        5
      ]
    ],
    "pagable": true,
    "importSwitchable": true,
    "schema": [
      {
        "fieldName": "uid1",
        "visible": true,
        "config": {},
        "type": "string",
        "hideValue": false,
        "suggestedTypes": [
          "string"
        ],
        "defaultAggrType": "count",
        "basicType": "string"
      },
      {
        "fieldName": "uid2",
        "visible": true,
        "config": {},
        "type": "string",
        "hideValue": false,
        "suggestedTypes": [
          "string"
        ],
        "defaultAggrType": "count",
        "basicType": "string"
      },
      {
        "fieldName": "uid3",
        "visible": true,
        "config": {},
        "type": "string",
        "hideValue": false,
        "suggestedTypes": [
          "string"
        ],
        "defaultAggrType": "count",
        "basicType": "string"
      },
      {
        "fieldName": "uid4",
        "visible": true,
        "config": {},
        "type": "number",
        "hideValue": false,
        "suggestedTypes": [
          "number"
        ],
        "defaultAggrType": "sum",
        "basicType": "number"
      },
      {
        "fieldName": "uid5",
        "visible": true,
        "config": {
          "dialectName": "HologresDialect"
        },
        "type": "number",
        "hideValue": false,
        "suggestedTypes": [
          "number"
        ],
        "defaultAggrType": "sum",
        "basicType": "number"
      }
    ],
    "validFilterUids": [],
    "lastQueryTime": "2024-09-06T16:14:37.706471"
  },
  "chartDataStartTimeMillis": 0
}

HENGSHI SENSE API 使用手册

版权所有 © 2016-2025 hengshi.com