aue/AI接口使用规范.md

AI接口使用规范

1. 接口概览

接口路径	方法	功能描述
/ai/chat/stream	POST	AI流式问答，实时返回处理过程
/ai/sessions	GET	获取用户会话列表，支持分页
/ai/session/{sessionId}	GET	获取指定会话的完整交互记录
/ai/message/{messageId}/references	GET	获取指定消息的引用信息
/ai/session/{sessionId}/references	GET	获取指定会话的所有引用信息
/ai/session/{sessionId}	DELETE	删除指定的会话及其相关信息
/ai/sessions	DELETE	批量删除多个会话及其相关信息

2. 认证方式

所有接口均需要在请求头中携带 Authorization 字段，格式为：

Authorization: Bearer {token}

其中 {token} 是用户登录后获取的JWT令牌。

3. 接口详情

3.1 AI流式问答接口

接口路径: /ai/chat/stream 请求方法: POST 功能描述: 向AI服务发起流式问答请求，实时返回处理过程，完成后自动保存到数据库

请求参数:

参数名	类型	必选	描述
message	String	是	用户提问内容
id	String	否	请求ID，用于追踪请求
session_id	String	否	会话ID，若不提供则自动生成

请求示例:

{
  "message": "公司的出差补助标准是什么？",
  "id": "req_123456",
  "session_id": "sess_123456"
}

响应格式: 流式SSE (Server-Sent Events)

响应示例:

event: message
data: {"type":"message","content":"根据公司政策，出差补助标准如下："}

event: message
data: {"type":"message","content":"1. 一线城市：500元/天"}

event: message
data: {"type":"message","content":"2. 二线城市：350元/天"}

event: message
data: {"type":"message","content":"3. 三线城市：250元/天"}

event: complete
data: {"type":"complete","message":"回答完成"}

错误响应:

event: error
data: {"type":"error","message":"用户未登录"}

3.2 获取用户会话列表接口

接口路径: /ai/sessions 请求方法: GET 功能描述: 获取当前登录用户的所有会话列表，按创建时间倒序排列

请求参数:

参数名	类型	必选	默认值	描述
page	Integer	否	1	页码
pageSize	Integer	否	10	每页大小

请求示例:

GET /ai/sessions?page=1&pageSize=10

响应格式:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "sessionId": "sess_123456",
      "userId": 1,
      "summary": "用户询问公司政策相关问题",
      "createTime": "2026-04-21 09:00:00"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 10,
  "pages": 1
}

错误响应:

{
  "success": false,
  "message": "用户未登录"
}

3.3 获取会话详情接口

接口路径: /ai/session/{sessionId} 请求方法: GET 功能描述: 获取指定会话的完整交互记录，包括用户提问与AI回答

请求参数:

参数名	类型	必选	默认值	描述
sessionId	String	是	-	会话ID
page	Integer	否	1	页码
pageSize	Integer	否	20	每页大小

请求示例:

GET /ai/session/sess_123456?page=1&pageSize=20

响应格式:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "conversationId": "sess_123456",
      "role": "user",
      "content": "公司的出差补助标准是什么？",
      "messageType": "text",
      "isFinished": 1,
      "createTime": "2026-04-21 09:00:00"
    },
    {
      "id": 2,
      "conversationId": "sess_123456",
      "role": "assistant",
      "content": "根据公司政策，出差补助标准如下：\n1. 一线城市：500元/天\n2. 二线城市：350元/天\n3. 三线城市：250元/天",
      "messageType": "text",
      "isFinished": 1,
      "createTime": "2026-04-21 09:01:30"
    }
  ],
  "total": 2,
  "page": 1,
  "pageSize": 20,
  "pages": 1
}

错误响应:

{
  "success": false,
  "message": "无权访问该会话"
}

3.4 获取消息引用信息接口

接口路径: /ai/message/{messageId}/references 请求方法: GET 功能描述: 获取指定消息的引用信息，包括文档来源、页码、片段内容等

请求参数:

参数名	类型	必选	描述
messageId	Long	是	消息ID

请求示例:

GET /ai/message/2/references

