SpringAI流式对话全栈实践：SSE与Flux实现打字机效果

1. 项目概述与核心需求解析1.1 这个项目到底解决什么问题先说结论SpringAI不是让Java开发者去跟OpenAI官方SDK较劲的东西它把大模型对话能力做成了Spring风格的工具箱让你能用写Controller和Service的方式去调大模型。最近折腾这个SpringAI流式对话(带前端)的项目核心就两个功能模块基础对话和流式输出。基础对话好理解就是用户发一句话后端调大模型等完整结果返回再回给前端。流式输出则完全不一样它允许大模型在生成过程中把一个个token逐渐推到前端用户能看到打字机般的实时效果而不是盯着转圈等十几秒。我带前端的这个方案本质上是一个完整的全栈对话机器人工程包含Spring Boot后端、Thymeleaf或Vue前端页面、以及SpringAI对大模型的统一接入层。做一个这样的会话界面价值不只是能聊而是把流式数据从大模型一路传到浏览器的完整链路跑通顺便把前端的打字机效果、流式渲染优化、异常处理这些细节都吃透。1.2 适合谁来参考这个项目适合三类人一是正在学SpringAI但官网示例只有curl测试没有页面的朋友二是要给内部系统加一个AI对话助手的后端开发前端技术栈薄弱但需要快速出一个可用的交互界面三是准备做毕业设计、想展示全栈能力的同学——一个带漂亮前端流式打字效果的AI对话项目在答辩中很容易讲清技术亮点。我这次做的界面没有用太重的前端框架而是用原生HTML加Fetch API处理流式响应核心原因后面会讲到。先把整个工程怎么搭起来、每一步为什么这么做讲透。注意SpringAI目前对模型的支持覆盖面很广OpenAI、通义千问、Ollama本地模型都能接。下面以最常见的OpenAI兼容接口作为主示例其他接入方式在文末会补充。2. 工程搭建与整体架构设计2.1 选型思路为什么是SpringAI先说选型。在SpringAI出现之前Java后端接大模型无非两条路直接用OpenAI或各家云厂商的SDK或者自己用RestTemplate/WebClient手写HTTP调用。这两条路都难受。SDK写法五花八门各家参数风格不一样手写HTTP请求又要把鉴权、错误码、流式解析全做一遍代码重复率高得离谱。SpringAI走的是Spring生态最擅长的路子统一抽象加自动配置。它把模型调用封装成一个ChatClient你只需要注入它组织好Prompt消息结构剩下的配置扔到application.yml里。模型切换时改配置比改代码多。而且SpringAI对流式的支持非常优雅底层用的是WebFlux的Flux流天然适配推模式。这意味着后端到前端的链路可以用SSEServer-Sent Events来推流前段用原生的EventSource或者fetch流式读取都能接。这是这个项目最核心的技术路线下面详细展开。2.2 Maven工程结构与依赖配置创建Spring Boot工程Java版本选17或21都行Spring Boot版本建议3.2以上因为SpringAI的官方Starter对Boot 3.x支持得最好。我在实际搭建中用的组合是Spring Boot 3.2.5、Spring AI 1.0.0-M6注意这个版本迭代很快建议用当前最新稳定版。工程结构上我的做法是springai-chat-demo ├── pom.xml ├── src/main/java/com/example/chat │ ├── ChatApplication.java │ ├── controller │ │ └── ChatController.java │ ├── service │ │ └── ChatService.java │ └── config │ └── ChatConfig.java ├── src/main/resources │ ├── application.yml │ └── static │ ├── index.html │ ├── css/style.css │ └── js/chat.jspom.xml里最核心的依赖dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId version1.0.0-M6/version /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-webflux/artifactId /dependency这里有个容易被坑的点spring-ai-openai-spring-boot-starter目前还在里程碑版本阶段中央仓库的坐标和正式版不一样有些老教程用的是spring-ai-spring-boot-starter。如果编译时拉不到依赖去Spring官方文档的Release Notes里找最新的dependency坐标。2.3 统一配置把模型信息收敛到application.yml模型相关的配置全部放application.yml不散落在代码里。这样做的好处是后续切换模型、换Key、调参数都只需要改配置spring: ai: openai: api-key: ${OPENAI_API_KEY:sk-xxxx} base-url: ${OPENAI_BASE_URL:https://api.openai.com} chat: options: model: gpt-4o-mini temperature: 0.7 max-tokens: 2048 stream: truebase-url支持自定义非常重要。国内开发者如果用的是各种中转服务或者兼容OpenAI接口的国内大模型改这里就行代码一行不用动。stream: true虽然配置在这里但后续控制器里我们也会显式控制流式开关双重保障。这里的${OPENAI_API_KEY:sk-xxxx}写法是Spring的占位符语法支持环境变量注入避免把密钥硬编码提交到Git仓库。这也是我在实际项目里坚持的底线任何密钥不进代码库。3. 后端核心逻辑实现3.1 基础对话先跑通非流式后端逻辑我从非流式起步先把整条链路打通再切流式。这个顺序很重要因为流式调试的排查面更窄如果非流式都调不通流式更没法看。先看Service层Service public class ChatService { private final ChatClient chatClient; public ChatService(ChatClient.Builder chatClientBuilder) { this.chatClient chatClientBuilder.build(); } public String getCompletion(String userMessage) { String response chatClient.prompt() .system(你是一个乐于助人的中文AI助手回答要简洁清晰尽量用列表和要点组织内容。) .user(userMessage) .call() .content(); return response; } }这段代码是SpringAI最典型的用法。ChatClient是SpringAI提供的对话客户端prompt()方法开启一次Prompt构建system()设置系统级提示词user()放用户输入然后call()是同步调用拿完整结果。Controller层就简单了RestController RequestMapping(/api/chat) public class ChatController { private final ChatService chatService; public ChatController(ChatService chatService) { this.chatService chatService; } PostMapping(/completion) public MapString, String completion(RequestBody MapString, String payload) { String message payload.get(message); String result chatService.getCompletion(message); return Map.of(reply, result); } }前端用一个普通的fetchPOST请求就能对接。跑通这一步标志着SpringAI的依赖注入、自动配置、ChatClient使用这三件事全部验证完毕。3.2 流式输出的核心SSE与Flux基础对话没问题以后开始做流式。这里面的核心原理要先讲清楚。传统HTTP请求是请求-响应模式服务器必须等所有数据处理完才能返回。而流式对话的场景是大模型生成一个token可能只需要几十毫秒但一句话要生成几百个token如果整体等完再返回用户体验就是漫长的等待。SSE就是一种服务端向客户端单向推送的协议。它本质上是HTTP长连接服务器可以分多次把数据写回客户端。前端用EventSource或者fetch的ReadableStream读取每个数据块到达就立刻处理。我们后端借助WebFlux的Flux把大模型的流式输出转成SSE格式推给前端。它的核心实现方式就是用FluxString作为返回类型。SpringMVC框架看到这个返回类型会自动启用SSE传输机制每个流元素都会被包装成data:格式发送。PostMapping(value /stream, produces text/event-stream) public FluxString stream(RequestBody MapString, String payload) { String message payload.get(message); return chatClient.prompt() .system(你是一个乐于助人的中文AI助手回答要简洁清晰。) .user(message) .stream() .content(); }注意两个关键点。第一返回类型从String变成FluxString这是从一次性应答变为持续推流的开关。第二produce text/event-stream告诉浏览器这是一个SSE连接。stream().content()返回的Flux里面每一个元素就是大模型生成的一个或者一段token。框架层面已经帮我们处理了响应式背压、并发缓冲这些底层细节。实际测试的时候用浏览器的Network面板可以看到响应不再是单一的一个大JSON而是一行行data:开头的内容持续刷新。3.3 流式控制器细节响应头与连接保持光有上面的基础代码还不行SSE连接对响应头有额外要求否则前端刷新时会出现各种奇怪的问题。我在代码里显式添加了响应头配置PostMapping(value /stream, produces text/event-stream) public FluxString stream(RequestBody MapString, String payload) { return chatClient.prompt() .system(你是一个乐于助人的中文AI助手回答要简洁清晰。) .user(payload.get(message)) .stream() .content() .doOnComplete(() - log.info(流式响应完成)) .doOnError(e - log.error(流式响应异常, e)); }这里用doOnComplete和doOnError挂上日志钩子调试阶段非常有用。实际排查时发现在nginx代理层需要额外配置proxy_buffering off; proxy_cache off; proxy_read_timeout 300s; proxy_set_header Connection ;如果前端的请求经过nginx反向代理不关掉proxy_buffering的话nginx会默认把上游响应缓冲到一定大小才发给浏览器流式就会变成一股一股的顿挫感甚至直接不推流。这是我踩过的一个很隐蔽的坑。4. 前端页面与流式渲染实现4.1 页面布局与交互设计前端页面我坚持用原生HTML CSS JavaScript不引入Vue或者React。原因有三第一这个项目的核心价值是流式对话链路重框架反而稀释重点第二原生FetchAPI对流式响应的支持非常好代码量并不大第三方便读者直接把页面拷走嵌入自己的系统。页面布局分三块顶部标题栏、中间消息列表、底部输入区。CSS要点是给消息容器设置overflow-y: auto确保消息多了可以滚动。输入框监听回车键发送ShiftEnter换行这是聊天软件里比较通用的交互习惯。div classchat-container div classchat-header spanSpringAI 流式对话/span /div div classchat-messages idchatMessages !-- 消息列表动态渲染 -- /div div classchat-input-area textarea iduserInput placeholder请输入你的问题.../textarea button idsendBtn发送/button /div /div4.2 用fetch流式读取后端数据浏览器的fetchAPI从Chrome 105开始支持了ReadableStream的完整读取能力。前端核心逻辑是这样的async function sendMessage() { const message input.value.trim(); if (!message) return; appendUserMessage(message); const assistantMessage appendAssistantMessage(); input.value ; try { const response await fetch(/api/chat/stream, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ message: message }) }); if (!response.ok) { throw new Error(HTTP ${response.status}); } const reader response.body.getReader(); const decoder new TextDecoder(); let buffer ; while (true) { const { done, value } await reader.read(); if (done) break; buffer decoder.decode(value, { stream: true }); // 按SSE格式解析每个消息以 data: 开头以换行结束 const lines buffer.split(\n); buffer lines.pop(); for (const line of lines) { if (line.startsWith(data:)) { const data line.substring(5).trim(); if (data [DONE]) continue; assistantMessage.textContent data; scrollToBottom(); } } } } catch (error) { appendErrorMessage(error.message); } }这段代码做了几件关键的事用TextDecoder的stream: true参数处理流式编码问题维护一个缓冲字符串处理跨包数据按SSE规范解析data:前缀的数据行每个数据块到达时立即追加到消息节点。这样用户就能看到逐字输出的打字机效果。4.3 打字机效果的细节优化打字机效果看着简单但细节决定体验。我调试中发现几个需要注意的地方第一textContent的累加性能其实不错但如果消息很长频繁触发DOM更新会有轻微卡顿。优化方案是加一个简单的RequestAnimationFrame节流用一个标记变量在一次动画帧内如果多次收到数据只执行一次DOM更新。第二自动滚动别每次都调scrollTop。正确的做法是判断用户当前是否接近底部如果用户正在向上翻看历史消息就不应该强制滚到底部否则体验很糟糕。我的实现是function scrollToBottom() { const container document.getElementById(chatMessages); const distanceFromBottom container.scrollHeight - container.scrollTop - container.clientHeight; if (distanceFromBottom 100) { container.scrollTop container.scrollHeight; } }第三发送按钮在流式生成过程中应该禁用防止用户连续点击导致多个并发请求。等流结束后再恢复。sendBtn.disabled true; sendBtn.classList.add(is-disabled); // 流结束后 sendBtn.disabled false; sendBtn.classList.remove(is-disabled);4.4 消息数据结构与渲染消息对象我简单定义为{ role: user | assistant, content: string }用数组存储在内存里方便将来扩展多个会话。每次发送前把用户消息推入数组收到流式回复后逐渐更新assistant消息的content。渲染函数的核心逻辑function appendUserMessage(text) { const wrapper document.createElement(div); wrapper.className message-item user-message; const content document.createElement(div); content.className message-content; content.textContent text; wrapper.appendChild(content); chatMessages.appendChild(wrapper); } function appendAssistantMessage() { const wrapper document.createElement(div); wrapper.className message-item assistant-message; const content document.createElement(div); content.className message-content; wrapper.appendChild(content); chatMessages.appendChild(wrapper); return content; }需要提醒的是如果你的业务需要支持Markdown渲染或者代码高亮就不能用textContent直接追加了得改成用innerHTML配合Markdown解析库但要注意XSS注入问题——用户消息和模型输出都不应该被当作可信HTML直接渲染。这个项目先保持纯文本安全性最好。5. 系统联调与实测效果5.1 启动与第一次正式测试工程启动很简单执行mvn spring-boot:run或者IDE里直接跑主类。启动日志里看到Tomcat started on port 8080后浏览器打开http://localhost:8080。第一次测试先发一条普通问题用三句话介绍什么是JWT。页面上的效果是用户消息立刻出现然后约1秒钟后助理消息一个字符一个字符地跳出来。这里有个细节第一次连接时因为有网络握手和模型鉴权会有一个短暂的延迟通常0.5到3秒这是正常的。用Chrome开发者工具的Network面板去看/api/chat/stream这个请求响应预览里能看到一段一段的data:增量的刷新痕迹。如果这个接口直到全部结束后才一次性返回那说明流式链路有问题优先排查反向代理和浏览器版本。5.2 大模型上下文记忆的演进方案当前实现是无状态对话每次请求独立发送模型不会记住前文。要做多轮对话我的方案是维护一个历史消息列表发送时携带上下文。SpringAI里可以用ChatMemory接口来管理也可以自己简单实现public FluxString streamWithHistory(String userMessage, String sessionId) { return chatClient.prompt() .system(你是一个乐于助人的中文AI助手。) .user(userMessage) .history(sessionId) // 需要配置ChatMemory .stream() .content(); }SpringAI提供InMemoryChatMemory实现类注册成Bean即可。但要注意内存存储意味着服务重启聊天记录就没了生产环境如果要持久化需要换成数据库或Redis存储这个根据自己的实际场景扩展。5.3 流式输出测试中的异常观察实测中我故意用了一个不存在的模型名结果前端连接正常建立但很快收到一个data: {error: ...}格式的消息。这提醒我流式链路中的错误信息也顺着SSE通道传回到前端了前端解析逻辑不能只处理正向数据还要对错误data做判断和展示。这也是流式和一次性请求定位问题的一个差别。因为连接建立了state code已经是200但模型层错误是在流式过程中才暴露的。所以前端的try...catch捕获不到HTTP层面的错误必须在数据解析层处理非正常数据。我在前端做了一层保护如果解析到的data字符串是JSON格式且包含error字段就在界面提示AI服务暂时不可用请稍后重试同时把错误打印到控制台。6. 常见问题与排查技巧实录6.1 流式连接建立失败或秒断现象前端发出请求后长时间无响应或刚收到第一个token就断开。排查思路按优先级来第一步确认后端日志。如果日志没有任何反应很可能是CORS问题——如果你用不同端口跑前端和后端浏览器会先发OPTIONS预检请求需要在后端配置跨域。Configuration public class WebConfig implements WebMvcConfigurer { Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping(/api/**) .allowedOrigins(http://localhost:5173) .allowedMethods(GET, POST, OPTIONS) .allowedHeaders(*); } }我这个项目里前后端同源部署所以不需要CORS配置。但如果你把前端单独跑到Vite或者Nginx下这一步必配。第二步检查API Key有效性。直接在浏览器或命令行里调用一次非流式接口验证。curl http://localhost:8080/api/chat/completion \ -H Content-Type: application/json \ -d {message:你好}返回结果说明后端的模型接入没问题问题在前端或网络链路。6.2 Nginx代理流式响应缓存问题现象本地直连后端流式效果正常部署到服务器后变成等很久后一次性全部显示。对策确认nginx配置文件中的proxy_buffering off是否生效。很多教程只写了加这一行但如果你在location块里已经有proxy_buffering on的继承设置可能会覆盖。我踩过这个坑最后用add_header X-Accel-Buffering no在应用层配了双重保险。spring: web: resources: cache: cachecontrol: no-store: true确保所有响应头里带上Cache-Control: no-cache, no-transform这能让中间代理不对流式内容做任何缓冲。6.3 前端中文乱码与编码问题现象流式推送到前端后中文字符有时出现半个字、乱码。原因分析TextDecoder默认用UTF-8解码一般不会出问题。但如果你后端框架自动加了一些内容编码头或者遇到了省流编码就需要在解码时指定编码const decoder new TextDecoder(utf-8);另外有种情况是后端返回的数据块本身就被截断了比如一个中文字符的UTF-8编码跨越了两个数据包。如果用decoder.decode(value, { stream: true })就能保证跨包的宽字符被正确缓冲编码问题大多能解决。6.4 超时设置不合理导致中长回答被截断现象短问题回复正常长问题回复到一半就没有了前端控制台报网络错误。原因通常有两个一是模型侧max-tokens设太小回复长度受限这个调整application.yml里的max-tokens即可二是网关或反向代理的超时时间设置太短。在Nginx配置里加proxy_read_timeout 300s在Spring Boot层如果有网关模拟也要相应调整。实际生产环境这个问题必须提前规划因为大模型生成长文耗时难以预估。6.5 快速排查速查表现象可能原因首选排查动作请求发出但无任何响应API Key无效、base-url错误先curl测非流式接口流式变一块一块的中间代理缓冲开启关proxy_buffering首token延迟过高模型网关拥塞看模型接口延迟考虑换模型前端中文乱码编码缓冲未设置确保TextDecoder带stream参数聊天内容与上文无关没带历史上下文检查ChatMemory配置页面打开404静态资源路径错误确认前端文件在resources/static下6.6 关于并发与服务容量的一点体会最后说一个容易被忽视的问题SSE连接比普通HTTP连接占用时间更长。普通接口几百毫秒就释放连接流式接口可能要维持几十秒。所以如果做高并发生产部署连接池和线程池的配置需要重新评估。Tomcat默认线程池200如果同时有大量SSE连接挂着线程资源很容易被占满。我当时的做法是在配置里显式调整了最大工作线程数并给流式接口单独划分了路径前缀方便用网关做隔离。server: tomcat: threads: max: 200 min-spare: 20这只是保守方案如果并发预期很高可以考虑把流式接口放到独立的WebFlux应用里或者用云厂商的流式网关组件彻底和普通API隔离。7. 更进一步扩展方向与个人心得当前项目已经跑通了基础对话、流式输出、前端展示三条核心链路但离一个可用的生产级对话系统还有距离。我在实际使用中觉得有几个扩展方向最值得做第一是接入Ollama本地模型。把spring-ai-openai-spring-boot-starter换成spring-ai-ollama-spring-boot-starter用Ollama跑Qwen2或LLaMA3配置字段类似代码几乎不用改。好处是数据不出内网隐私性有保障模型可以离线跑。第二是前端增加停止生成按钮。当模型回答跑偏或者长度太长时用户可以中断流。实现方式是在前端调用reader.cancel()关断读取流后端收到连接断开后Flux的取消信号会向上传递模型层会停止生成。const controller new AbortController(); // 创建请求时传入 signal: controller.signal // 点击停止时 controller.abort();第三是增加会话持久化。把历史消息存入数据库用户刷新页面后还能恢复上下文。SpringAI的ChatMemory接口有对应的持久化实现方案也可以自己写消息仓储对接MySQL或Redis。第四是给消息内容支持Markdown渲染。大模型回复天然带Markdown格式代码块、列表、粗体都很常见。接入markdown-it这类库后渲染效果会提升一个档次。但记住我之前说的用innerHTML前必须做HTML转义或使用专门的Markdown渲染库否则XSS漏洞风险很大。我个人的整体体会是SpringAI把这些大模型对接工作简化到了一个非常舒服的程度真正考验开发者的反而是流式传输链路的前后端协调。很多教程只写了后端API怎么返回Flux但前端怎么解析SSE、代理层怎么配合、超时怎么处理这些才是实际项目里花时间最多的地方。这也是我为什么在这个项目里坚持把前端页面一起做完——只有把前后端当作一条完整链路去调试才能真正理解流式对话的工作原理。如果你照着这个项目跑通了建议下一步不要急着堆功能先自己手动在浏览器里观察原始SSE数据流理解每个data:块的含义再动手改代码。这种对协议的直观感受是看多少文档都换不来的。