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 为什么值得放进协议里:曾经出过一个很难发现的 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