响应格式:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "messageId": 2,
      "chunkId": "chunk_001",
      "docPath": "uploads/policies/travel_policy.pdf",
      "docName": "出差政策.pdf",
      "page": 10,
      "excerpt": "出差补助标准：一线城市500元/天，二线城市350元/天，三线城市250元/天。此标准适用于所有员工。",
      "createTime": "2026-04-21 09:01:30"
    }
  ],
  "total": 1
}

错误响应:

{
  "success": false,
  "message": "用户未登录"
}

3.5 获取会话引用信息接口

接口路径: /ai/session/{sessionId}/references 请求方法: GET 功能描述: 获取指定会话的所有引用信息，包括文档来源、页码、片段内容等

请求参数:

参数名	类型	必选	描述
sessionId	String	是	会话ID

请求示例:

GET /ai/session/sess_123456/references

响应格式:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "messageId": 2,
      "chunkId": "chunk_001",
      "docPath": "uploads/policies/travel_policy.pdf",
      "docName": "出差政策.pdf",
      "page": 10,
      "excerpt": "出差补助标准：一线城市500元/天，二线城市350元/天，三线城市250元/天。此标准适用于所有员工。",
      "createTime": "2026-04-21 09:01:30"
    }
  ],
  "total": 1
}

错误响应:

{
  "success": false,
  "message": "无权访问该会话"
}

3.6 删除单个会话接口

接口路径: /ai/session/{sessionId} 请求方法: DELETE 功能描述: 删除指定的会话及其所有相关消息和引用信息

请求参数:

参数名	类型	必选	描述
sessionId	String	是	会话ID

请求示例:

DELETE /ai/session/sess_123456

响应格式:

{
  "success": true,
  "message": "会话删除成功"
}

错误响应:

{
  "success": false,
  "message": "无权删除该会话"
}

3.7 批量删除会话接口

接口路径: /ai/sessions 请求方法: DELETE 功能描述: 批量删除多个会话及其所有相关消息和引用信息

请求参数:

参数名	类型	必选	描述
sessionIds	List	是	会话ID列表

请求示例:

[
  "sess_123456",
  "sess_789012"
]

响应格式:

{
  "success": true,
  "message": "会话批量删除成功",
  "deletedCount": 2
}

错误响应:

{
  "success": false,
  "message": "无权删除部分会话"
}

4. 权限控制

1. 用户认证：所有接口均需要有效的JWT令牌
2. 会话访问权限：用户只能访问和删除自己的会话
3. 批量操作验证：批量删除时，所有会话必须都属于当前用户

5. 错误处理

错误类型	状态码	错误信息	说明
未登录	401	用户未登录	缺少有效的Authorization头
无权限	403	无权访问该会话/无权删除该会话	会话不属于当前用户
参数错误	400	会话ID列表不能为空	请求参数不符合要求
服务器错误	500	操作失败: {具体错误信息}	服务器内部错误

6. 最佳实践

1. 会话管理：

   • 每次对话使用相同的session_id以保持上下文
   • 定期清理不需要的会话以节省存储空间

2. 请求优化：

   • 使用分页参数减少返回数据量
   • 合理设置pageSize，避免一次请求过多数据

3. 错误处理：

   • 捕获并处理接口返回的错误信息
   • 对网络异常和超时进行适当处理

4. 安全性：

   • 不要在前端存储敏感的会话信息
   • 定期更新JWT令牌

7. 接口性能

1. 响应时间：

   • 会话列表和详情接口：< 500ms
   • 引用信息接口：< 300ms
   • 删除接口：< 200ms

2. 并发处理：

   • 支持同时处理多个请求
   • 流式接口采用SSE技术，支持长时间连接

3. 数据量限制：

   • 单个会话最多存储1000条消息
   • 批量删除最多支持100个会话

8. 版本控制

版本	变更内容	发布日期
v1.0	初始版本，包含基础AI对话功能	2026-04-25
v1.1	新增会话管理和引用信息接口	2026-04-25

9. 联系支持

• 技术支持：tech-support@example.com
• API文档：https://api.example.com/docs
• 服务状态：https://status.example.com

---

本规范文档由系统自动生成，如有变更请以实际接口为准。