guxz/aue
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0910ba9cbe5c1969014f4be5f988b22f48bbfa73
aue/AI接口规范文档.md
guxz 0910ba9cbe 前端项目初始化提交
2026-06-03 13:16:30 +08:00

10 KiB
Raw Blame History

AI接口规范文档

1. 接口概览

接口路径 方法 功能描述
/ai/chat/stream POST AI流式问答，实时返回处理过程
/ai/chat/stop 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流式问答接口

接口路径: /ai/chat/stop 请求方法: POST 功能描述: 中断指定会话的AI流式问答进程，用于用户主动取消正在进行的AI回答

请求参数:

参数名 类型 必选 描述
sessionId String 是 要中断的会话ID

请求示例:

POST /ai/chat/stop?sessionId=sess_123456

响应格式:

// 成功
{
  "success": true,
  "message": "已中断AI回答"
}

// 失败（进程不存在或已结束）
{
  "success": false,
  "message": "未找到活跃的AI进程或已结束"
}

// 错误响应
{
  "success": false,
  "message": "用户未登录"
}

中断后SSE事件: 当中断成功时，前端会收到一个特殊的stop事件：

event: stop
data: {"type":"stopped","message":"用户主动中断"}

使用场景:

  • 用户等待AI回答时间过长，想取消当前问题
  • 用户问错问题了，想重新提问
  • AI回答跑偏了，想中断重新组织语言

3.3 获取用户会话列表接口

接口路径: /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": 1,
      "role": "assistant",
      "content": "公司的出差补助标准是什么？",
      "answer": "根据公司政策，出差补助标准如下：\n1. 一线城市：500元/天\n2. 二线城市：350元/天\n3. 三线城市：250元/天",
      "messageType": "text",
      "isFinished": 1,
      "kbPaths": "[\"public_kb\"]",
      "durationMs": 1250,
      "createTime": "2026-04-21 09:01:30"
    }
  ],
  "total": 1,
  "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. 联系支持

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

Reference in New Issue View Git Blame Copy Permalink