package com.custom.webui.dto.resp; import lombok.Data; import java.util.List; /** * SSE 流式对话的事件载荷。 * *

前端通过 {@code event:} 区分事件类型,{@code data:} 里是本对象序列化后的 JSON。 * 唯一例外是 {@code delta} 事件也可以只推送纯文本,但为了统一解析这里始终用 JSON 包裹。 */ @Data public class StreamEvent { /** 事件类型:start / delta / done / error / title */ private String type; /** 会话 id */ private Long chatId; /** 本次生成的 assistant 消息 id(start 事件下发,前端据此占位) */ private Long messageId; /** 触发本次生成的 user 消息 id */ private Long userMessageId; /** 增量文本(delta 事件) */ private String delta; /** 累积的完整文本,done 事件下发,前端用于校准(防止丢包导致内容不一致) */ private String content; /** 生成所用模型 */ private String model; /** 是否为 reasoning 模型的思考内容 */ private Boolean thinking; /** 错误信息(error 事件) */ private String error; /** 本轮命中的 RAG 引用来源,前端可在消息下方展示 */ private List sources; /** 自动生成的会话标题(title 事件) */ private String title; /** * 本轮**实际带进上下文的历史消息条数**(done 事件下发,仅用于诊断)。 * *

为什么值得放进协议里:曾经出过一个很难发现的 bug —— * 上下文预算裁剪时,最新一条(模型上一条长回答)放不下就整段放弃, * 于是模型收到的上下文里只有用户刚问的那一句,表现为「每轮都不记得上文」。 * 从 HTTP 层面完全看不出来,只能翻服务端日志。 * 把它放进 done 事件后,用一个请求就能确认「模型到底看到了几条历史」, * 冒烟测试也能直接断言它 —— 这类问题以后不会再静默发生。 */ private Integer contextMessages; @Data /** * 引用来源。 * *

这个对象会随 done 事件下发,同时写入消息的 metadata 持久化 —— * 刷新页面后仍能看到「这条回答引用了哪些文档的哪一节」。 * 前端按数组下标 +1 显示为 [1][2],与 prompt 里给模型的编号一致。 */ public static class Source { /** 来源文档名 */ private String filename; /** 章节路径,如「第2章 架构 / 2.1 消息树」,可能为空 */ private String section; /** 相似度得分,越小越相关(Chroma 距离) */ private Double score; /** 片段摘要,仅用于展示 */ private String snippet; /** 该片段在原文分块中的序号,便于定位 */ private Integer chunkIndex; /** 所属向量集合名(本质上对应一个知识库文件) */ private String collectionName; } // ---------- 静态工厂,避免各处手工拼装 ---------- public static StreamEvent start(Long chatId, Long userMessageId, Long messageId, String model) { StreamEvent e = new StreamEvent(); e.type = "start"; e.chatId = chatId; e.userMessageId = userMessageId; e.messageId = messageId; e.model = model; return e; } public static StreamEvent delta(Long messageId, String delta, boolean thinking) { StreamEvent e = new StreamEvent(); e.type = "delta"; e.messageId = messageId; e.delta = delta; e.thinking = thinking; return e; } public static StreamEvent done(Long messageId, String content, List sources) { return done(messageId, content, sources, null); } public static StreamEvent done(Long messageId, String content, List sources, Integer contextMessages) { StreamEvent e = new StreamEvent(); e.type = "done"; e.messageId = messageId; e.content = content; e.sources = sources; e.contextMessages = contextMessages; return e; } public static StreamEvent error(String error) { StreamEvent e = new StreamEvent(); e.type = "error"; e.error = error; return e; } public static StreamEvent title(Long chatId, String title) { StreamEvent e = new StreamEvent(); e.type = "title"; e.chatId = chatId; e.title = title; return e; } }