Docker7530
361 lines
11 KiB
Markdown
361 lines
11 KiB
Markdown
## 1. 对话相关模块与入口
|
||
|
||
### 1.1 HTTP 接口入口（后端）
|
||
|
||
聊天（SSE 流式）：`POST /session/chat`
|
||
查询会话列表：`POST /session/page/list`
|
||
查询某会话的历史消息列表：`POST /session/message/list`
|
||
消息反馈（点赞/点踩/评论）：`POST /session/message_feedback`
|
||
|
||
### 1.2 鉴权与用户上下文
|
||
|
||
对 `/session/**` 路径做拦截：
|
||
|
||
Filter：`web/src/main/java/com/cmcc/ai/web/filter/UserAuthFilter.java:31-55`
|
||
|
||
---
|
||
|
||
## 2. 前端怎么传参（对话接口）
|
||
|
||
### 2.1 发送消息：`POST /session/chat`
|
||
|
||
```json
|
||
{
|
||
"content": "用户输入的文本",
|
||
"sessionId": 123,
|
||
"parentMessageId": 456,
|
||
"contentType": "text",
|
||
"role": "user"
|
||
}
|
||
```
|
||
|
||
#### 实际必填/有效字段（按当前后端实现）
|
||
|
||
- **必填**：`content`
|
||
- **可选**：`sessionId`
|
||
- `sessionId == null`：后端会创建一个新会话
|
||
- `sessionId != null`：后端按该会话进行多轮
|
||
|
||
### 2.2 前端接收方式：SSE
|
||
|
||
`core/src/main/java/com/cmcc/ai/core/vo/MessageVO.java:20-72`
|
||
|
||
```json
|
||
{
|
||
"sessionId": 1,
|
||
"messageId": 10002,
|
||
"parentMessageId": 10001,
|
||
"role": "assistant",
|
||
"contentType": "text",
|
||
"msgStatus": "sending",
|
||
"content": "本次增量 token",
|
||
"reasoningContent": "（可选）模型推理内容"
|
||
}
|
||
```
|
||
|
||
当流结束时，后端会发送一条 `msgStatus=finished` 的消息（通常 `content` 为空或为最后一段），并结束 SSE 连接。
|
||
|
||
---
|
||
|
||
## 3. 后端对话编排流程（从 Controller 到落库）
|
||
|
||
核心实现类：
|
||
|
||
- `core/src/main/java/com/cmcc/ai/core/service/impl/SessionServiceImpl.java`
|
||
|
||
### 3.1 会话创建 / parentMessageId 选择
|
||
|
||
入口：`generateChatResponses(TextMessageParam param, Long userId)`
|
||
|
||
- `SessionServiceImpl.java:446-464`
|
||
|
||
逻辑：
|
||
|
||
1. **首次对话**（`param.sessionId == null`）
|
||
- `parentMessageId` 被强制设为 `0L`（常量 `DEFAULT_PARENT_MSG_ID`）
|
||
- 创建 `session_info` 记录（summary 取首条消息截断）
|
||
- 代码：`SessionServiceImpl.java:449-453`
|
||
|
||
2. **非首次对话**（`param.sessionId != null`）
|
||
- 查询该 session 下 `message_info` 的最大 id 作为 `parentMessageId`
|
||
- 代码：`SessionServiceImpl.java:454-456`
|
||
- Mapper：`MessageInfoMapper.xml:143-145`（`select max(id)`）
|
||
|
||
> 这意味着当前实现的父子关系是“链式”的：每次提问默认挂在上一条消息后面，而不是维护一棵分支对话树。
|
||
|
||
### 3.2 历史消息拼接（多轮上下文）
|
||
|
||
历史消息查询：
|
||
|
||
- `queryHistoryMsg(sessionId)`：`SessionServiceImpl.java:596-607`
|
||
|
||
构造规则：
|
||
|
||
1. 第一条固定是 **system prompt**
|
||
- `generateFirstMsg()`：`SessionServiceImpl.java:614-617`
|
||
- system prompt 来源：系统配置 `OLLAMA_CHART_SYSTEM_MSG`
|
||
- 若配置不存在则使用默认常量 `SYSTEM_MSG`
|
||
|
||
2. 从 DB 查出该 session 的所有历史 `message_content`（按 `mc.id asc`）
|
||
- SQL：`MessageContentMapper.xml:151-157`
|
||
- 每条记录映射为 `ChatMessage{role, content}`
|
||
|
||
3. 把“本次用户提问”也 append 到 historyMsg（作为最后一条 user 消息）
|
||
- `aiChatDialog()`：`SessionServiceImpl.java:632-634`
|
||
|
||
最终 historyMsg 会被完整送给大模型（多轮上下文就是这么实现的）。
|
||
|
||
### 3.3 用户消息落库
|
||
|
||
在真正请求大模型之前，用户消息会先落库：
|
||
|
||
- 插入 `message_info`（用户侧）：`insertMessage(…)`
|
||
- `SessionServiceImpl.aiChatDialog():628-630`
|
||
- 插入 `message_content`（用户文本）：`insertMessageContent(…)`
|
||
- `SessionServiceImpl.aiChatDialog():630-631`
|
||
|
||
对应表结构见 `web/src/main/resources/init.sql`：
|
||
|
||
- `session_info`
|
||
- `message_info`
|
||
- `message_content`
|
||
|
||
---
|
||
|
||
## 4. 调用的哪个 AI 接口？请求长什么样？
|
||
|
||
### 4.1 AI 接口地址与模型配置来自哪里
|
||
|
||
后端不在配置文件里写死模型与地址，而是从 DB 的 `system_config` 表读取：
|
||
|
||
- 读取 service：`SystemConfigServiceImpl.java:31-50`
|
||
- key 枚举：`common/src/main/java/com/cmcc/ai/enums/SysConfigKeyEnum.java:14-31`
|
||
|
||
对话相关的 key：
|
||
|
||
- `OLLAMA_MODEL`：模型名
|
||
- `OLLAMA_CHART_URL`：多轮对话接口地址
|
||
- `OLLAMA_CHART_SYSTEM_MSG`：system prompt
|
||
- `API_KEY`：调用上游 AI 服务时的 Authorization（代码里默认按 Bearer 使用，具体值建议视为敏感信息）
|
||
|
||
在示例初始化 SQL 中（`init.sql:70-75`），`OLLAMA_CHART_URL` 指向一个 **OpenAI 兼容风格** 的路径：`/v1/chat/completions`。
|
||
|
||
> 虽然命名叫 `OLLAMA_*`，但实际对接的上游接口形态更接近 OpenAI/DeepSeek 的 Chat Completions 流式接口。
|
||
|
||
### 4.2 后端发给上游 AI 的请求体
|
||
|
||
组装请求的代码：
|
||
|
||
- `aiChatDialog()`：`SessionServiceImpl.java:648-653`
|
||
|
||
请求体类型：`OllamaMutiplePrompt`
|
||
|
||
- `common/src/main/java/com/cmcc/ai/model/OllamaMutiplePrompt.java:20-36`
|
||
|
||
结构：
|
||
|
||
```json
|
||
{
|
||
"model": "<来自 system_config.OLLAMA_MODEL>",
|
||
"messages": [
|
||
{
|
||
"role": "system",
|
||
"content": "..."
|
||
},
|
||
{
|
||
"role": "user",
|
||
"content": "..."
|
||
},
|
||
{
|
||
"role": "assistant",
|
||
"content": "..."
|
||
},
|
||
{
|
||
"role": "user",
|
||
"content": "本次问题"
|
||
}
|
||
],
|
||
"stream": true
|
||
}
|
||
```
|
||
|
||
HTTP 请求（后端 → 上游 AI）：
|
||
|
||
- 方法：POST
|
||
- URL：`system_config.OLLAMA_CHART_URL`
|
||
- Header：`Authorization: <system_config.API_KEY>`
|
||
- 代码：`SessionServiceImpl.handleMessageWithWebClient():156-175`
|
||
- Accept：`text/event-stream`
|
||
|
||
---
|
||
|
||
## 5. AI 接口返回的什么？后端如何解析？
|
||
|
||
上游 AI 返回被按“流式”逐行消费：
|
||
|
||
- `bodyToFlux(String.class)`：`SessionServiceImpl.handleMessageWithWebClient():170-178`
|
||
|
||
后端假定每一行 `line`：
|
||
|
||
- 要么是 `"[DONE]"`
|
||
- 要么是一个 JSON chunk，可反序列化为 `ChatCompletionChunk`
|
||
|
||
解析模型（按 DeepSeek/OpenAI streaming chunk 风格）：
|
||
|
||
- `common/src/main/java/com/cmcc/ai/model/ChatCompletionChunk.java`
|
||
- 主要取值：`choices[0].delta.content`
|
||
- 推理字段：`choices[0].delta.reasoning_content`
|
||
|
||
对应解析与映射：
|
||
|
||
- `generateDeepSeekChatMessage()`：`SessionServiceImpl.java:272-311`
|
||
|
||
映射结果是内部统一的 `MessageVO`：
|
||
|
||
- `messageVO.content = delta.content`
|
||
- `messageVO.reasoningContent = delta.reasoningContent`
|
||
- `messageVO.msgStatus`：
|
||
- chunk 中包含 `finish_reason / stop_reason` 或 line 为 `[DONE]` 时，置为 `finished`
|
||
- 否则为 `sending`
|
||
|
||
> 文件里还存在 `generateChatMessage()` 用于解析 `OllamaStreamResponse`（`SessionServiceImpl.java:321-345`），但当前 `handleMessageWithWebClient()` 实际调用的是 `generateDeepSeekChatMessage()`（`SessionServiceImpl.java:184`）。
|
||
|
||
---
|
||
|
||
## 6. 后端给前端返回的什么？
|
||
|
||
### 6.1 SSE 推送的内容
|
||
|
||
后端对每个上游 chunk 都会向前端推一个 SSE event：
|
||
|
||
- `ServerSentEvent.builder(JSON.toJSONString(message)).build()`
|
||
- 代码：`SessionServiceImpl.handleMessageWithWebClient():178-189`
|
||
|
||
也就是：
|
||
|
||
- SSE 的 `data` = `MessageVO` 的 JSON 字符串
|
||
|
||
前端收到后：
|
||
|
||
- 通过 `messageId` 把同一条 assistant 消息的 token 拼起来
|
||
- 通过 `msgStatus` 判断是否完成
|
||
- 通过 `sessionId` 确定归属会话
|
||
|
||
### 6.2 对话完成后的落库与状态更新
|
||
|
||
后端在发起上游请求时，会先创建一条“assistant message_info（sending）”：
|
||
|
||
- `assistantMessage = insertMessage(…, MsgStatusEnum.SENDING)`
|
||
- 代码：`SessionServiceImpl.handleMessageWithWebClient():162-168`
|
||
|
||
流式接收过程中：
|
||
|
||
- `contentBuilder` 累积每个 chunk 的 `delta.content`
|
||
- `generateDeepSeekChatMessage():303-306`
|
||
|
||
流结束后（`doFinally`）：
|
||
|
||
- 正常完成：
|
||
- `message_content` 插入完整文本（role=assistant）
|
||
- `message_info.msg_status` 更新为 `finished`
|
||
- 并触发异步评价（见下一节）
|
||
- 代码：`SessionServiceImpl.handleMessageWithWebClient():191-195` + `handlerResponseMessage():208-218`
|
||
- 异常 / 取消：
|
||
- 仍会尽量保存已累积内容
|
||
- 并将 `message_info.msg_status` 更新为 `error/cancelled`
|
||
- 代码：`handlerResponseMessage():219-235`
|
||
|
||
### 6.3 非流式查询：历史消息列表接口返回
|
||
|
||
- `POST /session/message/list`
|
||
- 返回：`ApiResponse<List<MessageListVO>>`
|
||
- `MessageListVO`：`core/src/main/java/com/cmcc/ai/core/vo/MessageListVO.java`
|
||
- 内含 `contents: List<MessageContentVO>`
|
||
|
||
这用于“进入会话后加载历史对话”的场景。
|
||
|
||
---
|
||
|
||
## 7. 多轮对话是如何实现的？（关键点总结）
|
||
|
||
本项目的多轮对话实现方式可以概括为：
|
||
|
||
1. 每次用户发消息时：
|
||
- 先把用户消息写入 DB（`message_info + message_content`）
|
||
2. 组装“system + 历史 messages + 本次 user message”形成完整 messages 数组
|
||
- 历史消息来自 DB `message_content`，按 `mc.id asc`
|
||
3. 把完整 messages 一次性发给上游 `/v1/chat/completions`（stream=true）
|
||
4. 上游返回流式 chunk：
|
||
- 后端逐 chunk 转成 `MessageVO`，通过 SSE 推给前端
|
||
5. 流结束后：
|
||
- 把 assistant 的完整文本一次性落库
|
||
|
||
即：**上下文存储在 DB，每次请求时“全量带上历史”**。
|
||
|
||
---
|
||
|
||
## 8. 评价（可选链路，和对话强相关）
|
||
|
||
对话完成后会触发一次“问答质量评估”的异步调用：
|
||
|
||
- 触发点：`handlerResponseMessage()` 的 `ON_COMPLETE` 分支
|
||
- `SessionServiceImpl.java:209-217`
|
||
|
||
调用实现：`EvaluationServiceImpl.evaluationResult()`
|
||
|
||
- `core/src/main/java/com/cmcc/ai/core/service/impl/EvaluationServiceImpl.java:115-160`
|
||
|
||
它会：
|
||
|
||
1. 从 `system_config` 读取：
|
||
- `EVALUATE_TASK_URL`
|
||
- `CALLBACK_URL`
|
||
2. 读取“本次问/答”的 message_content 内容
|
||
3. POST 到评估系统（请求包含 query/response/callbackUrl）
|
||
4. 评估系统回调：`POST /evaluation/callback`
|
||
- Controller：`web/src/main/java/com/cmcc/ai/web/rest/EvaluationCallController.java:36-46`
|
||
|
||
这条链路不影响前端展示主流程，但会写入 `evaluation_result` 表并支撑后续统计/导出。
|
||
|
||
---
|
||
|
||
## 9. 给前端的最小对接清单（建议）
|
||
|
||
### 9.1 发起对话
|
||
|
||
- `POST /session/chat`
|
||
- body：
|
||
|
||
```json
|
||
{ "content": "...", "sessionId": 123 }
|
||
```
|
||
|
||
### 9.2 处理 SSE
|
||
|
||
- 每个 event 的 `data` 是 JSON 字符串（`MessageVO`）
|
||
- 用 `content` 做增量拼接
|
||
- 用 `msgStatus` 判断完成
|
||
- **首次对话**从第一条 event 里取 `sessionId`，用于后续多轮
|
||
|
||
### 9.3 加载历史
|
||
|
||
- `POST /session/message/list`
|
||
- body：
|
||
|
||
```json
|
||
{ "sessionId": 123 }
|
||
```
|
||
|
||
（后端只读取 `sessionId` 字段：`SessionController.java:78-83`）
|
||
|
||
---
|
||
|
||
## 10. 关键代码定位索引
|
||
|
||
- 对话接口：`web/…/SessionController.java:98-105`
|
||
- 对话编排：`core/…/SessionServiceImpl.java:446-654`
|
||
- 上游流式请求与解析：`core/…/SessionServiceImpl.java:149-196` + `272-311`
|
||
- 历史消息查询 SQL：`core/…/MessageContentMapper.xml:151-157`
|
||
- 系统配置 key：`common/…/SysConfigKeyEnum.java:14-31`
|
||
- 初始化表结构与默认配置：`web/src/main/resources/init.sql`
|