1. 从“一问一答”到“逐字输出”为什么流式响应是LLM集成的刚需如果你最近在捣鼓Spring Boot项目里集成大语言模型LLM比如调用OpenAI的GPT、Claude或者国内的文心一言、通义千问这些API那你大概率已经踩过第一个坑了请求发出去后界面卡住转半天圈然后“唰”一下一整段答案突然全弹出来。这种感觉对于用户来说体验是割裂的。尤其是在生成长文本、代码或者需要逐步推理的场景下用户看着空白的界面心里会打鼓“是不是卡死了”“服务器崩了” 这种不确定性极大地损害了交互的流畅感和信任感。而流式响应Streaming Response要解决的就是这个“等待焦虑”问题。它让LLM的思考过程变得可见答案像打字一样一个字、一个词地“流”到前端这才是符合人类对话直觉的体验。在Spring Boot的语境下实现流式响应远不止是让前端有个“打字机”效果那么简单。它背后是一整套技术栈的选型和架构思想的转变。传统的Spring MVC是基于Servlet的同步阻塞模型一个HTTP请求对应一个线程线程必须等待后端LLM API完全生成完毕才能一次性返回结果。而LLM生成一段几百字的回复可能需要好几秒甚至十几秒这意味着宝贵的服务器线程资源被长时间占用并发能力急剧下降。所以当我们谈论“Spring Boot中实现LLM流式响应”时我们实际上在讨论两件事技术体验升级将同步阻塞的“批处理”式交互升级为异步非阻塞的“实时流”式交互。资源效率优化避免线程阻塞用更少的资源支撑更高的并发请求。从热搜词Spring WebFlux和SseEmitter的出现就能看出社区的主流解决方案已经聚焦在这两个核心组件上。SseEmitter代表了在传统Servlet栈上“打补丁”实现服务器推送的能力而WebFlux则代表了拥抱响应式编程、从底层重构的非阻塞架构。接下来我们就深入这两种“最佳实践”看看它们分别怎么玩以及你该在什么场景下选择谁。2. 基石理解LLM API的流式接口与数据格式在动手写Spring Boot代码之前我们必须先搞清楚“流”从哪里来。目前主流的LLM服务提供商其API设计都遵循了类似的原则。以OpenAI的Chat Completion API为例当你希望以流式方式获取回复时需要在请求体中设置stream: true。此时API返回的不再是一个完整的JSON对象而是一个遵循Server-Sent Events (SSE)规范的流。每个数据块chunk是一个独立的JSON对象用data:前缀分隔并以两个换行符\n\n结尾。一个典型的数据块看起来是这样的data: {id:chatcmpl-xxx,object:chat.completion.chunk,created:1234567890,model:gpt-4,choices:[{index:0,delta:{content:你},finish_reason:null}]}\n\n data: {id:chatcmpl-xxx,object:chat.completion.chunk,created:1234567890,model:gpt-4,choices:[{index:0,delta:{content:好},finish_reason:null}]}\n\n关键字段是choices[0].delta.content它包含了本次流式返回的文本增量。当整个回复生成完毕时会收到一个特殊的结束块data: {id:chatcmpl-xxx,object:chat.completion.chunk,created:1234567890,model:gpt-4,choices:[{index:0,delta:{},finish_reason:stop}]}\n\n data: [DONE]\n\n国内的大模型厂商如百度文心、阿里通义等其流式接口设计也大同小异可能字段名略有不同比如有的叫content有的叫result但核心模式都是分块chunk的、增量式的数据推送。这里有一个至关重要的实操细节这些API返回的原始流通常是一个application/x-ndjson换行分隔的JSON或纯文本流。我们的Spring Boot后端角色是一个“代理”或“中继”。它需要以流式方式调用LLM的API。持续不断地读取这个流解析每一个数据块。将解析出的文本增量content以某种方式再“流式”地推送给我们的前端客户端。理解了这个数据流动的链条LLM API - Spring Boot后端 - 浏览器我们才能正确设计后端的处理逻辑。两种最佳实践SseEmitter和WebFlux的核心区别就在于如何高效、可靠地实现这个“中继”过程。3. 实践一基于SseEmitter的轻量级Servlet栈方案如果你的项目是基于传统的Spring MVCServlet容器如Tomcat并且你不想引入响应式编程这套新概念那么SseEmitter是你的首选。它是Spring框架为Servlet异步处理提供的工具专门用于实现服务器向客户端的单向事件流。3.1 SseEmitter的核心工作机制与生命周期SseEmitter本质上是对DeferredResult的封装专为SSE协议优化。当你创建一个SseEmitter对象通常可以指定一个超时时间如new SseEmitter(30_000L)并返回给Spring MVC时请求的处理线程会立即释放但HTTP连接保持打开。此后你可以在任何其他线程比如处理LLM响应的线程中通过这个emitter对象向客户端发送数据。它的生命周期非常清晰创建与绑定在控制器方法中创建并返回。事件发送通过emitter.send(SseEmitter.event().data(“Hello”))方法发送事件。这里的data()可以发送字符串、对象会被Jackson序列化为JSON。完成与错误处理LLM流式读取完成后调用emitter.complete()来正常关闭连接。如果在任何阶段发生异常如LLM API调用失败、网络中断应调用emitter.completeWithError(exception)这也会向前端发送一个错误事件。超时与回调可以注册onCompletion和onTimeout回调用于资源清理和日志记录。3.2 完整实现步骤与关键代码拆解假设我们有一个非常简单的需求提供一个/chat/stream的POST接口接收用户消息转发给LLM API并将流式结果推送给前端。第一步控制器层设计RestController RequestMapping(/api/chat) Slf4j public class ChatController { Autowired private ChatStreamService chatStreamService; PostMapping(/stream) public SseEmitter streamChat(RequestBody ChatRequest request) { // 1. 创建SseEmitter设置超时时间建议略大于LLM生成最大预期时间 SseEmitter emitter new SseEmitter(120_000L); // 120秒超时 // 2. 提交异步任务避免阻塞当前Servlet线程 CompletableFuture.runAsync(() - { try { chatStreamService.streamResponse(request, emitter); } catch (Exception e) { emitter.completeWithError(e); log.error(流式处理失败, e); } }); // 3. 设置回调用于连接结束时的资源清理 emitter.onCompletion(() - log.debug(SSE连接完成)); emitter.onTimeout(() - { log.warn(SSE连接超时); emitter.complete(); }); emitter.onError((ex) - log.error(SSE连接错误, ex)); // 4. 立即返回SseEmitter对象释放请求线程 return emitter; } }关键点控制器方法必须立即返回SseEmitter对象。所有耗时的LLM交互逻辑必须封装在另一个服务方法中并通过CompletableFuture或任务执行器异步执行绝不能阻塞streamChat方法本身。第二步服务层实现流式中继逻辑这是最核心的部分我们需要一个HTTP客户端来流式调用LLM API并桥接到SseEmitter。Service Slf4j public class ChatStreamService { Value(${llm.api.url}) private String llmApiUrl; Value(${llm.api.key}) private String apiKey; public void streamResponse(ChatRequest request, SseEmitter emitter) throws IOException { // 1. 构建LLM API请求 HttpRequest llmRequest HttpRequest.newBuilder() .uri(URI.create(llmApiUrl)) .header(Content-Type, application/json) .header(Authorization, Bearer apiKey) .POST(HttpRequest.BodyPublishers.ofString(buildRequestBody(request))) .build(); // 2. 使用HttpClient发送请求并配置为流式接收 HttpClient client HttpClient.newHttpClient(); client.sendAsync(llmRequest, HttpResponse.BodyHandlers.ofLines()) .thenAccept(response - { // 3. 处理流式响应体 response.body().forEach(line - { if (line.startsWith(data: )) { String data line.substring(6).trim(); // 去掉data: 前缀 if ([DONE].equals(data)) { emitter.complete(); return; } try { // 4. 解析JSON提取content字段 JsonNode node new ObjectMapper().readTree(data); String content node.path(choices).get(0).path(delta).path(content).asText(null); if (content ! null !content.isEmpty()) { // 5. 通过SseEmitter发送给前端 emitter.send(SseEmitter.event().data(content)); } } catch (JsonProcessingException e) { log.warn(解析SSE数据块失败: {}, line, e); } catch (IOException e) { log.warn(向客户端发送数据失败, e); // 发送失败通常意味着客户端已断开可以中断处理 throw new RuntimeException(e); } } }); }) .exceptionally(ex - { emitter.completeWithError(ex); return null; }); } private String buildRequestBody(ChatRequest request) { // 构建LLM API所需的JSON请求体注意设置 stream: true ObjectMapper mapper new ObjectMapper(); ObjectNode root mapper.createObjectNode(); root.putArray(messages).addObject() .put(role, user) .put(content, request.getMessage()); root.put(model, gpt-3.5-turbo); root.put(stream, true); // 关键参数 // ... 其他参数如temperature, max_tokens等 return root.toString(); } }关键点解析与避坑指南使用HttpResponse.BodyHandlers.ofLines()这是Java 11HttpClient的利器它能将响应体按行流式处理完美匹配SSE的data: ...\n\n格式。避免使用ofString()那会等待整个响应体失去流式意义。异常处理要闭环HttpClient.sendAsync是异步的必须在exceptionally回调中将异常传递给emitter否则前端可能永远等不到响应或错误提示。连接状态管理在emitter.send()时可能抛出IOException这通常意味着客户端浏览器提前关闭了连接比如用户关了页面。此时应该中断后续处理避免无谓的LLM API调用和资源浪费。上面的代码通过抛出RuntimeException来触发外层异常处理是一种简化的方式更严谨的做法是检查emitter的状态。JSON解析性能对于每个数据块都new ObjectMapper()并readTree在高频流下可能有性能开销。可以考虑复用ObjectMapper实例或者使用更轻量的JSON解析器如JsonFactory直接解析特定字段。第三步前端如何连接前端使用EventSourceAPI可以轻松连接。const eventSource new EventSource(/api/chat/stream?message你好); // 注意EventSource只支持GET // 或者更常见的用POST传递复杂数据需要使用fetch模拟SSE function streamChat(message) { fetch(/api/chat/stream, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ message: message }) }).then(response { const reader response.body.getReader(); const decoder new TextDecoder(); function read() { return reader.read().then(({done, value}) { if (done) { console.log(流结束); return; } const chunk decoder.decode(value); // 处理接收到的数据块可能是多个SSE事件 processSSEChunk(chunk); return read(); // 继续读取下一个块 }); } return read(); }); }注意这是使用fetch读取流式响应的通用模式。如果后端严格遵循SSE格式data: ...\n\n前端也可以使用专门的SSE客户端库它们能自动处理重连、事件解析等。3.3 SseEmitter方案的优缺点与适用场景优点侵入性低无需改变项目整体架构在现有Spring MVC项目中即可快速集成。概念简单对于熟悉Servlet异步处理的开发者来说SseEmitter的API直观易懂。资源可控连接生命周期明确便于管理和监控。缺点与局限Servlet线程模型限制虽然请求线程被释放但底层仍然依赖Servlet容器的I/O处理。在极端高并发下大量保持打开的连接可能对容器如Tomcat造成压力需要调整maxConnections、connectionTimeout等参数。错误处理稍显繁琐需要手动管理异步任务、异常传递和连接状态。单向通信SSE是服务器向客户端的单向通道。如果需要双向流式通信如语音对话SSE就不适合了。适用场景传统的、基于Spring MVC的Web应用。需要快速为LLM集成添加流式输出功能且并发量不是极端高的场景。功能需求明确为服务器向浏览器推送文本流。4. 实践二基于WebFlux的响应式全栈方案如果你的项目是全新的或者你愿意拥抱更现代的架构以应对高并发、低延迟的挑战那么Spring WebFlux是更彻底、更强大的选择。WebFlux构建在Project Reactor之上采用非阻塞I/O模型通常运行在Netty上从底层到顶层都是为处理异步数据流而设计的。4.1 为什么WebFlux是流式处理的“原生家园”在SseEmitter方案中我们是在同步阻塞的世界里“模拟”异步流。而在WebFlux中流Flux是一等公民。一个HTTP请求可以映射为一个FluxT流框架会自动处理流的订阅、背压Backpressure和数据的按需推送。这意味着真正的非阻塞从网络I/O到业务逻辑没有线程会因为等待而阻塞。一个事件循环线程可以处理成千上万的并发连接。背压支持如果客户端处理速度慢服务器可以感知并减慢数据推送速度避免内存溢出这是响应式编程的核心优势之一。声明式编程你可以用类似map、filter、flatMap的操作符来处理数据流代码更简洁更专注于业务逻辑。4.2 使用WebClient实现响应式中继在WebFlux中我们使用WebClient同样是响应式的来调用外部LLM API并将返回的流直接映射为返回给前端的流。第一步添加依赖与配置确保你的pom.xml或build.gradle中包含了Spring Boot WebFlux的starter。dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-webflux/artifactId /dependency第二步编写响应式控制器与服务RestController RequestMapping(/api/reactive/chat) public class ReactiveChatController { Autowired private ReactiveChatService chatService; PostMapping(value /stream, produces MediaType.TEXT_EVENT_STREAM_VALUE) // 关键声明SSE媒体类型 public FluxServerSentEventString streamChat(RequestBody ChatRequest request) { return chatService.streamLlmResponse(request.getMessage()) .map(content - ServerSentEvent.builder(content).build()) // 包装成SSE事件 .onErrorResume(e - { log.error(流处理错误, e); // 返回一个错误事件流然后结束 return Flux.just(ServerSentEvent.builder(【服务错误】 e.getMessage()).build()) .concatWith(Flux.empty()); }); } }控制器方法直接返回FluxServerSentEventString。produces MediaType.TEXT_EVENT_STREAM_VALUE注解告诉框架这个端点返回的是SSE流。ServerSentEvent是WebFlux提供的用于构建SSE事件的工具类。第三步核心服务层——使用WebClient桥接流Service public class ReactiveChatService { private final WebClient webClient; public ReactiveChatService(WebClient.Builder builder, Value(${llm.api.url}) String baseUrl) { this.webClient builder.baseUrl(baseUrl).build(); } public FluxString streamLlmResponse(String userMessage) { // 1. 构建请求体 LlmRequest llmRequest new LlmRequest(userMessage, true); // 包含 stream: true // 2. 发起请求并指定以SSE流的形式接收响应 return webClient.post() .uri(/v1/chat/completions) .header(Authorization, Bearer apiKey) .contentType(MediaType.APPLICATION_JSON) .bodyValue(llmRequest) .accept(MediaType.TEXT_EVENT_STREAM) // 关键声明接受SSE流 .retrieve() .bodyToFlux(String.class) // 将响应体转换为FluxString每一行都是一个数据块 .takeUntil(line - [DONE].equals(line.trim())) // 遇到[DONE]停止 .filter(line - line.startsWith(data: )) .map(line - line.substring(6).trim()) // 去掉data: .filter(data - !data.isEmpty() ![DONE].equals(data)) .flatMap(data - Mono.fromCallable(() - { // 3. 解析JSON提取content。使用fromCallable包装可能阻塞的解析操作 JsonNode node new ObjectMapper().readTree(data); return node.path(choices).get(0).path(delta).path(content).asText(null); }).subscribeOn(Schedulers.boundedElastic())) // 在弹性线程池执行解析避免阻塞响应式线程 .filter(content - content ! null !content.isEmpty()); } }关键点解析与高级技巧accept(MediaType.TEXT_EVENT_STREAM)这是告诉WebClient我们期望服务器返回SSE流。WebClient会相应地处理data:前缀和\n\n分隔符。bodyToFlux(String.class)这是魔法发生的地方。它不会等待整个响应而是将接收到的字节缓冲区分行后源源不断地发射给下游的Flux。使用flatMap与弹性线程池JSON解析ObjectMapper.readTree是一个潜在的阻塞操作虽然很快但在严格非阻塞场景下需注意。我们使用Mono.fromCallable将其包装并通过.subscribeOn(Schedulers.boundedElastic())将其调度到一个专门的、用于阻塞任务的弹性线程池中执行。这确保了核心的响应式线程事件循环永远不会被阻塞。背压的自动传递如果前端处理慢Flux的背压机制会一直传递到WebClient的HTTP连接最终可能减慢从LLM API读取数据的速度实现全链路的流量控制。4.3 错误处理、超时与连接管理在响应式世界里错误处理是流的一部分。public FluxString streamLlmResponse(String userMessage) { return webClient.post() // ... 请求构建 .retrieve() .onStatus(status - status.isError(), response - { // 处理HTTP错误状态码 return response.bodyToMono(String.class) .flatMap(errorBody - Mono.error(new RuntimeException(LLM API Error: response.statusCode() - errorBody))); }) .bodyToFlux(String.class) .timeout(Duration.ofSeconds(90)) // 设置流超时时间 .doOnError(IOException.class, e - log.error(网络I/O错误, e)) .doOnError(TimeoutException.class, e - log.warn(流响应超时, e)) .retryWhen(Retry.backoff(3, Duration.ofSeconds(1)) // 失败重试策略 .filter(throwable - throwable instanceof IOException)); // ... 后续的数据处理操作符 }onStatus处理HTTP 4xx/5xx错误将其转换为业务异常。timeout为整个流设置一个总超时时间避免无限等待。doOnError副作用操作用于记录日志不会改变流。retryWhen定义重试逻辑。例如对于网络IO错误可以尝试指数退避重试。4.4 WebFlux方案的优缺点与适用场景优点极高的资源利用率非阻塞I/O模型可以用少量线程处理海量并发连接特别适合聊天、通知等长连接场景。完整的响应式栈从控制器到HTTP客户端编程模型统一流处理能力强大背压支持完善。强大的流操作符Reactor库提供了丰富的操作符filter,map,flatMap,zip,buffer等可以轻松实现复杂的流转换和组合逻辑。缺点与挑战学习曲线陡峭响应式编程范式Mono/Flux、订阅、背压与传统的命令式编程差异较大需要团队学习成本。调试复杂性异步流的调用栈不直观错误信息可能难以追踪需要借助专门的工具和经验。阻塞操作陷阱在响应式线程中意外执行阻塞操作如同步数据库调用、文件IO会严重破坏非阻塞优势必须格外小心。适用场景全新的、对高并发和低延迟有要求的项目。微服务架构中需要处理大量服务间流式通信的场景。团队愿意并能够接受响应式编程范式。5. 关键决策SseEmitter vs WebFlux我该如何选看了两种方案的实现你可能已经有点感觉了。选择哪一个不是一个单纯的技术优劣问题而是一个结合项目现状、团队能力和未来规划的架构决策。1. 技术栈与项目阶段现有Spring MVC项目快速上线功能无脑选SseEmitter。它的集成成本最低风险最小能让你的LLM流式功能在几天内跑起来。全新项目或重大重构追求技术前沿与极致性能认真考虑WebFlux。它为未来的扩展如集成更多响应式数据库、消息队列打下了更好的基础。2. 并发规模与性能要求预期QPS在几百到几千连接数在几千级别SseEmitter配合合理的Tomcat调优如调整线程池、连接器参数完全可以胜任。预期连接数上万或需要极低的响应延迟WebFlux的非阻塞模型优势会非常明显。它能用更少的硬件资源支撑更高的并发。3. 团队技能与维护成本团队熟悉Spring MVC对异步编程了解不深从SseEmitter入手更稳妥。它的问题域相对封闭更容易理解和调试。团队有探索精神或已有响应式编程经验可以挑战WebFlux。长期来看统一的响应式模型能减少认知负担。4. 功能需求的复杂性简单的问答流式输出两者都能很好地实现。需要复杂的流处理例如需要将用户输入流、LLM输出流和另一个知识库查询流进行实时合并与处理。WebFlux的Flux操作符如merge、zipWith会让这种场景的实现变得优雅而简单而在SseEmitter方案中实现类似功能会非常笨拙。一个折中的建议对于大多数中小型项目如果是从零开始我个人的倾向是优先使用SseEmitter。它的简单性和可控性在项目初期是巨大的优势。当业务增长到一定规模真的遇到了SseEmitter的瓶颈监控发现Tomcat线程池成为瓶颈再考虑将流式接口这部分单独迁移到基于WebFlux的微服务中而不是重构整个应用。这种渐进式的演进策略往往更稳健。6. 超越基础生产环境必须考虑的进阶问题无论选择哪种方案把Demo跑通只是第一步。要上线生产环境以下几个问题你必须给出答案。6.1 身份认证与授权流式接口也是API不能裸奔。但SSE或流式HTTP连接无法像普通REST API那样在每次请求中携带HeaderEventSourceAPI限制。常见的解决方案有Token in URL在建立SSE连接的URL中携带一个短期有效的Token如/stream?tokenxxx。但需注意Token可能出现在日志中存在安全风险。先鉴权后建连客户端先调用一个普通的登录/鉴权接口获取一个专用于流式连接的channelId或sessionToken。随后建立SSE连接时在URL或第一个数据包中携带这个channelId服务端将其与之前的鉴权会话绑定。WebSocket如果需要双向、安全的流式通信WebSocket是比SSE更通用的选择它可以自由携带Header。但实现复杂度更高。6.2 上下文管理与会话保持LLM对话通常需要上下文。在流式场景下一次连接对应一轮对话。你需要设计机制来关联同一个用户的多次流式请求。前端维护前端在每次流式请求结束后保存服务器返回的上下文ID如conversationId下次请求时携带。后端会话在服务器端为用户创建会话将SseEmitter或Flux的订阅与用户会话绑定。当连接断开超时、错误、主动完成时清理相关资源。6.3 监控、日志与可观测性流式连接是长生命周期的传统的基于请求/响应的监控指标可能不适用。连接数监控活跃的SseEmitter实例数或Flux订阅数这是系统负载的关键指标。流持续时间与数据量记录每个流从创建到结束的时长以及总共推送的数据包数量/大小用于分析用户体验和成本。错误率特别关注连接异常断开客户端中止、网络错误的比例。分布式追踪如果一个请求的流式响应涉及多个微服务如先查知识库再调LLM需要确保追踪IDTrace ID能在整个流式链路中传递以便排查问题。6.4 流量控制与熔断降级LLM API通常是按Token收费且可能有速率限制。你需要保护你的服务。限流在网关或应用层对用户或IP的流式连接创建速率进行限制。熔断如果下游LLM API持续超时或报错应快速失败熔断流式接口直接向前端返回错误而不是让用户无限等待。优雅降级当LLM服务不可用时是否可以降级为返回一个静态提示或者排队提示这需要在设计交互流程时考虑。6.5 前端体验优化后端提供了流前端的表现同样重要。自动滚动确保新的内容能自动滚动到可视区域。中断生成提供“停止生成”按钮点击后前端关闭EventSource或fetch流后端也需要能感知并中断对LLM API的调用避免浪费资源。错误提示与重连网络不稳定时前端应能友好提示并可能实现自动重连机制EventSource有内置重连但自定义fetch流需要自己实现。实现Spring Boot中的LLM流式响应从SseEmitter的轻量快捷到WebFlux的彻底重塑两种路径清晰地反映了软件工程中经典的“渐进改进”与“范式迁移”的选择。没有绝对的好坏只有是否适合。我的经验是先从SseEmitter把核心功能跑起来快速验证业务价值。当流量上来你真切地感受到线程池的力不从心或者业务逻辑需要更复杂的流处理时便是考虑向WebFlux演进的最佳时机。在这个过程中理解数据流的本质从LLM API到用户浏览器、妥善处理异常与资源、并设计好面向生产环境的监控与治理远比纠结于选择哪个技术组件更为重要。