企业官网建设流程全解析

干了十来年Java后端，从当年的Servlet、JSP、EJB一路做到Spring Boot，说实话最近这波大模型浪潮刚起来的时候，Java圈的开发者是有点慌的。身边不少同事第一时间去翻Python，觉得大模型这活儿Java干不了。但我的判断是：Java后端做AI功能，真正缺的不是语言能力，而是一个能像Spring MVC封装HTTP一样，把“聊天模型”这个能力封装成Java开发者顺手能调用的基础设施。这就是SpringAI出现以后，我花了大半个月把手里一个老JavaEE项目翻新成AI应用后最深的体会。

这篇文章就想聊聊SpringAI里的核心模块——聊天模型。我会从一个传统Java后端开发者的视角，把这套东西从概念拆解到实际落地，包括消息结构、Prompt模板、流式输出、多轮记忆、工具调用，以及我实际踩过的版本兼容、上下文溢出、成本失控这些坑。如果你也是Java出身，想在自己熟悉的生态里接上一个能聊天的智能体，这篇应该能帮你少走不少弯路。适合刚接触SpringAI的Java后端，也适合那些正在评估“老项目要不要接AI”的团队。

1. 为什么JavaEE背景的团队我会选SpringAI

1.1 从JavaEE到SpringAI，中间到底发生了什么

传统JavaEE那套体系，核心是分层：Servlet负责接收HTTP，EJB管业务事务，JSP负责渲染页面。后来Spring用IOC和AOP把这套东西揉成了一个更轻量的模型，JavaEE也改名为Jakarta EE。但本质上，不管是JavaEE还是Spring，我们的思维模式都没变：请求进来，业务方法处理，返回结果。这套“请求-响应”模型统治了Java后端十几年。

到了大模型时代，服务的形态变了。模型不是数据库，你没法写一条SQL去查它；模型也不是RPC接口，它接收的是自然语言，返回的是带概率的生成文本。很多Java团队第一反应是用HTTP客户端直接调模型服务商的接口，但这样写出来的代码非常难受：要自己拼JSON、自己处理鉴权、自己维护重试和超时、还要自己实现流式解析。一旦想换成别家的模型，又得重写一遍。

SpringAI做的事，就是把“聊天模型”抽象成Spring生态里的一种Bean。你不是在写HTTP调用，而是在声明一个ChatClient，然后像使用RestTemplate一样调用它。它自动帮你完成请求构建、参数注入、流式解析、工具调用绑定，甚至还能和Spring的AOP、消息队列、监控体系打通。对于一个维护着大量Spring应用的老Java团队来说，这个接入成本几乎是最低的。

1.2 手写HTTP调用、LangChain4j、SpringAI怎么选

我最早做技术选型的时候，三条路都试过。手写HTTP调用听起来简单，但真实工程里要处理的东西太多了：模型服务商的API风格不统一、错误返回格式各异、流式响应的格式需要自己解析、对话历史要自己管理。一旦业务发展到需要接三五个不同厂家的模型，这部分的维护成本会指数上涨。

LangChain4j是Java生态里一个独立的AI框架，设计思路比较接近Python的LangChain，功能很全，文档也不错。但问题在于它不是Spring官方出品的，和Spring Boot的自动配置、条件装配这些机制集成需要额外做不少适配工作。而SpringAI是Spring官方亲儿子，从依赖注入、Starter机制到Metrics监控，都能直接跟现有Spring Boot项目融为一体。

我自己的选择标准很直接：如果只是想快速验证一个Demo，手写HTTP没问题；如果目标是做一个会长期演进、要接入多种模型、要和现有业务代码深度集成的企业级聊天应用，那就选SpringAI。它牺牲了一点灵活性，换来的是和Spring生态的无缝衔接，这对Java团队来说是决定性的优势。

1.3 聊天模型在SpringAI全家桶里的位置

SpringAI这个框架包的东西远不止聊天模型，它还包括Embedding模型接口、向量数据库抽象（VectorStore）、提示词模板、工具调用（Tool Calling）、以及和Spring Batch、Spring Integration这些组件的集成。但对于绝大多数Java后端应用来说，最核心、最优先要掌握的，就是聊天模型这一块。

在SpringAI里，聊天模型这层从底往上分别是：各家模型服务商的Adapter，把不同厂家的API统一成ChatModel接口；再往上是一个更面向业务的ChatClient，它封装了Prompt的构建、记忆管理、顾问（Advisor）机制，让开发者不用直接面对底层的大模型API细节。我用这个项目本身的体会是，ChatModel有点像是过去的DataSource，而ChatClient更像是一个封装好事务、连接池的Repository，日常开发尽量面向ChatClient去编程。

2. 先理解这些东西：消息、提示词、上下文窗口

2.1 聊天模型里翻来覆去就是这三种消息

很多Java开发者第一次接触大模型，下意识会觉得“聊天嘛，就是把用户的话发给模型，模型回一句”。但真正要开发AI应用，只懂这个远远不够。模型接收的输入不是一个字符串，而是一组消息列表，每一条消息都有自己的角色。

SystemMessage是系统消息，用来设定模型的身份和行为规范。你可以跟它说“你是一个客服助手，只能回答物流相关的问题，不要胡编”，这些话用户是看不到的，但它决定了模型后续所有回复的方向。UserMessage就是用户输入，通常每次对话动态生成。AssistantMessage是模型之前的回复，在多轮对话中，必须把历史的AssistantMessage跟UserMessage一起发回去，模型才能记住聊过什么。

这三类消息构成了聊天模型的基本语法。我见过不少新手直接用一个String字段缓存对话，然后拼成一大段文本丢给模型，表面上能用，但一旦切换到复杂场景，比如做角色限定、做敏感内容过滤、做个性化回复，这种粗糙做法就完全失控了。老老实实用消息结构去组织，是正确使用聊天模型的第一步。

2.2 PromptTemplate不只是字符串拼接，要把它当模板引擎

在传统Java项目里，我们早就习惯用String.format或者Freemarker去组织动态文本。SpringAI提供了PromptTemplate，本质上走的也是这个路子。写提示词的时候，把会变的部分用占位符包起来，运行时动态注入。

PromptTemplate template = new PromptTemplate(""" 你是{domain}领域的资深客服，用户的问题是：{question} 请用{style}的风格回答，并且只回答和{domain}相关的内容。 """); Message message = template.createMessage(Map.of( "domain", "3C数码产品", "question", "我买的耳机声音断断续续怎么办", "style", "简洁耐心" ));

这么做最大的好处是，提示词可以被集中维护、甚至做成配置或数据库里的模板，业务人员也可以参与调整。项目里我把所有提示词模板独立成目录，谁要改客服话术就直接改文件，不用碰Java代码。这块才是提示词工程的现实意义。

2.3 Options参数：控制模型行为的几个旋钮

聊天模型不是一按就出的黑盒，它有参数可以调。最常用的有三个：temperature控制随机性，值越小回答越稳定保守，值越大越发散有创造力；maxTokens控制单次生成的最大Token数量，直接影响响应长度和成本；topP控制采样的累积概率，跟temperature类似但机制不同。

经验值方面，做客服问答、SQL生成这类对准确性要求极高的场景，我会把temperature调到0到0.3；做创意写作、头脑风暴，就调到0.7到0.9。maxTokens的设置要小心，因为输入输出都会占用上下文窗口，模型上限如果是128K，不代表你可以每次都把128K用完，要给历史记录留足空间。还有一个小坑：很多服务商是按Token计费的，maxTokens设得越大，一旦模型跑飞，账单就越夸张，后面我会专门说。

2.4 一次call()调用背后到底发生了什么

从Java代码调用chatClient.prompt().user("你好").call()，这一行代码背后其实走了一段不短的流程。首先是构建请求对象，把SystemMessage、UserMessage和配置的Options组装成Prompt；然后经过Advisor链，也就是记忆管理、审计日志、内容过滤这些横切逻辑；接着ChatModel接口把Prompt序列化成对应厂商的请求格式，通过HTTP或流式连接发给远端模型；拿到响应后再反序列化成ChatResponse，最终抽出其中的文本内容返回给调用方。

理解这条链路的价值在于出问题的时候你知道去排查哪一环。比如回话突然不带了上下文，那多半是Advisor这里忘了配ChatMemory；比如改了temperature没生效，要检查是不是请求对象里被别的配置覆盖了。我们团队后来把这条链路单独画成一张时序图贴在项目文档里，新来的同事上手特别快。

3. 实战：用SpringAI快速搭建一个聊天接口

3.1 环境准备与依赖引入

我用的是Spring Boot 3.4加JDK17，SpringAI版本是1.0.0 GA。老规矩，还是用Maven管理，先引入SpringAI的BOM统一版本管理，再按选择的模型服务商引入对应的Starter。这套依赖结构和当年引入Spring Boot Starter如出一辙，Java开发者的学习曲线非常平缓。

<dependencyManagement> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-bom</artifactId> <version>1.0.0</version> <type>pom</type> <scope>import</scope> </dependency> </dependencyManagement> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-starter-model-qwen</artifactId> </dependency> </dependencies>

如果项目里要接多个模型，比如通义千问负责日常问答、智谱GLM负责结构化抽取、Ollama跑本地模型做离线场景，每个Starter都可以同时引入，Spring容器里会对应创建多个ChatModel Bean，用@Qualifier区分即可。

3.2 写配置比想象中简单

我拿一个内部演示项目“模拟项目X”来举例。这个工程里接了通义千问和本地Ollama两种模型，配置分成两块。云上模型走API Key，本地模型只需要配个base-url：

spring: ai: model: qwen: api-key: ${DASHSCOPE_API_KEY} model: qwen-plus ollama: base-url: http://localhost:11434 model: qwen2.5:7b

这里有个要点：API Key千万别硬编码进配置文件，用环境变量或配置中心注入。我见过有人图省事把Key怼在application.yml里然后整个仓库传到Git，结果几个小时之内Key就被盗刷了一大笔。另外模型名也要注意，不同厂家甚至同一厂家的不同版本模型，命名风格差异很大，最好跟服务商文档核对准确。

3.3 同步聊天与流式聊天，两种方式都要会

同步调用是最直观的玩法，适合企业内部工具、异步工单处理这类场景。核心代码很短：

@Service public class ChatService { private final ChatClient chatClient; public ChatService(ChatClient.Builder builder) { this.chatClient = builder .defaultSystem("你是企业客服助手，回答问题时务必简洁专业，不要编造事实。") .build(); } public String chat(String userMessage) { return chatClient.prompt() .user(userMessage) .call() .content(); } }

流式输出则是用户交互体验升级的关键。传统同步接口要等模型全部生成完才能返回，遇到长回答，用户在浏览器里傻等十几秒。流式接口通过Server-Sent Events把模型生成的文本实时推给前端，用户看到的是一段段往外蹦的字。SpringAI默认就支持Flux流式返回，跟Spring WebFlux天然契合：

@RestController public class ChatController { private final ChatClient chatClient; public ChatController(ChatClient.Builder builder) { this.chatClient = builder.build(); } @GetMapping(value = "/chat/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE) public Flux<String> stream(@RequestParam String message) { return chatClient.prompt() .user(message) .stream() .content(); } }

注意，如果用的是Spring MVC而不是WebFlux，流式返回时最好单独引入WebFlux的依赖，或者在网关层处理SSE的缓存和超时。我在项目里就遇到过生产环境Nginx默认把SSE响应缓冲起来，导致前端一直等不到数据，最后关了proxy_buffering才解决。

3.4 用PromptTemplate支撑动态提示词

把提示词模板直接写在代码里终归是不好维护的，尤其是业务人员还要参与调整。我习惯把模板放在resources/prompts目录，然后用Resource对象加载。这样改提示词不用重新编译、重新发版，线上改个文件就能生效，对业务迭代特别友好。

@Value("classpath:/prompts/customer-service.st") private Resource promptTemplate; String result = chatClient.prompt() .user(u -> u.text(promptTemplate).param("product", "智能手环") .param("issue", "无法连接蓝牙")) .call() .content();

模板文件customer-service.st里，可以写成这样：

你是{product}产品的售后顾问。用户报告的问题：{issue} 请先判断问题类别，再给出排查步骤，最后提示用户如果仍未解决如何联系人工客服。

这套写法和Velocity、Freemarker的思维方式完全一致，Java后端一点学习成本都没有。

3.5 结构化输出的两个小技巧

聊天模型默认返回的是自由文本，但很多业务场景需要JSON。比如让模型抽取订单信息、识别用户意图，然后交给下游系统处理。SpringAI里最简单的做法是要求模型返回JSON，再用Jackson解析。但模型偶尔会犯浑，在JSON前后加一段说明文本，导致解析失败。

更稳妥的方式是直接用ChatClient.entity()方法声明返回类型。这算是SpringAI的一个亮点，框架内部会通过Prompt或JSON模式约束模型的输出，尽可能让返回结果直接映射成Java对象：

record RefundInfo(String orderId, double amount, String status) {} RefundInfo info = chatClient.prompt() .user("订单号D10086的退款进度如何？提取订单号、退款金额和状态") .call() .entity(RefundInfo.class);

不过在底层，不同的模型服务商对结构化输出的支持程度不一样。实测下来，有些模型在复杂嵌套结构上还是会有格式走样的情况，所以entity方法碰上解析失败时，最好做一次兜底重试或者降级到字符串解析。

4. 让聊天模型真正搞定业务：会话记忆与工具调用

4.1 没有记忆的聊天模型只是个玩具

很多Java开发者第一次写出聊天接口，兴冲冲地跑起来，结果发现问一句“我叫小明”，下一句问“我叫什么”，模型完全想不起来。这是因为HTTP请求默认是无状态的，聊天模型本身也没有记忆，你必须自己把历史消息喂回去。

SpringAI提供了ChatMemory抽象和一系列Advisor，内存版实现开箱即用：

@Bean ChatMemory chatMemory() { return new InMemoryChatMemory(); } @Bean ChatClient chatClient(ChatModel chatModel, ChatMemory chatMemory) { return ChatClient.builder(chatModel) .defaultAdvisors(MessageWindowChatMemory.builder() .chatMemory(chatMemory) .build()) .build(); }

这里MessageWindowChatMemory的思路是只保留最近N条消息，避免无限累积把上下文撑爆。实际项目中，我强烈建议自己实现一个ChatMemory来对接Redis或数据库，默认的内存版在应用重启后记忆全部丢失，多实例部署也没法共享会话历史。

4.2 用@Tool让模型调用你的Java方法

聊天模型最让人兴奋的能力是Tool Calling，也就是让模型自己决定要不要调用你写的业务方法。我最早看到这个能力时，第一反应是“这不就是让大模型写代码来调我们的老系统吗”。举个例子，用户问“D10086这个订单退款到哪一步了”，模型本身并不知道订单状态，但如果它能调用你的订单查询方法，就能拿到真实数据再组织回答。

SpringAI里定义一个工具异常简单，只要在方法上标注 @Tool：

@Component public class OrderTools { @Tool(description = "根据订单号查询订单的退款状态") public String queryRefundStatus(String orderId) { // 这里可以调用你们的订单服务、查数据库、发RPC return "订单" + orderId + "当前状态：退款处理中，预计2个工作日内到账"; } }

然后在ChatClient调用时，把这个工具注册进去：

String answer = chatClient.prompt() .user("帮我查一下D10086的退款进度") .tools("orderTools") .call() .content();

这里面有个重要的坑：模型本身不具备判断参数的能力，它会在描述信息的辅助下解析出orderId，但如果工具描述写得不够清楚，它可能漏传参数或传错格式。description一定要写清楚参数的含义、格式、必须项。还有，工具数量别一次给太多，模型在多个工具里选错工具的概率可不低。

4.3 多轮记忆、工具调用、流式输出怎么组合在一起

实际项目里很少只用单一能力。我给“模拟项目X”做的订单助手，就是把流式输出、记忆管理和订单查询工具组合在一起。代码的编排顺序大概是：给ChatClient配默认系统提示词和会话记忆，业务方法里通过.user().tools("orderTools")组织每次请求，返回类型用Flux实现SSE流式下发。

这里要提醒一句：当ChatClient开启记忆和工具调用后，每次请求实际发送给模型的消息数量会显著增加。因为历史消息要占上下文，工具的定义和工具的调用结果也要占上下文。如果模型上下文窗口不大，老项目里那种“一口气把所有工具都配上去”的做法，很容易触发上下文长度超限。轻量做法是只给当前对话注册和意图匹配的少数工具，或者是给不同场景拆成不同的ChatClient实例。

4.4 落一个典型场景：企业内部智能问答机器人

把上面的组件拼起来，就能落地一个常见需求。比如企业内部文档问答机器人，技术栈里再混一个Embedding模型和向量数据库，把企业知识库变成可检索的切片。用户提问后，系统先从向量库检索相关段落，再把检索结果和原始问题一起塞进提示词，让聊天模型基于给定资料回答。

这个链路里，聊天模型不是瓶颈，瓶颈在检索质量。切块大小、向量模型的选择、召回条数都会影响最终效果。我试过的最省事方案：先用LangChain4j的文档加载器切分PDF，再用SpringAI的VectorStore抽象存到本地向量库，最后用ChatClient把检索结果拼接进提示词。这套组合能显著减少模型幻觉，让回复落到企业自己的知识体系里。

5. 常见问题与排查技巧实录

5.1 版本兼容性：为什么你照抄代码却编译不过

SpringAI现在还处于快速迭代期，API变动比Spring老框架频繁得多。有些网上的示例是0.8.x写的，代码拿到1.0.0 GA上直接编译报错。我遇到最多的几个变化：ChatClient.Builder的defaultSystem写法变了、ChatMemory的包路径变了、部分Starter的groupId有过调整。

别硬记API，学会看官方文档。另外SpringAI版本跟Spring Boot的版本有对应关系，Spring Boot 3.2、3.3、3.4能用的SpringAI版本都不一样。BOM的版本号最好跟官方Release页面核对，不要随手选一个看起来最新的。

5.2 鉴权失败、限流、超时，这些底层问题躲不掉

接入云上模型服务，最常见的就是返回401或403。先是检查API Key是否过期、是否正确注入环境变量；再看是不是模型没有开通对应权限。限流这块也常有：某些免费模型并发限制很低，业务一上来，报429或者超时的概率飙升。

超时问题更要重视。同步聊天接口可能几十秒才返回，默认的HTTP客户端超时时间肯定不够。如果是通过Ollama跑本地小模型，冷启动时模型要加载参数到显存，第一次请求等个几十秒都正常。我习惯在配置里单独调大连接超时和读取超时，并且在网关层面对这类接口放宽超时限制。顺便说一句，人民币玩家限定场景，优先用流式接口，至少能给用户一个“系统正在努力生成”的体感。

5.3 流式返回乱码、SSE被缓冲、连接断开

流式聊天虽然体验好，但工程问题比同步接口多得多。最先遇到的就是中文乱码，多半是服务端响应没有正确设置UTF-8字符集。SSE接口要显式设置Content-Type和字符集，例如text/event-stream;charset=UTF-8。其次是代理服务器缓冲问题，Nginx默认会缓冲FastCGI和HTTP应答，SSE的增量数据可能被攒到一大块才返回，用户看到的还是“等了半天，突然蹦出全文”。关闭缓冲区或者配置适当的flush时间能缓解，但如果前端在公网环境，得提前把代理链路理一遍。

连接稳定性也要考虑。流式响应期间，模型可能随时中断。建议前端做断线重连、服务端做日志记录。有时候模型返回到一半报了异常，如果你用的是Flux，异常会顺着响应一路传下去，你不处理，用户的体验就是“回话戛然而止”。

5.4 上下文窗口溢出、Token成本失控

对话越聊越长，最终会把模型的上下文窗口撑爆。报错信息通常会直接告诉你超限，但这个错误往往出现在运行中段，业务日志一看全是错误。应对思路无非三个：一是限制对话长度，MessageWindowChatMemory配置小一些；二是做摘要压缩，当历史消息快满时，让一个模型把历史对话浓缩成摘要再放进去；三是控制工具定义的数量和长度。

成本失控是另一个隐形炸弹。我给几个团队做过咨询，发现不少聊天应用的月度账单高得吓人。原因很简单，没人监控每个会话消耗了多少Token。建议在链路里加上Metrics监控，按用户、按会话、按接口统计Token消耗。业务侧也要有熔断机制，比如单个会话每日消耗超过一个阈值，就自动切换到便宜的模型或者限制回复长度。大模型这东西，用起来一时爽，月底账单教做人。

5.5 内容安全过滤：这块必须放在代码里

最后聊一个容易被忽视的点。聊天模型如实回答是能力问题，但如果用户的提问里带风险和恶意，系统必须主动拦截。SpringAI提供的Advisor机制可以很方便地插入过滤逻辑。在发给模型之前，先做敏感词和风险意图识别；在返回给用户之前，再做一次内容合规检查。别盲目相信模型自带的安全机制，企业和产品的安全责任最终是在自己这一层，尤其当你把聊天能力开放给外部用户时，这个环节绝不能省略，宁可错杀也不要放行。

我个人的体会是，SpringAI把聊天模型带进了Java后端开发的日常，技术门槛确实是降下来了，但工程化要求反而更高了。你不再需要费劲拼HTTP请求，但你必须理解消息结构、提示词设计、上下文管理、成本控制这些干活真正需要的东西。建议大家从一个小场景入手，比如先给内部工具加一个问答入口，把同步和流式两种模式跑通，再加上记忆和工具调用，最后补齐监控和限额。这套走完，你对SpringAI聊天模型的理解，就算是真正扎到业务里了。

最后再分享一个小技巧：做多模型接入时，不要把所有Prompt里的语气词都写成面向某一个模型的。不同模型对提示词格式的敏感度不一样，同一套模板在A模型上表现完美，在B模型上可能效果很烂。比较省事的做法是，把温度、模型名、甚至提示词模板都做成可按租户配置的维度，这样换个模型试效果时，不用来回改代码发版。模型这东西迭代太快，今天的最优解三个月后可能就被淘汰了，接口层尽量留点余量，别把自己焊死在一家上。