SpringAI实战：从ChatModel到RAG，构建企业级AI应用工程化方案

最近在技术社区里，一个高频出现的组合是“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、PGVector（PostgreSQL扩展）等向量数据库。

所以，SpringAI的首要价值是标准化和简化集成。它让你可以用Spring熟悉的依赖注入、配置管理、测试框架来开发AI应用，避免了为每个模型供应商写一套胶水代码。

1.2 理解“胶水层”的职责与局限

正因为是“胶水”，SpringAI本身不解决以下问题：

1. 模型能力：回答的质量、速度、成本，取决于你背后接入的DeepSeek、GPT等模型本身。
2. 网络与稳定性：调用远程API的网络延迟、超时、限流、鉴权失败，需要你在应用层处理。
3. 业务逻辑：如何设计提示词（Prompt）、如何处理多轮对话、如何结合业务数据，这些是SpringAI提供工具（如PromptTemplate），但需要你来实现的部分。

一个常见的误解是，用了SpringAI，AI应用就自动“企业级”了。实际上，它只是提供了企业级集成的基础设施，真正的稳定性、可观测性、业务适配，依然需要开发者精心设计。

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> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>3.2.0</version> <!-- 建议使用较新版本 --> </parent> <!-- SpringAI OpenAI 兼容性依赖 --> <!-- 注意：DeepSeek的API格式与OpenAI兼容，所以通常使用openai的starter --> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-openai-spring-boot-starter</artifactId> <version>0.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

配置要点解析：

1. base-url：这是最关键的配置。如果不配置，默认会指向api.openai.com，必然失败。
2. model：必须填写DeepSeek平台支持的确切模型名称。错误的名字会导致API调用失败。
3. 超时设置：大模型响应可能较慢，特别是处理长文本时。read-timeout需要设置得足够长，避免在生成过程中被中断。
4. 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调用？

1. 复用与维护：SpringAI已经处理了请求/响应的序列化、异常转换、重试机制（可配置）等样板代码。
2. 可测试性：你可以很方便地使用@MockBean来模拟ChatModel，进行单元测试。
3. 未来可迁移：如果未来需要切换到另一个兼容OpenAI API的模型，理论上只需修改配置，业务代码几乎不动。

2.4 常见踩坑点与排查清单

当你兴冲冲地启动应用，却看到连接失败或401错误时，请按以下顺序排查：

1. 检查网络连通性：能否从部署环境访问https://api.deepseek.com？（公司防火墙是常见阻碍）。
2. 验证API Key：在DeepSeek平台检查密钥是否有效、是否有余额、是否启用了对应模型。
3. 核对base-url和model：确保没有拼写错误，base-url末尾不要加多余路径（如/v1），model名称完全正确。
4. 查看完整日志：将logging.level.org.springframework.ai.openai.client=DEBUG加入配置，查看详细的请求和响应日志，错误信息往往就在这里。
5. 注意依赖版本：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中，我们：

1. 用Embedding模型将知识库的所有文档块转化为向量，存入向量数据库。
2. 当用户提问时，用同一个Embedding模型将问题也转化为向量。
3. 在向量数据库中，快速查找与问题向量最相似的几个文档块向量。
4. 将这些相关文档块作为上下文，连同问题一起交给ChatModel生成最终答案。

所以，Embedding模型决定了“检索”的精度。如果它无法准确理解问题与文档之间的语义关联，那么检索到的上下文就是无关的，最终答案自然不准。

3.2 模型选型：在线API vs. 本地部署

这是第一个关键决策点，直接关系到成本、性能和数据隐私。

如何选择？

• 原型验证、低频小规模应用：直接使用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> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-ollama-spring-boot-starter</artifactId> <version>0.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即可。生产部署时，如果检索性能成为瓶颈（例如响应时间要求<100ms，QPS很高），再考虑升级到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流程分为两个阶段：

1. 索引（Indexing）：处理原始文档（PDF、Word、HTML等）-> 文本分割（Chunking）-> 文本嵌入（Embedding）-> 向量存储（VectorStore）。
2. 检索与生成（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. 将问题转换为向量 List<Double> questionVector = embeddingModel.embed(question); // 2. 检索相似文档（简化版） List<Document> 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. 执行检索 List<Document> candidates = vectorStore.similaritySearch(searchRequest); // 5. 重排序（可选，可使用更轻量的交叉编码器模型） List<Document> 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 生产环境必须考虑的要素

1. 异步化与批处理：文档索引（Embedding）过程非常耗时，必须做成异步任务，避免阻塞主线程。可以使用Spring的@Async或消息队列。
2. 错误处理与重试：对Embedding和ChatModel的调用要有完善的失败重试、降级策略（例如检索失败时，直接调用模型回答）。
3. 可观测性：在关键步骤（文档加载、分割、嵌入、检索、生成）打点，记录耗时、Token使用量、检索结果数量等指标，方便性能分析和问题排查。
4. 版本管理与回滚：知识库文档更新、Embedding模型更换、ChatModel升级都可能影响最终答案质量。需要有版本化的管理，并能快速回滚到稳定状态。
5. 评估体系：如何评估RAG系统的效果？需要建立一套评估集（QA对），定期运行，从答案相关性、事实准确性、上下文引用率等维度进行量化评估。

5. 迈向更高阶：Agentic RAG与工作流思考

搜索材料中提到了agentic rag和会搭建工作流。这是RAG未来的演进方向。

什么是Agentic RAG？传统的RAG是“一次检索，一次生成”。Agentic RAG引入了智能体（Agent）的概念，让系统能够：

• 判断：是否需要检索？需要拆解成多个子问题吗？
• 规划：先检索什么，再检索什么？
• 执行：可能执行多轮检索、调用工具（如计算器、搜索API）。
• 反思：对检索到的信息进行批判性思考，判断是否足够、是否相关，决定是否需要重新检索或调整策略。

在SpringAI生态中，你可以利用其Function Calling和Agent相关的抽象，来构建这样的智能流程。例如，先让一个“规划Agent”分析用户问题，生成一个检索计划，然后由“执行Agent”调用RAG工具获取信息，最后由“合成Agent”整合信息生成最终答案。

如何搭建工作流？这不仅仅是技术选型，更是对业务逻辑的深度梳理。

1. 识别节点：将你的AI应用流程分解为离散的、可复用的节点（如：意图识别、查询优化、向量检索、信息合成、格式检查）。
2. 选择编排工具：对于简单流程，用代码（如Spring的@Service）编排即可。对于复杂、长期运行、需要状态管理的流程，可以考虑工作流引擎（如Camunda、Flowable）或专为AI设计的编排框架（如LangChain的LangGraph、微软的Semantic Kernel）。
3. 实现每个节点：利用SpringAI的能力，将每个节点实现为一个独立的、可测试的组件。
4. 监控与调试：工作流中任何一个节点出错，都要能快速定位。需要为工作流提供可视化的执行轨迹和详细的日志。

回到开头的问题，SpringAI全套实战，远不止是添加几个依赖、写几行配置。它提供了一套符合Spring哲学的标准方式来集成AI能力，但真正的挑战在于，如何以软件工程的严谨性，去设计和实现一个可靠、可维护、可进化的AI应用。从打通第一个ChatModel调用，到部署一个带有多路召回、重排序、完备监控的RAG系统，再到思考如何用Agent理念重构工作流，每一步都需要在“快速验证”和“长期稳健”之间找到平衡。希望这篇文章提供的视角和路径，能帮助你在拥抱大模型浪潮时，不仅跑通Demo，更能构建出真正创造价值的工程实践。