1. 为什么这个组合值得实战SpringAI与DeepSeek的契合点做Java后端的人应该都有同感从去年开始各个业务方都在提能不能接入大模型但真到了落地环节Java生态里能直接上手还不太折腾的方案并不多。Python那一套虽然生态热可要硬塞进已有的Spring服务里既要额外维护一套进程又要处理跨语言调用的网络边界团队如果能不引入新语言栈就尽量不引。SpringAI这个项目的定位恰好踩在这个痛点上。它是Spring官方推出的大模型应用抽象层思路有点像当年Spring对JDBC的封装——把不同厂商的大模型API统一收敛成一套接口让你像配置数据源一样配置模型供应商再通过统一的ChatClient去对话。我最初看中的是它对底层细节的屏蔽不需要自己维护HTTP客户端、不需要自己拼请求体、也不用手动解析不同厂商返回的JSON结构。DeepSeek这边则解决了一个关键问题——成本。在需要频繁调用、批量处理文本、甚至跑一些Agent类任务时大模型的token消耗是必须直视的指标。DeepSeek的API定价在同类推理模型里属于非常能打的那一档而且它的推理质量在中英文任务上都有不错的表现尤其在代码生成和逻辑推演场景。加上它也提供了OpenAI兼容的接口风格SpringAI适配起来阻力很小。当然更多人知道DeepSeek是因为开源模型可以本地部署但在实际企业项目里直接接官方API其实是更稳妥的开始方式——不用运维推理集群、不用考虑显卡资源、按量付费起步成本几乎为零。等跑通业务流程、验证了效果再去考虑私有化部署也不迟。这次实战项目就是围绕这个组合来的用Spring Boot搭建一个Java服务通过SpringAI框架调用DeepSeek大模型API实现一个带问答、流式输出、函数调用和简单知识库检索的Demo应用。内容不涉及复杂的分布式架构但把开发过程中遇到的配置坑、模型参数问题、以及性能调优思路都沉淀下来给准备入门的Java团队一个可以直接参考的路径。2. 环境准备与配置落地把这些坑提前填平2.1 版本选型Spring Boot、SpringAI与JDK的兼容矩阵开始之前先明确一件事——SpringAI这个项目迭代速度非常快版本兼容性是你第一个要面对的问题。我最初直接在现有Spring Boot 2.7项目上加SpringAI依赖结果启动时报了一堆自动配置加载失败的错后来查了官方文档才发现新版本的SpringAI已经只支持Spring Boot 3.x了。如果你是从零搭建可以直接用Spring Boot 3.2以上版本加JDK 17这是目前最稳的组合。我当时用的版本组合是JDK 17Spring Boot 3.2.5SpringAI 0.8.1当时的最新release版Maven 3.9这里要提醒一句SpringAI的里程碑版本和快照版本之间API差异很大0.8.1里ChatClient的构建方式跟1.0.0-SNAPSHOT完全不同。如果你在社区看到某段代码复现不了先确认一下双方用的SpringAI版本是不是同一个大版本。我的建议是固定一个release版本不要追SNAPSHOT。2.2 依赖引入与基础配置在pom.xml里只需要引入一个核心starter它会连带把spring-ai-commons、spring-ai-client-chat等基础模块拉进来dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-deepseek-spring-boot-starter/artifactId version0.8.1/version /dependency需要注意SpringAI的模块结构在不同版本里调整过几次。早期版本是spring-ai-openai-spring-boot-starter通吃所有兼容OpenAI协议的模型后来才拆出了独立的DeepSeek模块。如果你用的版本里找不到deepseek这个starter退而求其次用OpenAI starter也能连上DeepSeek因为DeepSeek的API在协议层面兼容OpenAI格式只是要在配置里把base-url指到DeepSeek的地址。基础配置放在application.yml里spring: ai: deepseek: api-key: ${DEEPSEEK_API_KEY} base-url: https://api.deepseek.com chat: options: model: deepseek-chat temperature: 0.7 max-tokens: 2048api-key建议通过环境变量传入别硬编码在配置文件里提交到Git仓库这个习惯应该不用多说了。2.3 model参数一个容易翻车的细节如果你跟我一样配置里写的是DeepSeek官网文档里的模型名deepseek-chat而SpringAI内部某些版本对模型参数做了自定义校验就有可能在调用时报这样一个错Model deepseek-chat is not supported. Supported models: [deepseek-chat, deepseek-reasoner]两个名字看起来一样为什么还报错问题出在框架版本对模型名校验逻辑的实现上。有的版本是按精确字符串匹配的白名单来校验有的版本底层会自动做映射deepseek-chat会被解析成deepseek-chat对应的内部枚举然后再拼到请求路径上。如果你用的版本恰好有这种枚举映射但它识别的名称是其他格式比如带日期后缀的版本号就会卡在启动或者第一次调用的地方。我的解决思路是先确认SpringAI版本支持的模型常量列表再去Bean里显式指定。在配置类里可以这样覆盖Bean public ChatClient chatClient(ChatClient.Builder builder) { return builder .defaultOptions(DeepSeekChatOptions.builder() .withModel(deepseek-chat) .withTemperature(0.7) .build()) .build(); }这样做还有个额外好处同一个服务里可以定义多个ChatClient分别绑定deepseek-chat通用对话和deepseek-reasoner推理增强按业务场景切换。deepseek-reasoner是DeepSeek专门为复杂推理任务设计的模型在数学、逻辑类问题上的表现明显更稳但它的token消耗和响应延迟也更大不是所有场景都适合。提示如果你在配置后发现模型名始终不生效去依赖里翻一下DeepSeek的自动配置类看看它默认绑定的模型枚举是什么对照着改比在网上搜答案快得多。3. ChatClient的核心调用姿势从同步问答到流式输出3.1 最简单的对话调用配置好之后代码层面调用大模型比我想象的简单得多。通过注入的ChatClient一个方法就能完成对话Service public class ChatService { private final ChatClient chatClient; public ChatService(ChatClient chatClient) { this.chatClient chatClient; } public String ask(String question) { return chatClient.prompt(question) .call() .content(); } }就这么多。prompt()接受用户输入call()发起同步调用content()取回模型回复文本。整个过程中HTTP连接管理、请求序列化、鉴权头注入、响应解析这些脏活SpringAI全部做掉了。这段代码跑通之后项目的第一里程碑就算达成了——你的Java服务已经具备跟大模型对话的能力。3.2 多轮对话的上下文管理别踩无状态的坑很多第一次用ChatClient的人会掉进一个误区以为像调用普通接口一样一问一答就完事了。其实大模型本身是无状态的它每次收到请求都只根据你这次传给他的内容来生成回复。要做多轮对话必须把历史消息一起传过去。SpringAI里用一个Prompt对象承载当前请求而历史消息需要手动组装成Message列表public String chatWithHistory(String question, ListMapString, String history) { ListMessage messages new ArrayList(); // 把历史会话拼进去 for (MapString, String item : history) { String role item.get(role); String content item.get(content); if (user.equals(role)) { messages.add(new UserMessage(content)); } else if (assistant.equals(role)) { messages.add(new AssistantMessage(content)); } } // 拼上当前问题 messages.add(new UserMessage(question)); Prompt prompt new Prompt(messages); return chatClient.prompt(prompt).call().content(); }这个方案完全可用但不适合直接怼到生产环境。业务系统里会话往往需要跟用户ID、会话ID绑定而且要控制历史消息的长度防止token爆炸。我实际项目里是引入了Redis来存会话历史每次调用前拉最近N轮消息拼进去同时对总token做估算超了就丢弃更早的消息。这个逻辑不复杂但是必须提前设计不然后面会出现聊着聊着模型突然失忆的诡异现象。3.3 流式输出更接近真实大模型使用体验同步调用最简单但体验不够好。用户在浏览器里发一个问题页面要转圈好几秒才一次性拿到完整答案这在面向C端的聊天场景里基本不可接受。正确做法是流式返回模型生成一个字就传一个字用户看着文字一点点打出来体感延迟趋近于零。SpringAI对流式的支持做得挺顺手用Flux响应式流GetMapping(value /chat/stream, produces MediaType.TEXT_EVENT_STREAM_VALUE) public FluxString streamChat(RequestParam String question) { return chatClient.prompt(question) .stream() .content() .map(Content::text); }控制器方法返回FluxStringSpring WebFlux会自动把每个元素包装成text/event-stream格式推给前端。前端用原生的EventSource或者fetch的ReadableStream都能对接。这里要提醒一个容易忽略的点如果你的项目用的是Spring MVC传统的Tomcat阻塞模型只要方法本身返回Flux类型Spring Boot会自动切换到WebFlux的适配方式并不需要在项目里单独启用完整的WebFlux栈。但这也意味着这个方法所在的应用如果是通过网关对外提供服务的网关层必须支持SSE协议有些网关组件默认会缓冲整个响应导致流式效果失效甚至一直等到响应结束才发给客户端。这个问题在实测环境里排查了将近半天最后是在网关配置里关闭了响应缓冲才解决。3.4 参数调优的几条经验大模型的效果好坏很大程度取决于你怎么调参数。SpringAI的DeepSeekChatOptions支持这些关键参数参数作用我的建议temperature控制生成随机性越高越有创造性越低越稳定通用问答用0.7代码生成或信息抽取用0.2-0.3maxTokens单次回复最长token数默认1024业务需要长文本输出时调到2048以上topP核采样控制候选词范围一般用默认不跟temperature同时调frequencyPenalty惩罚重复词内容创作场景可调到0.5左右但只适合短文本我调过最典型的一个案例让模型做结构化信息抽取刚开始temperature设成默认的1.0同一段文本每次抽取的结果不完全一致字段值偶尔会变。后来把温度降到0.2连续跑10次结果完全一致业务方也就放心了。如果你的场景对结果一致性有硬性要求温度往低调准没错。4. 函数调用与结构化输出让模型真正触达业务数据4.1 函数调用的价值不是让模型联网大模型训练数据是有截止时间的而且它没有实时访问你内部系统的能力。这就带来一个经典问题用户问我上个月的订单总额是多少模型答不上来因为它的知识库里没有你的订单数据。让模型学会调用你预先注册好的函数是解决这类问题的标准手段。思路是这样的你不直接把数据喂给模型而是把有哪些函数可用告诉模型模型根据用户问题决定是否调用某个函数、以及用什么参数调用。真正取数据由你的Java代码执行结果再交给模型组织成自然语言回复。这种方式的最大价值在于模型不需要知道数据细节它只需要学会路由——判断当前问题该走哪个数据通道。数据安全和访问控制掌握在你自己手里。4.2 基于Tool注解的函数注册SpringAI对函数调用的实现非常简洁。你在一个Bean里定义方法加上Tool注解框架会自动把方法签名和描述信息注册给模型Service public class OrderToolService { Tool(description 根据订单ID查询订单状态) public String getOrderStatus(ToolParam(description 订单ID) String orderId) { // 这里写真实的业务查询逻辑 return 订单 orderId 当前状态已发货; } Tool(description 查询指定用户的订单数量) public int countUserOrders(ToolParam(description 用户名) String username) { // 查数据库或调内部接口 return 42; } }只要把这个工具服务注入到ChatClient所在的服务里SpringAI会在发起模型请求时自动加载工具定义。调用流程变成用户提问 → 附带工具定义发模型 → 模型解析意图并返回一个函数调用指令 → SpringAI自动执行对应方法 → 把执行结果返回模型 → 模型基于结果生成最终回复。这里需要注意一个使用细节工具方法的描述信息越详细越好模型判断要不要调用这个函数基本完全依赖这段描述。你写成根据订单ID查询订单状态模型在遇到帮我看看这个订单到哪了这类问题时就能准确匹配。如果描述含糊模型可能会漏调。4.3 实体映射让模型输出变成Java对象函数调用适合让模型去取数据的场景但还有另一类需求更常见让模型把一段非结构化文本整理成结构化数据。比如给模型一段简历文字希望它提取出姓名、年龄、技能列表、工作年限然后直接映射到Java类。传统做法是解析JSON但前提是模型必须输出合法的JSON而且字段名跟JavaBean属性完全对齐。手写提示词去约束很容易出偏差。SpringAI提供了EntityResponse接口来搞定这件事public record PersonInfo( String name, Integer age, ListString skills, Integer workYears ) {} public PersonInfo extractPerson(String text) { return chatClient.prompt() .user(u - u.text(从以下文本中提取人物信息{text}) .param(text, text)) .call() .entity(PersonInfo.class); }框架会隐式地把输出格式约束指令加到提示词里让模型输出JSON格式的响应然后反序列化成PersonInfo。这个方法在跑通之前我持怀疑态度但它确实稳定唯一要留意的是字段类型不要用复杂嵌套太深的对象模型在复杂结构上的表现会下降。能用扁平结构就用扁平的宁可多拆几个小类。5. 集成知识库的示例DemoRAG让回答不再凭空捏造5.1 RAG的基本流程拆解在实际业务里最头疼的问题是模型一本正经地胡说八道。解决这个问题的标准技术路线是RAG检索增强生成简单说在回答问题之前先从你自己的知识库里检索出相关片段把它塞进提示词里作为背景材料再让模型基于这些材料生成答案。这个流程拆开就是四步把文档切分成小块分块用嵌入模型把每块转成向量向量化用户提问时把问题也转成向量去向量库检索最相似的块检索把检索到的块拼进提示词交给大模型生成回答生成5.2 一个可跑的Demo基于产品FAQ的问答服务我搭建的Demo是针对一个产品的FAQ知识库问答系统效果很直接用户问这个产品的试用版有什么限制系统先从FAQ库里检索出相关条目再让DeepSeek基于这些条目组织回答而不是让模型凭训练数据瞎编。向量化环节要单独接嵌入模型。DeepSeek目前不提供嵌入接口所以这里我用了另一个开源嵌入模型通过HTTP接口调用。示例配置spring: ai: embedding: base-url: http://localhost:8081完整代码链路如下Service public class RagService { private final ChatClient chatClient; private final EmbeddingModel embeddingModel; private final VectorStore vectorStore; public RagService(ChatClient chatClient, EmbeddingModel embeddingModel, VectorStore vectorStore) { this.chatClient chatClient; this.embeddingModel embeddingModel; this.vectorStore vectorStore; } // 文档入库分块 向量化 存储 public void addDocument(String content) { ListDocument docs List.of(new Document(content)); vectorStore.add(docs); } // 问答检索 拼接 生成 public String askWithRag(String question) { ListDocument similarDocs vectorStore.similaritySearch( SearchRequest.builder().query(question).topK(3).build() ); String context similarDocs.stream() .map(doc - doc.getText()) .reduce(, (a, b) - a \n b); return chatClient.prompt() .user(u - u.text( 请根据以下资料回答问题。如果资料中没有相关内容请直接说不知道。\n 资料{context}\n问题{question} ).param(context, context).param(question, question)) .call() .content(); } }这里VectorStore用的是SpringAI内置的简单内存向量库仅限Demo验证。真实项目建议换成关系型数据库加pgvector插件或者专门的向量数据库。5.3 检索质量比模型能力更影响最终结果RAG的关键不在大模型而在检索质量。我实测中最直接的体会是文档分块的大小直接决定回答质量。块太大容易混入无关内容检索准确率下降块太小则上下文不完整模型理解不了全貌。一个经验值按段落分块每块控制在200-500个汉字左右。同时要设置合理的重叠窗口就是相邻块之间留出少量重叠内容这样跨块的内容查询时不容易被漏掉。这个细节很多教程里不写但实际效果影响非常大。我在Demo里跑过一个对比一种是把整个FAQ文档当成一个块入库另一种是做了切分加重叠同样的三个测试问题后者有三分之二能检索到正确条目前者几乎全部miss。数据说明一切。6. 性能与成本的隐形战场缓存策略、并发控制和token管理6.1 控制token消耗的三个手段大模型API是按token计费的所以每次调用都在消耗预算。我在实际项目里总结出三个层面的控制手段第一是参数层。maxTokens设置得合适可以防止模型在简单问题上拖出一大段废话。给模型更明确的输出长度指令也有用比如请用不超过200字回答。第二是缓存层。对业务问答类请求如果问题完全相同或高度相似没必要每次都调用模型。我在服务里加了一个简单的缓存把问题和答案的哈希存入Redis设置过期时间。在FAQ场景下缓存命中率最高能到40%左右这是相当可观的成本节省。第三是上下文裁剪。多轮对话场景中历史消息的token占用常常超过实际需要。我实现的策略是只保留最近三轮对话的完整消息再往前的内容用一句摘要替代。这个策略还能顺便提升响应速度因为模型处理更少的输入token需要更少的时间。6.2 并发调用线程池和超时设置SpringAI的ChatClient本身是线程安全的你可以在一个单例里安全地并发调用。但底层HTTP连接资源和模型服务的响应速度是瓶颈所以需要做好并发控制。我在项目里用信号量做了简单的限流控制同时进行的模型请求数不超过预设值防止突发流量把模型API打到限流。另外超时配置一定要加否则请求卡住时会无限占着线程池资源spring: ai: deepseek: client: connect-timeout: 10s read-timeout: 60s这里的read-timeout要留够余量尤其是推理模型reasoner在复杂问题上的响应时间可能达到30秒以上。如果设得太短会出现频繁的超时重试白白消耗token。6.3 重试机制的幂等性设计网络抖动、模型服务过载导致的调用失败是常态所以重试机制几乎必须做。但大模型接口的重试要格外小心一个事第一次调用可能已经成功了只是响应没及时返回如果再重发一次就会产生两次计费。正确做法是在业务数据表里记录本次生成请求的唯一标识和状态重试前先查一下状态如果已经成功就直接取结果如果超时无法确认状态宁可返回一个假失败也不能盲目重试。这一点和普通数据库事务的幂等设计思路完全一致只是很多人第一次做AI应用时没有意识到。6.4 实测下来的性能数据参考在Demo环境下做了一组粗略压测单线程连续调用deepseek-chat平均响应时间约2.5秒8个并发线程同时调用吞吐量约3.5请求/秒平均响应时间稍有上升但整体稳定。换用deepseek-reasoner后平均响应时间显著拉长在复杂问题上能到15秒以上。结论很明确通用问答走deepseek-chat只有确实需要深度推理的任务才切换deepseek-reasoner。整个App部署在一台2核4G的轻量云服务器上Java进程本身内存占用约500M有余量但不宽裕。这也说明了SpringAI这类框架的一个优势它把大模型的复杂计算外包给云端API本地应用需要承担的资源成本其实很低。7. 排查实录一次明明配置正确却调用失败的完整链路这里分享一下我在集成过程中印象最深的一次排查经历整个过程走了不少弯路但复盘下来非常有价值。现象是应用启动正常SpringAI自动配置也加载了日志里能看到Bean创建成功但第一次调用ChatClient时立刻抛出包含401状态码的异常。API Key我确认复制粘贴多次没有空格也没有不可见字符。然后我做了三步排查。第一步直接用curl调DeepSeek的官方API用同一个Key在命令行测试返回结果正常。这说明Key本身没问题。那问题就出在SpringAI构造请求的某个环节。第二步打开Spring的Debug日志查看SpringAI实际发出的请求内容重点看Authorization头。结果发现它传过去的Key和我配置里写的完全一致没有任何改动。那问题更奇怪了。第三步查看应用所在服务器的机器时间和时区。之前调试时遇到过一些API因为客户端时间偏差导致签名校验失败的情况但大模型的API通常不做这种签名逻辑。虽然不是这方面的问题但排查过程中还是多看了几眼。最后的突破口在SpringAI的自动配置源码里。翻到DeepSeekAutoConfiguration的实现后发现它读取API Key时存在一个属性覆盖逻辑如果环境变量里出现某个特定名称它会优先读环境变量而不是配置文件里spring.ai.deepseek.api-key的值。而我的部署环境里恰好有个历史遗留的全局环境变量正好是这个名称值是旧的测试Key。配置文件的Key没问题但被环境变量顶掉了。定位到原因之后解决方案就是把那个环境变量的名称和值都清理掉。改完后重启应用调用立刻恢复正常。这个坑给我最大的教训是自动配置是便利但也可能造成你以为生效了实际上没有的假象。遇到类似问题别只盯着代码和配置文件把应用运行环境的全局变量也翻一遍。类似的隐性覆盖规则在Spring家族里并不罕见。以后遇事不决先打开Debug级别的日志看框架到底实际加载了哪些配置值这比任何猜测都高效。8. 基于这一套实战我沉淀下来的几条扩展思考跑通SpringAIDeepSeek这个组合的Demo之后我从里面梳理出几条对未来项目更有参考价值的经验。第一接入大模型这件事本质上是在给自己的应用增加一种接口。无论这个接口背后是DeepSeek还是别的模型架构设计的核心永远是把AI能力封装成独立的服务模块让业务代码不直接感知模型的存在。这次用ChatClient注入服务的模式就很适合做这种模块化隔离。后续如果模型供应商要换或者要在DeepSeek之外再接入其他模型做对比底层代码不需要大面积改动。第二SpringAI这个框架目前还在快速成长期其API变动比我们熟悉的Spring Boot频繁得多。如果要在团队内推广最好把SpringAI版本锁死在某个release上把相关配置和调用代码封装成内部组件对外暴露的业务接口保持稳定。这样框架升级带来的冲击就能被限制在一个可控范围内。第三模型的选择应该以业务场景为标准而不是以哪个最热为标准。DeepSeek的通用对话模型在成本和效果之间取得了不错平衡但遇到复杂推理、长文档分析这类场景它的推理模型表现更好同时成本也更高。一个应用内部可以同时配置多个模型按功能域去路由这比把所有问题都扔给同一个模型聪明得多。实践下来SpringAIDeepSeek这个组合的落地门槛确实不高对Java团队尤其友好。如果你正在做一个需要大模型能力的Spring项目按这条路径先跑通一个端到端Demo再逐步替换成内部数据源和知识库是最稳妥的切入方式。 
长河君 · 2026/10/22 9:26:27 · 阅读 1.2k SpringAI整合DeepSeek实战：Java大模型应用从入门到落地
1. 为什么这个组合值得实战SpringAI与DeepSeek的契合点做Java后端的人应该都有同感从去年开始各个业务方都在提能不能接入大模型但真到了落地环节Java生态里能直接上手还不太折腾的方案并不多。Python那一套虽然生态热可要硬塞进已有的Spring服务里既要额外维护一套进程又要处理跨语言调用的网络边界团队如果能不引入新语言栈就尽量不引。SpringAI这个项目的定位恰好踩在这个痛点上。它是Spring官方推出的大模型应用抽象层思路有点像当年Spring对JDBC的封装——把不同厂商的大模型API统一收敛成一套接口让你像配置数据源一样配置模型供应商再通过统一的ChatClient去对话。我最初看中的是它对底层细节的屏蔽不需要自己维护HTTP客户端、不需要自己拼请求体、也不用手动解析不同厂商返回的JSON结构。DeepSeek这边则解决了一个关键问题——成本。在需要频繁调用、批量处理文本、甚至跑一些Agent类任务时大模型的token消耗是必须直视的指标。DeepSeek的API定价在同类推理模型里属于非常能打的那一档而且它的推理质量在中英文任务上都有不错的表现尤其在代码生成和逻辑推演场景。加上它也提供了OpenAI兼容的接口风格SpringAI适配起来阻力很小。当然更多人知道DeepSeek是因为开源模型可以本地部署但在实际企业项目里直接接官方API其实是更稳妥的开始方式——不用运维推理集群、不用考虑显卡资源、按量付费起步成本几乎为零。等跑通业务流程、验证了效果再去考虑私有化部署也不迟。这次实战项目就是围绕这个组合来的用Spring Boot搭建一个Java服务通过SpringAI框架调用DeepSeek大模型API实现一个带问答、流式输出、函数调用和简单知识库检索的Demo应用。内容不涉及复杂的分布式架构但把开发过程中遇到的配置坑、模型参数问题、以及性能调优思路都沉淀下来给准备入门的Java团队一个可以直接参考的路径。2. 环境准备与配置落地把这些坑提前填平2.1 版本选型Spring Boot、SpringAI与JDK的兼容矩阵开始之前先明确一件事——SpringAI这个项目迭代速度非常快版本兼容性是你第一个要面对的问题。我最初直接在现有Spring Boot 2.7项目上加SpringAI依赖结果启动时报了一堆自动配置加载失败的错后来查了官方文档才发现新版本的SpringAI已经只支持Spring Boot 3.x了。如果你是从零搭建可以直接用Spring Boot 3.2以上版本加JDK 17这是目前最稳的组合。我当时用的版本组合是JDK 17Spring Boot 3.2.5SpringAI 0.8.1当时的最新release版Maven 3.9这里要提醒一句SpringAI的里程碑版本和快照版本之间API差异很大0.8.1里ChatClient的构建方式跟1.0.0-SNAPSHOT完全不同。如果你在社区看到某段代码复现不了先确认一下双方用的SpringAI版本是不是同一个大版本。我的建议是固定一个release版本不要追SNAPSHOT。2.2 依赖引入与基础配置在pom.xml里只需要引入一个核心starter它会连带把spring-ai-commons、spring-ai-client-chat等基础模块拉进来dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-deepseek-spring-boot-starter/artifactId version0.8.1/version /dependency需要注意SpringAI的模块结构在不同版本里调整过几次。早期版本是spring-ai-openai-spring-boot-starter通吃所有兼容OpenAI协议的模型后来才拆出了独立的DeepSeek模块。如果你用的版本里找不到deepseek这个starter退而求其次用OpenAI starter也能连上DeepSeek因为DeepSeek的API在协议层面兼容OpenAI格式只是要在配置里把base-url指到DeepSeek的地址。基础配置放在application.yml里spring: ai: deepseek: api-key: ${DEEPSEEK_API_KEY} base-url: https://api.deepseek.com chat: options: model: deepseek-chat temperature: 0.7 max-tokens: 2048api-key建议通过环境变量传入别硬编码在配置文件里提交到Git仓库这个习惯应该不用多说了。2.3 model参数一个容易翻车的细节如果你跟我一样配置里写的是DeepSeek官网文档里的模型名deepseek-chat而SpringAI内部某些版本对模型参数做了自定义校验就有可能在调用时报这样一个错Model deepseek-chat is not supported. Supported models: [deepseek-chat, deepseek-reasoner]两个名字看起来一样为什么还报错问题出在框架版本对模型名校验逻辑的实现上。有的版本是按精确字符串匹配的白名单来校验有的版本底层会自动做映射deepseek-chat会被解析成deepseek-chat对应的内部枚举然后再拼到请求路径上。如果你用的版本恰好有这种枚举映射但它识别的名称是其他格式比如带日期后缀的版本号就会卡在启动或者第一次调用的地方。我的解决思路是先确认SpringAI版本支持的模型常量列表再去Bean里显式指定。在配置类里可以这样覆盖Bean public ChatClient chatClient(ChatClient.Builder builder) { return builder .defaultOptions(DeepSeekChatOptions.builder() .withModel(deepseek-chat) .withTemperature(0.7) .build()) .build(); }这样做还有个额外好处同一个服务里可以定义多个ChatClient分别绑定deepseek-chat通用对话和deepseek-reasoner推理增强按业务场景切换。deepseek-reasoner是DeepSeek专门为复杂推理任务设计的模型在数学、逻辑类问题上的表现明显更稳但它的token消耗和响应延迟也更大不是所有场景都适合。提示如果你在配置后发现模型名始终不生效去依赖里翻一下DeepSeek的自动配置类看看它默认绑定的模型枚举是什么对照着改比在网上搜答案快得多。3. ChatClient的核心调用姿势从同步问答到流式输出3.1 最简单的对话调用配置好之后代码层面调用大模型比我想象的简单得多。通过注入的ChatClient一个方法就能完成对话Service public class ChatService { private final ChatClient chatClient; public ChatService(ChatClient chatClient) { this.chatClient chatClient; } public String ask(String question) { return chatClient.prompt(question) .call() .content(); } }就这么多。prompt()接受用户输入call()发起同步调用content()取回模型回复文本。整个过程中HTTP连接管理、请求序列化、鉴权头注入、响应解析这些脏活SpringAI全部做掉了。这段代码跑通之后项目的第一里程碑就算达成了——你的Java服务已经具备跟大模型对话的能力。3.2 多轮对话的上下文管理别踩无状态的坑很多第一次用ChatClient的人会掉进一个误区以为像调用普通接口一样一问一答就完事了。其实大模型本身是无状态的它每次收到请求都只根据你这次传给他的内容来生成回复。要做多轮对话必须把历史消息一起传过去。SpringAI里用一个Prompt对象承载当前请求而历史消息需要手动组装成Message列表public String chatWithHistory(String question, ListMapString, String history) { ListMessage messages new ArrayList(); // 把历史会话拼进去 for (MapString, String item : history) { String role item.get(role); String content item.get(content); if (user.equals(role)) { messages.add(new UserMessage(content)); } else if (assistant.equals(role)) { messages.add(new AssistantMessage(content)); } } // 拼上当前问题 messages.add(new UserMessage(question)); Prompt prompt new Prompt(messages); return chatClient.prompt(prompt).call().content(); }这个方案完全可用但不适合直接怼到生产环境。业务系统里会话往往需要跟用户ID、会话ID绑定而且要控制历史消息的长度防止token爆炸。我实际项目里是引入了Redis来存会话历史每次调用前拉最近N轮消息拼进去同时对总token做估算超了就丢弃更早的消息。这个逻辑不复杂但是必须提前设计不然后面会出现聊着聊着模型突然失忆的诡异现象。3.3 流式输出更接近真实大模型使用体验同步调用最简单但体验不够好。用户在浏览器里发一个问题页面要转圈好几秒才一次性拿到完整答案这在面向C端的聊天场景里基本不可接受。正确做法是流式返回模型生成一个字就传一个字用户看着文字一点点打出来体感延迟趋近于零。SpringAI对流式的支持做得挺顺手用Flux响应式流GetMapping(value /chat/stream, produces MediaType.TEXT_EVENT_STREAM_VALUE) public FluxString streamChat(RequestParam String question) { return chatClient.prompt(question) .stream() .content() .map(Content::text); }控制器方法返回FluxStringSpring WebFlux会自动把每个元素包装成text/event-stream格式推给前端。前端用原生的EventSource或者fetch的ReadableStream都能对接。这里要提醒一个容易忽略的点如果你的项目用的是Spring MVC传统的Tomcat阻塞模型只要方法本身返回Flux类型Spring Boot会自动切换到WebFlux的适配方式并不需要在项目里单独启用完整的WebFlux栈。但这也意味着这个方法所在的应用如果是通过网关对外提供服务的网关层必须支持SSE协议有些网关组件默认会缓冲整个响应导致流式效果失效甚至一直等到响应结束才发给客户端。这个问题在实测环境里排查了将近半天最后是在网关配置里关闭了响应缓冲才解决。3.4 参数调优的几条经验大模型的效果好坏很大程度取决于你怎么调参数。SpringAI的DeepSeekChatOptions支持这些关键参数参数作用我的建议temperature控制生成随机性越高越有创造性越低越稳定通用问答用0.7代码生成或信息抽取用0.2-0.3maxTokens单次回复最长token数默认1024业务需要长文本输出时调到2048以上topP核采样控制候选词范围一般用默认不跟temperature同时调frequencyPenalty惩罚重复词内容创作场景可调到0.5左右但只适合短文本我调过最典型的一个案例让模型做结构化信息抽取刚开始temperature设成默认的1.0同一段文本每次抽取的结果不完全一致字段值偶尔会变。后来把温度降到0.2连续跑10次结果完全一致业务方也就放心了。如果你的场景对结果一致性有硬性要求温度往低调准没错。4. 函数调用与结构化输出让模型真正触达业务数据4.1 函数调用的价值不是让模型联网大模型训练数据是有截止时间的而且它没有实时访问你内部系统的能力。这就带来一个经典问题用户问我上个月的订单总额是多少模型答不上来因为它的知识库里没有你的订单数据。让模型学会调用你预先注册好的函数是解决这类问题的标准手段。思路是这样的你不直接把数据喂给模型而是把有哪些函数可用告诉模型模型根据用户问题决定是否调用某个函数、以及用什么参数调用。真正取数据由你的Java代码执行结果再交给模型组织成自然语言回复。这种方式的最大价值在于模型不需要知道数据细节它只需要学会路由——判断当前问题该走哪个数据通道。数据安全和访问控制掌握在你自己手里。4.2 基于Tool注解的函数注册SpringAI对函数调用的实现非常简洁。你在一个Bean里定义方法加上Tool注解框架会自动把方法签名和描述信息注册给模型Service public class OrderToolService { Tool(description 根据订单ID查询订单状态) public String getOrderStatus(ToolParam(description 订单ID) String orderId) { // 这里写真实的业务查询逻辑 return 订单 orderId 当前状态已发货; } Tool(description 查询指定用户的订单数量) public int countUserOrders(ToolParam(description 用户名) String username) { // 查数据库或调内部接口 return 42; } }只要把这个工具服务注入到ChatClient所在的服务里SpringAI会在发起模型请求时自动加载工具定义。调用流程变成用户提问 → 附带工具定义发模型 → 模型解析意图并返回一个函数调用指令 → SpringAI自动执行对应方法 → 把执行结果返回模型 → 模型基于结果生成最终回复。这里需要注意一个使用细节工具方法的描述信息越详细越好模型判断要不要调用这个函数基本完全依赖这段描述。你写成根据订单ID查询订单状态模型在遇到帮我看看这个订单到哪了这类问题时就能准确匹配。如果描述含糊模型可能会漏调。4.3 实体映射让模型输出变成Java对象函数调用适合让模型去取数据的场景但还有另一类需求更常见让模型把一段非结构化文本整理成结构化数据。比如给模型一段简历文字希望它提取出姓名、年龄、技能列表、工作年限然后直接映射到Java类。传统做法是解析JSON但前提是模型必须输出合法的JSON而且字段名跟JavaBean属性完全对齐。手写提示词去约束很容易出偏差。SpringAI提供了EntityResponse接口来搞定这件事public record PersonInfo( String name, Integer age, ListString skills, Integer workYears ) {} public PersonInfo extractPerson(String text) { return chatClient.prompt() .user(u - u.text(从以下文本中提取人物信息{text}) .param(text, text)) .call() .entity(PersonInfo.class); }框架会隐式地把输出格式约束指令加到提示词里让模型输出JSON格式的响应然后反序列化成PersonInfo。这个方法在跑通之前我持怀疑态度但它确实稳定唯一要留意的是字段类型不要用复杂嵌套太深的对象模型在复杂结构上的表现会下降。能用扁平结构就用扁平的宁可多拆几个小类。5. 集成知识库的示例DemoRAG让回答不再凭空捏造5.1 RAG的基本流程拆解在实际业务里最头疼的问题是模型一本正经地胡说八道。解决这个问题的标准技术路线是RAG检索增强生成简单说在回答问题之前先从你自己的知识库里检索出相关片段把它塞进提示词里作为背景材料再让模型基于这些材料生成答案。这个流程拆开就是四步把文档切分成小块分块用嵌入模型把每块转成向量向量化用户提问时把问题也转成向量去向量库检索最相似的块检索把检索到的块拼进提示词交给大模型生成回答生成5.2 一个可跑的Demo基于产品FAQ的问答服务我搭建的Demo是针对一个产品的FAQ知识库问答系统效果很直接用户问这个产品的试用版有什么限制系统先从FAQ库里检索出相关条目再让DeepSeek基于这些条目组织回答而不是让模型凭训练数据瞎编。向量化环节要单独接嵌入模型。DeepSeek目前不提供嵌入接口所以这里我用了另一个开源嵌入模型通过HTTP接口调用。示例配置spring: ai: embedding: base-url: http://localhost:8081完整代码链路如下Service public class RagService { private final ChatClient chatClient; private final EmbeddingModel embeddingModel; private final VectorStore vectorStore; public RagService(ChatClient chatClient, EmbeddingModel embeddingModel, VectorStore vectorStore) { this.chatClient chatClient; this.embeddingModel embeddingModel; this.vectorStore vectorStore; } // 文档入库分块 向量化 存储 public void addDocument(String content) { ListDocument docs List.of(new Document(content)); vectorStore.add(docs); } // 问答检索 拼接 生成 public String askWithRag(String question) { ListDocument similarDocs vectorStore.similaritySearch( SearchRequest.builder().query(question).topK(3).build() ); String context similarDocs.stream() .map(doc - doc.getText()) .reduce(, (a, b) - a \n b); return chatClient.prompt() .user(u - u.text( 请根据以下资料回答问题。如果资料中没有相关内容请直接说不知道。\n 资料{context}\n问题{question} ).param(context, context).param(question, question)) .call() .content(); } }这里VectorStore用的是SpringAI内置的简单内存向量库仅限Demo验证。真实项目建议换成关系型数据库加pgvector插件或者专门的向量数据库。5.3 检索质量比模型能力更影响最终结果RAG的关键不在大模型而在检索质量。我实测中最直接的体会是文档分块的大小直接决定回答质量。块太大容易混入无关内容检索准确率下降块太小则上下文不完整模型理解不了全貌。一个经验值按段落分块每块控制在200-500个汉字左右。同时要设置合理的重叠窗口就是相邻块之间留出少量重叠内容这样跨块的内容查询时不容易被漏掉。这个细节很多教程里不写但实际效果影响非常大。我在Demo里跑过一个对比一种是把整个FAQ文档当成一个块入库另一种是做了切分加重叠同样的三个测试问题后者有三分之二能检索到正确条目前者几乎全部miss。数据说明一切。6. 性能与成本的隐形战场缓存策略、并发控制和token管理6.1 控制token消耗的三个手段大模型API是按token计费的所以每次调用都在消耗预算。我在实际项目里总结出三个层面的控制手段第一是参数层。maxTokens设置得合适可以防止模型在简单问题上拖出一大段废话。给模型更明确的输出长度指令也有用比如请用不超过200字回答。第二是缓存层。对业务问答类请求如果问题完全相同或高度相似没必要每次都调用模型。我在服务里加了一个简单的缓存把问题和答案的哈希存入Redis设置过期时间。在FAQ场景下缓存命中率最高能到40%左右这是相当可观的成本节省。第三是上下文裁剪。多轮对话场景中历史消息的token占用常常超过实际需要。我实现的策略是只保留最近三轮对话的完整消息再往前的内容用一句摘要替代。这个策略还能顺便提升响应速度因为模型处理更少的输入token需要更少的时间。6.2 并发调用线程池和超时设置SpringAI的ChatClient本身是线程安全的你可以在一个单例里安全地并发调用。但底层HTTP连接资源和模型服务的响应速度是瓶颈所以需要做好并发控制。我在项目里用信号量做了简单的限流控制同时进行的模型请求数不超过预设值防止突发流量把模型API打到限流。另外超时配置一定要加否则请求卡住时会无限占着线程池资源spring: ai: deepseek: client: connect-timeout: 10s read-timeout: 60s这里的read-timeout要留够余量尤其是推理模型reasoner在复杂问题上的响应时间可能达到30秒以上。如果设得太短会出现频繁的超时重试白白消耗token。6.3 重试机制的幂等性设计网络抖动、模型服务过载导致的调用失败是常态所以重试机制几乎必须做。但大模型接口的重试要格外小心一个事第一次调用可能已经成功了只是响应没及时返回如果再重发一次就会产生两次计费。正确做法是在业务数据表里记录本次生成请求的唯一标识和状态重试前先查一下状态如果已经成功就直接取结果如果超时无法确认状态宁可返回一个假失败也不能盲目重试。这一点和普通数据库事务的幂等设计思路完全一致只是很多人第一次做AI应用时没有意识到。6.4 实测下来的性能数据参考在Demo环境下做了一组粗略压测单线程连续调用deepseek-chat平均响应时间约2.5秒8个并发线程同时调用吞吐量约3.5请求/秒平均响应时间稍有上升但整体稳定。换用deepseek-reasoner后平均响应时间显著拉长在复杂问题上能到15秒以上。结论很明确通用问答走deepseek-chat只有确实需要深度推理的任务才切换deepseek-reasoner。整个App部署在一台2核4G的轻量云服务器上Java进程本身内存占用约500M有余量但不宽裕。这也说明了SpringAI这类框架的一个优势它把大模型的复杂计算外包给云端API本地应用需要承担的资源成本其实很低。7. 排查实录一次明明配置正确却调用失败的完整链路这里分享一下我在集成过程中印象最深的一次排查经历整个过程走了不少弯路但复盘下来非常有价值。现象是应用启动正常SpringAI自动配置也加载了日志里能看到Bean创建成功但第一次调用ChatClient时立刻抛出包含401状态码的异常。API Key我确认复制粘贴多次没有空格也没有不可见字符。然后我做了三步排查。第一步直接用curl调DeepSeek的官方API用同一个Key在命令行测试返回结果正常。这说明Key本身没问题。那问题就出在SpringAI构造请求的某个环节。第二步打开Spring的Debug日志查看SpringAI实际发出的请求内容重点看Authorization头。结果发现它传过去的Key和我配置里写的完全一致没有任何改动。那问题更奇怪了。第三步查看应用所在服务器的机器时间和时区。之前调试时遇到过一些API因为客户端时间偏差导致签名校验失败的情况但大模型的API通常不做这种签名逻辑。虽然不是这方面的问题但排查过程中还是多看了几眼。最后的突破口在SpringAI的自动配置源码里。翻到DeepSeekAutoConfiguration的实现后发现它读取API Key时存在一个属性覆盖逻辑如果环境变量里出现某个特定名称它会优先读环境变量而不是配置文件里spring.ai.deepseek.api-key的值。而我的部署环境里恰好有个历史遗留的全局环境变量正好是这个名称值是旧的测试Key。配置文件的Key没问题但被环境变量顶掉了。定位到原因之后解决方案就是把那个环境变量的名称和值都清理掉。改完后重启应用调用立刻恢复正常。这个坑给我最大的教训是自动配置是便利但也可能造成你以为生效了实际上没有的假象。遇到类似问题别只盯着代码和配置文件把应用运行环境的全局变量也翻一遍。类似的隐性覆盖规则在Spring家族里并不罕见。以后遇事不决先打开Debug级别的日志看框架到底实际加载了哪些配置值这比任何猜测都高效。8. 基于这一套实战我沉淀下来的几条扩展思考跑通SpringAIDeepSeek这个组合的Demo之后我从里面梳理出几条对未来项目更有参考价值的经验。第一接入大模型这件事本质上是在给自己的应用增加一种接口。无论这个接口背后是DeepSeek还是别的模型架构设计的核心永远是把AI能力封装成独立的服务模块让业务代码不直接感知模型的存在。这次用ChatClient注入服务的模式就很适合做这种模块化隔离。后续如果模型供应商要换或者要在DeepSeek之外再接入其他模型做对比底层代码不需要大面积改动。第二SpringAI这个框架目前还在快速成长期其API变动比我们熟悉的Spring Boot频繁得多。如果要在团队内推广最好把SpringAI版本锁死在某个release上把相关配置和调用代码封装成内部组件对外暴露的业务接口保持稳定。这样框架升级带来的冲击就能被限制在一个可控范围内。第三模型的选择应该以业务场景为标准而不是以哪个最热为标准。DeepSeek的通用对话模型在成本和效果之间取得了不错平衡但遇到复杂推理、长文档分析这类场景它的推理模型表现更好同时成本也更高。一个应用内部可以同时配置多个模型按功能域去路由这比把所有问题都扔给同一个模型聪明得多。实践下来SpringAIDeepSeek这个组合的落地门槛确实不高对Java团队尤其友好。如果你正在做一个需要大模型能力的Spring项目按这条路径先跑通一个端到端Demo再逐步替换成内部数据源和知识库是最稳妥的切入方式。