🔥 不只是 Token 流：Solon AI 4.1 的语义化聊天事件

LLM 流式输出看起来像是不断返回文本分片，但现代模型的一条连接中可能同时出现正文、思考过程、工具参数、引用、媒体、安全事件、用量快照、状态和错误。若把每一帧都包装成“部分 ChatResponse”，调用方很难区分过程数据和最终结果，也容易把供应商协议细节带进 UI、Agent 和网关。 Solon AI 4.1 将流式接口调整为： 4.1 之前：Flux<ChatResponse> 4.1： Flux<ChatEvent> 其中： ChatEvent 表示响应进行中的语义事件； ChatResponse 表示已经聚合的结果； call() 与 stream() 回答不同问题 同步调用直接取得完整结果： ChatResponse response = chatModel.prompt("解释语义化流式输出").call(); String text = response.getText(); 流式调用观察响应生命周期： Flux<ChatEvent> events = chatModel .prompt("解释语义化流式输出") .stream(); 只投影正文时，应按精确事件类型过滤： Flux<String> text = chatModel.prompt(message).stream() .filter(event -> event.is(ChatEventType.TEXT_DELTA) && event.hasText()) .map(ChatEvent::getText); 这里不能只用 isDelta()，因为增量事件还可能是思考、工具参数、媒体片段或拒答。getText() 也允许为空，因此映射前要先调用 hasText()。 九组事件构成稳定路由层 当前源码定义了 31 种事件，归入九个分组： 分组 语义 代表事件 LIFECYCLE 整个响应生命周期 RESPONSE_START、RESPONSE_END、ABORT STEP 一轮模型调用 STEP_START、STEP_END TEXT 用户可见正文 TEXT_START、TEXT_DELTA、TEXT_END THINKING 思考相关输出 THINKING_START、THINKING_DELTA、THINKING_END TOOL_CALL 客户端执行工具 TOOL_CALL_START、TOOL_CALL_ARGS_DELTA、TOOL_RESULT SERVER_TOOL 供应商侧工具 SERVER_TOOL_START、SERVER_TOOL_RESULT MEDIA 引用与媒体 CITATION、MEDIA_PARTIAL、MEDIA_DONE SAFETY 拒答与内容过滤 REFUSAL_DELTA、CONTENT_FILTER META 用量、错误、原始与自定义数据 USAGE、ERROR、RAW、CUSTOM 通用消费端可以先按分组路由，再在组内识别具体类型。这样新增具体事件时，不需要把整个消费者改写为封闭式枚举分支。 END 阶段不等于全流终止 TEXT_END、THINKING_END、TOOL_CALL_END 和 STEP_END 只关闭局部范围。当前 isTerminal() 只对以下三类返回 true： RESPONSE_END ABORT ERROR 因此不能用 event.getPhase() == END 判断整个响应是否结束。ERROR 是终止事件，但它的阶段为 NONE；多个局部事件阶段为 END，却不会终止整个响应。 从 RESPONSE_END 获取最终聚合 同步提取： ChatResponse response = chatModel.prompt(query).stream() .filter(event -> event.is(ChatEventType.RESPONSE_END)) .map(ChatEvent::getResponse) .blockFirst(); 响应式提取： Mono<ChatResponse> response = chatModel.prompt(query).stream() .filter(event -> event.is(ChatEventType.RESPONSE_END)) .map(ChatEvent::getResponse) .next(); 不要直接对整个事件流调用 blockFirst()，因为第一个事件通常是 RESPONSE_START。前端可以自行拼接 TEXT_DELTA 做打字机效果，但完整消息、工具调用和用量应以 Solon AI 聚合的终态响应为准。 Normalizer 把供应商帧变成可消费协议 供应商流不一定有完整边界。ChatEventNormalizer 负责补齐和整理： TEXT_START -> TEXT_DELTA* -> TEXT_END THINKING_START -> THINKING_DELTA* -> THINKING_END TOOL_CALL_START -> TOOL_CALL_ARGS_DELTA* -> TOOL_CALL_END 正文和思考采用较严格的块跟踪： 裸增量可自动补开始事件； 重复开始事件会被丢弃； 没有对应开始的结束事件会被丢弃； 正文与思考切换时会关闭前一个块； 正常或错误收尾时补齐仍开放的块。 工具调用采取更宽松的策略。后续参数分片可能不再携带完整调用 ID，因此归一化器倾向于“缺边界时补齐”，而不是充当严格协议校验器。 业务端不应把某个 TOOL_CALL_ARGS_DELTA 当成完整 JSON。完整工具调用应从已完成步骤或最终响应中读取。 自动工具调用引入 Step 一次工具辅助回答通常包含多轮模型请求： RESPONSE_START STEP_START (0) TOOL_CALL_START TOOL_CALL_ARGS_DELTA ... TOOL_CALL_END TOOL_RESULT STEP_END (0) STEP_START (1) TEXT_START TEXT_DELTA ... TEXT_END STEP_END (1) RESPONSE_END 整个过程只有一个响应生命周期，每轮模型调用对应一个 step。当前实现从 step 0 开始递增。 正常完成的 STEP_END 携带该步终态快照和该步用量；RESPONSE_END 携带整个成功响应的聚合结果和跨步骤总用量。这使监控系统既能分析单轮调用，也能分析完整工具链路。 用量聚合有两个层次 同一步中的供应商 usage 通常是累计快照，不能对每帧直接相加；不同 step 是独立模型请求，需要跨步累计。 步内：保留或合并供应商累计快照 步间：累加正常完成步骤的 usage 因此： STEP_END.getUsage() 是当前步骤用量； RESPONSE_END.getUsage() 是整个成功响应的累计用量； 单个 USAGE 事件不等于“把所有字段再次加入全局计数器”。 ERROR、ABORT 与 cancel 是三件事 ERROR 与 Reactor onError 进入主要响应式错误路径的失败，会尝试先发 ERROR 事件，再触发 Reactor onError： ERROR 用于携带语义上下文，例如此前已完成步骤的结果或累计用量； onError 用于 retryWhen、onErrorResume、超时和降级。 它们描述的是同一次失败。ERROR.getResponse() 也不保证包含当前失败步骤已经流出的所有文本；首步很早失败时，它可能为空。 自定义过滤器可以过滤掉属于 META 的 ERROR，因此无论是否处理错误事件，都应保留 Reactor 错误消费者。 ABORT ABORT 是上游语义事件，不等于订阅方取消。 Reactor cancel take(...) 等操作符可能主动取消订阅。取消后不能期待额外的 TEXT_END、STEP_END、ABORT 或 RESPONSE_END。资源清理应放在 doFinally 等 Reactor 生命周期钩子中。 事件过滤只控制投递 默认过滤器会拒绝 HEARTBEAT 和 RAW。诊断或网关场景可以显式开启全部事件： chatModel.prompt(query) .eventFilter(ChatEventFilter.all()) .stream(); 也可在默认策略上开放 RAW： ChatEventFilter filter = ChatEventFilter.DEFAULT.or( ChatEventFilter.of(ChatEventType.RAW)); 当前源码还有一个细节：运行时会对非空自定义过滤器增加保护，强制保留 LIFECYCLE 和 STEP。所以 of(TEXT_DELTA) 并不意味着订阅方只会收到正文增量。稳妥做法是： eventFilter 控制粗粒度投递； 下游再次按精确事件类型做业务投影； 只有协议诊断或透传确实需要时才用 all()。 过滤发生在内部归一化与聚合之后，因此订阅方看不到某个事件，不会反向破坏 Solon AI 的终态聚合。 自定义方言只负责协议翻译 方言的流式解析入口为： void parseResponseJson(ChatStreamContext ctx, String respJson); 正文、思考和客户端工具调用通常进入 accumulator，由核心统一产生标准事件与聚合结果；引用、状态、供应商侧工具、媒体等扩展语义可以直接发射事件。 同一份语义负载不要同时写入 accumulator 又直接 emit，否则可能造成重复增量和重复聚合。 迁移清单 从 4.1 之前的流式代码迁移时： 将 Flux<ChatResponse> 改为 Flux<ChatEvent>； 只用 TEXT_DELTA + hasText() 渲染正文； 将思考与正文分开路由； 不要把 isDelta() 当成正文判断； 先过滤 RESPONSE_END，再用 blockFirst() 或 next() 获取终态； 不要从单个工具参数分片解析完整调用； 区分 step usage 与 response usage； 即使处理 ERROR 事件，也保留 Reactor onError； 不把 cancel 当作 ABORT； 自定义方言迁移到 parseResponseJson(ChatStreamContext, String)； 后续升级时重新核对 4.1 预览 API。 测试核验 本次对源码检出的三个确定性核心测试类执行了验证： ChatEventNormalizerTest 20 ChatEventFilterTest 6 ChatStreamSessionUsageTest 9 -------------------------------- 合计 35 结果： Tests run: 35, Failures: 0, Errors: 0, Skipped: 0 BUILD SUCCESS 这些测试覆盖边界归一化、过滤组合和跨步骤用量聚合，但不能证明所有供应商、所有任意事件序列、所有并发情况或整个负载对象图的深度不可变性。不同供应商也不一定都会产生思考、引用、媒体、安全、服务端工具和用量事件。 总结 Solon AI 4.1 的关键变化不是“多了 31 个枚举”，而是形成了清晰分层： 供应商 SSE / JSON 帧 ↓ 方言解析 ↓ 语义累积与事件发射 ↓ 边界归一化 ↓ UI、Agent、监控和协议适配 Token 流回答“下一段字符是什么”，语义事件流回答“下一件发生的事是什么”。当系统开始组合思考、工具、引用、安全事件和多轮模型调用时，后一个问题更适合支撑可维护的工程架构。