Skip to content

[BUG] 流式节点未正常完成时,下一轮对话消息序列结构错乱(导致LLM 拒绝请求) #4789

Closed as not planned

Description

@mz0113

Is there an existing issue for this?

  • I have searched the existing issues

Current Behavior

Title: 流式节点未正常完成时 checkpoint 丢失,导致下一轮对话消息序列结构错乱(LLM 拒绝请求)
问题描述
在使用 ReactAgent.streamMessages(...) 订阅流式输出时,如果外部订阅者在流式过程中取消订阅(如 flux.timeout(...) 超时、前端断开 SSE 连接、断点调试卡住等),会导致:
1.
当前 LLM 节点产生的 AssistantMessage 未被持久化到 checkpoint(MySQL/Postgres/Redis 等 saver);
2.
但该 LLM 节点之前已执行完成的 tool 节点的 ToolResponseMessage 已经持久化了;
3.
用户下次发送消息时,框架从 saver 加载历史消息列表,出现 ... -> assistant(tool_call) -> toolResponse -> user 的结构;
4.
该结构违反了主流 LLM API(OpenAI / DashScope 等)对 messages 序列的硬性约束——tool 角色消息后必须紧跟 assistant 消息,导致 LLM 直接返回 400 错误,拒绝整个请求。
复现步骤
1.
配置一个带 tool calling 的 ReactAgent,使用 MySQL(或任意) CheckpointSaver;
2.
拿到流式 Flux 并加超时:
Flux streamMessages = reactAgent.streamMessages(request.getPrompt(), config);
streamMessages.timeout(Duration.ofSeconds(60)).subscribe(...); // 给前端做 SSE
3.
发送一个会触发 tool call 的问题;
4.
在 com.alibaba.cloud.ai.graph.agent.Agent.extractMessages 处打断点,或在 60 秒内不消费 flux,让其超时;
5.
timeout 触发后,检查数据库 checkpoint 的 messages 列表;
6.
用户再次发送 "请继续"。
预期行为
•
外部订阅超时/取消,只应影响前端 SSE 输出,不应影响框架内部的状态持久化完整性;
•
即便流被中断,已完成的 tool 节点的 ToolResponseMessage 和未完成的 LLM 节点的 AssistantMessage 应当保持配对一致——要么都落库,要么都不落库;
•
下一轮对话加载历史消息时,序列结构应始终合法。
实际行为
数据库中持久化的 messages 列表变为:
user
assistant
user
assistant (with tool_call)
toolResponse ← 缺少紧随其后的 assistant 消息
用户再次输入后变成:
user
assistant
user
assistant (with tool_call)
toolResponse
user ← toolResponse 后直接跟 user,结构非法
发送给 LLM 时被拒绝(400),类似:
"messages: roles must alternate between user/assistant/tool, expected assistant after tool"
根因分析
框架的整个图执行是一条惰性的 Reactor 响应式流,节点的推进、状态合并、checkpoint 持久化全部由下游订阅的 request(n) 拉动驱动,没有独立的后台执行线程。

  1. 图执行链通过 concatWith + Flux.defer 递归拼接
    MainGraphExecutor.java:134-135、NodeExecutor.java:208-209:
    return Flux.just(GraphResponse.of(output))
    .concatWith(Flux.defer(() -> mainGraphExecutor.execute(context, resultValue)));
    下一个节点只有在前一个 Flux onComplete 后才会被 subscribe。
  2. 流式 LLM 节点的 checkpoint 写入挂在流的末尾 Mono 里
    NodeExecutor.processGraphResponseFlux(NodeExecutor.java:543-599):
    Mono updateContextMono = Mono.fromRunnable(() -> {
    ...
    context.mergeIntoCurrentState(updateState);
    context.buildNodeOutputAndAddCheckpoint(updateState); // :588 才真正写库
    ...
    });

