一、背景
做一个 AI 对话功能,回答是流式输出的:后端把模型生成的内容一段一段推给浏览器。方案定了之后遇到一个经典难题——用户刷新了页面怎么办?
SSE 连接断了,正在生成的内容就丢了:浏览器里显示一半的回答消失,重新提问又要花钱花时间。更麻烦的是,用户可能因为网络抖动、切后台、误操作等原因频繁断连。
完整链路如下:
用户提问 → AgentScope(ReActAgent) 流式生成 → 增量写入 Redis Stream
│
浏览器 ◄── SSE 推送 ◄── 快照校正 + 阻塞续读 ──┘
(刷新页面重连,内容无缝恢复)
本文记录这套方案从选型到落地的全部细节。
二、技术栈
| 层次 | 技术 | 职责 |
|---|---|---|
| Agent 框架 | AgentScope Java(ReActAgent + OpenAIChatModel) | 对话生成、事件流(正文/思考增量)、任务取消 |
| Web 层 | Spring Boot MVC + SseEmitter | SSE 长连接推送、异步请求管理 |
| 事件缓存 | Redis Stream(Redisson 客户端) | 生成过程的只追加事件日志,支持重放 |
| 持久化 | MySQL + MyBatis-Plus | 消息身份、会话、终态正文落库 |
| 并发 | Java 21 虚拟线程 | 承载阻塞的模型调用和 XREAD,不占用 MVC 请求线程 |
| 响应式 | Reactor(bufferTimeout/blockLast) | 对 AgentScope 事件流做攒批合并 |
架构上的职责划分一句话说清:
AgentScope 管生成,本机内存管任务状态机,Redis Stream 管可重放的内容缓存,MySQL 管终态。浏览器断开、刷新都不影响生成任务本身。
单节点部署时,任务句柄保存在本机内存;进入多节点部署后,任务控制和 Agent 会话状态需要引入共享能力,文末会展开说明。
三、核心思路
把"正在生成的回答"看作一份只追加的事件日志:
- 生成端:AgentScope 的事件流每吐出一小段文字(delta),攒批后追加写入 Redis Stream;
- 订阅端:每次建立 SSE 连接,先把日志里的历史事件拼成完整快照发给浏览器"校正",再从快照位置继续阻塞读取新事件;
- 浏览器:不需要记录任何游标,刷新后直接重连,服务端负责补齐全部内容。
这样 SSE 从"一次性管道"变成了"随时可重放的直播"——刷新等于换个客户端重新连上同一场直播。
四、生成端:AgentScope 事件流 → Redis
4.1 提问与任务登记
用户发送消息后,在一个事务里完成校验与登记:
transactions.executeWithoutResult(transaction -> {
// 会话行锁串行化发送与删除(单节点仍有并发请求)
ChatSession session = sessionMapper.selectForUpdate(request.sessionId(), userId);
// 同一会话不允许排队、插队
ChatMessage active = messageMapper.selectBySessionIdStatus(request.sessionId(), WIP);
if (active != null && tasks.containsKey(active.getId())) {
throw new BusinessException(CONFLICT, "上一条回复还在生成中,请稍候");
}
save(user); save(assistant);
streams.create(task.messageId); // 建 Redis Stream 占位
tasks.put(task.messageId, task); // 登记本机任务句柄
});
tasks 是 ConcurrentHashMap<String, GenerationTask>——任务状态机就在这块内存里。任务对象持有两个关键字段:
private static final class GenerationTask {
volatile AgentRun<AgentEvent> run; // AgentScope 运行句柄,stop 靠它取消
volatile ChatStatusEnum status = WIP; // volatile,跨线程可见
long seq; // 事件序号,任务锁内自增
}
4.2 构建 Agent 并执行生成
生成跑在虚拟线程上,用 AgentScope 的 ReActAgent:
try (ReActAgent agent = ReActAgent.builder()
.name("助手")
.sysPrompt("你是豆包")
.model(chatModel) // OpenAIChatModel(AgentScope extensions)
.stateStore(stateStore) // 会话状态存储
.toolkit(new Toolkit())
.middleware(new TimingMiddleware())
.build()) {
RuntimeContext context = RuntimeContext.builder()
.sessionId(task.sessionId).userId(userId).build();
// 先拿句柄挂回任务,stop 才有对象可取消;订阅 stream 之后才真正执行。
task.run = agent.prepareRun(List.of(new UserMessage(content)), context);
task.run.stream()
.filter(event -> event instanceof TextBlockDeltaEvent text && isNotEmpty(text.getDelta())
|| event instanceof ThinkingBlockDeltaEvent t && isNotEmpty(t.getDelta()))
.bufferTimeout(64, DELTA_BATCH_INTERVAL) // 攒批:64 个或 50ms 先到先发
.doOnNext(batch -> {
StringBuilder delta = new StringBuilder(); // 正文片段
StringBuilder thinkingDelta = new StringBuilder(); // 思考片段
for (AgentEvent event : batch) { /* 分类累积 */ }
synchronized (task) {
if (task.status == WIP) {
streams.append(task.messageId, ++task.seq, delta.toString(), thinkingDelta.toString());
}
}
})
.blockLast(); // 虚拟线程上阻塞直到生成结束
}
三个关键设计:
- prepareRun 先于 stream() 订阅:AgentScope 的
AgentRun是句柄式的——先拿到 run 再订阅事件流才真正开始执行。这让"停止生成"有对象可取消(task.run.cancel()),哪怕用户在模型还没吐第一个字时就点了停止。 - bufferTimeout 攒批:模型一次可能吐很多小 token,逐条 XADD 会把 Redis 写爆。攒 64 个事件或 50ms(先到先触发)合并成一次写入,一次 Redis 写对应一段有意义的增量。
- append 在任务锁内 + WIP 校验:追加与停止共用同一把任务锁,停止确定后不再写入增量,序号也不会在 stop 边界上产生竞争。
4.3 停止与收尾
private void finish(GenerationTask task, ChatStatusEnum status) {
synchronized (task) {
if (task.status != WIP) return; // 幂等:多处调用只收尾一次
task.status = status;
}
// 取消放在任务锁外,避免模型结束回调再次进入 finish 时等待同一把锁。
if (status != FINISHED) task.cancel();
ChatStreamStore.Snapshot snapshot = streams.snapshot(task.messageId);
streams.finish(task.messageId, snapshot.seq() + 1, status, status.hint()); // 补 done
messageMapper.saveResult(task.messageId, snapshot.content(), status); // 落库
tasks.remove(task.messageId, task);
}
正常结束、用户停止、模型异常都汇聚到这一个方法。done 事件的 seq 取"快照最后一条 + 1",保证终态排在所有 patch 之后、序号不断裂。
还有两处兜底:
- 应用重启(
@PostConstruct):扫描数据库里还是 WIP 但已无活任务的消息,从缓存快照收尾,补一条 done 让残留的 SSE 订阅者也能退出; - 应用关闭(
@PreDestroy):把所有活任务按 ERROR 收尾,再关闭虚拟线程池。
五、数据模型设计
5.1 三种事件
每条事件是一个 JSON,对应一个 record:
public record StreamEventVO(String type, String content, String delta, String thinkingDelta,
String status, String message, long seq) { ... }
| type | 写入时机 | 作用 |
|---|---|---|
snapshot | 连接建立时 | 校正浏览器已显示的内容(content 为完整正文) |
patch | 每批模型输出 | 增量:delta 正文片段、thinkingDelta 思考片段 |
done | 任务结束 | 只通知终态(成功/失败/停止),不再携带正文 |
设计取舍:done 不带正文。终态事件只负责告诉订阅端"结束了、什么状态",正文一律由 patch 累积,避免同一份数据存两处。思考内容只在缓存和页面里临时保留,不落库、不进历史消息。
5.2 seq 直接当 Stream ID
这是整个方案最核心的一个决定:业务序号 seq 就是 Redis Stream 的消息 ID。
- 第 1 批增量 → Stream ID
1-0,seq=1 - 第 2 批增量 → Stream ID
2-0,seq=2
好处有三个:
- 天然有序:Stream 按 ID 排序,游标读取就是按 seq 顺序;
- 游标语义免费获得:
XREAD greaterThan(seq)直接从任意位置续读; - 连续性校验有依据:订阅端每收到一条事件,校验
seq == 上一次 + 1,序号断裂说明日志残缺,宁可报错重连也不交付错乱内容。
注意 Redis 本身要求 XADD 的 ID 严格递增(但不要求是时间戳),这里由生成端在任务锁内 ++task.seq 保证。
5.3 一个小坑:Redis 不接受 0-0
Stream ID 理论上从 0-0 开始,但 XADD 拒绝显式写入 0-0。所以任务启动时用 0-1 写一条空快照占位,正文事件从 1-0 开始。订阅端游标对应特判:seq == 0 时从 0-1 之后开始读(跳过占位)。
六、存储层实现(ChatStreamStore)
6.1 写入:三个方法对应任务生命周期
create(messageId) 任务启动 → 写占位快照
append(messageId, seq, delta, ...) 每批输出 → 写一条 patch
finish(messageId, seq, status, msg) 任务结束 → 写一条 done
内部统一走一个 write:
private void write(String messageId, StreamMessageId id, StreamEventVO event) {
RStream<String, String> stream = stream(messageId);
stream.add(id, StreamAddArgs.entries(Map.of("data", JSON.toJSONString(event))));
// 每次写入刷新 TTL,会话活跃期间缓存不过期。
stream.expire(AgentScopeConstant.STREAM_RETENTION); // 1 天
}
两个细节:
- 显式指定消息 ID(
seq-0),而不是让 Redis 自动生成,序号才能被业务掌控; - 每次写入刷新 TTL。生成期间缓存永不过期,任务结束后没人再续命,到期自动清理,不需要额外的删除任务。
6.2 读取一:snapshot —— 重连时拼全量(重点)
用户刷新页面、新连接建立时,需要把已生成的内容一次性拼出来。难点在于:拼接的同时,AI 可能还在往 Stream 里写新事件,读和写是并发的。
如果直接"从第 1 条读到当前最新",读的过程中新写入的数据会漏掉,快照和后续增量的接缝处就丢了内容。
解法:先固定读取上界,只读不可变前缀。
public Snapshot snapshot(String messageId) {
RStream<String, String> stream = stream(messageId);
// 先取最后一条记录,用它的 seq 固定读取上界。
List<StreamEventVO> last = decode(stream.rangeReversed(1, StreamMessageId.MAX, StreamMessageId.MIN));
if (last.isEmpty()) return null;
long upper = last.getFirst().seq();
long cursor = 0;
StringBuilder content = new StringBuilder();
StringBuilder thinking = new StringBuilder();
while (cursor < upper) {
Map<StreamMessageId, Map<String, String>> batch = stream.range(READ_BATCH,
new StreamMessageId(cursor + 1, 0), new StreamMessageId(upper, 0));
if (batch.isEmpty()) throw new IllegalStateException("生成事件不完整,请重新连接");
for (StreamEventVO event : decode(batch)) {
if (event.seq() != cursor + 1) throw new IllegalStateException("生成事件序号不连续");
if ("patch".equals(event.type())) {
if (event.delta() != null) content.append(event.delta());
if (event.thinkingDelta() != null) thinking.append(event.thinkingDelta());
}
if (event.terminal()) { /* 记录终态 */ }
cursor = event.seq();
}
}
return new Snapshot(content.toString(), thinking.toString(), cursor, status, message);
}
算法分四步:
rangeReversed(1, MAX, MIN)取最后一条记录,用它的 seq 作为读取上界upper;- 分批(每批 128 条)扫描
[0, upper]这段不可变前缀——期间新写入的事件都在上界之后,不受影响; - 逐条校验 seq 连续性,把 patch 的 delta 拼回完整正文和思考;
- 记录 done 事件的终态。
为什么接缝处不丢不重? 读取期间新来的增量全部位于 upper 之后,随后的 XREAD greaterThan(upper) 从该位置继续——两段范围没有交集,也没有空洞。
6.3 读取二:readAfter —— 连接期间持续收增量
public List<StreamEventVO> readAfter(String messageId, long seq) {
StreamMessageId cursor = seq == 0 ? INITIAL_ID : new StreamMessageId(seq, 0);
// 阻塞 1s 等新事件,避免空转轮询。
return decode(stream(messageId).read(StreamReadArgs.greaterThan(cursor)
.count(READ_BATCH).timeout(Duration.ofSeconds(1))));
}
对应 Redis 命令 XREAD COUNT 128 BLOCK 1000 STREAMS events:{id} cursor:
greaterThan(cursor):严格大于游标,不含本条。传 seq=50,返回的第一条是 51-0,正好对接cursor + 1的校验;timeout(1s):没有新消息时连接挂起最多 1 秒——有新事件立刻返回,超时返回空列表。这就是用阻塞读代替轮询的关键。
七、投递层实现(ChatStreamDelivery)
存储层只负责读写 Redis,把内容推给浏览器的是投递层。投递循环跑在虚拟线程上,阻塞的 XREAD 不占用 MVC 请求线程;正常完成/超时/出错三种结束方式都落到同一个 closed 标志,循环据此退出。
7.1 投递循环:快照校正 → 增量续读
private void deliver(ChatMessage message, SseEmitter emitter, AtomicBoolean closed) {
try {
ChatStreamStore.Snapshot snapshot = loadSnapshot(message);
// 每次连接都以完整快照校正,刷新后无需浏览器保存上次的游标。
sendEvent(emitter, StreamEventVO.snapshot(snapshot.content(), snapshot.thinkingDelta(), snapshot.seq()));
if (snapshot.terminal()) {
sendEvent(emitter, StreamEventVO.done(snapshot.status(), snapshot.message(), snapshot.seq()));
return;
}
long cursor = snapshot.seq();
long lastHeartbeat = System.nanoTime();
while (!closed.get()) {
for (StreamEventVO event : streams.readAfter(messageId, cursor)) {
if (closed.get()) return;
if (event.seq() != cursor + 1) throw new IllegalStateException("生成事件序号不连续");
sendEvent(emitter, event);
cursor = event.seq();
if (event.terminal()) return;
}
if (System.nanoTime() - lastHeartbeat >= STREAM_HEARTBEAT.toNanos()) { // 10s
emitter.send(SseEmitter.event().comment("heartbeat"));
lastHeartbeat = System.nanoTime();
}
}
} finally {
closed.set(true);
emitter.complete();
}
}
流程非常清晰:
- 先发快照:浏览器收到
snapshot事件后直接用完整 content 覆盖本地内容(而不是 append),刷新后自然对齐;seq 兼作 SSE 事件 id; - 已终态则结束:任务已经完成的话,快照里就带终态,补发一个 done 就收工;
- 未终态进入循环:阻塞读增量 → 逐条校验 seq → 推给浏览器 → 读到 done 退出;
- 心跳:每轮阻塞读最多 1 秒,空档期按 10 秒间隔发 SSE 注释(comment)作为心跳,防止 Nginx 等中间层把"空闲"连接掐断。
7.2 缓存过期降级
Redis 缓存只保留 1 天,用户第二天才打开页面怎么办?投递层做了降级:
- 任务还在生成中(WIP)但缓存没了 → 异常,直接抛错(正常情况下活跃任务一定有缓存);
- 任务已结束但缓存过期 → 回 MySQL 读已落库的正文,拼一个静态快照返回,浏览器照样能显示完整回答。
八、为什么事件日志选 Redis Stream
实现前对比过几种结构:
| 方案 | 结论 |
|---|---|
| Pub/Sub | ❌ 无历史、不能重放,刷新即丢,直接排除 |
| 纯 String 存全量 | ⚠️ 重放最简单,但并发覆盖要加锁,丢失事件日志(终态/边界/校验都要另存) |
| List | ⚠️ 有序追加可以,但没有"查看式阻塞读"(BLPOP 是弹出语义),只能轮询 |
| ZSET(score=seq) | ⚠️ 游标语义可以,同样没有阻塞读 |
| Kafka/MQ | ⚠️ 语义够,但每条 delta 一次写入太重,运维成本不成比例 |
| Redis Stream | ✅ 追加日志 + 消息 ID 游标 + 阻塞读 + TTL,四件事原生支持 |
Stream 是 Redis 里唯一同时原生提供这四样能力的结构,代码量最小、接缝最少。
顺带说明:这里没有用消费者组(XREADGROUP),而是每个订阅者独立游标 + 普通 XREAD。因为场景是"广播"——每个连接都要读到完整事件序列才能拼出正文,不是队列分发。
九、踩过的坑
- Stream ID 不能是 0-0:用
0-1占位,游标读取时对 seq=0 特判; - 并发读写的接缝:快照必须先固定上界再读,直接"读到最新"会丢掉读取期间的新数据;
- 停止的幂等与锁序:finish 先在锁内置状态再在锁外 cancel,模型结束回调重复进入时直接返回,避免死锁和重复写 done;
- seq 必须严格递增:Redis 要求 XADD 的 ID 严格大于上一条,由生成端任务锁内自增保证;
- 攒批窗口与响应速度:bufferTimeout(64, 50ms) 在写放大和流畅度之间取平衡,窗口太大浏览器会明显卡顿;
- 旧数据兼容:早期日志没有 thinkingDelta 字段,拼接时必须判 null,否则会拼出字符串 “null”;
- 心跳必不可少:SSE 长连接容易被中间层按空闲掐断,阻塞读的空档期要主动发心跳。
十、上生产:多节点部署的设计思路
单节点方案解决了生成、缓存和断线续传。部署多个应用实例时,还需要处理任务存活、跨节点停止、异常收尾和共享 Agent 状态。
10.1 部署结构:请求可以落到任意实例
所有实例连接同一套 Redis 和 MySQL。Gateway 负责把请求转给应用实例,Nacos 提供服务发现;任务控制由应用和共享存储完成。
一次对话的请求可能这样分布:
- 发送请求落到 A,模型由 A 执行;
- SSE 请求落到 B,B 从共享 Redis Stream 读取 A 写入的内容;
- 停止请求落到 B,B 需要通知持有模型句柄的 A 取消任务。
事件缓存和读取协议可以直接复用。多节点方案不要求新请求固定到某台实例;已经建立的 SSE 连接仍由原实例维护,连接断开后,浏览器重新连接并读取共享快照。
10.2 哪些数据共享,哪些仍留在本机
| 数据 | 存放位置 | 职责 |
|---|---|---|
AgentRun、任务对象、线程内状态 | 执行实例内存 | 驱动模型、接收增量、执行取消 |
| Redis Stream | 共享 Redis | 正文与思考缓存、快照、增量续传、done |
| 停止意图、任务存活信息 | 共享 Redis | 跨节点控制和失效判断 |
| 会话、消息 ID、WIP 占位、终态正文 | MySQL | 消息归属和持久历史 |
| Agent 会话状态 | 后续接入共享状态存储 | 下一轮可以在其他实例读取模型上下文 |
AgentRun 是正在运行的模型句柄,应继续留在执行实例,无法通过保存到 Redis 把一个已经开始的调用搬到另一台机器。共享的是可查询的任务信息和可恢复的内容。
10.3 跨节点停止:Redis Pub/Sub 通知执行实例
初期采用 Redis Pub/Sub,所有实例订阅同一个公共频道。下面的键名和频道名用于说明设计:
agent:stop:{messageId} 停止意图,任务登记时为 0,请求停止时为 1
agent:stop-notice 公共通知频道,消息只携带 messageId
停止请求的处理顺序:
- 校验消息归属,确认仍有需要处理的生成任务;
- 把停止意图写入 Redis,再发布通知;更新已有停止键,避免已结束的任务被重新登记;
- 每个实例查询自己的
tasks.get(messageId),只有持有句柄的实例请求取消; - 生成线程退出、Agent 状态保存完成后统一收尾,保存终态正文并写入 done,再清理任务控制信息。
这条路径无需手工配置唯一的 node-id:消息 ID 标识任务,各实例通过本机句柄判断是否需要处理通知。
Pub/Sub 不保存断线期间的消息,所以停止意图必须单独保留。生成启动前、通知订阅恢复后和生成收尾前,补查相关任务的停止标志;不增加每秒查询停止状态的循环。通知断线期间,停止可能延迟到订阅恢复,因此不能承诺固定的停止时限。
停止接口返回成功表示请求已提交。取消过程中仍应阻止同一会话的新一轮,直到原任务退出并完成状态保存,避免新旧调用同时修改模型上下文。
10.4 同会话互斥:数据库 WIP 表示“尚未收尾”
单节点代码用 WIP && tasks.containsKey(messageId) 判断上一轮是否仍在运行。多节点下,B 没有 A 的本机句柄,这个判断会错误地放行新一轮。
可以保留现有 MySQL 会话行锁,让发送、删除和异常收尾共用同一个锁。持有锁时检查共享任务信息,登记新任务后再放行同一会话的其他请求。Redis 与 MySQL 不在同一事务里,还需要处理发送回滚后的登记清理,以及终态保存失败后的补存。
数据库 WIP 可以保留,但它只表示这条回复已经创建、尚未完成收尾,不能单独证明模型还活着。 它保留消息 ID、会话归属及未完成记录,避免未完成回复完全依赖缓存。
遇到数据库 WIP 时,按共享信息决定后续动作:
| 共享信息 | 处理 |
|---|---|
| 任务仍有效,尚未收尾 | 拒绝下一轮发送和会话删除 |
| Redis 已有 done,数据库仍是 WIP | 按缓存终态补存数据库 |
| 新版任务满足约定的失效条件 | 保存已收到的正文,标记中断,再允许后续操作 |
| Redis 不可用,或旧数据缺少任务登记 | 保留未确定状态,不能直接判断进程已经退出 |
若彻底移除数据库 WIP 占位,还需让历史查询合并 Redis 中的未完成消息、从 Redis 校验消息归属,并把收尾改成幂等插入。因此保留占位行更简单:发送时插入、结束时更新,运行判断交给 Redis,不使用数据库轮询控制模型。
10.5 强制退出:任务 TTL、低频续期、访问时收尾
生产环境需要处理进程崩溃、强制结束和滚动发布。可以参考 Open WebUI 的任务存活设计,增加独立的任务键:
agent:alive:{messageId} TTL:300 秒
续期间隔 75 秒
每个实例只给本机仍持有的任务批量执行 EXPIRE,没有任务时不发送续期请求。续期只能延长已有键,不能重新创建已经失效的任务;发现键已经失效时,执行实例应取消对应任务。停止意图和正文缓存独立保留,以便后续收尾。
这里有三种不同的时间机制:
- SSE 心跳:告诉浏览器和代理连接还在,防止空闲断连;
- 任务心跳:续期任务存活键,供其他实例判断任务是否仍有效;
- Stream 保留时间:决定已生成内容还能重放多久,示例配置为 24 小时。
它们不能相互替代。只根据正文是否更新判断存活,会把模型思考、工具执行等正常的静默阶段误判为中断。
进程被强制结束后,任务键不再续期,距离最后一次成功续期最长约 5 分钟后过期。用户查询消息、发送、停止、删除或重新订阅时,只检查对应会话或消息,并在会话锁内处理遗留任务:
- 缓存已有 done:保留原终态,补存数据库,不重复追加 done;
- 新版任务已失效、缓存尚未终结:读取缓存正文,按
ERROR收尾,补 done,提示“生成中断,已保留收到的内容”; - 缓存正文也已过期:只能保留数据库已有内容,不能恢复未保存的增量。
仍连接在其他实例上的 SSE,可以在现有心跳时点检查该消息是否需要收尾,避免一直等待一个已经退出的生成进程。整个恢复路径按访问触发,不做后台全库扫描。
终态保存成功后再清理控制数据,正文缓存继续按原保留时间供页面重放。数据库更新保留 WHERE status = WIP 的条件,并配合会话锁处理重复请求。Redis 已写 done、数据库保存失败时,后续访问应能够补存。
TTL 是约定的失效条件,不能绝对证明进程死亡。长时间网络分区或进程暂停也可能导致过期;Redis 请求失败不能直接当作任务不存在。实现还需要阻止失效任务恢复后继续追加、覆盖终态或修改下一轮上下文,不能把简单的 TTL 续期当成严格的跨节点互斥保证。
正常关闭时,先停止接收新生成请求,请求取消本机任务,再等待生成线程保存已收到的内容,最后关闭执行器。异常恢复只保留内容和收尾,无法恢复已退出的模型调用;重新生成应是一次明确的新调用。
10.6 启动与旧数据:不能再全库收尾 WIP
单节点启动时,可以假定上一个进程的模型调用已经退出。多节点部署中,启动 B 时 A 可能还在生成,因此必须移除“新实例启动就收尾数据库全部 WIP”的行为。
新版任务登记应包含版本标记,以区分“有存活机制、后来已失效的任务”和“从未接入该机制的旧任务”。旧版 WIP 缺少存活键,不能据此自动认定中断。
首次升级时,正常关闭旧版实例,确认旧生成进程均已退出后,一次性收尾遗留 WIP,再切换到多节点版本。后续新实例启动只初始化自己的订阅和执行环境。
10.7 模型上下文与后续 MQ
若 InMemoryAgentStateStore 按单节点使用,下一轮请求落到其他实例时可能缺少模型上下文。要让请求真正落到任意实例,需要接入按会话共享的状态存储;共享状态存储也需要遵守同会话互斥,确保上一轮已经退出并完成保存。
停止通知可以抽成一个小接口,只提供发布、订阅、订阅就绪回调和关闭。后续更换 MQ 时,业务层的停止意图、模型取消和生成收尾可以继续复用。
MQ 需要采用广播消费,或者根据任务归属路由到执行实例。如果所有实例竞争消费同一条停止消息,可能由没有句柄的实例消费掉,真正执行模型的实例收不到。MQ 的持久化和重投可以改善通知可靠性,但进程存活判断仍需单独处理;重复通知也必须幂等。
10.8 入口代理与滚动发布
Nginx / Gateway 应允许 SSE 持续转发,关闭会攒住流式响应的缓冲,并让空闲读取超时大于 SSE 心跳间隔。应用已返回的 X-Accel-Buffering: no、Cache-Control: no-cache, no-transform 需要配合实际代理配置生效。
滚动发布时,先让实例停止接收新生成请求,再执行本机任务关闭流程。原实例上的 SSE 连接可能断开,前端通过重连从其他实例读取共享缓存。还需按并发订阅数配置 Redis 阻塞读的连接资源:虚拟线程减少线程占用,不能消除 XREAD 对 Redis 连接的需求。
落地可以按这个顺序推进:公共停止通知 → 共享运行判断与失效收尾 → 共享 Agent 状态 → 入口代理及滚动发布验证。Gateway 和 Nacos 在部署阶段接入即可,核心任务控制无需依赖它们的请求路由。
十一、总结
整套方案可以浓缩成一句话:
AgentScope 的事件流经攒批后落成 Redis Stream 里一份带序号的只追加日志;重连时"固定上界拼全量 + 阻塞读续增量",接缝处靠游标语义保证不丢不重。
它带来三个体验上的收益:
- 刷新页面/断线重连,内容无缝恢复;
- 浏览器零状态——不用记录游标,重连即可;
- 多端同时观看同一个生成过程互不影响(每个订阅独立游标)。
单节点部署时,执行句柄留在本机;多节点部署时,停止意图和存活信息由 Redis 共享,数据库保留消息身份与终态,再配合共享 Agent 状态和异常收尾。Redis Stream 的快照与增量续传协议可以继续复用。
技术栈:AgentScope Java(ReActAgent / OpenAIChatModel)· Spring Boot MVC(SseEmitter)· Redisson(Redis Stream)· MyBatis-Plus(MySQL)· Reactor(bufferTimeout)· Java 21 虚拟线程
本文复盘基于AgentScope实现AI对话流式输出的断线续传方案:生成端将模型增量事件攒批写入Redis Stream,订阅端通过快照校正+阻塞读增量实现刷新不丢内容;核心设计包括seq直作Stream ID、WIP状态与Redis Pub/Sub跨节点停止、多实例共享缓存与本地任务句柄分离;技术栈涵盖Java虚拟线程、Spring Boot SSE、Redisson Stream及MySQL终态存储。
198

被折叠的 条评论
为什么被折叠?



