Javaer转型Agent开发：Spring AI与LangChain4j学习路线及RAG实战

1. 从Java到Agent一个老Javaer的转型路线图做了七八年Java后端CRUD写了无数遍Spring的源码翻来覆去看了好几轮突然发现招聘JD上开始频繁出现“Agent开发”“大模型应用”“RAG”这些词。说实话一开始我是有点抗拒的——毕竟Java生态这么成熟为什么要去碰一个看起来还很不稳定的领域但后来接手了一个内部知识库问答的项目硬着头皮用Spring AI做了一版才发现这事儿没有想象中那么玄乎而且Javaer转Agent开发其实有天然的优势。这篇文章不是那种“三天带你从入门到精通”的速成教程而是把我自己从零开始摸索Agent开发过程中看过的资料、踩过的坑、总结出来的学习路径完整地梳理一遍。核心关键词就几个Java、Agent、Spring AI、LangChain4j、Spring Boot。如果你也是一个有Java基础、想往Agent方向转的开发者或者团队里开始要求用Spring AI做AI应用集成那这篇内容应该能帮你省下不少瞎找资料的时间。先说清楚一个前提Agent开发不等于要你去训练模型。绝大多数Javaer转Agent做的是应用层集成——把大模型的能力接入到现有的Spring Boot系统里做RAG检索增强、做工具调用、做多轮对话编排。这跟算法工程师的工作是两码事。你需要理解模型的能力边界和调用方式但不需要去推导反向传播。这个定位想清楚了后面的学习路线才不会跑偏。我自己的学习路径大致分三个阶段第一阶段是搞清楚Agent到底是什么、跟普通API调用有什么区别第二阶段是选一个框架上手我选的是Spring AI和LangChain4j第三阶段是找一个真实场景做完整落地。下面按这个顺序展开每个阶段该看什么资料、重点理解什么概念、有哪些坑我都会详细说。2. 先搞明白Agent到底跟普通接口调用有什么不同2.1 Agent的本质是一个循环决策系统很多人第一次听到“Agent”这个词会把它跟“调用大模型API”画等号。其实不是。普通的API调用是你问一句它答一句一次性的。Agent的核心在于循环——它会根据当前状态决定下一步做什么执行完一个动作后观察结果再决定下一步直到任务完成或者达到终止条件。用生活化的类比普通API调用像你去餐厅点菜服务员把菜单递给厨房厨房做好端出来结束。Agent更像你请了一个私人助理你说“帮我安排下周去北京的行程”他会先查你的日历看哪天有空然后查航班再对比酒店价格中间可能还会问你“预算大概多少”最后把方案给你。这个过程中助理做了多次决策和工具调用这就是Agent。从技术实现角度看一个Agent系统至少包含四个部分规划Planning、记忆Memory、工具使用Tool Use、执行Action。规划是拆解任务记忆是保存上下文和历史工具使用是调用外部能力比如查数据库、调API、搜网页执行是真正落地动作。Spring AI和LangChain4j这些框架本质上就是在帮你把这四个部分串起来。2.2 Javaer做Agent的独特优势在哪里我刚开始学的时候有个误区觉得Python才是AI领域的正统语言Java做这个是不是有点“歪门邪道”。后来发现完全不是。Javaer做Agent有几个非常实在的优势第一企业级系统的集成能力。大部分公司的核心业务系统是Java写的用Spring Boot构建。Agent要真正产生价值必须能接入这些系统——查订单、查库存、走审批流。Python脚本做Demo很快但要接入企业级系统Java的生态成熟度是碾压级的。第二工程化思维。Javaer习惯了依赖注入、面向接口编程、分层架构、异常处理这些工程实践。Agent开发看起来是AI的事但真正落地的时候稳定性、可观测性、错误恢复这些工程问题才是决定成败的关键。我见过太多Python写的Agent Demo跑起来很惊艳一上生产就各种超时、死循环、上下文溢出。第三Spring生态的加持。Spring AI和LangChain4j都是为Javaer量身定做的。Spring AI的API设计跟Spring Boot一脉相承自动配置、Starter依赖、注解驱动你之前用Spring的经验几乎可以无缝迁移。LangChain4j则是把Python LangChain的核心概念用Java重新实现了一遍如果你之前了解过LangChain上手会非常快。2.3 学习资料的选择逻辑少即是多网上关于Agent开发的资料铺天盖地但真正适合Javaer的其实不多。我的筛选标准是三条第一代码示例必须是Java或Spring Boot的Python示例看了也白看语言特性差异太大第二必须基于Spring AI或LangChain4j这两个是Java Agent开发的主流框架学其他小众框架性价比不高第三要有完整的项目结构不是那种几行代码的玩具示例而是能看到分层、配置、异常处理的工程化代码。按照这个标准我整理了一份学习资料清单后面会详细展开。这里先给一个总览官方文档是地基必须精读GitHub上的示例项目是脚手架帮你快速搭起结构技术博客和视频教程是补充用来理解某些难点最后一定要自己动手做一个完整项目否则看再多都是纸上谈兵。3. 核心框架选型Spring AI还是LangChain4j3.1 两个框架的定位差异Spring AI和LangChain4j是Java Agent开发的两大主流框架但它们的定位和设计哲学有明显差异。我两个都用过说一下实际感受。Spring AI是Spring官方团队推出的设计理念是“把AI能力变成Spring生态的一等公民”。它的API风格跟Spring Data、Spring Security这些模块高度一致用起来非常“Spring”。比如你要调用OpenAI的接口只需要在application.yml里配好api-key然后注入一个ChatClient就能用。它支持自动配置、条件装配、Actuator监控跟现有Spring Boot项目的集成成本极低。LangChain4j则是社区驱动的项目灵感来自Python的LangChain。它的抽象层次更高提供了Chain、Agent、Tool、Memory、Retriever这些概念适合构建复杂的Agent工作流。它的优势在于灵活性和功能丰富度比如对RAG的支持更细致有专门的文档加载器、文本分割器、向量存储抽象。但相对来说跟Spring Boot的集成需要自己多写一些配置。我的建议是如果你的项目是标准的Spring Boot应用优先用Spring AI集成成本最低团队上手最快。如果你需要构建复杂的Agent编排逻辑或者需要更细粒度的RAG控制选LangChain4j。当然两个也可以混用Spring AI负责模型调用和基础集成LangChain4j负责复杂的Chain编排我现在的项目就是这么干的。3.2 Spring AI的核心概念与上手路径Spring AI有几个核心概念必须搞清楚否则看文档会一头雾水。ChatClient是最基础的入口封装了跟大模型对话的能力。你可以把它理解为一个“增强版的RestTemplate”只不过调的不是普通HTTP接口而是大模型的Chat API。它支持同步调用、流式调用、结构化输出等多种模式。Prompt和PromptTemplate是提示词管理工具。PromptTemplate允许你用占位符定义模板运行时填充变量。这个在构建可复用的Agent逻辑时非常有用避免把提示词硬编码在Java代码里。Advisor是Spring AI的一个特色机制类似Spring MVC的拦截器。你可以在对话前后插入自定义逻辑比如记录日志、做内容过滤、注入上下文。这个机制在实现RAG的时候特别有用——在用户提问后、发给模型前先检索相关文档并注入到Prompt里。Tool Calling是Agent的核心能力。Spring AI允许你把普通的Java方法注册为工具模型在需要的时候会自动调用。比如你定义一个queryOrderStatus(String orderId)方法用户问“我的订单到哪了”模型会自动识别需要调用这个工具并传入订单号。上手路径我建议这样先跑通最简单的ChatClient调用理解基本的请求响应流程然后学PromptTemplate把提示词管理起来接着学Advisor理解拦截器机制最后学Tool Calling这是Agent的关键。官方文档的Getting Started部分写得很好跟着走一遍基本就能上手。3.3 LangChain4j的抽象层次与适用场景LangChain4j的抽象比Spring AI更丰富学习曲线也稍陡一些。它的核心概念包括ChatLanguageModel是模型调用的基础接口跟Spring AI的ChatClient类似。AiServices是一个很有意思的抽象你可以定义一个Java接口用注解标注每个方法的行为LangChain4j会自动生成实现。比如你定义一个Assistant接口里面有个String chat(String message)方法加上SystemMessage注解它就变成了一个可用的对话服务。RetrievalAugmentor是RAG的核心组件负责在对话前检索相关文档并注入上下文。它支持多种检索策略包括向量检索、全文检索、混合检索。LangChain4j对RAG的支持比Spring AI更细致有专门的DocumentLoader、DocumentSplitter、EmbeddingStore等组件。Agent在LangChain4j里是一个更高级的抽象支持多步推理和工具调用。你可以定义一个Agent给它一组工具它会自动规划执行步骤。这个在构建复杂工作流的时候很有用。LangChain4j适合的场景需要精细控制RAG流程、需要构建多Agent协作系统、需要用到比较新的Agent模式比如ReAct、Plan-and-Execute。如果只是简单的对话集成Spring AI更省事。3.4 框架选型的决策清单为了帮你快速做决定我整理了一个对比表格维度Spring AILangChain4j官方支持Spring官方团队社区驱动Spring Boot集成极低Starter自动配置中等需手动配置API风格Spring风格注解驱动链式调用接口抽象RAG支持基础支持够用丰富细粒度控制Tool Calling支持注解方式支持接口方式学习曲线平缓中等适合场景标准Spring Boot集成复杂Agent编排我的实际建议先学Spring AI把基础概念跑通然后再看LangChain4j。两个框架的核心概念是相通的学会一个再学另一个会快很多。不要一上来就两个一起学容易混淆。4. 学习资料清单从入门到实战的完整路径4.1 官方文档必须精读的地基Spring AI官方文档是第一个要看的东西。地址在Spring官网的Projects下面直接搜“Spring AI”就能找到。文档结构很清晰Getting Started、Core Concepts、API Reference、Examples。我建议按这个顺序读先看Getting Started跑通第一个Demo然后精读Core Concepts理解ChatClient、Prompt、Advisor、Tool Calling这几个核心概念最后翻API Reference查漏补缺。官方文档有个好处是代码示例都是最新的跟当前版本匹配。但缺点是有些概念讲得比较简略比如Advisor的执行顺序、Tool Calling的底层机制这些需要配合其他资料来理解。LangChain4j官方文档在GitHub的langchain4j仓库里README写得很详细还有专门的文档站点。它的文档比Spring AI更偏重概念解释每个组件都有详细的说明和示例。特别推荐看它的Tutorials部分有从零构建RAG应用的完整教程。Spring AI Alibaba是阿里做的Spring AI扩展对国内开发者很友好。它封装了通义千问、智谱AI等国内模型的接入还提供了一些企业级特性。如果你用的是国内模型这个文档值得一看。4.2 GitHub示例项目最好的脚手架光看文档容易陷入“看懂了但写不出来”的困境。这时候需要找一些完整的示例项目来参考。我推荐几个我实际看过的spring-ai-examples是Spring AI官方的示例仓库里面有各种场景的示例代码包括基础对话、RAG、Tool Calling、多模态等。代码质量很高结构清晰适合作为项目脚手架。langchain4j-examples是LangChain4j的官方示例覆盖了它的大部分功能。特别推荐看它的RAG示例和Agent示例能帮你理解LangChain4j的设计思路。spring-ai-alibaba-examples是阿里的示例仓库如果你用国内模型这个更实用。里面有对接通义千问、智谱AI的完整示例。看示例项目的时候不要只是复制粘贴。我的方法是先把项目跑起来然后逐行读代码理解每个类的作用、每个配置项的含义。遇到不懂的就去查文档这样学得最扎实。4.3 技术博客与视频教程理解难点的补充官方文档和示例项目覆盖了“怎么做”但有些“为什么”需要靠博客和视频来补充。我收藏了几个质量比较高的来源Spring官方博客会不定期发布Spring AI的深度文章讲解设计理念和最佳实践。这些文章质量很高但更新频率不高。B站和YouTube上的实战教程适合视觉学习者。搜“Spring AI实战”“LangChain4j教程”能找到不少。但要注意筛选有些教程版本太老代码跑不起来。我一般看发布时间在半年内的并且会对照官方文档验证。掘金和CSDN上的技术文章质量参差不齐但有些深度文章确实写得好。我一般搜具体问题比如“Spring AI Advisor执行顺序”“LangChain4j RAG优化”能找到一些实战经验分享。4.4 我实际用过的资料组合说一下我自己的学习资料组合供你参考第一阶段理解概念Spring AI官方文档的Getting Started和Core Concepts LangChain4j README 几篇高质量的入门博客。第二阶段动手实践spring-ai-examples仓库 langchain4j-examples仓库 Spring AI Alibaba文档。第三阶段深入理解Spring AI源码重点看ChatClient和Advisor的实现 LangChain4j源码重点看RetrievalAugmentor和Agent的实现 自己动手写一个完整项目。这个组合的好处是先建立概念框架然后通过示例项目快速上手最后通过读源码理解底层机制。整个过程大概花了两个月每天投入两三个小时。5. 实操落地从零搭建一个RAG知识库问答系统5.1 项目背景与技术选型光说不练假把式。我选了一个最典型的场景来练手企业内部知识库问答。需求很简单把公司的产品文档、FAQ、技术手册导入系统员工用自然语言提问系统检索相关文档并生成回答。技术选型Spring Boot 3.x Spring AI 向量数据库我用的Redis Stack因为公司已经在用Redis了 通义千问的Embedding和Chat模型。选通义千问是因为国内访问稳定而且Spring AI Alibaba有现成的集成。为什么选RAG而不是直接微调三个原因第一成本低微调需要标注数据和GPU资源RAG只需要把文档处理好导入向量库第二更新快文档变了重新导入就行不用重新训练第三可解释RAG能告诉你答案来自哪篇文档微调做不到。5.2 核心流程拆解与关键代码整个RAG流程分两个阶段离线索引和在线检索。离线索引阶段读取文档 → 分割成小块Chunk→ 调用Embedding模型生成向量 → 存入向量数据库。关键点是Chunk的大小和重叠。我试过256、512、1024三种大小最后选了512重叠128。太小了语义不完整太大了检索精度下降。在线检索阶段用户提问 → 生成问题向量 → 在向量库中检索最相似的K个Chunk → 把Chunk和问题一起拼成Prompt → 调用Chat模型生成回答。关键点是K值的选择和相似度阈值。我设的K5相似度阈值0.7低于阈值的直接返回“没有找到相关信息”。核心代码用Spring AI的Advisor机制实现Configuration public class RagConfig { Bean public ChatClient chatClient(ChatClient.Builder builder, VectorStore vectorStore) { return builder .defaultAdvisors(new QuestionAnswerAdvisor(vectorStore)) .build(); } }QuestionAnswerAdvisor是Spring AI内置的RAG Advisor它会自动完成检索和上下文注入。如果你需要更细粒度的控制可以自己实现Advisor接口。5.3 参数调优与效果评估RAG的效果很大程度上取决于参数调优。我踩过的坑包括Chunk大小一开始用1024检索出来的内容太泛回答不够精准。改成512后明显改善。但也不能太小256的时候经常检索到不完整的句子。相似度阈值设太低会检索到不相关的内容模型容易被误导设太高会漏掉相关内容回答“不知道”。我最后设的0.7但不同模型和数据集需要调整。Prompt模板这个很关键。我一开始用的模板是“根据以下内容回答问题{context} 问题{question}”效果一般。后来改成“你是一个企业知识库助手请根据以下参考资料回答问题。如果参考资料中没有相关信息请明确告知用户。参考资料{context} 问题{question}”效果好很多。效果评估我用了两个指标检索命中率检索到的Chunk中是否包含正确答案和回答准确率人工评估回答是否正确。调优过程中检索命中率从60%提升到了85%回答准确率从50%提升到了75%。5.4 部署与性能优化上线的时候遇到几个性能问题Embedding调用延迟每次检索都要调用Embedding模型延迟在200ms左右。优化方案是加缓存相同的问题直接返回缓存的向量。用Caffeine做本地缓存命中率大概30%。向量库查询性能Redis Stack的向量检索在数据量小的时候很快但超过10万条后延迟明显上升。优化方案是加索引并且限制检索范围比如只检索某个分类下的文档。模型调用超时大模型调用偶尔会超时需要设置合理的超时时间和重试策略。我设的超时是30秒重试2次重试间隔1秒。并发控制多个用户同时提问时模型调用会成为瓶颈。我用了Spring AI的流式调用 WebFlux用户体验好很多不用等整个回答生成完才看到内容。6. 常见问题与避坑指南6.1 版本兼容性问题Spring AI和LangChain4j都还在快速迭代版本兼容性是最大的坑。我遇到过好几次升级版本后代码跑不起来的情况。Spring AI的版本选择建议用最新的稳定版GA版本不要用SNAPSHOT。Spring AI 1.0.0 GA之后API基本稳定了但之前的小版本之间差异很大。如果你看的是半年前的教程代码很可能跑不起来。LangChain4j的版本选择同样建议用最新稳定版。LangChain4j的API变动也比较频繁特别是Agent相关的模块。Spring Boot版本Spring AI 1.0.x需要Spring Boot 3.2LangChain4j对Spring Boot版本要求宽松一些但建议也用3.2。提示升级框架版本前先看Release Notes里的Breaking Changes避免踩坑。6.2 模型接入的常见问题API Key配置Spring AI的API Key配置在application.yml里格式是spring.ai.openai.api-key。但如果你用的是国内模型需要配置对应的base-url。比如通义千问的base-url是https://dashscope.aliyuncs.com/compatible-mode。模型名称不同模型的名称不一样配错了会报404。通义千问的Chat模型是qwen-plus或qwen-maxEmbedding模型是text-embedding-v2。网络问题调用国外模型API时可能会超时需要配置代理或换用国内模型。我现在的项目全部用国内模型稳定性和速度都好很多。6.3 RAG效果不佳的排查思路RAG效果不好按这个顺序排查第一步检查检索结果。把检索到的Chunk打印出来看是否包含正确答案。如果不包含说明是检索问题需要调整Chunk大小、相似度阈值或Embedding模型。第二步检查Prompt。如果检索结果包含正确答案但模型没答对说明是Prompt问题。检查Prompt模板是否清晰、是否给了模型足够的指令。第三步检查模型能力。如果Prompt没问题但回答还是不对可能是模型能力不够。换一个更强的模型试试。第四步检查文档质量。如果文档本身写得含糊不清RAG也救不了。确保文档结构清晰、信息准确。6.4 常见问题速查表问题现象可能原因解决方案启动报错NoSuchBean依赖版本不兼容检查Spring AI和Spring Boot版本调用模型返回401API Key配置错误检查api-key和base-url检索结果不相关Chunk太大或阈值太低调小Chunk调高阈值回答“不知道”检索不到相关内容调低阈值增加K值响应超时模型调用慢设置超时和重试用流式调用内存溢出上下文太长限制历史消息数量压缩上下文7. 进阶方向从RAG到真正的Agent7.1 Tool Calling让Agent动起来RAG只是让模型“知道更多”Tool Calling才是让模型“能做更多”。Spring AI的Tool Calling用起来很简单定义一个Java方法加上Tool注解注册到ChatClient里。Component public class OrderTools { Tool(description 根据订单号查询订单状态) public String queryOrderStatus(String orderId) { // 实际查询逻辑 return 订单已发货; } }模型在对话中会自动识别需要调用这个工具并传入参数。这个机制让Agent能接入现有系统真正产生业务价值。7.2 多Agent协作复杂任务的拆解单个Agent能力有限复杂任务需要多个Agent协作。比如一个客服系统可以有“意图识别Agent”“知识检索Agent”“工单创建Agent”“回复生成Agent”各司其职。LangChain4j对多Agent协作的支持更好一些有Agent接口和AgentExecutor。Spring AI目前需要自己实现编排逻辑但用Spring的依赖注入和事件机制也能做。7.3 可观测性与生产化Agent上生产可观测性是关键。需要监控的指标包括模型调用延迟、Token消耗、检索命中率、工具调用成功率、用户满意度。Spring AI集成了Micrometer可以很方便地接入Prometheus和Grafana。LangChain4j也有类似的监控接口。我现在的项目用Micrometer Prometheus Grafana做监控能实时看到每个环节的耗时和成功率。7.4 学习路线总结最后给一个简化的学习路线供参考第1-2周Spring AI官方文档 跑通基础Demo理解ChatClient、Prompt、Advisor。第3-4周LangChain4j文档 示例项目理解RAG和Agent的概念。第5-6周动手做一个RAG项目从文档处理到检索到生成完整走一遍。第7-8周加入Tool Calling让Agent能调用外部系统。第9-10周优化性能加监控准备上生产。这个路线是我自己走过的不一定适合所有人但大方向应该没问题。关键是不要只看不练每学一个概念就动手写代码验证。Agent开发是一个实践性很强的领域看十篇教程不如自己写一个Demo。我在实际项目中发现Javaer转Agent最大的障碍不是技术难度而是思维方式的转变。从确定性的CRUD逻辑到概率性的模型输出需要适应“不完美”的结果。但一旦跨过这个坎你会发现Java的工程能力在Agent落地时是巨大的优势。