当 Python 生态里 LangChain、LlamaIndex 已经堆满教程的时候很多 Java 开发者的心态其实是矛盾的想学 AI 应用开发又不想丢掉 Java 的技术栈去重新学一遍 Python。尤其是做企业级应用、后端架构、数据中台的团队核心系统全是 Spring Boot不可能因为要接一个大模型就把整个服务重写。Spring AI 2.0 的出现给这条困境提供了一条比较明确的出路Java 生态正在把大模型能力变成 Spring 体系里一个普通的 starter 依赖。你不需要成为 Prompt 工程师也不需要转语言就能在原有工程里接入模型对话、RAG 知识库、Agent 工具调用。这篇文章会从这套实战教程的核心内容出发把 Spring AI 2.0、LangChain4j、Tools、RAG、Agent 这几块拆开讲清楚。无论你是刚接触 AI 应用开发的 Java 后端还是已经在项目里试过接大模型但踩了一堆坑的人按照这篇文章的顺序走一遍能少走不少弯路。1. 这篇文章真正要解决的问题先说实话Java 生态做大模型应用最大的问题不是技术难度而是资料断层。Python 那边有 LangChain、LlamaIndex、Dify教程多、社区活跃、案例丰富。而 Java 这边你搜“Java 接入大模型”能搜到的要么是调用 HTTP 接口的简单 Demo要么就是翻译过来的概念科普真正能落地到 Spring Boot 工程里的完整链路少得可怜。这就造成一种现象很多 Java 团队想做一个企业内部的知识库问答系统结果发现网上能找到的 Java 案例只覆盖了“调用 API 聊天”这一步再往后——文档怎么切分、向量怎么存储、检索怎么和模型输出结合、Agent 怎么调用自己的业务接口——就没有下文了。这篇文章要解决的就是这个断层。它不是从零讲什么是大模型而是直接回答一个问题如果你是一个 Java 后端开发想在自己的 Spring Boot 项目里做出一个带 RAG 和 Agent 能力的应用最快最稳的路径是什么围绕这个核心问题文章会覆盖四个层次模型接入层Spring AI 2.0 怎么统一不同厂商的大模型 API。知识增强层RAG 的完整链路从文档加载到向量检索。能力扩展层Tools 机制让大模型能够调用你自己的业务接口。智能编排层Agent 怎么把工具组合成一个能自主决策的系统。如果你看这套教程是为了应付面试那么 RAG 和 Agent 这两块的原理与实现细节已经是 Java 面试题里出现频率越来越高的问题如果你是为了实际落地这篇文章的代码和排错思路可以直接拿去做工程参考。2. Spring AI 2.0 与 LangChain4j 到底在解决什么很多刚接触的 Java 开发者会有一个困惑Spring AI 和 LangChain4j 看着功能差不多到底有什么区别是不是重复造轮子理解这个问题要从 Java 生态做 AI 应用的两条路线说起。2.1 Spring AISpring 官方对 AI 的抽象层Spring AI 的定位非常明确让 Spring 开发者用熟悉的编程模型接入 AI 能力。它做的事情本质上和 Spring 对其他中间件的抽象是一样的——定义一套统一接口把不同厂商的模型封装成可替换的实现。在 Spring AI 里ChatClient是一个核心入口你通过它发起对话请求底层是 OpenAI 还是 DeepSeek 还是通义千问被抽象层屏蔽掉了。这意味着你写业务代码时不需要关心每个模型厂商的 API 格式差异切换模型时只需要改配置。Spring AI 2.0 在这条路上走得更远。它不只是做单轮对话的抽象而是把 RAG 的常用组件也纳入了标准体系文档加载器、文本切分器、Embedding 模型、向量存储、检索器这些都有对应的接口和默认实现。你可以理解成Spring 官方想给 Java 生态造一个“AI 开发的标准底座”。2.2 LangChain4jLangChain 思想在 Java 的移植LangChain4j 的历史和 Spring AI 不太一样。它最早是把 Python 社区 LangChain 的核心思路移植到 Java/JVM 生态发展到现在已经有了自己的风格尤其是AiServices这套声明式 Agent 开发模型用起来很像写 Spring Service。LangChain4j 的优势在于它起步早组件多对各类向量数据库、Embedding 模型的支持比 Spring AI 更丰富。如果你要做深度定制的 RAG 链路或者想用 Agent 做复杂编排LangChain4j 的灵活性会更高。2.3 怎么选技术选型判断从这套教程和 Java 社区的实践来看比较推荐的选择逻辑是维度Spring AILangChain4j背景Spring 官方项目迭代快社区驱动功能丰富上手成本低熟悉 Spring 就能快速上手中概念相对多一些RAG 支持组件完整采用统一抽象集成丰富向量库支持多Agent 开发支持 Function Calling使用 AiServices开发效率高长远趋势与 Spring Boot 深度融合社区活跃生态持续增长如果你是在一个标准的 Spring Boot 项目里做功能增强优先考虑 Spring AI如果你想要灵活的编排能力和更细粒度的控制LangChain4j 是很强的补充。两者并不是非此即彼的关系。实际项目里用 Spring AI 做底层的模型接入和 RAG 链路用 LangChain4j 做 Agent 编排是完全可行的组合。这也是这套教程里的一个重要思路。3. 核心概念拆解RAG、Tools、Agent 到底怎么回事有了框架基础还需要把几个核心概念讲透。因为网上很多教程把概念说得很玄乎实际上它们对应的是非常具体的工程问题。3.1 RAG给大模型发一本参考书大模型的训练数据是有截止时间的企业内部的知识它也完全不知道。你直接问它“我们公司的报销流程是什么”它只能瞎编。RAGRetrieval-Augmented Generation检索增强生成解决的就是这个问题。它的核心思路很朴素每次问答时先从你的知识库里检索出相关内容把检索结果拼到 Prompt 里让模型基于这些资料回答。用生活场景类比以前你让实习生直接回答问题他只能靠自己的记忆瞎说RAG 的做法是先给他一本参考书告诉他“遇到不知道的就去书里查回答时以书里的内容为准”。RAG 的完整链路包括文档加载读取 PDF、Word、Markdown 等格式的文档。文本切分把长文档切成适合检索的片段。向量化用 Embedding 模型把文本转换成向量。向量存储把向量写入向量数据库。检索召回根据用户问题找出最相关的文档片段。生成回答把检索结果和问题一起交给大模型。很多 Java 开发者问Spring AI 2.0 和 LangChain4j 哪个做 RAG 更合适其实框架只是辅助RAG 的工程质量取决于文档切分策略、Embedding 模型质量、检索策略这几块和语言、框架关系不大。3.2 Tools让大模型有手有脚大模型本身不能查询天气、不能查数据库、不能调你的业务接口。它本质上是一个文本生成器只能根据输入输出文本。Tools工具调用机制解决的就是这个问题。它的原理可以简单理解成你把你系统中的函数暴露给大模型大模型在回答问题时如果发现自己需要的某个信息需要通过执行代码才能拿到它会在回复里生成一个“我要调用某某函数参数是某某”的请求。你的程序收到这个请求后执行实际的函数把执行结果返回给大模型。大模型再根据这个结果生成最终回答。这就是所谓的 Function Calling函数调用。例如用户问“帮我查一下订单 10086 的配送状态”大模型本身不知道这个信息但它知道有一个queryOrderStatus(orderId)函数。于是它输出“我要调用 queryOrderStatus参数是 10086”。程序执行这个函数拿到状态信息再交给大模型组织回答。在 Spring AI 里你可以用Tool注解标记一个普通 Spring Bean 方法框架会自动把方法的参数描述、功能描述暴露给模型。3.3 Agent从回答问题到完成任务Tools 解决的是单次调用的问题Agent 解决的是多步骤决策的问题。举个例子用户说“帮我把上周的销售数据整理成一份周报发给部门经理”。这个任务不是一个函数能完成的它需要查询销售数据库拿到数据。分析数据组织成周报格式。找到部门经理的邮箱。调用接口发送邮件。Agent 做的事情就是拆解任务、决定调用哪些工具、按照什么顺序调用、观察每一步的结果、直到最终完成任务。你可以把 Agent 理解成一个“有大脑的调度器”。大模型是大脑Tools 是手脚Agent 负责协调大脑和手脚完成复杂任务。从这套教程的实践来看Java 开发者最容易踩的坑是一开始就想过度设计 Agent结果调度逻辑复杂、链条不稳定、排错困难。更推荐的做法是先用 RAG 解决知识问答再逐步升级到 Agent 编排。4. 开发环境准备与版本选择在做实战之前环境准备和版本选择非常关键。很多教程里代码跑不通不是代码写错了而是版本不匹配。4.1 JDK 与构建工具JDK建议 JDK 17 及以上Spring Boot 3.x 的最低要求是 JDK 17。Maven3.8Gradle 也可以但 Maven 在 Spring 生态里更常见。IDEIntelliJ IDEA 社区版或旗舰版均可建议使用 2023.1 以上版本对 Spring Boot 支持更好。java -version # 期望输出 openjdk version 17.0.x 或更高版本 mvn -version # 期望输出 Apache Maven 3.8.x4.2 依赖引入以 Maven 为例核心依赖分为三部分Spring Boot 基础依赖、Spring AI 相关依赖、向量数据库与工具类依赖。parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.3.x/version relativePath/ /parent properties java.version17/java.version !-- 具体版本号以实际官方版本为准 -- spring-ai.version2.0.x/spring-ai.version /properties dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version${spring-ai.version}/version typepom/type scopeimport/scope /dependency !-- 模型接入以 OpenAI 兼容接口为例 -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai/artifactId /dependency !-- 支持读取 PDF、Word 等文档 -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-tika-document-reader/artifactId /dependency /dependencies这里要注意Spring AI 的版本迭代非常快不同版本的 API 调整幅度可能不小。如果你发现代码里的ChatClient、Document、EmbeddingModel方法名和网上文章不一样先检查版本号。4.3 模型 API Key 配置以 DeepSeek 为例因为 DeepSeek 提供了 OpenAI 兼容的 API所以在 Spring AI 里可以直接使用 OpenAI 模块配置只是把 base-url 改成 DeepSeek 的地址。# application.yml spring: ai: openai: base-url: https://api.deepseek.com api-key: ${DEEPSEEK_API_KEY} chat: options: model: deepseek-chat temperature: 0.7需要注意API Key 不要硬编码在代码里建议使用环境变量或配置文件占位符。5. 第一步实战跑通一个最小对话应用很多人学框架有个误区上来就做复杂的 RAG、Agent结果链路太长出了问题无法定位。正确做法是先把最小链路跑通再逐步叠加功能。5.1 写一个最简单的 Controller// 文件路径src/main/java/com/example/ai/AiController.java RestController RequestMapping(/api/chat) public class AiController { private final ChatClient chatClient; public AiController(ChatClient.Builder chatClientBuilder) { this.chatClient chatClientBuilder.build(); } GetMapping(/simple) public String simple(RequestParam String message) { return chatClient.prompt() .user(message) .call() .content(); } }这段代码的逻辑很直观通过ChatClient.Builder创建一个ChatClient用户传入消息框架将消息发送给配置好的大模型然后把模型返回的文本作为响应输出。ChatClient是 Spring AI 中最常用的入口。它类似RestTemplate之于 HTTP 调用是统一封装模型调用的门面。5.2 增加上下文记忆单轮对话很容易写但真实场景需要多轮对话。Spring AI 提供ChatMemory来管理对话历史。Component public class ChatService { private final ChatClient chatClient; public ChatService(ChatClient.Builder builder) { this.chatClient builder .defaultSystem(你是一个友善的AI助手请用简洁的语言回答问题。) .build(); } public String chatWithMemory(String message, String conversationId) { return chatClient.prompt() .user(message) .advisors(a - a.param(ChatMemory.CONVERSATION_ID, conversationId)) .call() .content(); } }这里通过conversationId标识不同的会话框架会自动保存和读取对话历史。5.3 运行验证启动 Spring Boot 应用访问http://localhost:8080/api/chat/simple?message你好请介绍一下你自己如果配置正确会返回大模型的对话结果。到这里你的第一个 Spring AI 2.0 应用就跑通了。这个步骤看起来很简单但它验证了最关键的事情模型接入、配置管理、Spring Bean 注入这一整套链路是否通畅。这时候再继续做 RAG 和 Agent出了问题就能判断是哪一层的问题。6. RAG 实战构建一个 Java 版知识库问答系统RAG 是这套教程的重头戏。很多 Java 团队做企业内部知识库核心需求就是上传一批文档用户用自然语言提问系统基于文档内容回答。下面完整走一遍 RAG 链路。6.1 知识库处理的完整流程RAG 的流程可以分成两个阶段离线阶段预处理加载文档。切分文档。向量化。写入向量数据库。在线阶段查询用户输入问题。问题向量化。从向量库检索最相关的文档片段。把文档片段和问题组成 Prompt。大模型生成回答。6.2 文档加载与切分Spring AI 提供了一系列文档读取抽象底层集成 Tika 来支持多格式解析。// 文件路径src/main/java/com/example/ai/rag/DocumentIngestionService.java Service public class DocumentIngestionService { private final EmbeddingModel embeddingModel; private final VectorStore vectorStore; public DocumentIngestionService(EmbeddingModel embeddingModel, VectorStore vectorStore) { this.embeddingModel embeddingModel; this.vectorStore vectorStore; } public void ingestPdf(String filePath) { // 1. 加载文档 TikaDocumentReader reader new TikaDocumentReader(Resource.fromFile(filePath)); ListDocument documents reader.get(); // 2. 切分文档避免超出模型上下文窗口 TokenTextSplitter splitter new TokenTextSplitter(); ListDocument splitDocuments splitter.apply(documents); // 3. 分割后的文档写入向量存储框架内部会自动调用 embeddingModel 做向量化 vectorStore.add(splitDocuments); } }核心要点TikaDocumentReader负责读取各种格式的文档包括 PDF、Word、TXT 等。TokenTextSplitter负责切分文本它是按 Token 数来切分而非简单按字符数。vectorStore.add()会先调用EmbeddingModel生成向量再写入存储。切分策略是 RAG 里最容易影响效果的一环。切得太短语义不完整切得太长检索噪音大。实际项目中建议先从官方默认参数开始再根据业务文档类型做调整。6.3 配置向量存储Spring AI 的VectorStore是统一的向量存储接口底层实现可以是 Redis、Milvus、PGVector 等。从社区使用趋势看Milvus 是很多团队的选择因为它对大规模向量检索的支撑更好也支持混合检索的扩展能力。为了让代码能直接跑通这里用 Redis 作为示例因为 Redis 在企业里很常见不需要额外搭建复杂的向量数据库服务。dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-redis/artifactId /dependencyspring: data: redis: host: localhost port: 6379 ai: vectorstore: redis: index-name: knowledge_base prefix: doc:注意Spring Data Redis 的spring-boot-starter-data-redis也需要引入否则无法自动配置 Redis 连接。6.4 检索式问答向量存储配置好之后编写检索问答的核心代码// 文件路径src/main/java/com/example/ai/rag/RagChatService.java Service public class RagChatService { private final ChatClient chatClient; public RagChatService(ChatClient.Builder builder, VectorStore vectorStore) { this.chatClient builder .defaultSystem( 你是一个企业知识库助手。 请严格基于提供的资料回答问题。 如果资料中没有相关信息请明确说“根据当前知识库无法回答”不要编造答案。 ) .defaultAdvisors(QuestionAnswerAdvisor.builder(vectorStore).build()) .build(); } public String answer(String question) { return chatClient.prompt() .user(question) .call() .content(); } }这里的核心是QuestionAnswerAdvisor。它的工作流程是接收用户问题 → 从 VectorStore 中检索相关文档 → 将文档内容和用户问题组装成新 Prompt → 调用模型生成回答。对比之前的最小 Demo你会发现差异非常小只需要加一个 Advisor就把“普通问答”升级成了“基于知识库的问答”。这也是 Spring AI 设计得比较好的地方RAG 能力通过组合式扩展嵌入到现有流程中。6.5 使用 Qwen Embedding 模型如果你希望 Embedding 效果更适合中文场景可以使用 Qwen 的 Embedding 模型。从搜索结果看这也是 Java 开发者非常关注的一个问题。具体做法是通过 OpenAI 兼容接口或自建 Embedding 服务接入。spring: ai: openai: embedding: base-url: https://你的embedding服务地址 api-key: ${EMBEDDING_API_KEY} options: model: text-embedding-v4如果 Embedding 模型和 Chat 模型不是同一个服务可能需要分别配置。具体配置项会随版本变化建议优先查看 Spring AI 对应当前版本的文档。6.6 RAG 效果验证RAG 链路跑通后不要直接上线先用测试集验证效果。推荐的验证方式是准备 10-20 个典型的业务问题。逐个提问检查回答是否引用正确文档。检查“知识库中其实没有答案”的问题模型是否给出了错误回答。RAG 最常见的问题就是“检索到的内容不对”导致模型胡编这时候问题不一定在大模型而在文档切分、Embedding、检索策略上。此外如果团队有条件做更精细的检索可以关注“混合检索 重排”Hybrid Search Rerank的思路这也是当前 RAG 技术比较热门的演进方向。混合检索结合了向量检索和关键词检索的优势重排模型会对初次召回的结果做二次排序。不过在工程落地时我的建议是先保证向量检索的入库质量和检索策略是对的再叠加混合检索和重排不要一上来就把链路搞得太复杂。7. Tools 与 Agent 实战从回答问题到执行任务RAG 解决知识类问答Tools 和 Agent 解决的是操作类任务。7.1 用 Spring AI 暴露一个 Tool假设你有这样一个需求用户可以直接用自然语言查询天气信息。模型不知道天气数据但它可以调用你写好的工具方法。// 文件路径src/main/java/com/example/ai/tool/WeatherTools.java Component public class WeatherTools { Tool(description 根据城市名称查询当前天气) public String getWeather(String city) { // 这里可以做真实 API 调用 return 城市 city 天气晴温度26℃空气质量良; } }在 Spring AI 中Tool注解会自动生成工具定义暴露给大模型。大模型在回答天气问题时会优先考虑使用这个工具而不是自己编造天气数据。然后在业务代码里开启工具调用// 文件路径src/main/java/com/example/ai/tool/ToolChatService.java Service public class ToolChatService { private final ChatClient chatClient; public ToolChatService(ChatClient.Builder builder, WeatherTools weatherTools) { this.chatClient builder .defaultTools(weatherTools) .build(); } public String chat(String message) { return chatClient.prompt() .user(message) .call() .content(); } }这个模式的实际意义在于你的 Java 业务方法可以直接变成大模型的能力。数据库查询、订单状态查询、第三方接口调用、内部系统操作都可以用这种方式暴露给模型。需要特别提醒的是工具调用涉及系统操作生产环境必须做权限校验。不能因为接口是给内部模型用的就直接暴露敏感操作。7.2 用 LangChain4j 写声明式 Agent如果要在 Java 里做更复杂的 Agent 编排LangChain4j 的AiServices是更舒服的方式。LangChain4j 的核心 API 设计非常接近 Spring 风格// 文件路径src/main/java/com/example/ai/agent/OrderAgent.java public interface OrderAgent { SystemMessage(你是订单助手负责帮助用户查询和管理订单信息。) String chat(UserMessage String userMessage); }// 文件路径src/main/java/com/example/ai/agent/OrderAgentConfig.java Configuration public class OrderAgentConfig { Bean public OrderAgent orderAgent(ChatLanguageModel chatLanguageModel) { return AiServices.builder(OrderAgent.class) .chatLanguageModel(chatLanguageModel) .tools(new OrderTools()) .build(); } }这里OrderTools是一个普通的类方法上加Tool注解// 文件路径src/main/java/com/example/ai/agent/OrderTools.java Slf4j public class OrderTools { Tool(根据订单号查询订单状态) public String queryOrderStatus(String orderId) { // 实际项目中替换为数据库或第三方接口调用 return 订单 orderId 当前状态已发货预计2天内送达; } Tool(根据用户ID获取最近订单列表) public String getRecentOrders(String userId) { return 用户 userId 最近的订单20260701-00120260705-002; } }这套机制的本质是AiServices把接口方法、SystemMessage和Tool组合起来自动完成 Agent 的决策循环。用户发送的问题会被模型分析模型决定调用哪些工具、以什么顺序调用最终汇总结果回答用户。你不需要手动编写复杂的循环判断逻辑。7.3 Agentic RAG让 Agent 自己决定查什么如果 RAG 的知识库有多个比如一个销售知识库、一个技术支持知识库传统的单一路径 RAG 需要手动配置选择逻辑。而 Agentic RAG 的做法是让 Agent 根据用户问题自主决定调用哪一个检索工具。public class MultiKnowledgeTools { Tool(从销售知识库检索信息) public String searchSalesKnowledge(String query) { return salesVectorStore.similaritySearch(query); } Tool(从技术支持知识库检索信息) public String searchTechSupportKnowledge(String query) { return techSupportVectorStore.similaritySearch(query); } }这样用户问“我们的销售提成比例是多少”Agent 会调用searchSalesKnowledge用户问“系统报错代码 5002 怎么解决”Agent 会调用searchTechSupportKnowledge。在 Java 工程里Agentic RAG 是比单纯 RAG 更灵活的方案但前提是你已经能跑通基础的 RAG 链路否则问题排查会很痛苦。7.4 Agent 和 Harness 的区别搜索热词里有一项是“harness 和 agent 区别”。这确实是 Agent 开发里容易混淆的概念。Harness 的直译是“安全带/操控装置”。在 Agent 框架的语境里它通常指代模型推理时外部的流程控制框架——比如模型推理调用工具的整个执行循环模型生成 → 发现工具调用 → 执行工具 → 返回结果 → 模型继续生成。Harness 提供的是基础执行壳它不关心任务是否完成只负责让“模型 工具”能循环跑起来。而 Agent 偏重“目标导向的自主行为”拆解任务、调度工具、观察结果、规划下一步。Agent 是一个设计模式或产品概念Harness 是实现 Agent 循环的底层基础设施。在实际项目中你不需要过度纠结这个概念差异。简单理解就是你写的业务逻辑是 Agent而框架Spring AI / LangChain4j执行的循环逻辑就是 Harness。8. 常见问题与排查思路这套教程涉及的链路比较长从模型接入到 RAG 到 Agent每一层都可能踩坑。下面整理一些高频问题问题现象可能原因排查方式解决方案Spring AI 连接 DeepSeek 不输出 contentbase-url 配置不对或模型名与实际不匹配检查配置和官方 API 文档直接 curl 测试 API确认 OpenAI 兼容地址的路径使用正确的模型名请求超时或响应慢模型服务网络不稳定、超时设置过短查看日志测试单次 API 调用延迟调大超时时间使用异步调用文档向量化后检索结果不相关切分粒度过长或过短、Embedding 模型不适合中文尝试不同切分参数单独调用 Embedding 生成向量检查调整切分策略或更换 Embedding 模型vectorStore.add 报错向量数据库未启动、索引配置错误查看向量数据库日志检查 Redis/Milvus 连接确认服务正常检查索引名称和维度等Tool 方法没有被调用工具方法没有注册、参数描述不清晰打印 Prompt 中生成的工具定义检查Tool注解和 Bean 注册Agent 出现循环调用工具没有设置最大迭代次数或 Agent 判断逻辑不收敛查看调用日志追踪模型决策过程设置最大步骤数增加终止条件Jedis/Lettuce 连接拒接Redis 未启动或密码配置错误检查 Redis 进程和配置启动 Redis检查配置Java 内存溢出 OOM文档过大、向量数据过多、JVM 堆内内存不足查看 GC 日志使用 JVisualVM 分析调整 JVM 参数对大批量任务分批次处理中文支持不好回答乱码编码问题或模型对中文指令理解不足检查请求和响应的编码统一使用 UTF-8适当调整 System Prompt这里特别说一下“Spring AI 连接 DeepSeek 不输出 content”这个问题。从 Java 社区的反馈来看比较常见的场景是请求能发出去但返回的 content 为空。排查顺序建议先用 curl 直接调用 DeepSeek 官方 API确认 API 本身正常。检查 Spring AI 的 base-url 是否配置正确。检查模型名是否为deepseek-chatDeepSeek 的模型名与 OpenAI 不完全一致。检查是否使用了不兼容的请求参数比如某些只在 OpenAI 上有效的参数。通常按这个顺序排查能在前两步定位到大部分问题。9. 最佳实践与工程建议教程能跑通是一回事生产环境能稳定运行又是另一回事。下面这些工程建议是实际项目中沉淀出来的经验。9.1 开发顺序建议不要一上来就同时把 RAG、Tools、Agent 全部集成到一个系统里。建议按照以下顺序渐进推进先跑通 ChatClient 基础对话。再叠加 RAG验证知识库检索效果。再接 Tools让模型能调用业务接口。最后做 Agent 编排实现多工具协同。每一步都在前一步稳定运行的基础上进行。这样出了问题很快就能定位是模型层、检索层还是编排层的问题。9.2 文档质量决定 RAG 上限很多团队把大量精力花在框架选择上却忽略了知识库文档本身的质量。实际上RAG 的效果上限是由文档质量决定的。建议文档格式统一避免扫描件和图片型 PDF。文档结构清晰有标题层级。切分参数根据文档类型调整不要一个参数用到底。定期更新向量库删除失效文档。如果发现检索效果不好先看文档再看技术。9.3 生产环境安全与权限Agent 工具调用能直接操作业务系统这也带来了更大的安全风险。API Key 使用环境变量或密钥管理服务不写入代码仓库。所有 Tool 方法必须做权限校验。涉及删除、修改、转账等敏感操作必须有二次确认机制。生产环境启用访问日志记录模型输入输出和工具调用记录。对模型输出做内容安全过滤。9.4 性能与成本为聊天接口配置合理的超时时间和重试策略。大批量文档向量化时使用分批处理避免 OOM。对话历史缓存设置过期时间防止内存持续增长。监控 Token 消耗设置预算告警。9.5 可观测性AI 应用的可观测性比传统后端更复杂因为你不仅要盯服务器指标还要看模型决策链路的每一步。建议至少记录用户原始输入。最终 Prompt 内容包含检索到的哪些文档、系统提示词。模型原始输出。工具调用记录。每次请求耗时和 Token 消耗。检索召回的相关性评分。有了这些日志你才能在模型回答质量下降时快速定位是检索问题、模型问题还是 Prompt 问题。10. 总结与后续学习路径这篇文章从 Java 开发者的实际困境出发把 Spring AI 2.0 和 LangChain4j 这两套 Java AI 开发框架的核心链路完整走了一遍。核心结论可以归纳为三点第一Java 做 AI 应用已经具备完整的技术路径。Spring AI 2.0 把模型接入、RAG、Tools 抽象成了 Spring 风格的组件Java 开发者不需要转 Python 也能做出高质量的知识库问答和 Agent 应用。第二RAG 是当前落地价值最高、上手难度又比较可控的切入点。如果你所在团队有大量文档需要变成可检索、可问答的知识资产优先从这里开始收益最直接。第三Agent 的开发要克制。先学会用 Tools 把业务能力暴露给模型再考虑复杂的多工具编排。对多数企业场景来说一个稳定的 RAG 少量 Tools比一个花哨但不稳定的 Agent 更有实际价值。后续如果你想深入可以沿着这几个方向继续学习LangChain4j 的 AiServices 更完整的 Agent 模式。向量数据库的选型和混合检索优化比如 Milvus 的环境搭建与索引调优。Embedding 模型的中文效果对比与选型。企业级 AI 应用的评测体系怎么量化回答质量。这套教程在 B 站涵盖了从入门到实战的完整讲解如果文字版看完还有不清楚的细节配合视频学习会更直观。建议先跟着敲一遍最小 Demo再逐步加深——记代码不如记思路把链路理解透了以后不管框架怎么升级都不会慌。如果你在实际运行中遇到其它报错欢迎在评论区把堆栈信息贴出来一起讨论解决思路。
当 Python 生态里 LangChain、LlamaIndex 已经堆满教程的时候很多 Java 开发者的心态其实是矛盾的想学 AI 应用开发又不想丢掉 Java 的技术栈去重新学一遍 Python。尤其是做企业级应用、后端架构、数据中台的团队核心系统全是 Spring Boot不可能因为要接一个大模型就把整个服务重写。Spring AI 2.0 的出现给这条困境提供了一条比较明确的出路Java 生态正在把大模型能力变成 Spring 体系里一个普通的 starter 依赖。你不需要成为 Prompt 工程师也不需要转语言就能在原有工程里接入模型对话、RAG 知识库、Agent 工具调用。这篇文章会从这套实战教程的核心内容出发把 Spring AI 2.0、LangChain4j、Tools、RAG、Agent 这几块拆开讲清楚。无论你是刚接触 AI 应用开发的 Java 后端还是已经在项目里试过接大模型但踩了一堆坑的人按照这篇文章的顺序走一遍能少走不少弯路。1. 这篇文章真正要解决的问题先说实话Java 生态做大模型应用最大的问题不是技术难度而是资料断层。Python 那边有 LangChain、LlamaIndex、Dify教程多、社区活跃、案例丰富。而 Java 这边你搜“Java 接入大模型”能搜到的要么是调用 HTTP 接口的简单 Demo要么就是翻译过来的概念科普真正能落地到 Spring Boot 工程里的完整链路少得可怜。这就造成一种现象很多 Java 团队想做一个企业内部的知识库问答系统结果发现网上能找到的 Java 案例只覆盖了“调用 API 聊天”这一步再往后——文档怎么切分、向量怎么存储、检索怎么和模型输出结合、Agent 怎么调用自己的业务接口——就没有下文了。这篇文章要解决的就是这个断层。它不是从零讲什么是大模型而是直接回答一个问题如果你是一个 Java 后端开发想在自己的 Spring Boot 项目里做出一个带 RAG 和 Agent 能力的应用最快最稳的路径是什么围绕这个核心问题文章会覆盖四个层次模型接入层Spring AI 2.0 怎么统一不同厂商的大模型 API。知识增强层RAG 的完整链路从文档加载到向量检索。能力扩展层Tools 机制让大模型能够调用你自己的业务接口。智能编排层Agent 怎么把工具组合成一个能自主决策的系统。如果你看这套教程是为了应付面试那么 RAG 和 Agent 这两块的原理与实现细节已经是 Java 面试题里出现频率越来越高的问题如果你是为了实际落地这篇文章的代码和排错思路可以直接拿去做工程参考。2. Spring AI 2.0 与 LangChain4j 到底在解决什么很多刚接触的 Java 开发者会有一个困惑Spring AI 和 LangChain4j 看着功能差不多到底有什么区别是不是重复造轮子理解这个问题要从 Java 生态做 AI 应用的两条路线说起。2.1 Spring AISpring 官方对 AI 的抽象层Spring AI 的定位非常明确让 Spring 开发者用熟悉的编程模型接入 AI 能力。它做的事情本质上和 Spring 对其他中间件的抽象是一样的——定义一套统一接口把不同厂商的模型封装成可替换的实现。在 Spring AI 里ChatClient是一个核心入口你通过它发起对话请求底层是 OpenAI 还是 DeepSeek 还是通义千问被抽象层屏蔽掉了。这意味着你写业务代码时不需要关心每个模型厂商的 API 格式差异切换模型时只需要改配置。Spring AI 2.0 在这条路上走得更远。它不只是做单轮对话的抽象而是把 RAG 的常用组件也纳入了标准体系文档加载器、文本切分器、Embedding 模型、向量存储、检索器这些都有对应的接口和默认实现。你可以理解成Spring 官方想给 Java 生态造一个“AI 开发的标准底座”。2.2 LangChain4jLangChain 思想在 Java 的移植LangChain4j 的历史和 Spring AI 不太一样。它最早是把 Python 社区 LangChain 的核心思路移植到 Java/JVM 生态发展到现在已经有了自己的风格尤其是AiServices这套声明式 Agent 开发模型用起来很像写 Spring Service。LangChain4j 的优势在于它起步早组件多对各类向量数据库、Embedding 模型的支持比 Spring AI 更丰富。如果你要做深度定制的 RAG 链路或者想用 Agent 做复杂编排LangChain4j 的灵活性会更高。2.3 怎么选技术选型判断从这套教程和 Java 社区的实践来看比较推荐的选择逻辑是维度Spring AILangChain4j背景Spring 官方项目迭代快社区驱动功能丰富上手成本低熟悉 Spring 就能快速上手中概念相对多一些RAG 支持组件完整采用统一抽象集成丰富向量库支持多Agent 开发支持 Function Calling使用 AiServices开发效率高长远趋势与 Spring Boot 深度融合社区活跃生态持续增长如果你是在一个标准的 Spring Boot 项目里做功能增强优先考虑 Spring AI如果你想要灵活的编排能力和更细粒度的控制LangChain4j 是很强的补充。两者并不是非此即彼的关系。实际项目里用 Spring AI 做底层的模型接入和 RAG 链路用 LangChain4j 做 Agent 编排是完全可行的组合。这也是这套教程里的一个重要思路。3. 核心概念拆解RAG、Tools、Agent 到底怎么回事有了框架基础还需要把几个核心概念讲透。因为网上很多教程把概念说得很玄乎实际上它们对应的是非常具体的工程问题。3.1 RAG给大模型发一本参考书大模型的训练数据是有截止时间的企业内部的知识它也完全不知道。你直接问它“我们公司的报销流程是什么”它只能瞎编。RAGRetrieval-Augmented Generation检索增强生成解决的就是这个问题。它的核心思路很朴素每次问答时先从你的知识库里检索出相关内容把检索结果拼到 Prompt 里让模型基于这些资料回答。用生活场景类比以前你让实习生直接回答问题他只能靠自己的记忆瞎说RAG 的做法是先给他一本参考书告诉他“遇到不知道的就去书里查回答时以书里的内容为准”。RAG 的完整链路包括文档加载读取 PDF、Word、Markdown 等格式的文档。文本切分把长文档切成适合检索的片段。向量化用 Embedding 模型把文本转换成向量。向量存储把向量写入向量数据库。检索召回根据用户问题找出最相关的文档片段。生成回答把检索结果和问题一起交给大模型。很多 Java 开发者问Spring AI 2.0 和 LangChain4j 哪个做 RAG 更合适其实框架只是辅助RAG 的工程质量取决于文档切分策略、Embedding 模型质量、检索策略这几块和语言、框架关系不大。3.2 Tools让大模型有手有脚大模型本身不能查询天气、不能查数据库、不能调你的业务接口。它本质上是一个文本生成器只能根据输入输出文本。Tools工具调用机制解决的就是这个问题。它的原理可以简单理解成你把你系统中的函数暴露给大模型大模型在回答问题时如果发现自己需要的某个信息需要通过执行代码才能拿到它会在回复里生成一个“我要调用某某函数参数是某某”的请求。你的程序收到这个请求后执行实际的函数把执行结果返回给大模型。大模型再根据这个结果生成最终回答。这就是所谓的 Function Calling函数调用。例如用户问“帮我查一下订单 10086 的配送状态”大模型本身不知道这个信息但它知道有一个queryOrderStatus(orderId)函数。于是它输出“我要调用 queryOrderStatus参数是 10086”。程序执行这个函数拿到状态信息再交给大模型组织回答。在 Spring AI 里你可以用Tool注解标记一个普通 Spring Bean 方法框架会自动把方法的参数描述、功能描述暴露给模型。3.3 Agent从回答问题到完成任务Tools 解决的是单次调用的问题Agent 解决的是多步骤决策的问题。举个例子用户说“帮我把上周的销售数据整理成一份周报发给部门经理”。这个任务不是一个函数能完成的它需要查询销售数据库拿到数据。分析数据组织成周报格式。找到部门经理的邮箱。调用接口发送邮件。Agent 做的事情就是拆解任务、决定调用哪些工具、按照什么顺序调用、观察每一步的结果、直到最终完成任务。你可以把 Agent 理解成一个“有大脑的调度器”。大模型是大脑Tools 是手脚Agent 负责协调大脑和手脚完成复杂任务。从这套教程的实践来看Java 开发者最容易踩的坑是一开始就想过度设计 Agent结果调度逻辑复杂、链条不稳定、排错困难。更推荐的做法是先用 RAG 解决知识问答再逐步升级到 Agent 编排。4. 开发环境准备与版本选择在做实战之前环境准备和版本选择非常关键。很多教程里代码跑不通不是代码写错了而是版本不匹配。4.1 JDK 与构建工具JDK建议 JDK 17 及以上Spring Boot 3.x 的最低要求是 JDK 17。Maven3.8Gradle 也可以但 Maven 在 Spring 生态里更常见。IDEIntelliJ IDEA 社区版或旗舰版均可建议使用 2023.1 以上版本对 Spring Boot 支持更好。java -version # 期望输出 openjdk version 17.0.x 或更高版本 mvn -version # 期望输出 Apache Maven 3.8.x4.2 依赖引入以 Maven 为例核心依赖分为三部分Spring Boot 基础依赖、Spring AI 相关依赖、向量数据库与工具类依赖。parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.3.x/version relativePath/ /parent properties java.version17/java.version !-- 具体版本号以实际官方版本为准 -- spring-ai.version2.0.x/spring-ai.version /properties dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version${spring-ai.version}/version typepom/type scopeimport/scope /dependency !-- 模型接入以 OpenAI 兼容接口为例 -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai/artifactId /dependency !-- 支持读取 PDF、Word 等文档 -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-tika-document-reader/artifactId /dependency /dependencies这里要注意Spring AI 的版本迭代非常快不同版本的 API 调整幅度可能不小。如果你发现代码里的ChatClient、Document、EmbeddingModel方法名和网上文章不一样先检查版本号。4.3 模型 API Key 配置以 DeepSeek 为例因为 DeepSeek 提供了 OpenAI 兼容的 API所以在 Spring AI 里可以直接使用 OpenAI 模块配置只是把 base-url 改成 DeepSeek 的地址。# application.yml spring: ai: openai: base-url: https://api.deepseek.com api-key: ${DEEPSEEK_API_KEY} chat: options: model: deepseek-chat temperature: 0.7需要注意API Key 不要硬编码在代码里建议使用环境变量或配置文件占位符。5. 第一步实战跑通一个最小对话应用很多人学框架有个误区上来就做复杂的 RAG、Agent结果链路太长出了问题无法定位。正确做法是先把最小链路跑通再逐步叠加功能。5.1 写一个最简单的 Controller// 文件路径src/main/java/com/example/ai/AiController.java RestController RequestMapping(/api/chat) public class AiController { private final ChatClient chatClient; public AiController(ChatClient.Builder chatClientBuilder) { this.chatClient chatClientBuilder.build(); } GetMapping(/simple) public String simple(RequestParam String message) { return chatClient.prompt() .user(message) .call() .content(); } }这段代码的逻辑很直观通过ChatClient.Builder创建一个ChatClient用户传入消息框架将消息发送给配置好的大模型然后把模型返回的文本作为响应输出。ChatClient是 Spring AI 中最常用的入口。它类似RestTemplate之于 HTTP 调用是统一封装模型调用的门面。5.2 增加上下文记忆单轮对话很容易写但真实场景需要多轮对话。Spring AI 提供ChatMemory来管理对话历史。Component public class ChatService { private final ChatClient chatClient; public ChatService(ChatClient.Builder builder) { this.chatClient builder .defaultSystem(你是一个友善的AI助手请用简洁的语言回答问题。) .build(); } public String chatWithMemory(String message, String conversationId) { return chatClient.prompt() .user(message) .advisors(a - a.param(ChatMemory.CONVERSATION_ID, conversationId)) .call() .content(); } }这里通过conversationId标识不同的会话框架会自动保存和读取对话历史。5.3 运行验证启动 Spring Boot 应用访问http://localhost:8080/api/chat/simple?message你好请介绍一下你自己如果配置正确会返回大模型的对话结果。到这里你的第一个 Spring AI 2.0 应用就跑通了。这个步骤看起来很简单但它验证了最关键的事情模型接入、配置管理、Spring Bean 注入这一整套链路是否通畅。这时候再继续做 RAG 和 Agent出了问题就能判断是哪一层的问题。6. RAG 实战构建一个 Java 版知识库问答系统RAG 是这套教程的重头戏。很多 Java 团队做企业内部知识库核心需求就是上传一批文档用户用自然语言提问系统基于文档内容回答。下面完整走一遍 RAG 链路。6.1 知识库处理的完整流程RAG 的流程可以分成两个阶段离线阶段预处理加载文档。切分文档。向量化。写入向量数据库。在线阶段查询用户输入问题。问题向量化。从向量库检索最相关的文档片段。把文档片段和问题组成 Prompt。大模型生成回答。6.2 文档加载与切分Spring AI 提供了一系列文档读取抽象底层集成 Tika 来支持多格式解析。// 文件路径src/main/java/com/example/ai/rag/DocumentIngestionService.java Service public class DocumentIngestionService { private final EmbeddingModel embeddingModel; private final VectorStore vectorStore; public DocumentIngestionService(EmbeddingModel embeddingModel, VectorStore vectorStore) { this.embeddingModel embeddingModel; this.vectorStore vectorStore; } public void ingestPdf(String filePath) { // 1. 加载文档 TikaDocumentReader reader new TikaDocumentReader(Resource.fromFile(filePath)); ListDocument documents reader.get(); // 2. 切分文档避免超出模型上下文窗口 TokenTextSplitter splitter new TokenTextSplitter(); ListDocument splitDocuments splitter.apply(documents); // 3. 分割后的文档写入向量存储框架内部会自动调用 embeddingModel 做向量化 vectorStore.add(splitDocuments); } }核心要点TikaDocumentReader负责读取各种格式的文档包括 PDF、Word、TXT 等。TokenTextSplitter负责切分文本它是按 Token 数来切分而非简单按字符数。vectorStore.add()会先调用EmbeddingModel生成向量再写入存储。切分策略是 RAG 里最容易影响效果的一环。切得太短语义不完整切得太长检索噪音大。实际项目中建议先从官方默认参数开始再根据业务文档类型做调整。6.3 配置向量存储Spring AI 的VectorStore是统一的向量存储接口底层实现可以是 Redis、Milvus、PGVector 等。从社区使用趋势看Milvus 是很多团队的选择因为它对大规模向量检索的支撑更好也支持混合检索的扩展能力。为了让代码能直接跑通这里用 Redis 作为示例因为 Redis 在企业里很常见不需要额外搭建复杂的向量数据库服务。dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-redis/artifactId /dependencyspring: data: redis: host: localhost port: 6379 ai: vectorstore: redis: index-name: knowledge_base prefix: doc:注意Spring Data Redis 的spring-boot-starter-data-redis也需要引入否则无法自动配置 Redis 连接。6.4 检索式问答向量存储配置好之后编写检索问答的核心代码// 文件路径src/main/java/com/example/ai/rag/RagChatService.java Service public class RagChatService { private final ChatClient chatClient; public RagChatService(ChatClient.Builder builder, VectorStore vectorStore) { this.chatClient builder .defaultSystem( 你是一个企业知识库助手。 请严格基于提供的资料回答问题。 如果资料中没有相关信息请明确说“根据当前知识库无法回答”不要编造答案。 ) .defaultAdvisors(QuestionAnswerAdvisor.builder(vectorStore).build()) .build(); } public String answer(String question) { return chatClient.prompt() .user(question) .call() .content(); } }这里的核心是QuestionAnswerAdvisor。它的工作流程是接收用户问题 → 从 VectorStore 中检索相关文档 → 将文档内容和用户问题组装成新 Prompt → 调用模型生成回答。对比之前的最小 Demo你会发现差异非常小只需要加一个 Advisor就把“普通问答”升级成了“基于知识库的问答”。这也是 Spring AI 设计得比较好的地方RAG 能力通过组合式扩展嵌入到现有流程中。6.5 使用 Qwen Embedding 模型如果你希望 Embedding 效果更适合中文场景可以使用 Qwen 的 Embedding 模型。从搜索结果看这也是 Java 开发者非常关注的一个问题。具体做法是通过 OpenAI 兼容接口或自建 Embedding 服务接入。spring: ai: openai: embedding: base-url: https://你的embedding服务地址 api-key: ${EMBEDDING_API_KEY} options: model: text-embedding-v4如果 Embedding 模型和 Chat 模型不是同一个服务可能需要分别配置。具体配置项会随版本变化建议优先查看 Spring AI 对应当前版本的文档。6.6 RAG 效果验证RAG 链路跑通后不要直接上线先用测试集验证效果。推荐的验证方式是准备 10-20 个典型的业务问题。逐个提问检查回答是否引用正确文档。检查“知识库中其实没有答案”的问题模型是否给出了错误回答。RAG 最常见的问题就是“检索到的内容不对”导致模型胡编这时候问题不一定在大模型而在文档切分、Embedding、检索策略上。此外如果团队有条件做更精细的检索可以关注“混合检索 重排”Hybrid Search Rerank的思路这也是当前 RAG 技术比较热门的演进方向。混合检索结合了向量检索和关键词检索的优势重排模型会对初次召回的结果做二次排序。不过在工程落地时我的建议是先保证向量检索的入库质量和检索策略是对的再叠加混合检索和重排不要一上来就把链路搞得太复杂。7. Tools 与 Agent 实战从回答问题到执行任务RAG 解决知识类问答Tools 和 Agent 解决的是操作类任务。7.1 用 Spring AI 暴露一个 Tool假设你有这样一个需求用户可以直接用自然语言查询天气信息。模型不知道天气数据但它可以调用你写好的工具方法。// 文件路径src/main/java/com/example/ai/tool/WeatherTools.java Component public class WeatherTools { Tool(description 根据城市名称查询当前天气) public String getWeather(String city) { // 这里可以做真实 API 调用 return 城市 city 天气晴温度26℃空气质量良; } }在 Spring AI 中Tool注解会自动生成工具定义暴露给大模型。大模型在回答天气问题时会优先考虑使用这个工具而不是自己编造天气数据。然后在业务代码里开启工具调用// 文件路径src/main/java/com/example/ai/tool/ToolChatService.java Service public class ToolChatService { private final ChatClient chatClient; public ToolChatService(ChatClient.Builder builder, WeatherTools weatherTools) { this.chatClient builder .defaultTools(weatherTools) .build(); } public String chat(String message) { return chatClient.prompt() .user(message) .call() .content(); } }这个模式的实际意义在于你的 Java 业务方法可以直接变成大模型的能力。数据库查询、订单状态查询、第三方接口调用、内部系统操作都可以用这种方式暴露给模型。需要特别提醒的是工具调用涉及系统操作生产环境必须做权限校验。不能因为接口是给内部模型用的就直接暴露敏感操作。7.2 用 LangChain4j 写声明式 Agent如果要在 Java 里做更复杂的 Agent 编排LangChain4j 的AiServices是更舒服的方式。LangChain4j 的核心 API 设计非常接近 Spring 风格// 文件路径src/main/java/com/example/ai/agent/OrderAgent.java public interface OrderAgent { SystemMessage(你是订单助手负责帮助用户查询和管理订单信息。) String chat(UserMessage String userMessage); }// 文件路径src/main/java/com/example/ai/agent/OrderAgentConfig.java Configuration public class OrderAgentConfig { Bean public OrderAgent orderAgent(ChatLanguageModel chatLanguageModel) { return AiServices.builder(OrderAgent.class) .chatLanguageModel(chatLanguageModel) .tools(new OrderTools()) .build(); } }这里OrderTools是一个普通的类方法上加Tool注解// 文件路径src/main/java/com/example/ai/agent/OrderTools.java Slf4j public class OrderTools { Tool(根据订单号查询订单状态) public String queryOrderStatus(String orderId) { // 实际项目中替换为数据库或第三方接口调用 return 订单 orderId 当前状态已发货预计2天内送达; } Tool(根据用户ID获取最近订单列表) public String getRecentOrders(String userId) { return 用户 userId 最近的订单20260701-00120260705-002; } }这套机制的本质是AiServices把接口方法、SystemMessage和Tool组合起来自动完成 Agent 的决策循环。用户发送的问题会被模型分析模型决定调用哪些工具、以什么顺序调用最终汇总结果回答用户。你不需要手动编写复杂的循环判断逻辑。7.3 Agentic RAG让 Agent 自己决定查什么如果 RAG 的知识库有多个比如一个销售知识库、一个技术支持知识库传统的单一路径 RAG 需要手动配置选择逻辑。而 Agentic RAG 的做法是让 Agent 根据用户问题自主决定调用哪一个检索工具。public class MultiKnowledgeTools { Tool(从销售知识库检索信息) public String searchSalesKnowledge(String query) { return salesVectorStore.similaritySearch(query); } Tool(从技术支持知识库检索信息) public String searchTechSupportKnowledge(String query) { return techSupportVectorStore.similaritySearch(query); } }这样用户问“我们的销售提成比例是多少”Agent 会调用searchSalesKnowledge用户问“系统报错代码 5002 怎么解决”Agent 会调用searchTechSupportKnowledge。在 Java 工程里Agentic RAG 是比单纯 RAG 更灵活的方案但前提是你已经能跑通基础的 RAG 链路否则问题排查会很痛苦。7.4 Agent 和 Harness 的区别搜索热词里有一项是“harness 和 agent 区别”。这确实是 Agent 开发里容易混淆的概念。Harness 的直译是“安全带/操控装置”。在 Agent 框架的语境里它通常指代模型推理时外部的流程控制框架——比如模型推理调用工具的整个执行循环模型生成 → 发现工具调用 → 执行工具 → 返回结果 → 模型继续生成。Harness 提供的是基础执行壳它不关心任务是否完成只负责让“模型 工具”能循环跑起来。而 Agent 偏重“目标导向的自主行为”拆解任务、调度工具、观察结果、规划下一步。Agent 是一个设计模式或产品概念Harness 是实现 Agent 循环的底层基础设施。在实际项目中你不需要过度纠结这个概念差异。简单理解就是你写的业务逻辑是 Agent而框架Spring AI / LangChain4j执行的循环逻辑就是 Harness。8. 常见问题与排查思路这套教程涉及的链路比较长从模型接入到 RAG 到 Agent每一层都可能踩坑。下面整理一些高频问题问题现象可能原因排查方式解决方案Spring AI 连接 DeepSeek 不输出 contentbase-url 配置不对或模型名与实际不匹配检查配置和官方 API 文档直接 curl 测试 API确认 OpenAI 兼容地址的路径使用正确的模型名请求超时或响应慢模型服务网络不稳定、超时设置过短查看日志测试单次 API 调用延迟调大超时时间使用异步调用文档向量化后检索结果不相关切分粒度过长或过短、Embedding 模型不适合中文尝试不同切分参数单独调用 Embedding 生成向量检查调整切分策略或更换 Embedding 模型vectorStore.add 报错向量数据库未启动、索引配置错误查看向量数据库日志检查 Redis/Milvus 连接确认服务正常检查索引名称和维度等Tool 方法没有被调用工具方法没有注册、参数描述不清晰打印 Prompt 中生成的工具定义检查Tool注解和 Bean 注册Agent 出现循环调用工具没有设置最大迭代次数或 Agent 判断逻辑不收敛查看调用日志追踪模型决策过程设置最大步骤数增加终止条件Jedis/Lettuce 连接拒接Redis 未启动或密码配置错误检查 Redis 进程和配置启动 Redis检查配置Java 内存溢出 OOM文档过大、向量数据过多、JVM 堆内内存不足查看 GC 日志使用 JVisualVM 分析调整 JVM 参数对大批量任务分批次处理中文支持不好回答乱码编码问题或模型对中文指令理解不足检查请求和响应的编码统一使用 UTF-8适当调整 System Prompt这里特别说一下“Spring AI 连接 DeepSeek 不输出 content”这个问题。从 Java 社区的反馈来看比较常见的场景是请求能发出去但返回的 content 为空。排查顺序建议先用 curl 直接调用 DeepSeek 官方 API确认 API 本身正常。检查 Spring AI 的 base-url 是否配置正确。检查模型名是否为deepseek-chatDeepSeek 的模型名与 OpenAI 不完全一致。检查是否使用了不兼容的请求参数比如某些只在 OpenAI 上有效的参数。通常按这个顺序排查能在前两步定位到大部分问题。9. 最佳实践与工程建议教程能跑通是一回事生产环境能稳定运行又是另一回事。下面这些工程建议是实际项目中沉淀出来的经验。9.1 开发顺序建议不要一上来就同时把 RAG、Tools、Agent 全部集成到一个系统里。建议按照以下顺序渐进推进先跑通 ChatClient 基础对话。再叠加 RAG验证知识库检索效果。再接 Tools让模型能调用业务接口。最后做 Agent 编排实现多工具协同。每一步都在前一步稳定运行的基础上进行。这样出了问题很快就能定位是模型层、检索层还是编排层的问题。9.2 文档质量决定 RAG 上限很多团队把大量精力花在框架选择上却忽略了知识库文档本身的质量。实际上RAG 的效果上限是由文档质量决定的。建议文档格式统一避免扫描件和图片型 PDF。文档结构清晰有标题层级。切分参数根据文档类型调整不要一个参数用到底。定期更新向量库删除失效文档。如果发现检索效果不好先看文档再看技术。9.3 生产环境安全与权限Agent 工具调用能直接操作业务系统这也带来了更大的安全风险。API Key 使用环境变量或密钥管理服务不写入代码仓库。所有 Tool 方法必须做权限校验。涉及删除、修改、转账等敏感操作必须有二次确认机制。生产环境启用访问日志记录模型输入输出和工具调用记录。对模型输出做内容安全过滤。9.4 性能与成本为聊天接口配置合理的超时时间和重试策略。大批量文档向量化时使用分批处理避免 OOM。对话历史缓存设置过期时间防止内存持续增长。监控 Token 消耗设置预算告警。9.5 可观测性AI 应用的可观测性比传统后端更复杂因为你不仅要盯服务器指标还要看模型决策链路的每一步。建议至少记录用户原始输入。最终 Prompt 内容包含检索到的哪些文档、系统提示词。模型原始输出。工具调用记录。每次请求耗时和 Token 消耗。检索召回的相关性评分。有了这些日志你才能在模型回答质量下降时快速定位是检索问题、模型问题还是 Prompt 问题。10. 总结与后续学习路径这篇文章从 Java 开发者的实际困境出发把 Spring AI 2.0 和 LangChain4j 这两套 Java AI 开发框架的核心链路完整走了一遍。核心结论可以归纳为三点第一Java 做 AI 应用已经具备完整的技术路径。Spring AI 2.0 把模型接入、RAG、Tools 抽象成了 Spring 风格的组件Java 开发者不需要转 Python 也能做出高质量的知识库问答和 Agent 应用。第二RAG 是当前落地价值最高、上手难度又比较可控的切入点。如果你所在团队有大量文档需要变成可检索、可问答的知识资产优先从这里开始收益最直接。第三Agent 的开发要克制。先学会用 Tools 把业务能力暴露给模型再考虑复杂的多工具编排。对多数企业场景来说一个稳定的 RAG 少量 Tools比一个花哨但不稳定的 Agent 更有实际价值。后续如果你想深入可以沿着这几个方向继续学习LangChain4j 的 AiServices 更完整的 Agent 模式。向量数据库的选型和混合检索优化比如 Milvus 的环境搭建与索引调优。Embedding 模型的中文效果对比与选型。企业级 AI 应用的评测体系怎么量化回答质量。这套教程在 B 站涵盖了从入门到实战的完整讲解如果文字版看完还有不清楚的细节配合视频学习会更直观。建议先跟着敲一遍最小 Demo再逐步加深——记代码不如记思路把链路理解透了以后不管框架怎么升级都不会慌。如果你在实际运行中遇到其它报错欢迎在评论区把堆栈信息贴出来一起讨论解决思路。