return processedFlux
.concatWith(updateContextMono.thenThen(Flux.defer(() -> mainGraphExecutor.execute(...))));
buildNodeOutputAndAddCheckpoint -> addCheckpoint -> saver.put(...)(GraphRunnerContext.java:244-255)是同步写库,但它被包在 updateContextMono 里,只有当 processedFlux 正常 onComplete 后,这个 Mono 才会被 subscribe。
3. 而 tool 节点是非流式的,checkpoint 是立即同步写的
NodeExecutor.java:204:
NodeOutput output = context.buildNodeOutputAndAddCheckpoint(updateState); // 立即写库
所以 ToolResponseMessage 在 timeout 前已经落库。
4. timeout/cancel 的破坏
flux.timeout(...) 超时后会向上游发 cancel。由于整条链是同一个响应式流(没有 cache()/replay()/独立线程解耦):
•
processedFlux 被 cancel,LLM 的 HTTP 流被中断;
•
concatWith 尾部的 updateContextMono 永远不会被 subscribe,因为 concatWith 依赖前一个 Flux 的 onComplete,而 cancel 不触发 onComplete;
•
于是 :588 的 buildNodeOutputAndAddCheckpoint 从未执行,这条 AssistantMessage 既没进 OverAllState,也没写 checkpoint。
结果:ToolResponseMessage 已落库,配对的 AssistantMessage 丢失,下一轮消息序列非法。
5. 补充:LLM 流式异常时也有类似问题
即便没有外部 timeout,若 LLM 流式过程中抛异常,transformFluxToGraphResponse 的 .onErrorResume(NodeExecutor.java:314-321)会把错误包成 GraphResponse.error 当作数据元素继续发,流会正常 onComplete,updateContextMono 会被执行。但此时 lastData.get() 是 error,resultValue() 不是 Map,updateState 为空 map(:566-575),:582 merge 进去的是空,:588 写的 checkpoint 里仍然没有这条 assistant 消息。同样会导致下一轮消息序列非法。
影响范围
•
任何使用 streamMessages / stream + CheckpointSaver 的场景;
•
外部订阅因任何原因(timeout、前端断开、异常)未正常完成时都会触发;
•
ReactAgent、SequentialAgent 等带 tool calling 的 agent 尤其严重,因为 tool 节点和 model 节点的持久化时机不一致。
建议的修复方向
核心问题是持久化与前端订阅生命周期强耦合。可能的修复方向:
1.
解耦持久化与前端订阅:在内部用 Sinks/publish 多播,持久化由一个独立的内部订阅消费,即使前端断开,内部订阅仍跑完,确保 checkpoint 完整。
2.
流式节点也边吐边写 / 或在 cancel 时兜底写:在 processGraphResponseFlux 的 updateContextMono 之外,增加 doOnCancel 兜底逻辑,在 cancel 时也尝试用已聚合的 lastChatResponseRef 落库。
3.
保证消息序列一致性:在 updateContextMono 里增加校验——若上一条是 toolResponse 且本次没有产出 assistant,要么补一条占位 AssistantMessage,要么回滚到 tool 节点之前的 checkpoint,避免落库一个非法的中间状态。
4.
至少在文档中明确警告:当前 streamMessages 返回的 Flux 不支持外部 timeout/cancel,否则会破坏状态一致性。
环境
•
框架版本:当前 main 分支
•
Saver:MySQL(其他 saver 同理)
•
调用方式:reactAgent.streamMessages(prompt, config) + 外部 flux.timeout(...)

Expected Behavior

No response

Steps To Reproduce

No response

Environment

Spring AI Alibaba version(s):

Debug logs

No response

Anything else?

No response

Activity

  1. Jupiter363 commented on Jul 8, 2026

    @Jupiter363
    Contributor

    我重新收敛了一版更保守的修复方案:#4791。

    这次没有继续采用 #4790 里的后台继续执行方案。#4790 的思路是:前端 SSE / downstream subscription timeout 或 cancel 后,框架内部仍继续跑完后续节点,把 ToolResponseMessage -> AssistantMessage 的链路补完整。这个方案语义更强,但会引入额外并发风险:旧的 cancelled run 可能还在后台写 checkpoint,而用户已经在同一个 thread 上发起了下一轮请求,二者会竞争 latest checkpoint / releaseThread(true)。为了让这个方案安全,需要额外的 lineage guard、release guard,甚至还会牵涉多实例共享 checkpoint 后端时的 saver-level CAS / 分布式锁问题,整体范围会明显扩大。

    所以我关闭了 #4790,改用 #4791 的 rollback-oriented 方案:保持 Reactor 原有 cancellation 语义,不引入 detached/background execution;如果某次 timeout/cancel 已经留下了不完整的 tool-call checkpoint,下一轮用户输入加载初始状态时会跳过这类不安全 checkpoint,并回退到最近一个可以安全追加 user message 的 checkpoint。

    本次修改点:

    1. 新增 MessageSequenceValidator,判断 checkpoint 中的 messages 是否可以作为下一轮 user input 的基底。
    2. CompiledGraph.getInitialState(...) 不再无条件使用 latest checkpoint,而是从 latest-first checkpoint history 中选择最近的 safe checkpoint。
    3. 不修改、不删除历史 checkpoint,也不伪造空的 assistant message;只是避免下一轮从非法消息序列恢复。

    会被跳过的 checkpoint 包括:

    • assistant tool calls 没有对应 tool responses;
    • 多个 tool calls 只有部分 tool responses;
    • tool response 后没有最终 assistant message;
    • tool -> user 这种会导致 OpenAI / DashScope-compatible message ordering 非法的历史。

    已补充覆盖:

    • tool 节点写入 checkpoint 后 downstream cancel,下一轮仍能构造合法 OpenAI-compatible messages;
    • streaming model 开始后 timeout,下一轮仍能构造合法 OpenAI-compatible messages;
    • latest checkpoint 以 ToolResponseMessage 结尾时,会回退到上一个 safe checkpoint;
    • validator 对未闭合 tool-call 链路、partial tool responses、完整闭合链路的判断;
    • 现有 resume message order 和 streaming tool-call merge 回归。

    本地验证:

    mvn -pl spring-ai-alibaba-graph-core -Dtest=CheckpointRollbackConsistencyTest,MessageSequenceValidatorTest,GraphRunnerContextResumeMessageOrderTest,StreamFunctionCallTest test
    Tests run: 9, Failures: 0, Errors: 0, Skipped: 0
    
    mvn -pl spring-ai-alibaba-graph-core checkstyle:check
    You have 0 Checkstyle violations.
    
    mvn -pl spring-ai-alibaba-graph-core spotless:check
    0 needs changes
    
    git diff --check
    no whitespace errors
    
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions