1. 项目整体设计与思路拆解
1.1 这个项目到底在解决什么问题
先说个很直白的感受：Java EE（或者说Spring Boot）开发者想接入大模型能力，市面上能直接参考的资料不少，但大多是“Hello World”级别的示例，调通接口就结束了。真正把对话机器人做成一个能落地的、带业务语义的模块，中间隔着很多细节。这个项目就是在补这些细节。
所谓智能聊天机器人，拆开来看，本质上解决的是三件事：第一，怎么把用户的话变成大模型能理解的输入；第二，怎么让大模型返回的内容符合业务场景的约束和预期；第三，怎么把这个来回过程嵌进Java EE体系里，跟现有的账号体系、数据库、日志链路共存。
SpringAI这个框架的好处在于，它不是让开发者直接面对各家大模型厂商的SDK差异，而是提供了一套统一的Java层面的抽象。底层接OpenAI也好、接通义也罢，上层代码不用跟着换。对于Java团队来说，这比在Python服务里单独维护一套AI调用逻辑要舒服得多——至少技术栈统一了，运维和排查问题都省事。
这个项目对我来说最有参考价值的部分，是它不只在做“一问一答”，而是把对话机器人设计成了一个带业务属性的组件：能记住上下文、能按预设的人设说话、还能在内容安全性上做一层把关。这其实是很多企业接入AI时真正的需求，而不是单纯为了“炫技”。
1.2 为什么选择SpringAI而不是直接调API
这个选择我实际对比过，也走过弯路。最直接的方式是拿HTTP客户端去调大模型接口，自己拼请求、解析响应、维护会话状态。听起来不复杂，但一旦涉及流式输出、多轮记忆、工具调用这些场景，代码量会迅速膨胀，而且每次对接一个新模型都要重写一遍适配逻辑。
SpringAI解决的是这层“重复劳动”。它把大模型调用抽象成了ChatClient这样的接口，开发者只需要关注业务本身。同时它提供了PromptTemplate这种机制，把系统提示词和用户输入做模板化管理，配合ChatMemory做对话记忆，配合Advisor机制做拦截和增强。这些都是对话机器人在真实场景里高频使用的能力，自己从零去实现，不仅工作量大，而且容易出bug。
有人可能会担心SpringAI生态不够成熟。这个担心合理，但就目前来看，它的核心链路（模型对接、提示词管理、记忆管理、结构化输出）已经覆盖了一个聊天机器人90%以上的需求。剩下的10%，比如某些特定模型的特殊参数，框架也提供了扩展点，不至于卡死。对一个Java EE项目来说，选SpringAI的核心逻辑是：技术栈统一、维护成本低、生态在快速补齐。
1.3 整体技术架构和模块划分
整个项目的模块设计，一句话概括就是：传统Java EE分层架构做骨架，SpringAI做AI能力的接入层，业务逻辑单独隔离，不跟具体模型绑定。
我用的是经典的四层结构：Controller层接收请求、Service层处理业务逻辑、Repository层访问持久化数据，再加一个独立于这三层之外的AI服务模块。AI服务模块内部按照职责再拆分：一个是ChatService，负责跟模型交互；一个是MemoryService，负责会话上下文的管理；还有一个是GuardService，负责敏感内容和业务约束的审核。这个拆法让我后来加功能时特别舒服，比如要加一个审核策略，只需要在GuardService里新增实现，不必去动Controller和Service。
数据库层面用的是MySQL，存的是用户ID、会话ID、消息记录、反馈标注这几张表。Redis用来做短期会话状态的缓存，比如当前会话的Token用量、最近几轮的对话摘要，这些不一定要落库。思路很清晰：高频的、短生命周期的数据放Redis，需要追溯和统计的放MySQL。
这套架构如果画成图，链路是：前端请求进入Controller，带着用户ID和消息内容，Service层先检查会话归属、组装Prompt，把请求交给ChatService。ChatService从MemoryService加载历史消息，拼装消息列表，传给模型。模型返回结果后，经过GuardService的合规检查，再由Service层落库并返回前端。
关于架构选型的补充：后端Java版本建议直接用17，Spring Boot用3.x，SpringAI用1.0.0M系列版本。这个组合在目前是稳定的，而且M系列版本的API基本定型，和网上大部分最新教程对得上。
2. 核心依赖准备与基础设施搭建
2.1 Maven依赖配置和版本踩坑实录
先把依赖这块说透，因为这里的坑最多。SpringAI的依赖是以模型提供商作为维度区分的，接OpenAI加一个spring-ai-openai-spring-boot-starter，接其他家就加对应的starter。版本这块务必看齐Spring Boot父POM里的BOM管理，否则容易出兼容性问题。
<parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>3.3.5</version> <relativePath/> </parent> <dependencyManagement> <dependencies> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-bom</artifactId> <version>1.0.0-M3</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> <dependencies> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-openai-spring-boot-starter</artifactId> </dependency> <!-- 如果用通义千问则替换为 spring-ai-alibaba-tongyi-spring-boot-starter --> </dependencies>这里有个很重要的点：Spring AI的M系列版本发布节奏算快的，但如果你的Spring Boot版本是3.2.x，那就要选对应的更早的M版本。我在本地搭环境时先用了最新的M3，结果Spring Boot 3.2.5启动报错，报的是组件扫描路径不匹配。解决办法是升Spring Boot到3.3.x。如果你不想动父版本，就锁一个较旧的SpringAI版本。
还有一点，spring-ai-openai的starter本身不带模型调用的实现，它依赖spring-ai-core和spring-ai-model。传递依赖通常能拉全，但如果你在排除依赖后出现ClassNotFoundException，优先检查spring-ai-model在不在依赖树里。
2.2 配置文件里的关键项和模型参数设置
配置这块哪怕差一个参数，效果都可能天差地别。下面这份是接OpenAI兼容接口的配置，包含了我调过的最合理的默认值：
spring: application: name: ai-chatbot ai: openai: base-url: https://api.openai.com api-key: ${OPENAI_API_KEY} chat: options: model: gpt-4o-mini temperature: 0.7 max-tokens: 1024 top-p: 0.9 completions-path: /v1/chat/completionstemperature这个参数我多说几句：它不是越高越好。做开放域闲聊，0.7到0.9会有惊喜感，回答更灵动。但如果你的场景偏向智能审核或者客服问答，那我建议把temperature降到0.2以下，这个值越低，模型的输出越“保守”和“确定性”，减少自由发挥带来的风险。
max-tokens决定单次回答最大长度，注意这个是模型生成部分的最大值，不是输入限制。如果业务上需要长文本输出，比如生成报告，可以放宽到2048甚至更高，但同时延迟也会变大。
base-url这个配置项特别容易被忽略。如果你接的是国内云厂商提供的OpenAI兼容接口，这里可以指向你自己的网关地址。SpringAI对兼容接口的支持很好，不用改代码，只改配置就能切换。
2.3 基础表结构和会话存储方案
聊天机器人要做得靠谱，必须把消息记录和会话状态分开存储。我建了三张核心表，结构如下：
CREATE TABLE chat_session ( id BIGINT AUTO_INCREMENT PRIMARY KEY, user_id VARCHAR(64) NOT NULL, session_title VARCHAR(255), status TINYINT DEFAULT 1, created_at DATETIME DEFAULT CURRENT_TIMESTAMP, updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, INDEX idx_user_id (user_id) ); CREATE TABLE chat_message ( id BIGINT AUTO_INCREMENT PRIMARY KEY, session_id BIGINT NOT NULL, role VARCHAR(20) NOT NULL, content TEXT NOT NULL, tokens INT DEFAULT 0, feedback TINYINT DEFAULT NULL, created_at DATETIME DEFAULT CURRENT_TIMESTAMP, INDEX idx_session_id (session_id) ); CREATE TABLE chat_memory_snapshot ( id BIGINT AUTO_INCREMENT PRIMARY KEY, session_id BIGINT NOT NULL, summary TEXT, message_count INT DEFAULT 0, updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, UNIQUE KEY uk_session_id (session_id) );第一张表管会话，第二张管消息明细，第三张是记忆快照。记忆快照的用途是用来做长对话压缩：当某个会话的历史消息超过阈值（比如20条），就把早期消息浓缩成一段摘要存进快照，后续请求携带摘要加最近的少量消息，而不是无限叠加全部历史。
存储这块的原则是：高频读写、允许丢失的短期记忆先放Redis，长久需要追溯的消息落MySQL。所以我会在Redis里存当前会话最近10轮的消息结构，读取时直接从Redis拿，只有生成完成后才异步写库。
注意：不要尝试在数据库字段里直接存整个JSON数组作为消息历史，虽然看起来方便，但更新和扩展都很痛苦。拆成明细表一劳永逸。
3. 系统提示词配置与Prompt工程实战
3.1 系统提示词为什么是聊天机器人的灵魂
模型本身是一个“什么都知道一点的通用大脑”，但通用意味着不可控。系统提示词就是给大脑设置“工作守则”的那份员工手册。同一个模型，配上不同的系统提示词，可以是一个幽默的脱口秀演员，也可以是一个严谨的银行客服。
热词里专门提到“SpringAI系统提示词怎么配置”，说明这确实是高频痛点。在SpringAI里，配置系统提示词有两种主流方式：一种是直接在yaml里通过spring.ai.openai.chat.options.system写死，另一种是在代码里用PromptTemplate动态组装。前一种适合固定人设，后一种适合根据用户、场景做差异化设置。
我的建议是：默认值放yaml，动态变化走代码。把提示词模板放到resources/prompts/目录下，用模板引擎渲染，这比在Java代码里拼接字符串要干净得多。
3.2 用PromptTemplate动态管理系统提示词
SpringAI的PromptTemplate是构建Prompt的核心工具，它基于StringTemplate引擎，支持变量插值。我写了一个典型的人设提示词模板：
你是{assistantName}，一个专业、友好、耐心的智能助手。 ## 你的性格特征 - {personality} - 说话风格亲切自然，不使用过于夸张的语气 - 解答问题时先给结论，再展开说明 ## 你的职责范围 - {responsibilities} - 超出职责范围的问题，礼貌告知用户你无法处理 - 不编造事实，不确定的信息明确说明 ## 交互规范 - 用户使用中文时用中文回复，使用英文时用英文回复 - 每次回复控制在{maxLength}字以内 - 涉及安全敏感话题时，拒绝回答并说明原因引用这段模板的代码非常简单：
PromptTemplate promptTemplate = new PromptTemplate("classpath:/prompts/assistant.st"); Message systemMessage = promptTemplate.createMessage(Map.of( "assistantName", "小助手", "personality", "热情但不谄媚，专业但不生硬", "responsibilities", "解答Java技术问题、帮忙排查问题", "maxLength", "300" )); ChatClient chatClient = ChatClient.builder(chatModel).build(); String response = chatClient.prompt() .system(systemMessage.getContent()) .user("帮我看一下这个Spring Boot启动报错的原因") .call() .content();这里有一个我一开始踩过的大坑：不要把用户的具体业务数据拼进系统提示词。系统提示词应该只包含“规则”和“身份”，用户数据走user消息。如果数据混在系统消息里，某些模型的上下文管理策略会把这些内容当成长期指令，造成后续所有对话都被带偏。
3.3 实战：一组适合不同场景的提示词示例
既然聊到提示词配置，我多给几组实际能用的模板，覆盖最常见的三种场景。
客服场景：
你是XX产品的官方客服，你的名字叫小X。 你的目标是：快速解决用户使用产品过程中的疑问。 规则： 1. 优先引导用户查看帮助文档中已有的内容 2. 涉及账户资金、隐私数据的问题，引导用户联系人工客服 3. 不承诺任何超出产品能力范围的补偿 4. 保持语气亲切，但不要过度使用表情和语气词技术顾问场景：
你是一名资深的Java后端工程师，擅长Spring Boot、微服务架构、数据库调优。 当用户提出技术问题时，请遵循以下步骤： 1. 先根据问题描述判断可能的原因 2. 给出排查建议，按可能性从高到低排列 3. 涉及代码问题时，给出具体的代码示例 4. 如果信息不足，先询问缺失的关键信息 5. 不要给出不安全的建议，比如直接关闭安全检查智能审核场景：
你是一名内容安全审核员。用户的消息可能是任意文本。 你的工作是：对消息内容进行安全性和合规性检查。 输出格式要求： - 如果消息含敏感、违规、高风险内容，输出：拒绝 - 如果消息含违规倾向但程度较轻，输出：警告并说明原因 - 如果消息完全正常，输出：通过 - 如果消息属于正常业务询问，输出：通过第三组尤其实用，结合热搜词里的“SpringAI智能审核”，后面我会专门演示这个场景怎么落地成完整的审核API。
3.4 提示词版本管理和A/B测试的思路
提示词写完之后不是一劳永逸的，它会像业务代码一样迭代。我在项目里给提示词做了版本管理：每个版本的提示词文件以prompt_xxx_v1.st、prompt_xxx_v2.st这样的方式命名，同时数据库里加了一张prompt_config表，记录当前生效的版本号。这样即便线上提示词调坏了，也能秒级回滚。
这里有个小细节：换提示词不一定要重启服务。可以把提示词内容放进配置中心或数据库，代码里做成定时刷新缓存的结构。流量的切换逻辑也可以做成按用户灰度：百分之五的用户走新提示词，效果稳定再逐步放量。这个思路在企业级项目里几乎是必备的。
4. 核心功能实现与实操全流程
4.1 初始化工程和验证模型连通性
这块内容技术含量不高，但连通性验证做不好，后面所有功能都是空中楼阁。创建工程时直接把Spring Initializr的Spring Boot版本选到3.3.x，Java选17，依赖先只加Web和Validation。SpringAI的依赖在Initializr里还没有，需要手动添加。
工程建好后，第一步不是写业务代码，而是先写一个只带main方法的测试类，验证模型能通：
@SpringBootTest class ChatbotApplicationTests { @Autowired private ChatModel chatModel; @Test void testModelConnection() { String response = chatModel.call("用一句话介绍你自己"); System.out.println(response); } }跑这个测试前，确认环境变量OPENAI_API_KEY已经设置好，或者配置文件里的api-key能正确读取。如果网络环境特殊，可以临时把base-url切到本地代理上，但切记这只是调试手段，不要写死在代码里。
常见报错：如果遇到401，检查api-key是否正确；如果遇到404，检查completions-path是不是被改过；如果遇到超时，看是不是base-url指向错误；如果遇到“connection refused”，优先排查网络策略。
4.2 多轮对话记忆的实现：让机器人记住上下文
聊天机器人最核心的体验差异就是“能不能记住我说了什么”。SpringAI提供了ChatMemory接口，以及InMemoryChatMemory和MessageWindowChatMemory两种默认实现。MessageWindowChatMemory是窗口滑动式的，只保留最近N条消息，超出窗口的自动丢弃，非常适合控制Token消耗。
我先说一个误区：很多人把“多轮对话”理解成把用户和AI的全部历史消息一股脑塞给模型，这在大模型时代是灾难级的做法。每次请求都携带全部历史，Token消耗会随对话轮数线性上升，而且大量早期无效信息会干扰模型的注意力。正确做法是：设置合理的窗口（比如6到10轮），结合历史摘要。
具体的实现代码：
@Service public class ChatSessionService { private final ChatModel chatModel; private final MessageWindowChatMemory chatMemory; public ChatSessionService(ChatModel chatModel, MessageWindowChatMemory chatMemory) { this.chatModel = chatModel; this.chatMemory = chatMemory; } public String chat(String sessionId, String userMessage) { // 将用户消息加入记忆窗口 chatMemory.add(sessionId, new UserMessage(userMessage)); // 取出窗口内的全部历史消息并与系统提示词组装 List<Message> messages = chatMemory.get(sessionId, 10); // 构建请求并调用模型 ChatClient chatClient = ChatClient.builder(chatModel).build(); return chatClient.prompt() .messages(messages) .call() .content(); } }实践中重要的是sessionId的生成策略。我用的是UUID，每次前端初始化对话时向服务端请求一个，后续所有消息都带上这个ID。Redis里的key结构是chat:memory:{sessionId}，带过期时间，比如24小时。过期后会话自动清理，MySQL里的历史消息还在，用户可以从会话列表重新加载。
4.3 流式输出的实现：让回答一个字一个字地“蹦”出来
如果机器人等好几秒才一次性吐出全部回答，用户大概率会觉得卡顿。流式输出就是把模型的生成过程实时推给前端，效果上像打字机一样。这个体验提升非常明显，而且SpringAI实现起来不复杂。
配合WebFlux的Flux做推送，SpringBoot本身对这块支持得很好。Controller里方法返回类型改成Flux，框架自动处理SSE协议：
@PostMapping(value = "/chat/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE) public Flux<String> chatStream(@RequestBody ChatRequest request) { return chatClient.prompt() .system(systemPrompt) .user(request.getMessage()) .stream() .content(); }前端用EventSource或者fetch的ReadableStream接口接收。这里有个需要注意的细节：SSE的响应头必须显式设置X-Accel-Buffering: no，否则经过Nginx时会被缓冲，导致前端拿不到逐步输出的效果，而是等全部生成完一次性返回。
流式输出的另一个好处是：单元测试里可以直接collectList()把Flux聚合成List，从而对完整文本做断言，测试方式和普通接口差别不大。
4.4 智能审核功能的完整实现流程
聊到热搜词里的“SpringAI 智能审核”，这个功能值得单独拎出来展开讲。我在聊天机器人外面套了一层内容审核的GuardService，拦截所有用户输入和模型输出，双通道检测，确保进出的内容都合规。
审核的实现思路是先预检再过模型：
@Component public class ContentGuardService { private final ChatModel chatModel; public GuardResult check(String text) { // 快速过滤：敏感词库命中直接拒绝 if (sensitiveWordFilter.contains(text)) { return GuardResult.reject("包含敏感词"); } // 深度过滤：调用审核提示词模型做语义判断 String prompt = "你是一名内容安全审核员。请判断以下内容是否合规：\n" + text + "\n" + "只回复：通过 或 拒绝，并简短说明理由。"; String result = chatModel.call(prompt); if (result.contains("拒绝")) { return GuardResult.reject(result); } return GuardResult.pass(); } }敏感词过滤我用的是前缀树实现，配合一段几千词的词库，能在毫秒级完成第一轮筛查。语义层面的风险（比如隐晦表达、组合词攻击）交给大模型兜底。两个通道都通过，才放行。
这个审核模块在架构上是独立于聊天机器人本体的，它其实是一个通用的API，任何业务模块都能调用。这就是前面提到模块划分的收益：审核能力是可复用的。
4.5 与Java EE传统业务体系的整合
这个项目如果只是做一个简单的接口，那和“Java EE”其实没什么关系。我刻意做了几件让它融入传统Java EE生态的事情：接入Spring Security做接口鉴权，接入MyBatis-Plus做数据持久化，接入了已有的日志框架ELK。
鉴权的逻辑是：前端请求header里带JWT Token，Controller前的拦截器解析用户ID，塞进ThreadLocal上下文。ChatService从上下文拿用户ID，而不是从请求参数里额外传。这样可以避免用户伪造别人的用户ID去查看历史会话。
日志链路这一块，我用MDC把traceId和sessionId绑定，每个AI请求的Token消耗、耗时都输出到日志里。排查线上问题的效率有了质的飞跃——什么会话、哪个prompt版本、模型返回了什么，全都能串起来。
5. ChatClient高阶用法与常见问题排查
5.1 ChatClient API的核心方法说明
ChatClient是SpringAI1.0之后最核心的入口，它像是一个面向AI调用的流式API。很多人在官方文档里看到一堆方法名就头晕，我在这里给一份实战对照说明：
- prompt()：返回PromptSpec，用来构建整个请求上下文，包括system、user、messages、advisors等；
- system(String) / system(Message)：设置系统提示词，一次请求可以设置多个，框架会合并；
- user(String) / user(Message)：设置用户输入；
- messages(List )：直接注入历史消息列表，和user()互斥，使用时选一个即可；
- call()：同步调用，返回ChatResponse，包含完整生成内容和Token使用情况；
- stream()：异步流式调用，返回Flux ，用于流式场景；
- advisors(Advisor...)：注入顾问链，用于打印日志、修改Prompt、做函数调用等。
这套API设计得比旧版自然语言API（OpenAiApi那套）顺手得多。升级到1.0之后，直接放弃旧写法就行。
5.2 Advisor机制：给每一次请求加上全局观察者
Advisor是SpringAI里容易被忽略但价值极高的扩展点。它可以理解为请求的全链路拦截器，在请求发送前修改Prompt，在响应返回后处理结果。我常用的几个Advisor用法包括：
- 日志记录：记录用户输入、模型输出、耗时、Token消耗；
- 敏感信息脱敏：在请求发出前把身份证号、手机号替换成脱敏文本；
- Prompt增强：在每次请求时注入额外的业务上下文，比如当前用户的会员等级。
自定义Advisor的实现方式很简单：
public class LoggingAdvisor implements Advisor { private static final Logger log = LoggerFactory.getLogger(LoggingAdvisor.class); @Override public AdvisedRequest before(AdvisedRequest request) { log.info("用户会话{}，发送消息：{}", request.chatId(), request.userText()); return request; } @Override public AdvisedResponse after(AdvisedResponse response) { log.info("AI回复：{}", response.response()); return response; } }这个机制用得越多，越能感受到SpringAI的框架感——它本质上就是一套专为大模型调用设计的AOP。
5.3 高频错误排查清单与解决实录
这里把我在开发调试中遇到的高频问题列成一张速查表，都是实战中真实踩过的坑：
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
| 启动报错Quote：组件扫描找不到类 | Spring Boot版本与SpringAI BOM不匹配 | 升级Spring Boot到3.3.x |
| 调用超时 | 网络不通或base-url错误 | 检查网络连通性；确认base-url是OpenAI兼容接口地址 |
| 400 Bad Request | Prompt中消息类型不对，比如user消息传成了空字符串 | 检查messages列表，确保消息内容不为空 |
| 输出内容没约束 | 系统提示词没生效或拼写错误 | 检查system消息是否在messages列表第一位 |
| 流式输出卡顿 | Nginx缓冲未关闭 | 响应头添加X-Accel-Buffering: no |
| 多轮对话机器人“失忆” | 窗口长度设置过小或摘要策略缺失 | 调整MessageWindowChatMemory的窗口大小；长对话启用摘要快照 |
| Token消耗暴涨 | 未限制消息窗口长度，历史消息无限堆积 | 启用内存窗口管理，限制最近N轮 |
有一条特别值得单独说：如果你复用了同一个ChatMemory实例但sessionId生成重复，极易出现串号。排查方式是把sessionId和用户ID绑定，每次请求校验当前会话归属，不匹配直接拒绝。
5.4 效果调优：temperature、上下文窗口与回复控制的平衡
说实话，同一个模型在同等参数下，由不同的人配置，体验差距可以非常大。原因不在模型，在上下文的管理和提示词的质量。我试过几组配置组合，总结几条经验：
第一，核心问答场景不要贪窗口。5到8轮窗口是黄金区间，超过这个区间，模型被早期信息干扰的概率显著上升。如果业务真的需要长程上下文，用摘要压缩而不是盲目加轮数。
第二，temperature的调整幅度不要太大。从0.7调到0.9，输出的变化会比想象中剧烈。如果某天发现回答风格突然不对，先检查是不是有人动过配置。
第三，max-tokens要考虑业务类型。智能问答不需要设太大，但要留余量给推理链。如果发现输出经常被截断，不是模型出问题了，是max-tokens不够。
第四，性能优化上建议开输出Token缓存。对相同或高度相似的问题，直接返回历史命中结果，能省掉一大部分重复调用成本。
6. 从聊天机器人到智能Agent的扩展思路
6.1 对话界面之外的“处理动作”怎么做
聊天机器人做久了会发现，用户要的不只是“回答”，还有“做事”。比如“帮我查一下上个月的订单量”“帮我总结一下这份文档”——只靠对话能力是无解的，需要Agent机制，也就是让模型能够调用业务系统的工具。
SpringAI对这块也有支持，核心是@Tool注解。把需要暴露给模型的方法打上注解，模型在生成回答时如果判断需要调用工具，会在回复中携带调用指令，框架自动完成工具调用，并把结果回填给模型继续生成。
@Component public class OrderTools { @Tool(name = "getOrderCount", description = "根据日期获取订单总量") public int getOrderCount(String date) { // 查询数据库订单表 return orderMapper.countByDate(date); } }把这类工具类注册进ChatClient后，模型就具备了“动手”的能力。这其实才是智能化升级的真正分水岭：从“能说话”到“能办事”。
6.2 向量库与RAG：让机器人知道你的私有知识
聊天机器人如果只会拿通用知识回答，对很多企业来说价值有限。真正让CIO觉得“这项目值”的，是把企业内部文档、产品手册、FAQ变成机器人的训练知识库，这就是RAG（检索增强生成）。
SpringAI的向量化模块支持多种Embedding模型和向量数据库。链条通俗理解是：先切文档，生成向量，存入向量库；用户提问时，把问题也向量化，从库里召回最相关的几个片段，连同问题一起交给模型生成答案。
这样做的优势是：不微调模型也能获得领域知识，知识库更新只需重新向量化文档，不需要重新训练。如果你在一个Java EE的项目里接入了SpringAI，再往前走一步接上向量库，就是一个标准的智能客服中台了。
6.3 把智能审核模块独立成通用能力
我在前面提到了审核模块，这里再补充一个建议：尽早把它抽成独立的服务或公共组件。原因很直接，内容合规不是聊天机器人一个场景的需求，内容发布、用户评论、私聊消息等场景都会用到。
我当时的做法是把GuardService抽到一个独立的Maven模块里，提供Spring Boot Starter的方式给其他服务引入。任何服务引入该Starter后，只需要在配置文件中声明审核等级，调用一行API即可完成审核。这个模块本身不依赖聊天机器人的任何代码。
提示：审核提示词的维护要单独管理，跟对话提示词分开。审核提示词追求稳定和保守，对话提示词追求个性和灵活，混在一起会两头都做不好。
7. 部署实践与上线后的性能优化
7.1 容器化部署与关键环境变量管理
项目到后期就是部署上线的问题了。我采用的是最标准的做法：写Dockerfile，用Maven插件直接构建镜像，推到私有镜像仓库。Dockerfile的关键点在于多阶段构建，最终运行镜像只带JRE，不带Maven，能省一半以上的镜像体积。
FROM maven:3.9-eclipse-temurin-17 AS build WORKDIR /app COPY pom.xml . RUN mvn dependency:go-offline COPY src ./src RUN mvn package -DskipTests FROM eclipse-temurin:17-jre-alpine WORKDIR /app COPY --from=build /app/target/chatbot-1.0.0.jar app.jar EXPOSE 8080 ENTRYPOINT ["java", "-jar", "app.jar"]环境变量管理这块，一定要把API密钥和数据库链接信息从配置文件中剥离出去，通过环境变量注入。示例配置文件里使用${OPENAI_API_KEY}这种占位符，部署时由K8s的Secret或配置中心注入，避免密钥泄露到镜像仓库。
7.2 性能压测与吞吐量优化
上线之前我做了压测，用的是jmeter，场景是普通对话接口。单实例默认配置下QPS大概在80左右，延迟平均在2.3秒。这个数字不算差，但可以通过几个措施明显提升。
第一层优化是本地缓存：把不变的系统提示词和公共RAG知识直接放本地缓存，省掉反复IO；第二层是限制并发数：模型提供方一般有速率限制，盲目提高客户端并发只会换来429错误。我这里用了Semaphore信号量控制同时进行中的请求数，配合队列等待，实测吞吐更稳定；第三层是超时控制，connect-timeout设3秒，读取超时30秒，避免某个慢请求长时间占住线程池。
@Service public class ChatRateLimiter { private final Semaphore semaphore = new Semaphore(20); public void acquire() { try { semaphore.acquire(); } catch (InterruptedException e) { Thread.currentThread().interrupt(); throw new RuntimeException("请求被中断", e); } } public void release() { semaphore.release(); } }7.3 Token成本监控和用量告警
最后说一个很多教程不会提的话题：Token成本。接大模型API，每一轮对话都在花钱。上线后如果不做成本控制，月底账单会让人肉疼。
我在Redis里维护了一个计数器，每次调用完成后从ChatResponse里取到promptTokens和completionTokens，累加到当天当会话的计量字段里。每天零点定时任务把这个汇总写到MySQL的成本表，同时设置一个阈值，比如单日消耗超过200万Token就触发企业微信告警。
每一个会话也要设单会话Token上限，达到上限后强制触发摘要压缩并清空上下文。这个措施能有效阻止某些异常场景下Token的无限膨胀。
经验之谈：模型调用成本的大头往往不是正常对话，而是异常链路——比如某次循环请求、某个忘关的测试进程、某个没限制长度的重试逻辑。上成本监控比优化参数更能止损。
一路做到这里，这个项目其实已经远远超出了一个“聊天机器人”的范畴：它具备对话能力、内容审核能力、工具调用能力和成本控制能力。我个人在两个星期内从零把这个项目跑通，最大的感受是SpringAI把Java生态接大模型的路上最难走的那段路给铺平了，剩下的路由自己去探索。如果你手里也有一个成型Java EE项目，想低成本接入AI能力，这个方案值得直接上手试。
