AiController（AI 对话/RAG）¶

cn.myapps.ai.controller.AiController —— AI 模块的对话主控制器，基于 LangChain4j 提供带 RAG 召回与系统提示词的聊天、聊天历史查询、聊天记忆清除、健康检查等能力。

Tag：AI 服务
基址：${myapps.context-path.ai:}/api（缺省 context-path /ai，故完整前缀常为 /ai/api）
鉴权：否（obpm-ai 无鉴权过滤器，详见 index.md「鉴权说明」）
响应：直接返回 ResponseEntity<Map<String, Object>> / ResponseEntity<List<ChatMessageDto>>，非统一 Resource（见 index.md「响应结构与错误码」）

路径前缀说明：下文「请求路径」一律写出 <context-path> + /api + <相对路径> 的完整形式；<context-path> 部署时由 ${myapps.context-path.ai:} 解析（独立部署缺省为 /ai，lite 统一打包下为空，此时由部署侧前缀 /ai 区分模块）。

1. 发送聊天消息（RAG 增强）¶

携带 RAG 召回与系统提示词发送一条消息给 AI，返回回复文本。disk_id 未传时，若部署集成了 KMS 则按当前登录态自动解析可访问网盘，否则返回 400。

接口类型：REST 资源
请求方式：POST
请求路径：<context-path>/api/chat（完整：${myapps.context-path.ai:}/api/chat）
鉴权：否（业务层在 disk_id 未传且未登录时返回 401，详见下文）
Tag：AI 服务

请求体¶

JSON 对象（application/json）：

字段	类型	必填	说明
message	string	是	用户消息内容，不能为空
memoryId	string	否	会话记忆 ID，缺省 `"user_123"`
topK	int	否	RAG 召回 top-k，缺省 `10`
systemPromptId	long	否	系统提示词 ID，缺省不使用
disk_id	string	否	RAG 检索的网盘 ID（可多个英文逗号分隔）；未传且集成 KMS 时按当前登录态自动解析

请求示例¶

POST /ai/api/chat HTTP/1.1
Content-Type: application/json

{
  "message": "如何配置数据源？",
  "memoryId": "user_123",
  "topK": 10,
  "systemPromptId": 1,
  "disk_id": "disk-001,disk-002"
}

响应¶

结构：ResponseEntity<Map<String, Object>>，非统一 Resource。

data：

字段	类型	说明
response	string	AI 回复文本
memoryId	string	本次会话使用的记忆 ID
topK	int	实际使用的 top-k
systemPromptId	long/null	实际使用的系统提示词 ID
mode	string	固定 `"RAG"`

成功示例（HTTP 200）：

{
  "response": "您可以在「应用管理 > 数据源」中...",
  "memoryId": "user_123",
  "topK": 10,
  "systemPromptId": 1,
  "mode": "RAG"
}

失败示例：

HTTP 400（消息为空 / disk_id 未传且未集成 KMS / 业务异常）：{ "error": "消息不能为空" }
HTTP 401（disk_id 未传、已集成 KMS 但未登录或身份校验失败）：{ "error": "未登录或无法校验身份，请携带 token 后重试，或显式传 disk_id" }
HTTP 500（解析可访问网盘异常）：{ "error": "无法解析可访问的 KMS 网盘: <异常消息>" }

2. 获取聊天历史（默认记忆 ID）¶

获取默认记忆 ID（"user_123"）的聊天历史。等价于 3. 获取聊天历史（指定记忆 ID）。

接口类型：REST 资源
请求方式：GET
请求路径：<context-path>/api/history
鉴权：否
Tag：AI 服务

请求参数¶

无。

请求示例¶

GET /ai/api/history HTTP/1.1

响应¶

结构：ResponseEntity<List<ChatMessageDto>>，数组元素结构见 3. 获取聊天历史（指定记忆 ID）。

3. 获取聊天历史（指定记忆 ID）¶

按指定记忆 ID 获取聊天历史，返回 LangChain4j 序列化后的消息列表。

接口类型：REST 资源
请求方式：GET
请求路径：<context-path>/api/history/{memoryId}（完整：${myapps.context-path.ai:}/api/history/{memoryId}）
鉴权：否
Tag：AI 服务

路径变量¶

变量	类型	必填	说明
memoryId	string	是	会话记忆 ID

请求示例¶

GET /ai/api/history/user_123 HTTP/1.1

响应¶

结构：ResponseEntity<List<ChatMessageDto>>，非统一 Resource。

data：JSON 数组，元素结构：

字段	类型	说明
role	string	角色：`"user"` / `"assistant"` / `"unknown"`
content	string	LangChain4j `ChatMessageSerializer.messageToJson` 序列化后的消息 JSON 字符串

成功示例（HTTP 200）：

[
  { "role": "user", "content": "{\"type\":\"user-message\",\"text\":\"如何配置数据源？\"}" },
  { "role": "assistant", "content": "{\"type\":\"ai-message\",\"text\":\"您可以在...\"}" }
]

4. 清除聊天记忆（默认记忆 ID）¶

清除默认记忆 ID（"user_123"）的聊天记忆。等价于 5. 清除聊天记忆（指定记忆 ID）。

接口类型：REST 资源
请求方式：DELETE
请求路径：<context-path>/api/memory
鉴权：否
Tag：AI 服务

请求参数¶

无。

请求示例¶

DELETE /ai/api/memory HTTP/1.1

响应¶

结构：ResponseEntity<Map<String, String>>，详见 5. 清除聊天记忆（指定记忆 ID）。

5. 清除聊天记忆（指定记忆 ID）¶

按指定记忆 ID 清除聊天记忆。

接口类型：REST 资源
请求方式：DELETE
请求路径：<context-path>/api/memory/{memoryId}（完整：${myapps.context-path.ai:}/api/memory/{memoryId}）
鉴权：否
Tag：AI 服务

路径变量¶

变量	类型	必填	说明
memoryId	string	是	会话记忆 ID

请求示例¶

DELETE /ai/api/memory/user_123 HTTP/1.1

响应¶

结构：ResponseEntity<Map<String, String>>，非统一 Resource。

成功示例（HTTP 200）：

{
  "message": "聊天记忆已清除",
  "memoryId": "user_123"
}

6. 健康检查¶

返回 AI 服务健康状态。

接口类型：REST 资源
请求方式：GET
请求路径：<context-path>/api/health
鉴权：否
Tag：AI 服务

请求参数¶

无。

请求示例¶

GET /ai/api/health HTTP/1.1

响应¶

结构：ResponseEntity<Map<String, String>>，非统一 Resource。

成功示例（HTTP 200）：

{ "status": "UP", "service": "OBPM AI" }