简介这份PDF文档面向希望将大模型能力落地到企业级应用的Java开发者与架构师围绕SpringAI与DeepSeek的跨平台集成展开系统讲解从环境搭建、基础配置到核心功能实现的完整路径。内容涵盖SpringAI依赖引入与配置、DeepSeek模型接入与参数调优、两者集成架构设计、数据交互与异常处理并延伸至智能对话、智能推荐、智能决策支持与数据可视化等企业级功能模块同时涉及性能优化、监控、安全合规及实际案例分析。资源为单个PDF文件共35页压缩包约2.01MB文档内容完整、目录条理清晰文字与图表均显示正常。目前已有132人学习关注。读者可借助这份指南掌握SpringAI与DeepSeek协同开发的关键步骤与排错思路快速理解企业级智能系统的构建流程与优化策略适合作为项目实践中的参考手册。1. 跨平台集成指南SpringAIDeepSeek 构建企业级智能系统到底在解决什么问题很多团队在 2024 年之后都遇到同一个尴尬业务部门要一个「能问答、能查数据、能写报告」的智能助手IT 部门手里却是一堆异构系统——Java 老服务、Python 算法脚本、内网数据库、企业微信入口。直接调 DeepSeek 的 API 写个 demo 只要半天但要把它做成能上线、能审计、能换模型、能跨平台跑的企业级系统往往卡在集成层。SpringAI 的价值就在这里它把大模型调用抽象成 Spring 生态里的一等公民用一套统一的 ChatClient、EmbeddingClient、VectorStore 接口把 DeepSeek 这类模型接进已有的 Java 服务体系而不是另起一个 Python 孤岛。这篇笔记讲的就是这条路径怎么用 SpringAI 把 DeepSeek 接进来怎么在 Windows、Linux、容器三种环境下跑通参数怎么设坑在哪。适合已经有 Spring Boot 基础、正在评估企业级 AI 集成方案的工程师也适合想从「调 API」升级到「做系统」的开发者。2. SpringAI 接 DeepSeek 的集成原理与最小可跑工程2.1 为什么选 SpringAI 而不是直接写 HTTP 客户端直接写 HTTP 客户端调 DeepSeek 的/chat/completions接口代码量不大但企业级场景下会迅速暴露问题多模型切换要改代码、流式响应要自己处理 SSE、重试和超时要自己封装、对话记忆要自己维护、可观测性要自己埋点。SpringAI 把这些都做成了可配置的抽象层。它的核心接口是ChatModel和ChatClient前者负责底层通信后者负责对话编排。DeepSeek 的 API 兼容 OpenAI 协议所以 SpringAI 里可以直接用 OpenAI 的 starter只改base-url和api-key两个配置就能指向 DeepSeek。这个设计的好处是今天用 DeepSeek明天要换别的兼容 OpenAI 协议的模型改配置就行业务代码不动。对于企业级系统来说这种「模型可替换」的能力比省几行代码重要得多。2.2 最小可跑工程从 pom 到第一个对话接口先建一个标准的 Spring Boot 3.x 工程JDK 17 起步。SpringAI 对 Spring Boot 版本有要求1.0.x 系列需要 Boot 3.2 以上。下面是 Maven 依赖的核心部分dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version1.0.0/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement dependencies !-- OpenAI 兼容协议 starterDeepSeek 走这个 -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency /dependencies依赖说明spring-ai-bom统一管理版本避免各 starter 版本打架spring-ai-openai-spring-boot-starter是核心它内部用的是 OpenAI 的 Java SDK但允许覆盖 base-url。注意 SpringAI 的里程碑版本和正式版本在包名上有差异如果你用的是 0.8.x 以前的版本artifactId 可能是spring-ai-openai-spring-boot-starter之外的写法建议以你实际拉到的依赖树为准。配置文件application.ymlspring: ai: openai: base-url: https://api.deepseek.com api-key: ${DEEPSEEK_API_KEY} chat: options: model: deepseek-chat temperature: 0.7 max-tokens: 2048参数说明base-url指向 DeepSeek 的开放平台地址注意不要带/v1后缀SpringAI 会自己拼路径api-key从环境变量读不要硬编码进仓库model填deepseek-chat或deepseek-reasoner前者是通用对话模型后者是推理模型按场景选temperature在 0.3 到 0.7 之间比较稳做数据抽取建议 0.1 到 0.3做创意文案可以到 1.0max-tokens控制单次输出上限设太小会导致回答被截断设太大在流式场景下首字延迟感知不明显但成本会上去。写一个最小的 ControllerRestController public class ChatController { private final ChatClient chatClient; public ChatController(ChatClient.Builder builder) { // 构造时注入系统提示词企业场景下通常放角色约束 this.chatClient builder .defaultSystem(你是一个企业知识助手回答要简洁不确定时明确说不知道。) .build(); } GetMapping(/chat) public String chat(RequestParam String message) { // call() 是同步阻塞stream() 是流式按接口类型选 return chatClient.prompt() .user(message) .call() .content(); } }逻辑说明ChatClient.Builder由 starter 自动装配注入时已经带好了 base-url 和 api-keydefaultSystem设置全局系统提示词这是企业级系统里做「角色约束」和「安全边界」的第一道闸prompt().user().call().content()是最短调用链同步返回字符串。启动后访问/chat?message你好就能看到 DeepSeek 的回复。这一步跑通说明网络、密钥、模型名三件事都对了。2.3 流式响应与对话记忆的配置方式企业级系统里同步接口只适合后台任务面向用户的入口基本都要流式。SpringAI 的流式写法GetMapping(value /chat/stream, produces MediaType.TEXT_EVENT_STREAM_VALUE) public FluxString chatStream(RequestParam String message) { return chatClient.prompt() .user(message) .stream() .content(); }这里返回FluxString配合TEXT_EVENT_STREAM_VALUE就是标准 SSE。注意 DeepSeek 的流式返回里最后一个 chunk 可能带finish_reasonSpringAI 已经帮你过滤了空 delta但如果你自己在前端做拼接要处理「空字符串 chunk」的情况否则会出现多余换行。对话记忆用ChatMemoryBean public ChatMemory chatMemory() { // 保留最近 20 条消息超出后按策略淘汰 return new InMemoryChatMemory(); }然后在构建 ChatClient 时挂上 advisorthis.chatClient builder .defaultSystem(...) .defaultAdvisors(new MessageChatMemoryAdvisor(chatMemory())) .build();参数说明InMemoryChatMemory只适合单机 demo生产环境要换成基于 Redis 或数据库的实现否则重启就丢记忆条数不是越多越好DeepSeek 的上下文窗口虽然大但历史消息越多每次请求的 token 消耗越高延迟也越大一般保留最近 10 到 20 轮足够。如果做的是「对话上限之后承接上一个对话」这类需求本质就是把历史消息做摘要后压缩成一条 system 消息再塞回去这个策略要自己实现SpringAI 只提供存储抽象。3. 跨平台部署Windows、Linux、容器三种环境的落地差异3.1 Windows 本地开发环境的两个必调项Windows 上跑 SpringAI DeepSeek最常见的问题不是代码是环境和网络。第一JDK 版本要用 17 或 21不要用 8SpringAI 的很多 API 用了 record 和 sealed class。第二如果公司网络有出口限制base-url的连通性要先单独验证用 curl 或 PowerShell 的Invoke-RestMethod测一下不要等应用启动报错才排查。PowerShell 里测$headers { Authorization Bearer $env:DEEPSEEK_API_KEY } $body { model deepseek-chat; messages ({ role user; content ping }) } | ConvertTo-Json Invoke-RestMethod -Uri https://api.deepseek.com/chat/completions -Method Post -Headers $headers -Body $body -ContentType application/json如果这一步返回正常说明密钥和网络都没问题应用里再报错就是配置写法问题。Windows 上还有一个坑环境变量的读取。IDEA 里配的 Environment variables 和系统环境变量是两回事${DEEPSEEK_API_KEY}在 IDEA 运行配置里要单独加否则启动时占位符解析失败。3.2 Linux 服务器上的 systemd 与日志配置Linux 上部署 Spring Boot 应用常见做法是打成 jar 后用 systemd 托管。关键配置[Unit] DescriptionSpringAI DeepSeek Service Afternetwork.target [Service] Userappuser EnvironmentDEEPSEEK_API_KEYsk-xxxx EnvironmentJAVA_OPTS-Xms512m -Xmx2g -Dfile.encodingUTF-8 ExecStart/usr/bin/java $JAVA_OPTS -jar /opt/app/ai-service.jar Restarton-failure RestartSec10 [Install] WantedBymulti-user.target参数说明Environment里放密钥注意文件权限设成 600不要让其他用户读到-Dfile.encodingUTF-8必须加否则中文日志和中文回答可能乱码Restarton-failure配合RestartSec10做基础自愈。日志方面SpringAI 默认不打请求体排查问题时可以在application.yml里把logging.level.org.springframework.ai调到 DEBUG但生产环境不要长期开会把 API key 和用户输入打进日志。3.3 容器化部署的镜像分层与健康检查容器化是企业级系统的标配但 SpringAI 应用的镜像有两个特殊点。第一模型调用是外部依赖健康检查不能只检查应用端口要加一个轻量的模型连通性探针。第二镜像分层要把依赖和业务代码分开利用 Docker 缓存加速构建。FROM eclipse-temurin:17-jre-jammy WORKDIR /app # 先拷依赖描述利用缓存层 COPY target/classes/application.yml /app/config/ COPY target/ai-service.jar /app/app.jar ENV JAVA_OPTS-Xms512m -Xmx2g EXPOSE 8080 HEALTHCHECK --interval30s --timeout5s --retries3 \ CMD curl -f http://localhost:8080/actuator/health || exit 1 ENTRYPOINT [sh, -c, java $JAVA_OPTS -jar /app/app.jar]逻辑说明HEALTHCHECK走 Spring Boot Actuator 的/actuator/health需要在 pom 里加spring-boot-starter-actuator并在配置里暴露端点如果要做模型连通性探针可以自定义一个HealthIndicator在里面发一个极短的 ping 请求但注意探针频率不要太高否则会白白消耗 token。容器里跑的时候base-url如果走内网代理要确认容器网络的 DNS 和出口策略这是容器化部署翻车最多的地方。4. 企业级能力补齐RAG、工具调用与多模型路由4.1 用 VectorStore 做企业知识库检索增强企业级智能系统和 demo 的最大区别是「回答要有依据」。DeepSeek 本身不知道你公司的内部文档所以要接 RAG。SpringAI 的 RAG 链路是文档读取 → 切分 → 向量化 → 存 VectorStore → 检索 → 拼进 prompt。最小实现Bean public VectorStore vectorStore(EmbeddingModel embeddingModel) { // 内存向量库生产换 Redis 或 PGVector return new SimpleVectorStore(embeddingModel); } Bean public ApplicationRunner loadDocs(VectorStore vectorStore) { return args - { ListDocument docs List.of( new Document(公司报销标准差旅住宿一线城市不超过 500 元/晚。), new Document(年假规则入职满一年享 5 天满三年 10 天。) ); vectorStore.add(docs); }; }检索时用QuestionAnswerAdvisorthis.chatClient builder .defaultSystem(...) .defaultAdvisors(new QuestionAnswerAdvisor(vectorStore)) .build();参数说明SimpleVectorStore只适合验证重启就丢生产用 PGVector 或 Redis 的向量能力注意 embedding 模型要和存储时一致换模型必须重建索引切分粒度一般 300 到 500 字一段重叠 50 字太大检索不准太小上下文断裂。DeepSeek 本身不提供 embedding 接口embedding 要用别的模型这是很多团队第一次做 RAG 时没预料到的。4.2 工具调用让模型能查实时数据DeepSeek 支持 function callingSpringAI 里用Tool注解暴露方法Component public class OrderTools { Tool(description 根据订单号查询订单状态) public String queryOrderStatus(String orderId) { // 实际接内部订单服务 return 订单 orderId 状态已发货; } }注册到 ChatClientthis.chatClient builder .defaultTools(new OrderTools()) .build();逻辑说明模型会根据用户问题决定是否调用工具调用参数由模型生成返回值再喂回模型做最终回答。注意工具方法的参数类型要简单String、int 这类复杂对象模型容易生成错工具描述要写清楚这是模型判断「什么时候调」的唯一依据。企业场景下工具方法内部要做权限校验不能因为模型调了就无条件执行。4.3 多模型路由与降级策略企业级系统不能把鸡蛋放一个篮子里。常见做法是配多个 ChatModel用一个 Router 按场景选public class ModelRouter { private final ChatClient deepseekClient; private final ChatClient backupClient; public String chat(String scene, String message) { try { return deepseekClient.prompt().user(message).call().content(); } catch (Exception e) { // 主模型失败降级到备用 return backupClient.prompt().user(message).call().content(); } } }参数说明降级要区分异常类型超时和限流可以降级参数错误降级没意义备用模型可以是另一个兼容 OpenAI 协议的模型配置方式一样只是 base-url 和 model 不同路由策略可以按场景硬编码也可以按 token 长度、按是否流式来分。这套东西不复杂但要在项目初期就设计好后期补会动到很多调用点。5. 避坑与排查SpringAI 接 DeepSeek 最常见的 5 个翻车点5.1 启动报 401 但密钥明明是对的现象应用启动后第一次调用返回 401 Unauthorized但用 curl 测同样的密钥是通的。原因SpringAI 的 OpenAI starter 默认会在 api-key 前面拼Bearer如果你在配置里自己写了Bearer sk-xxx就会变成Bearer Bearer sk-xxx。解决api-key只填sk-开头的原始值不要带前缀。另外检查环境变量有没有多余空格YAML 里${DEEPSEEK_API_KEY}如果变量不存在会原样传入也会导致 401。5.2 流式接口返回乱码或粘包现象前端收到的 SSE 数据里中文乱码或者多个 chunk 粘在一起。原因响应头没设 charset或者中间有网关做了缓冲。解决produces里明确写MediaType.TEXT_EVENT_STREAM_VALUESpring Boot 默认会带 UTF-8如果前面有 Nginx要关掉proxy_buffering否则流式会被攒成一坨再发。这个坑在容器化部署时特别常见因为 ingress 层默认就是缓冲的。5.3 对话记忆导致 token 暴涨现象用了一段时间后每次请求的 token 数越来越大费用涨得比预期快。原因InMemoryChatMemory默认不限制条数历史消息全量塞进 prompt。解决换用带窗口限制的记忆实现或者自己写一个按条数或按 token 数淘汰的策略。经验值是保留最近 10 轮更早的做摘要压缩。另外注意系统提示词和 RAG 检索到的文档也会占 token做预算时要一起算。5.4 工具调用在 DeepSeek 上不触发现象配了Tool但模型始终不调用直接编答案。原因DeepSeek 的 function calling 对工具描述和参数 schema 比较敏感描述太模糊模型就不敢调另外有些模型版本对并行工具调用的支持不一致。解决工具描述写成「什么时候用 参数含义 返回什么」越具体越好参数用基本类型如果还是不触发在系统提示词里明确写「需要查询订单时必须调用 queryOrderStatus 工具不要自己编造」。5.5 容器里连不上 DeepSeek 但宿主机可以现象本地跑没问题打进容器就超时。原因容器网络的 DNS 配置和宿主机不同或者公司出口策略对容器网段有限制。解决进容器里用curl或wget测一下base-url的连通性检查/etc/resolv.conf如果是 K8s 环境检查 NetworkPolicy 和 egress 规则。这个坑没有代码层面的解法纯粹是网络排查但它是跨平台集成里最高频的阻塞点。6. 进阶技巧用配置化路由把模型切换成本降到零走到这里系统基本能跑了。但企业级项目还有一个隐性需求模型要能换而且换的时候不改代码、不重新打包。我的做法是把模型配置抽成一张表用 Spring 的ConfigurationProperties绑定运行时按 key 取对应的 ChatClient。ConfigurationProperties(prefix ai.models) Component public class ModelProperties { // key 是场景名value 是该场景的模型配置 private MapString, ModelConfig routes new HashMap(); public static class ModelConfig { private String baseUrl; private String apiKey; private String model; private Double temperature; // getter/setter 省略 } // getter/setter 省略 }配置长这样ai: models: routes: chat: base-url: https://api.deepseek.com api-key: ${DEEPSEEK_API_KEY} model: deepseek-chat temperature: 0.7 reason: base-url: https://api.deepseek.com api-key: ${DEEPSEEK_API_KEY} model: deepseek-reasoner temperature: 0.3然后写一个工厂按场景名构建 ChatClient 并缓存Component public class ChatClientFactory { private final MapString, ChatClient cache new ConcurrentHashMap(); private final ModelProperties properties; public ChatClientFactory(ModelProperties properties) { this.properties properties; } public ChatClient get(String scene) { return cache.computeIfAbsent(scene, s - { ModelProperties.ModelConfig cfg properties.getRoutes().get(s); if (cfg null) throw new IllegalArgumentException(未配置场景: s); OpenAiApi api OpenAiApi.builder() .baseUrl(cfg.getBaseUrl()) .apiKey(cfg.getApiKey()) .build(); return ChatClient.builder(new OpenAiChatModel(api)) .defaultSystem(你是企业助手场景 s) .build(); }); } }逻辑说明computeIfAbsent保证每个场景只构建一次避免每次请求都 new 一个客户端OpenAiApi的 builder 允许每个场景用不同的 base-url 和 key这样主备模型、不同厂商模型可以共存场景名从业务层传入业务代码只依赖ChatClientFactory.get(chat)不关心底层是哪个模型。参数说明temperature按场景配推理场景调低创意场景调高如果某个场景要流式工厂返回的 ChatClient 同时支持call()和stream()不用改。验证这套路由是否生效最直接的办法是写一个集成测试对每个场景发一条固定问题断言返回非空且耗时在阈值内。我一般还会加一个/actuator/info的自定义端点把当前加载的场景列表和模型名暴露出来上线后一眼就能确认配置有没有生效。这个习惯帮我省过好几次「以为改了配置其实没生效」的后悔药。最后说一个我踩过的坑配置化路由做完之后团队里有人直接在 YAML 里写 api-key提交到了仓库。后来我们加了一条 CI 检查扫描配置文件里有没有sk-开头的字符串有就阻断合并。技术方案再优雅也架不住流程上的疏忽该上的闸还是得上。希望帮到你。本文还有配套的精品资源点击获取 SpringAI+DeepSeek跨平台集成：企业级智能系统构建指南
简介这份PDF文档面向希望将大模型能力落地到企业级应用的Java开发者与架构师围绕SpringAI与DeepSeek的跨平台集成展开系统讲解从环境搭建、基础配置到核心功能实现的完整路径。内容涵盖SpringAI依赖引入与配置、DeepSeek模型接入与参数调优、两者集成架构设计、数据交互与异常处理并延伸至智能对话、智能推荐、智能决策支持与数据可视化等企业级功能模块同时涉及性能优化、监控、安全合规及实际案例分析。资源为单个PDF文件共35页压缩包约2.01MB文档内容完整、目录条理清晰文字与图表均显示正常。目前已有132人学习关注。读者可借助这份指南掌握SpringAI与DeepSeek协同开发的关键步骤与排错思路快速理解企业级智能系统的构建流程与优化策略适合作为项目实践中的参考手册。1. 跨平台集成指南SpringAIDeepSeek 构建企业级智能系统到底在解决什么问题很多团队在 2024 年之后都遇到同一个尴尬业务部门要一个「能问答、能查数据、能写报告」的智能助手IT 部门手里却是一堆异构系统——Java 老服务、Python 算法脚本、内网数据库、企业微信入口。直接调 DeepSeek 的 API 写个 demo 只要半天但要把它做成能上线、能审计、能换模型、能跨平台跑的企业级系统往往卡在集成层。SpringAI 的价值就在这里它把大模型调用抽象成 Spring 生态里的一等公民用一套统一的 ChatClient、EmbeddingClient、VectorStore 接口把 DeepSeek 这类模型接进已有的 Java 服务体系而不是另起一个 Python 孤岛。这篇笔记讲的就是这条路径怎么用 SpringAI 把 DeepSeek 接进来怎么在 Windows、Linux、容器三种环境下跑通参数怎么设坑在哪。适合已经有 Spring Boot 基础、正在评估企业级 AI 集成方案的工程师也适合想从「调 API」升级到「做系统」的开发者。2. SpringAI 接 DeepSeek 的集成原理与最小可跑工程2.1 为什么选 SpringAI 而不是直接写 HTTP 客户端直接写 HTTP 客户端调 DeepSeek 的/chat/completions接口代码量不大但企业级场景下会迅速暴露问题多模型切换要改代码、流式响应要自己处理 SSE、重试和超时要自己封装、对话记忆要自己维护、可观测性要自己埋点。SpringAI 把这些都做成了可配置的抽象层。它的核心接口是ChatModel和ChatClient前者负责底层通信后者负责对话编排。DeepSeek 的 API 兼容 OpenAI 协议所以 SpringAI 里可以直接用 OpenAI 的 starter只改base-url和api-key两个配置就能指向 DeepSeek。这个设计的好处是今天用 DeepSeek明天要换别的兼容 OpenAI 协议的模型改配置就行业务代码不动。对于企业级系统来说这种「模型可替换」的能力比省几行代码重要得多。2.2 最小可跑工程从 pom 到第一个对话接口先建一个标准的 Spring Boot 3.x 工程JDK 17 起步。SpringAI 对 Spring Boot 版本有要求1.0.x 系列需要 Boot 3.2 以上。下面是 Maven 依赖的核心部分dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version1.0.0/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement dependencies !-- OpenAI 兼容协议 starterDeepSeek 走这个 -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency /dependencies依赖说明spring-ai-bom统一管理版本避免各 starter 版本打架spring-ai-openai-spring-boot-starter是核心它内部用的是 OpenAI 的 Java SDK但允许覆盖 base-url。注意 SpringAI 的里程碑版本和正式版本在包名上有差异如果你用的是 0.8.x 以前的版本artifactId 可能是spring-ai-openai-spring-boot-starter之外的写法建议以你实际拉到的依赖树为准。配置文件application.ymlspring: ai: openai: base-url: https://api.deepseek.com api-key: ${DEEPSEEK_API_KEY} chat: options: model: deepseek-chat temperature: 0.7 max-tokens: 2048参数说明base-url指向 DeepSeek 的开放平台地址注意不要带/v1后缀SpringAI 会自己拼路径api-key从环境变量读不要硬编码进仓库model填deepseek-chat或deepseek-reasoner前者是通用对话模型后者是推理模型按场景选temperature在 0.3 到 0.7 之间比较稳做数据抽取建议 0.1 到 0.3做创意文案可以到 1.0max-tokens控制单次输出上限设太小会导致回答被截断设太大在流式场景下首字延迟感知不明显但成本会上去。写一个最小的 ControllerRestController public class ChatController { private final ChatClient chatClient; public ChatController(ChatClient.Builder builder) { // 构造时注入系统提示词企业场景下通常放角色约束 this.chatClient builder .defaultSystem(你是一个企业知识助手回答要简洁不确定时明确说不知道。) .build(); } GetMapping(/chat) public String chat(RequestParam String message) { // call() 是同步阻塞stream() 是流式按接口类型选 return chatClient.prompt() .user(message) .call() .content(); } }逻辑说明ChatClient.Builder由 starter 自动装配注入时已经带好了 base-url 和 api-keydefaultSystem设置全局系统提示词这是企业级系统里做「角色约束」和「安全边界」的第一道闸prompt().user().call().content()是最短调用链同步返回字符串。启动后访问/chat?message你好就能看到 DeepSeek 的回复。这一步跑通说明网络、密钥、模型名三件事都对了。2.3 流式响应与对话记忆的配置方式企业级系统里同步接口只适合后台任务面向用户的入口基本都要流式。SpringAI 的流式写法GetMapping(value /chat/stream, produces MediaType.TEXT_EVENT_STREAM_VALUE) public FluxString chatStream(RequestParam String message) { return chatClient.prompt() .user(message) .stream() .content(); }这里返回FluxString配合TEXT_EVENT_STREAM_VALUE就是标准 SSE。注意 DeepSeek 的流式返回里最后一个 chunk 可能带finish_reasonSpringAI 已经帮你过滤了空 delta但如果你自己在前端做拼接要处理「空字符串 chunk」的情况否则会出现多余换行。对话记忆用ChatMemoryBean public ChatMemory chatMemory() { // 保留最近 20 条消息超出后按策略淘汰 return new InMemoryChatMemory(); }然后在构建 ChatClient 时挂上 advisorthis.chatClient builder .defaultSystem(...) .defaultAdvisors(new MessageChatMemoryAdvisor(chatMemory())) .build();参数说明InMemoryChatMemory只适合单机 demo生产环境要换成基于 Redis 或数据库的实现否则重启就丢记忆条数不是越多越好DeepSeek 的上下文窗口虽然大但历史消息越多每次请求的 token 消耗越高延迟也越大一般保留最近 10 到 20 轮足够。如果做的是「对话上限之后承接上一个对话」这类需求本质就是把历史消息做摘要后压缩成一条 system 消息再塞回去这个策略要自己实现SpringAI 只提供存储抽象。3. 跨平台部署Windows、Linux、容器三种环境的落地差异3.1 Windows 本地开发环境的两个必调项Windows 上跑 SpringAI DeepSeek最常见的问题不是代码是环境和网络。第一JDK 版本要用 17 或 21不要用 8SpringAI 的很多 API 用了 record 和 sealed class。第二如果公司网络有出口限制base-url的连通性要先单独验证用 curl 或 PowerShell 的Invoke-RestMethod测一下不要等应用启动报错才排查。PowerShell 里测$headers { Authorization Bearer $env:DEEPSEEK_API_KEY } $body { model deepseek-chat; messages ({ role user; content ping }) } | ConvertTo-Json Invoke-RestMethod -Uri https://api.deepseek.com/chat/completions -Method Post -Headers $headers -Body $body -ContentType application/json如果这一步返回正常说明密钥和网络都没问题应用里再报错就是配置写法问题。Windows 上还有一个坑环境变量的读取。IDEA 里配的 Environment variables 和系统环境变量是两回事${DEEPSEEK_API_KEY}在 IDEA 运行配置里要单独加否则启动时占位符解析失败。3.2 Linux 服务器上的 systemd 与日志配置Linux 上部署 Spring Boot 应用常见做法是打成 jar 后用 systemd 托管。关键配置[Unit] DescriptionSpringAI DeepSeek Service Afternetwork.target [Service] Userappuser EnvironmentDEEPSEEK_API_KEYsk-xxxx EnvironmentJAVA_OPTS-Xms512m -Xmx2g -Dfile.encodingUTF-8 ExecStart/usr/bin/java $JAVA_OPTS -jar /opt/app/ai-service.jar Restarton-failure RestartSec10 [Install] WantedBymulti-user.target参数说明Environment里放密钥注意文件权限设成 600不要让其他用户读到-Dfile.encodingUTF-8必须加否则中文日志和中文回答可能乱码Restarton-failure配合RestartSec10做基础自愈。日志方面SpringAI 默认不打请求体排查问题时可以在application.yml里把logging.level.org.springframework.ai调到 DEBUG但生产环境不要长期开会把 API key 和用户输入打进日志。3.3 容器化部署的镜像分层与健康检查容器化是企业级系统的标配但 SpringAI 应用的镜像有两个特殊点。第一模型调用是外部依赖健康检查不能只检查应用端口要加一个轻量的模型连通性探针。第二镜像分层要把依赖和业务代码分开利用 Docker 缓存加速构建。FROM eclipse-temurin:17-jre-jammy WORKDIR /app # 先拷依赖描述利用缓存层 COPY target/classes/application.yml /app/config/ COPY target/ai-service.jar /app/app.jar ENV JAVA_OPTS-Xms512m -Xmx2g EXPOSE 8080 HEALTHCHECK --interval30s --timeout5s --retries3 \ CMD curl -f http://localhost:8080/actuator/health || exit 1 ENTRYPOINT [sh, -c, java $JAVA_OPTS -jar /app/app.jar]逻辑说明HEALTHCHECK走 Spring Boot Actuator 的/actuator/health需要在 pom 里加spring-boot-starter-actuator并在配置里暴露端点如果要做模型连通性探针可以自定义一个HealthIndicator在里面发一个极短的 ping 请求但注意探针频率不要太高否则会白白消耗 token。容器里跑的时候base-url如果走内网代理要确认容器网络的 DNS 和出口策略这是容器化部署翻车最多的地方。4. 企业级能力补齐RAG、工具调用与多模型路由4.1 用 VectorStore 做企业知识库检索增强企业级智能系统和 demo 的最大区别是「回答要有依据」。DeepSeek 本身不知道你公司的内部文档所以要接 RAG。SpringAI 的 RAG 链路是文档读取 → 切分 → 向量化 → 存 VectorStore → 检索 → 拼进 prompt。最小实现Bean public VectorStore vectorStore(EmbeddingModel embeddingModel) { // 内存向量库生产换 Redis 或 PGVector return new SimpleVectorStore(embeddingModel); } Bean public ApplicationRunner loadDocs(VectorStore vectorStore) { return args - { ListDocument docs List.of( new Document(公司报销标准差旅住宿一线城市不超过 500 元/晚。), new Document(年假规则入职满一年享 5 天满三年 10 天。) ); vectorStore.add(docs); }; }检索时用QuestionAnswerAdvisorthis.chatClient builder .defaultSystem(...) .defaultAdvisors(new QuestionAnswerAdvisor(vectorStore)) .build();参数说明SimpleVectorStore只适合验证重启就丢生产用 PGVector 或 Redis 的向量能力注意 embedding 模型要和存储时一致换模型必须重建索引切分粒度一般 300 到 500 字一段重叠 50 字太大检索不准太小上下文断裂。DeepSeek 本身不提供 embedding 接口embedding 要用别的模型这是很多团队第一次做 RAG 时没预料到的。4.2 工具调用让模型能查实时数据DeepSeek 支持 function callingSpringAI 里用Tool注解暴露方法Component public class OrderTools { Tool(description 根据订单号查询订单状态) public String queryOrderStatus(String orderId) { // 实际接内部订单服务 return 订单 orderId 状态已发货; } }注册到 ChatClientthis.chatClient builder .defaultTools(new OrderTools()) .build();逻辑说明模型会根据用户问题决定是否调用工具调用参数由模型生成返回值再喂回模型做最终回答。注意工具方法的参数类型要简单String、int 这类复杂对象模型容易生成错工具描述要写清楚这是模型判断「什么时候调」的唯一依据。企业场景下工具方法内部要做权限校验不能因为模型调了就无条件执行。4.3 多模型路由与降级策略企业级系统不能把鸡蛋放一个篮子里。常见做法是配多个 ChatModel用一个 Router 按场景选public class ModelRouter { private final ChatClient deepseekClient; private final ChatClient backupClient; public String chat(String scene, String message) { try { return deepseekClient.prompt().user(message).call().content(); } catch (Exception e) { // 主模型失败降级到备用 return backupClient.prompt().user(message).call().content(); } } }参数说明降级要区分异常类型超时和限流可以降级参数错误降级没意义备用模型可以是另一个兼容 OpenAI 协议的模型配置方式一样只是 base-url 和 model 不同路由策略可以按场景硬编码也可以按 token 长度、按是否流式来分。这套东西不复杂但要在项目初期就设计好后期补会动到很多调用点。5. 避坑与排查SpringAI 接 DeepSeek 最常见的 5 个翻车点5.1 启动报 401 但密钥明明是对的现象应用启动后第一次调用返回 401 Unauthorized但用 curl 测同样的密钥是通的。原因SpringAI 的 OpenAI starter 默认会在 api-key 前面拼Bearer如果你在配置里自己写了Bearer sk-xxx就会变成Bearer Bearer sk-xxx。解决api-key只填sk-开头的原始值不要带前缀。另外检查环境变量有没有多余空格YAML 里${DEEPSEEK_API_KEY}如果变量不存在会原样传入也会导致 401。5.2 流式接口返回乱码或粘包现象前端收到的 SSE 数据里中文乱码或者多个 chunk 粘在一起。原因响应头没设 charset或者中间有网关做了缓冲。解决produces里明确写MediaType.TEXT_EVENT_STREAM_VALUESpring Boot 默认会带 UTF-8如果前面有 Nginx要关掉proxy_buffering否则流式会被攒成一坨再发。这个坑在容器化部署时特别常见因为 ingress 层默认就是缓冲的。5.3 对话记忆导致 token 暴涨现象用了一段时间后每次请求的 token 数越来越大费用涨得比预期快。原因InMemoryChatMemory默认不限制条数历史消息全量塞进 prompt。解决换用带窗口限制的记忆实现或者自己写一个按条数或按 token 数淘汰的策略。经验值是保留最近 10 轮更早的做摘要压缩。另外注意系统提示词和 RAG 检索到的文档也会占 token做预算时要一起算。5.4 工具调用在 DeepSeek 上不触发现象配了Tool但模型始终不调用直接编答案。原因DeepSeek 的 function calling 对工具描述和参数 schema 比较敏感描述太模糊模型就不敢调另外有些模型版本对并行工具调用的支持不一致。解决工具描述写成「什么时候用 参数含义 返回什么」越具体越好参数用基本类型如果还是不触发在系统提示词里明确写「需要查询订单时必须调用 queryOrderStatus 工具不要自己编造」。5.5 容器里连不上 DeepSeek 但宿主机可以现象本地跑没问题打进容器就超时。原因容器网络的 DNS 配置和宿主机不同或者公司出口策略对容器网段有限制。解决进容器里用curl或wget测一下base-url的连通性检查/etc/resolv.conf如果是 K8s 环境检查 NetworkPolicy 和 egress 规则。这个坑没有代码层面的解法纯粹是网络排查但它是跨平台集成里最高频的阻塞点。6. 进阶技巧用配置化路由把模型切换成本降到零走到这里系统基本能跑了。但企业级项目还有一个隐性需求模型要能换而且换的时候不改代码、不重新打包。我的做法是把模型配置抽成一张表用 Spring 的ConfigurationProperties绑定运行时按 key 取对应的 ChatClient。ConfigurationProperties(prefix ai.models) Component public class ModelProperties { // key 是场景名value 是该场景的模型配置 private MapString, ModelConfig routes new HashMap(); public static class ModelConfig { private String baseUrl; private String apiKey; private String model; private Double temperature; // getter/setter 省略 } // getter/setter 省略 }配置长这样ai: models: routes: chat: base-url: https://api.deepseek.com api-key: ${DEEPSEEK_API_KEY} model: deepseek-chat temperature: 0.7 reason: base-url: https://api.deepseek.com api-key: ${DEEPSEEK_API_KEY} model: deepseek-reasoner temperature: 0.3然后写一个工厂按场景名构建 ChatClient 并缓存Component public class ChatClientFactory { private final MapString, ChatClient cache new ConcurrentHashMap(); private final ModelProperties properties; public ChatClientFactory(ModelProperties properties) { this.properties properties; } public ChatClient get(String scene) { return cache.computeIfAbsent(scene, s - { ModelProperties.ModelConfig cfg properties.getRoutes().get(s); if (cfg null) throw new IllegalArgumentException(未配置场景: s); OpenAiApi api OpenAiApi.builder() .baseUrl(cfg.getBaseUrl()) .apiKey(cfg.getApiKey()) .build(); return ChatClient.builder(new OpenAiChatModel(api)) .defaultSystem(你是企业助手场景 s) .build(); }); } }逻辑说明computeIfAbsent保证每个场景只构建一次避免每次请求都 new 一个客户端OpenAiApi的 builder 允许每个场景用不同的 base-url 和 key这样主备模型、不同厂商模型可以共存场景名从业务层传入业务代码只依赖ChatClientFactory.get(chat)不关心底层是哪个模型。参数说明temperature按场景配推理场景调低创意场景调高如果某个场景要流式工厂返回的 ChatClient 同时支持call()和stream()不用改。验证这套路由是否生效最直接的办法是写一个集成测试对每个场景发一条固定问题断言返回非空且耗时在阈值内。我一般还会加一个/actuator/info的自定义端点把当前加载的场景列表和模型名暴露出来上线后一眼就能确认配置有没有生效。这个习惯帮我省过好几次「以为改了配置其实没生效」的后悔药。最后说一个我踩过的坑配置化路由做完之后团队里有人直接在 YAML 里写 api-key提交到了仓库。后来我们加了一条 CI 检查扫描配置文件里有没有sk-开头的字符串有就阻断合并。技术方案再优雅也架不住流程上的疏忽该上的闸还是得上。希望帮到你。本文还有配套的精品资源点击获取