UnisKB/监控统计数据API接口文档.md

监控统计数据API接口文档

1. 概述

本文档详细描述了AI-RAG系统中用于获取监控统计数据的API接口，包括对话统计趋势、Token使用统计和热门问题统计等功能。

2. 接口列表

接口名称	URL	方法	功能描述
对话统计趋势	/api/application/{workspace_id}/{application_id}/stats	GET	获取应用的对话相关统计趋势数据
Token使用统计	/api/application/{workspace_id}/{application_id}/stats/token-usage	GET	获取应用的Token使用统计数据
热门问题统计	/api/application/{workspace_id}/{application_id}/stats/top-questions	GET	获取应用的热门问题统计数据

3. 接口详细说明

3.1 对话统计趋势接口

接口信息

• URL: /api/application/{workspace_id}/{application_id}/stats
• 方法: GET
• 认证: Token认证
• 权限: 需要应用概览读取权限

请求参数

参数名	位置	类型	必填	描述
workspace_id	path	string	是	工作空间ID
application_id	path	string	是	应用ID
start_time	query	string	是	开始时间，格式：YYYY-MM-DD
end_time	query	string	是	结束时间，格式：YYYY-MM-DD

响应数据

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "chat_record_count": 10,
      "customer_added_count": 5,
      "customer_num": 100,
      "day": "2025-01-01",
      "star_num": 8,
      "tokens_num": 1000,
      "trample_num": 2
    },
    // 更多日期数据...
  ]
}

字段说明

• chat_record_count: 对话次数
• customer_added_count: 新增用户数
• customer_num: 用户总数
• day: 日期
• star_num: 点赞数
• tokens_num: Tokens消耗
• trample_num: 踩数

3.2 Token使用统计接口

接口信息

• URL: /api/application/{workspace_id}/{application_id}/stats/token-usage
• 方法: GET
• 认证: Token认证
• 权限: 需要应用概览读取权限

请求参数

参数名	位置	类型	必填	描述
workspace_id	path	string	是	工作空间ID
application_id	path	string	是	应用ID
start_time	query	string	是	开始时间，格式：YYYY-MM-DD
end_time	query	string	是	结束时间，格式：YYYY-MM-DD

响应数据

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "chat_user_id": "user123",
      "nick_name": "用户1",
      "tokens_num": 5000
    },
    // 更多用户数据...
  ]
}

字段说明

• chat_user_id: 用户ID
• nick_name: 用户昵称
• tokens_num: 该用户的Token消耗

3.3 热门问题统计接口

接口信息

• URL: /api/application/{workspace_id}/{application_id}/stats/top-questions
• 方法: GET
• 认证: Token认证
• 权限: 需要应用概览读取权限

请求参数

参数名	位置	类型	必填	描述
workspace_id	path	string	是	工作空间ID
application_id	path	string	是	应用ID
start_time	query	string	是	开始时间，格式：YYYY-MM-DD
end_time	query	string	是	结束时间，格式：YYYY-MM-DD

响应数据

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "problem_text": "如何使用MaxKB",
      "count": 50
    },
    // 更多问题数据...
  ]
}

字段说明

• problem_text: 问题文本
• count: 该问题的出现次数

4. 权限说明

所有统计接口都需要以下权限之一：

• 应用概览读取权限
• 工作空间管理角色权限
• 具有应用权限的普通用户角色
• 工作空间管理角色

5. 时间范围说明

• 开始时间和结束时间均为必填参数
• 时间格式必须为 YYYY-MM-DD
• 系统会自动处理时间范围，包括开始日期的 00:00:00 到结束日期的 23:59:59

6. 示例请求

6.1 对话统计趋势示例

curl -X GET "http://localhost:8080/api/application/workspace1/application1/stats?start_time=2025-01-01&end_time=2025-01-31" \
  -H "Authorization: Bearer your_token_here"

6.2 Token使用统计示例

curl -X GET "http://localhost:8080/api/application/workspace1/application1/stats/token-usage?start_time=2025-01-01&end_time=2025-01-31" \
  -H "Authorization: Bearer your_token_here"

6.3 热门问题统计示例

curl -X GET "http://localhost:8080/api/application/workspace1/application1/stats/top-questions?start_time=2025-01-01&end_time=2025-01-31" \
  -H "Authorization: Bearer your_token_here"

7. 错误响应

错误码	描述
401	未授权，Token无效或过期
403	无权限访问该资源
500	应用ID不存在
500	服务器内部错误

8. 数据来源

• 对话统计数据：来自 application_chat_record 表
• 用户统计数据：来自 ApplicationChatUserStats 表
• Token使用数据：来自 application_chat_record 表中的 tokens 字段
• 热门问题数据：来自 application_chat_record 表中的 problem_text 字段

9. Token获取方式

9.1 用户登录获取Token

接口信息

• URL: /api/users/login
• 方法: POST
• 认证: 无需认证

请求参数

参数名	类型	必填	描述
username	string	是	用户名
password	string	是	密码
captcha	string	否	验证码（登录失败次数超过阈值时需要）
encryptedData	string	否	加密数据

响应数据

{
  "code": 200,
  "message": "success",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

9.2 应用访问令牌

系统还支持应用级别的访问令牌，通过ApplicationAccessToken模型生成，用于应用间的API调用。

9.3 Token使用方式

获取token后，在调用其他API接口时，需要在请求头中添加：

Authorization: Bearer your_token_here

10. 注意事项

1. 统计数据可能存在一定的延迟，因为数据收集和处理需要时间
2. 对于较大的时间范围，响应时间可能会较长
3. 建议合理设置时间范围，避免请求过大的数据集
4. 所有接口都需要有效的Token认证
5. Token有过期时间，过期后需要重新获取
6. 登录失败次数过多时，需要输入验证码