最近在技术社区里一个高频出现的组合是“SpringAI DeepSeek”。很多开发者尤其是熟悉Java生态的朋友看到这个搭配的第一反应可能是兴奋终于能用熟悉的Spring Boot方式轻松地把大模型能力集成到自己的应用里了。但紧接着一连串问题就来了SpringAI到底是个什么项目它和OpenAI、DeepSeek这些模型提供商是什么关系为什么我的ChatModel连不上Embedding模型加载失败怎么办照着教程搭了个RAG为什么回答得还不如直接问模型准如果你也有类似的困惑那么这篇文章就是为你写的。这不是一篇简单的“Hello World”教程而是想和你一起把SpringAI、DeepSeek、ChatModel、Embedding、RAG这一整套技术栈从“能用”到“好用”再到“敢用在生产环境”的路径彻底理清楚。我们会发现真正的难点往往不在第一行代码而在于理解每个组件的边界、它们之间的协作方式以及如何为一个看似简单的问答功能构建起稳定、可控且可维护的工程化底座。1. 先拆解SpringAI它到底是“框架”还是“胶水”在开始写代码之前我们必须先给SpringAI一个清晰的定位。这直接决定了我们对它的期望和后续的工程实践。1.1 SpringAI的核心价值统一抽象而非具体实现SpringAI不是一个像TensorFlow或PyTorch那样的AI框架它不负责训练模型。它更像Spring Data对数据库操作的抽象。Spring Data定义了一套操作数据库的接口如CrudRepository具体的实现MySQL、PostgreSQL驱动由各个数据库厂商提供。SpringAI做的也是类似的事情ChatModel接口定义了与大语言模型对话的核心方法如call,stream。无论背后是OpenAI的GPT、阿里的通义千问还是DeepSeek对开发者而言调用的都是同一个ChatModel接口。EmbeddingModel接口定义了将文本转换为向量一组数字的方法。同样无论是OpenAI的text-embedding-ada-002还是本地的BGE模型接口是统一的。VectorStore接口定义了向量的存储、检索能力。这对应着Milvus、Pinecone、PGVectorPostgreSQL扩展等向量数据库。所以SpringAI的首要价值是标准化和简化集成。它让你可以用Spring熟悉的依赖注入、配置管理、测试框架来开发AI应用避免了为每个模型供应商写一套胶水代码。1.2 理解“胶水层”的职责与局限正因为是“胶水”SpringAI本身不解决以下问题模型能力回答的质量、速度、成本取决于你背后接入的DeepSeek、GPT等模型本身。网络与稳定性调用远程API的网络延迟、超时、限流、鉴权失败需要你在应用层处理。业务逻辑如何设计提示词Prompt、如何处理多轮对话、如何结合业务数据这些是SpringAI提供工具如PromptTemplate但需要你来实现的部分。一个常见的误解是用了SpringAIAI应用就自动“企业级”了。实际上它只是提供了企业级集成的基础设施真正的稳定性、可观测性、业务适配依然需要开发者精心设计。1.3 SpringAI与“SpringAI Alibaba”的关系在搜索材料中出现了“SpringAI Alibaba”。这里需要澄清SpringAI是Spring官方项目。而“SpringAI Alibaba”很可能是指阿里巴巴云效或内部团队基于SpringAI进行封装、或提供与阿里云模型服务如通义千问便捷集成的实践或示例。对于大多数开发者起点应该是官方的SpringAI项目文档和起步依赖。在选择具体模型实现时再决定使用OpenAI、DeepSeek还是阿里的客户端。2. 打通第一关用SpringAI接入DeepSeek ChatModel让我们从最常见的需求开始在Spring Boot应用里调用DeepSeek的聊天API。2.1 环境准备与依赖抉择首先创建一个标准的Spring Boot项目3.x版本。在pom.xml中你需要引入SpringAI的核心依赖以及对应模型的starter。!-- Spring Boot 基础依赖 -- parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.2.0/version !-- 建议使用较新版本 -- /parent !-- SpringAI OpenAI 兼容性依赖 -- !-- 注意DeepSeek的API格式与OpenAI兼容所以通常使用openai的starter -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId version0.8.1/version !-- 请查看官网使用最新稳定版 -- /dependency关键理解为什么用openai-starter来接入DeepSeek因为DeepSeek的Chat API在设计上遵循了OpenAI的格式这也是很多国产模型的常见做法。这个starter内部使用了OpenAI的Java客户端但我们可以通过配置将请求指向DeepSeek的端点。2.2 核心配置不仅仅是API Key在application.yml或application.properties中的配置是第一个容易踩坑的地方。spring: ai: openai: # DeepSeek的API密钥从平台获取 api-key: ${DEEPSEEK_API_KEY} # 这是关键将基础URL指向DeepSeek的API地址 base-url: https://api.deepseek.com # 指定使用的模型名称必须与DeepSeek平台提供的模型名一致 chat: options: model: deepseek-chat # 例如 deepseek-chat, deepseek-coder等 # 连接和读取超时设置根据网络情况调整 client: connect-timeout: 10s read-timeout: 30s配置要点解析base-url这是最关键的配置。如果不配置默认会指向api.openai.com必然失败。model必须填写DeepSeek平台支持的确切模型名称。错误的名字会导致API调用失败。超时设置大模型响应可能较慢特别是处理长文本时。read-timeout需要设置得足够长避免在生成过程中被中断。API Key管理切勿将密钥硬编码在配置文件中。务必使用环境变量${DEEPSEEK_API_KEY}或配置中心来管理。2.3 编写服务层拥抱ChatModel接口配置完成后你就可以像使用任何Spring Bean一样注入ChatModel了。import org.springframework.ai.chat.ChatClient; import org.springframework.ai.chat.messages.UserMessage; import org.springframework.ai.chat.prompt.Prompt; import org.springframework.stereotype.Service; Service public class DeepSeekChatService { private final ChatClient chatClient; // ChatClient 是 ChatModel 的一个便捷封装 public DeepSeekChatService(ChatClient chatClient) { this.chatClient chatClient; } public String chat(String userMessage) { // 最简单的调用方式 return chatClient.call(userMessage); } public String chatWithPrompt(String userQuestion) { // 使用PromptTemplate构建更复杂的提示词 String systemPrompt 你是一个专业的Java技术专家回答要简洁准确。; Prompt prompt new Prompt( List.of(new SystemMessage(systemPrompt), new UserMessage(userQuestion)) ); ChatResponse response chatClient.call(prompt); // 也可以注入ChatModel直接调用 return response.getResult().getOutput().getContent(); } }为什么推荐注入ChatClient或ChatModel而不是自己写HTTP调用复用与维护SpringAI已经处理了请求/响应的序列化、异常转换、重试机制可配置等样板代码。可测试性你可以很方便地使用MockBean来模拟ChatModel进行单元测试。未来可迁移如果未来需要切换到另一个兼容OpenAI API的模型理论上只需修改配置业务代码几乎不动。2.4 常见踩坑点与排查清单当你兴冲冲地启动应用却看到连接失败或401错误时请按以下顺序排查检查网络连通性能否从部署环境访问https://api.deepseek.com公司防火墙是常见阻碍。验证API Key在DeepSeek平台检查密钥是否有效、是否有余额、是否启用了对应模型。核对base-url和model确保没有拼写错误base-url末尾不要加多余路径如/v1model名称完全正确。查看完整日志将logging.level.org.springframework.ai.openai.clientDEBUG加入配置查看详细的请求和响应日志错误信息往往就在这里。注意依赖版本SpringAI和Spring Boot版本存在兼容性矩阵版本不匹配可能导致自动配置失败。注意单次调用成功只是第一步。在生产环境中你必须考虑API的限流策略、失败重试、熔断降级例如使用Resilience4j或Sentinel以及将AI调用纳入统一的可观测性体系链路追踪、指标监控。3. 攻克核心难点Embedding模型的选择与本地化部署如果说ChatModel是AI应用的“大脑”那么Embedding就是它的“记忆索引系统”。RAG检索增强生成效果的好坏一半取决于Embedding模型的质量。搜索材料中提到的no embedding model is loaded错误以及CPU/GPU部署的疑问都是这个阶段的典型问题。3.1 Embedding是什么为什么它是RAG的基石简单来说Embedding模型将一段文本一个词、一句话、一篇文章转换成一个固定长度的数值向量比如1024维。这个向量就像是这段文本在高维空间中的“坐标”。语义相似的文本它们的向量在空间中的距离通常用余弦相似度衡量也会很近。在RAG中我们用Embedding模型将知识库的所有文档块转化为向量存入向量数据库。当用户提问时用同一个Embedding模型将问题也转化为向量。在向量数据库中快速查找与问题向量最相似的几个文档块向量。将这些相关文档块作为上下文连同问题一起交给ChatModel生成最终答案。所以Embedding模型决定了“检索”的精度。如果它无法准确理解问题与文档之间的语义关联那么检索到的上下文就是无关的最终答案自然不准。3.2 模型选型在线API vs. 本地部署这是第一个关键决策点直接关系到成本、性能和数据隐私。特性在线API (如OpenAI, DeepSeek Embedding)本地部署模型 (如BGE, Jina, E5)易用性极高只需一个API调用。中高需要下载模型、管理推理服务。成本按调用次数/Token收费量大时成本显著。一次性的硬件成本后续调用边际成本几乎为零。延迟依赖网络有数十到数百毫秒延迟。本地调用延迟极低毫秒级吞吐量高。数据隐私文本数据需发送到第三方服务器。数据完全留在内部满足严格合规要求。可定制性固定无法针对特定领域微调。可微调能在特定领域如医疗、法律达到更好效果。运维复杂度无需运维模型服务。需要运维模型服务如使用Ollama, Transformers.js, 或自建推理API。如何选择原型验证、低频小规模应用直接使用DeepSeek等提供的Embedding API最快上手。生产环境、高频调用、数据敏感、成本敏感优先考虑本地部署。3.3 本地部署实战以Ollama BGE模型为例搜索材料中提到了ollama embedding。Ollama是一个强大的本地大模型运行和管理的工具它也让本地运行Embedding模型变得非常简单。步骤一安装并启动Ollama服务前往Ollama官网下载安装。安装后命令行拉取一个Embedding模型例如效果广受好评的BAAI/bge-small-en-v1.5。ollama pull nomic-embed-text # Ollama官方维护的嵌入模型基于BGE等 # 或者直接运行会自动拉取 ollama run nomic-embed-text步骤二在SpringAI中配置本地Embedding客户端SpringAI提供了Ollama的starter。在pom.xml中添加dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-ollama-spring-boot-starter/artifactId version0.8.1/version /dependency在application.yml中配置spring: ai: ollama: base-url: http://localhost:11434 # Ollama默认地址 embedding: options: model: nomic-embed-text # 与Ollama中运行的模型名一致现在你可以在代码中注入EmbeddingModel接口它的实现会自动指向你本地的Ollama服务。3.4 CPU vs. GPU不只是速度问题搜索材料中提到了“embedding模型在cpu和gpu上的区别”。对于Embedding模型GPU推理速度极快尤其是批处理时。适合高并发、低延迟的生产场景。需要NVIDIA显卡和CUDA环境。CPU速度慢于GPU但无需额外硬件。使用Ollama时它会自动利用CPU进行推理。对于小规模应用或开发测试完全足够。建议开发测试阶段用CPU即可。生产部署时如果检索性能成为瓶颈例如响应时间要求100msQPS很高再考虑升级到GPU。对于大多数中小型RAG应用一个性能良好的CPU服务器足以支撑。注意解决no embedding model is loaded错误核心就是检查配置。确保spring.ai.ollama.embedding.options.model或对应starter的配置的值与本地实际运行的模型名称完全一致。Ollama的list命令可以查看已加载的模型。4. 构建生产可用的RAG系统超越简单Demo当我们把ChatModel和EmbeddingModel都准备好就可以组装RAG了。但一个玩具级的RAG和一个生产级的RAG差距巨大。4.1 RAG的核心工作流与SpringAI抽象一个完整的RAG流程分为两个阶段索引Indexing处理原始文档PDF、Word、HTML等- 文本分割Chunking- 文本嵌入Embedding- 向量存储VectorStore。检索与生成Retrieval Generation用户提问 - 问题嵌入 - 向量检索 - 上下文组装 - 提示词构建 - 调用ChatModel生成答案。SpringAI为这个流程提供了高层抽象DocumentReader读取不同格式的文档。TextSplitter将长文本分割成语义相关的块。VectorStore向量存储的通用接口。RetrievalAugmentor协调检索与生成过程。4.2 从简单实现到工程化考量一个简单的RAG服务可能长这样Service public class SimpleRagService { private final VectorStore vectorStore; private final EmbeddingModel embeddingModel; private final ChatModel chatModel; public String answerQuestion(String question) { // 1. 将问题转换为向量 ListDouble questionVector embeddingModel.embed(question); // 2. 检索相似文档简化版 ListDocument relevantDocs vectorStore.similaritySearch(questionVector, 4); // 3. 构建Prompt String context relevantDocs.stream().map(Doc::getContent).collect(Collectors.joining(\n)); String prompt String.format(请根据以下上下文回答问题\n%s\n\n问题%s, context, question); // 4. 调用模型 return chatModel.call(prompt); } }但这离生产可用还差得很远。我们需要思考以下问题1. 文本分割Chunking的学问固定长度分割简单但可能切断完整语义。递归分割按段落、句子等递归分割效果更好。语义分割更高级利用模型理解语义边界成本高。重叠Overlap在块之间保留一部分重叠文本有助于防止答案恰好被切在边界上。实践建议从递归字符分割RecursiveCharacterTextSplitter开始设置合适的块大小如500-1000字符和重叠长度如100字符。2. 检索策略的优化简单相似度检索如上例可能检索到相关但不包含答案的文档。混合检索Hybrid Search结合稠密向量检索语义和稀疏向量检索关键词如BM25。这是提升召回率的关键。SpringAI的某些VectorStore实现如支持Elasticsearch的可能提供此功能。重排序Re-ranking先用简单模型召回大量候选文档再用更精细但更慢的模型或交叉编码器对Top N个结果进行重排序提升精度。元数据过滤在检索时加入过滤器例如“只检索某年某部门的文档”这需要你在存储向量时一并存储元数据。3. 提示词Prompt工程简单的上下文拼接容易导致模型忽略上下文。需要使用更明确的指令例如“严格仅根据提供的上下文信息回答问题。如果上下文没有提供足够信息请直接回答‘根据已知信息无法回答该问题’。”可以将检索到的文档按相关性排序后以清晰格式如编号、引用来源提供给模型。4.3 搭建一个健壮的RAG服务框架基于以上考量一个更健壮的服务框架如下Service public class RobustRagService { // ... 注入必要的组件 public AnswerResult answerQuestion(QuestionRequest request) { // 1. 查询增强对原始问题进行改写、扩展提升检索效果可选 String enhancedQuery queryEnhancer.enhance(request.getQuestion()); // 2. 生成查询向量 Embedding queryEmbedding embeddingModel.embed(enhancedQuery); // 3. 构建检索请求支持元数据过滤、混合检索等 SimilaritySearchRequest searchRequest SimilaritySearchRequest.builder() .queryEmbedding(queryEmbedding) .topK(10) // 召回较多结果 .filterExpression(department IT) // 元数据过滤 .build(); // 4. 执行检索 ListDocument candidates vectorStore.similaritySearch(searchRequest); // 5. 重排序可选可使用更轻量的交叉编码器模型 ListDocument rerankedDocs reranker.rerank(enhancedQuery, candidates).subList(0, 4); // 6. 构建结构化Prompt Prompt prompt promptTemplate.create() .withContext(formatContext(rerankedDocs)) .withQuestion(request.getQuestion()) .withInstruction(请严格基于上下文以分点形式回答。) .build(); // 7. 调用模型并记录用于审计的完整信息 ChatResponse response chatModel.call(prompt); return AnswerResult.builder() .answer(response.getContent()) .sourceDocuments(rerankedDocs) // 返回来源增强可信度 .build(); } }4.4 生产环境必须考虑的要素异步化与批处理文档索引Embedding过程非常耗时必须做成异步任务避免阻塞主线程。可以使用Spring的Async或消息队列。错误处理与重试对Embedding和ChatModel的调用要有完善的失败重试、降级策略例如检索失败时直接调用模型回答。可观测性在关键步骤文档加载、分割、嵌入、检索、生成打点记录耗时、Token使用量、检索结果数量等指标方便性能分析和问题排查。版本管理与回滚知识库文档更新、Embedding模型更换、ChatModel升级都可能影响最终答案质量。需要有版本化的管理并能快速回滚到稳定状态。评估体系如何评估RAG系统的效果需要建立一套评估集QA对定期运行从答案相关性、事实准确性、上下文引用率等维度进行量化评估。5. 迈向更高阶Agentic RAG与工作流思考搜索材料中提到了agentic rag和会搭建工作流。这是RAG未来的演进方向。什么是Agentic RAG传统的RAG是“一次检索一次生成”。Agentic RAG引入了智能体Agent的概念让系统能够判断是否需要检索需要拆解成多个子问题吗规划先检索什么再检索什么执行可能执行多轮检索、调用工具如计算器、搜索API。反思对检索到的信息进行批判性思考判断是否足够、是否相关决定是否需要重新检索或调整策略。在SpringAI生态中你可以利用其Function Calling和Agent相关的抽象来构建这样的智能流程。例如先让一个“规划Agent”分析用户问题生成一个检索计划然后由“执行Agent”调用RAG工具获取信息最后由“合成Agent”整合信息生成最终答案。如何搭建工作流这不仅仅是技术选型更是对业务逻辑的深度梳理。识别节点将你的AI应用流程分解为离散的、可复用的节点如意图识别、查询优化、向量检索、信息合成、格式检查。选择编排工具对于简单流程用代码如Spring的Service编排即可。对于复杂、长期运行、需要状态管理的流程可以考虑工作流引擎如Camunda、Flowable或专为AI设计的编排框架如LangChain的LangGraph、微软的Semantic Kernel。实现每个节点利用SpringAI的能力将每个节点实现为一个独立的、可测试的组件。监控与调试工作流中任何一个节点出错都要能快速定位。需要为工作流提供可视化的执行轨迹和详细的日志。回到开头的问题SpringAI全套实战远不止是添加几个依赖、写几行配置。它提供了一套符合Spring哲学的标准方式来集成AI能力但真正的挑战在于如何以软件工程的严谨性去设计和实现一个可靠、可维护、可进化的AI应用。从打通第一个ChatModel调用到部署一个带有多路召回、重排序、完备监控的RAG系统再到思考如何用Agent理念重构工作流每一步都需要在“快速验证”和“长期稳健”之间找到平衡。希望这篇文章提供的视角和路径能帮助你在拥抱大模型浪潮时不仅跑通Demo更能构建出真正创造价值的工程实践。