慧眼数据灵犀智算平台 - ai小慧交互接口文档


一、接口概述
本接口文档描述了慧眼数据灵犀智算平台的ai小慧与前端交互的所有接口，包括 HTTP 接口和 WebSocket 接口。


二、HTTP 接口交互接口
2.1 对话历史列表接口
URL：/backend-api/conversation
Method：GET
描述：获取用户的所有对话历史列表，按时间分组展示
请求参数：无
返回示例：
json
{
  "success": true,
  "message": "success",
  "code": 200,
  "result": {
    "dataList": [
      {
        "date": "今天",
        "dataList": [
          {
            "dialogueGroupId": "chat123456",
            "dialogueGroupName": "查询A店铺客流数据"
          }
        ]
      },
      {
        "date": "昨天",
        "dataList": [
          {
            "dialogueGroupId": "chat789012",
            "dialogueGroupName": "北京天气查询"
          }
        ]
      },
      {
        "date": "2025-07",
        "dataList": [
          {
            "dialogueGroupId": "chat345678",
            "dialogueGroupName": "B店铺男女客流分析"
          }
        ]
      }
    ]
  },
  "totalSize": null,
  "timestamp": 1620000000
}
返回说明：
对话按时间分组：今天、昨天、更早（更早的按 "YYYY-MM-DD" 或 "YYYY-MM" 分组）
dialogueGroupId：对话唯一标识
dialogueGroupName：对话标题（由系统自动生成或用户自定义，不超过 20 字）

2.2 聊天页面接口
URL：/chat
Method：GET
描述：返回聊天页面的 HTML 内容
请求参数：无
返回：HTML 页面内容

2.3 对话记录管理接口
2.3.1 对话记录删除接口
URL：/backend-api/conversation
Method：POST
描述：根据对话 ID 删除指定的对话记录
请求参数：
chatid：对话唯一标识（必填，支持查询参数、表单数据或 JSON 数据传递）
action：固定值delete（必填，用于指定操作类型）
请求示例：
json
{
  "chatid": "chat123456",
  "action": "delete"
}
返回示例：
json
{
  "success": true,
  "code": 200,
  "timestamp": 1620000000
}
返回说明：
success: true：删除成功
success: false：删除失败
2.3.2 对话记录重命名接口
URL：/backend-api/conversation
Method：POST
描述：修改指定对话的标题
请求参数：
chatid：对话唯一标识（必填）
action：固定值update（必填）
title：新的对话标题（必填，非空字符串，建议不超过 20 字）
请求示例：
json
{
  "chatid": "chat123456",
  "action": "update",
  "title": "A店铺周末客流分析"
}
返回示例：
json
{
  "success": true,
  "message": "标题更新成功",
  "code": 200,
  "timestamp": 1620000000
}
异常返回示例：
json
{
  "success": false,
  "message": "标题不能为空",
  "code": 400,
  "timestamp": 1620000000
}
功能说明：
标题更新后会同步修改对话历史中的元数据，若对话历史中无元数据，会自动添加一条新的元数据记录存储标题
标题更新后，对话列表接口（/backend-api/conversation GET）返回的标题会同步更新


三、实时聊天 WebSocket 接口
3.1 连接信息
连接地址：ws://{域名}/socket.io
3.2 事件类型
3.2.1 客户端发送事件
事件名称：start_chat
发送数据格式：
json
{
  "user_id": "用户ID",
  "chat_id": "对话ID",
  "message": "用户消息内容"
}
3.2.2 服务端响应事件
事件名称：chat_response
接收数据格式（普通文本回复）：
json
{
  "choices": [
    {
      "delta": {
        "content": "助手回复内容",
        "role": "assistant",
        "type": "text",
        "data": null,
        "params": null
      },
      "finish_reason": "stop"
    }
  ]
}
接收数据格式（客流数据）：
json
{
  "choices": [
    {
      "delta": {
        "content": "客流数据查询结果:",
        "role": "assistant",
        "type": "bar",
        "data": {
          "type": "bar",
          "data": {
            "labels": ["2025-08-01 09", "2025-08-01 10"],
            "datasets": [
              {"label": "进人次", "data": [120, 150]},
              {"label": "出人次", "data": [80, 90]}
            ]
          }
        },
        "params": {
          "name": "A店铺",
          "time": {
            "start_time": "2025-08-01 09:00:00",
            "end_time": "2025-08-01 10:00:00"
          },
          "title": "客流数据柱状图"
        }
      },
      "finish_reason": "tool_response"
    }
  ]
}

3.2.3 服务端错误事件
事件名称：chat_error
错误数据格式：
json
{
  "error": "错误信息描述（如参数错误、查询失败等）"
}

3.3 类型说明
type: text：文本类型，用于普通对话、分析结果、错误提示（天气查询结果固定使用此类型）
type: table：表格类型，用于展示结构化数据
type: line：线性图类型，用于展示趋势数据
type: bar：柱状图类型，用于展示对比数据
type: pie：饼图类型，用于展示占比数据


四、数据格式说明
4.1 时间格式
精确时间：yyyy-MM-dd hh:mm:ss（例如：2025-08-01 09:30:00）
日期：yyyy-MM-dd（例如：2025-08-01）

4.2 图表数据格式
4.2.1 表格（table）
json
[
  ["时间", "进人次", "出人次"],
  ["2025-08-01 09", 120, 80],
  ["2025-08-01 10", 150, 90],
  ["总计", 270, 170]
]
4.2.2 折线图 / 柱状图（line/bar）
json
{
  "type": "bar",
  "data": {
    "labels": ["2025-08-01 09", "2025-08-01 10"],
    "datasets": [
      {"label": "进人次", "data": [120, 150]},
      {"label": "出人次", "data": [80, 90]}
    ]
  }
}
4.2.3 饼图（pie）
json
{
  "type": "pie",
  "data": {
    "datasets": [
      {"label": "总进人次", "data": 270},
      {"label": "总出人次", "data": 170}
    ]
  }
}


六、接口调用说明
删除对话：
前端需先确认用户删除操作（如弹窗提示）
调用时确保chatid正确无误，删除后数据不可恢复
成功删除后，建议前端刷新对话列表展示
重命名对话：
标题长度建议不超过 20 字（与自动生成标题规则保持一致）
需校验标题非空，避免提交空字符串
