kongdeqiang
2026-10-14 9f9e043849b6f497e00399900ff234cf097eba82
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
package com.custom.webui.dto.resp;
 
import lombok.Data;
 
import java.util.List;
 
/**
 * SSE 流式对话的事件载荷。
 *
 * <p>前端通过 {@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<Source> sources;
 
    /** 自动生成的会话标题(title 事件) */
    private String title;
 
    /**
     * 本轮**实际带进上下文的历史消息条数**(done 事件下发,仅用于诊断)。
     *
     * <p>为什么值得放进协议里:曾经出过一个很难发现的 bug ——
     * 上下文预算裁剪时,最新一条(模型上一条长回答)放不下就整段放弃,
     * 于是模型收到的上下文里只有用户刚问的那一句,表现为「每轮都不记得上文」。
     * 从 HTTP 层面完全看不出来,只能翻服务端日志。
     * 把它放进 done 事件后,用一个请求就能确认「模型到底看到了几条历史」,
     * 冒烟测试也能直接断言它 —— 这类问题以后不会再静默发生。
     */
    private Integer contextMessages;
 
    @Data
    /**
     * 引用来源。
     *
     * <p>这个对象会随 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<Source> sources) {
        return done(messageId, content, sources, null);
    }
 
    public static StreamEvent done(Long messageId, String content, List<Source> 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;
    }
}