Java开发者AI转型指南：Spring AI与LangChain4j实战RAG与Agent

1. 从写业务代码到调模型Java 开发者切入 AI 的真实路径写了五六年 Spring BootCRUD 写得飞起微服务拆分、消息队列、分布式事务都能搞定结果一看招聘市场AI 工程师的岗位薪资翻了一倍不止。更让人焦虑的是打开技术社区满屏都是 Python 的教程、LangChain 的示例、PyTorch 的文档好像 Java 开发者天生就跟 AI 无缘。我身边不少做 Java 的朋友都在问同一个问题我到底要不要转 Python转了之后之前积累的工程能力是不是全废了这个问题的答案其实很明确不需要转 PythonJava 开发者有自己切入 AI 的完整路径。而且从工程落地的角度看Java 开发者在构建企业级 AI 应用时反而有独特的优势——你懂事务、懂并发、懂服务治理、懂可观测性这些东西在把 AI 能力集成到真实业务系统时比会写几行 PyTorch 重要得多。我自己是从 2023 年底开始系统性地把 AI 能力往 Java 技术栈里搬的踩了不少坑也摸索出了一条相对清晰的路线。这篇文章就是把这套路线图完整地拆开讲——从需要补哪些 AI 基础概念到 Spring AI 和 LangChain4j 这两个核心框架怎么选、怎么用再到 RAG 知识库的搭建、Agent 的开发、以及最终怎么把 AI 能力集成到 Spring Boot 项目里。适合有 Java 基础、想往 AI 方向靠但不知道从哪下手的开发者也适合已经在做 AI 集成但想系统梳理一下技术栈的工程师。先说一个核心判断Java 开发者的 AI 入门重点不在训练模型而在应用集成。你不需要去搞模型微调、分布式训练这些事那是算法团队的工作。你需要掌握的是怎么调用大模型 API、怎么构建 RAG 检索增强生成链路、怎么用 Agent 编排复杂任务、怎么把这些能力封装成稳定的服务。这个定位想清楚了后面的学习路径就清晰了。2. 动手之前先想清楚Java AI 开发到底在做什么2.1 大模型应用开发的三层分工在聊具体技术之前有必要先把大模型应用开发的分工讲清楚。整个领域大致可以分成三层第一层是模型层负责预训练、微调、推理优化主要用 Python 和 PyTorch/JAX 这些工具参与者是算法工程师和研究员。这一层跟绝大多数 Java 开发者没关系。第二层是应用层负责把大模型能力接入业务系统包括 Prompt 工程、RAG 检索增强、Agent 任务编排、Function Calling 工具调用等。这一层是 Java 开发者的主战场核心框架就是 Spring AI 和 LangChain4j。第三层是基础设施层负责模型部署、向量数据库、推理服务网关等Java 开发者也可以参与比如用 Spring Boot 封装模型推理服务、做多模型路由网关等。大部分 Java 开发者应该把精力放在第二层和第三层。我见过不少人一上来就去啃 Transformer 原理、注意力机制公式啃了两个月发现还是不知道怎么把 AI 接进项目里这就是方向搞错了。先会用再理解原理这个顺序对工程背景的人更友好。2.2 Java 做 AI 集成的独特优势为什么我说 Java 开发者在 AI 应用层有优势因为真实的企业级 AI 应用难点从来不是调通模型 API而是稳定性模型 API 会超时、会限流、会返回格式错误你需要重试、熔断、降级这些是 Java 微服务的强项数据一致性RAG 场景下向量库和业务库的数据要同步文档更新后向量要重建这涉及分布式事务和最终一致性Java 开发者天天在处理可观测性AI 链路的耗时、Token 消耗、检索命中率都需要监控Micrometer Prometheus 这套东西 Java 生态最成熟并发与资源管理大模型调用是 IO 密集型操作线程池怎么配、连接怎么复用、背压怎么处理这些都是 Java 开发者的日常所以不要觉得自己在 AI 时代落伍了。你缺的只是 AI 领域的那几个核心概念和框架用法工程能力反而是你的护城河。2.3 需要补的 AI 基础概念清单不用学太多下面这几个概念搞懂了就能开始干活概念一句话解释在 Java AI 开发中的作用Token模型处理文本的最小单位约等于 0.75 个英文单词或 1-2 个汉字计费依据、上下文长度限制的判断标准Embedding把文本转成高维向量语义相近的文本向量距离近RAG 检索的基础向量数据库存储的就是它Prompt发给模型的指令文本决定模型输出质量的关键需要反复调试RAG检索增强生成先从知识库检索相关内容再让模型回答解决模型幻觉和私有知识问题的主流方案Agent能自主规划、调用工具、多步推理的 AI 程序处理复杂任务比如自动查数据库、调 APIFunction Calling模型根据用户意图决定调用哪个函数Agent 的基础能力让模型能操作外部系统向量数据库专门存储和检索向量的数据库RAG 的核心组件常用有 Milvus、PgVector、Redis这些概念不需要深究数学原理知道它们是什么、解决什么问题、怎么在代码里用就行。我建议的学习方式是边写代码边查概念遇到不懂的再回去补比系统性地啃教材效率高得多。3. 框架选型Spring AI 和 LangChain4j 到底怎么选3.1 两个框架的定位差异Java 生态里做 AI 集成目前主流就是 Spring AI 和 LangChain4j 两个框架。很多人纠结选哪个我的建议是先搞清楚它们的定位差异Spring AI是 Spring 官方团队推出的项目设计哲学跟 Spring 一脉相承——约定优于配置、依赖注入、自动装配。如果你已经在用 Spring Boot集成 Spring AI 几乎是零成本加个 starter 依赖配一下 API Key 就能用。它的优势是跟 Spring 生态无缝集成事务、安全、监控这些都能直接复用。LangChain4j是社区驱动的项目灵感来自 Python 的 LangChain功能更丰富、更灵活。它的优势在于 AI 特有的抽象做得更细比如 ChatMemory、DocumentSplitter、EmbeddingStore、AiServices 这些覆盖的场景更全。特别是 Agent 和 RAG 方面LangChain4j 的 API 设计更成熟。我自己的做法是简单集成用 Spring AI复杂 AI 链路用 LangChain4j。两个框架并不冲突可以在同一个项目里共存。3.2 核心 API 对比拿最基础的对话功能举例两个框架的写法差异很明显。Spring AI 的写法RestController public class ChatController { private final ChatClient chatClient; public ChatController(ChatClient.Builder builder) { this.chatClient builder.build(); } GetMapping(/chat) public String chat(RequestParam String message) { return chatClient.prompt() .user(message) .call() .content(); } }LangChain4j 的写法interface Assistant { String chat(String message); } Assistant assistant AiServices.builder(Assistant.class) .chatLanguageModel(model) .build(); String answer assistant.chat(你好);Spring AI 更符合 Spring 开发者的直觉LangChain4j 的 AiServices 则更像在定义一个远程服务接口声明式风格更强。3.3 选型决策表维度Spring AILangChain4j官方支持Spring 官方社区驱动Spring Boot 集成原生无缝需要手动配置RAG 支持基础功能齐全更丰富支持多种检索策略Agent 支持较新功能在完善成熟支持工具调用和编排学习曲线低Spring 开发者友好中等概念较多版本稳定性1.0 已 GA迭代快API 偶有变动适用场景企业级集成、快速落地复杂 AI 链路、实验性项目我的实际经验是新项目如果只是做对话、简单 RAG直接上 Spring AI如果要做多轮 Agent、复杂检索策略、多模型路由LangChain4j 更合适。另外要注意版本Spring AI 1.0 之后 API 稳定了很多LangChain4j 建议锁定版本号避免升级踩坑。3.4 模型接入的现实考量不管用哪个框架模型接入都是绕不开的。目前主流选择有几类云端 APIOpenAI、Claude、通义千问、DeepSeek 等接入简单按 Token 计费本地部署通过 Ollama 跑 Llama、Qwen 等开源模型数据不出内网适合敏感场景混合模式简单任务走本地小模型复杂任务走云端大模型平衡成本和效果Spring AI 和 LangChain4j 都支持这些接入方式。我建议开发阶段用云端 API 快速验证生产环境根据数据敏感度和成本预算决定。本地部署的话Ollama 是最省事的方案一条命令就能跑起来Java 侧通过 HTTP 接口调用即可。4. RAG 知识库从文档到可检索的向量库4.1 RAG 到底解决了什么问题大模型有两个硬伤一是知识截止训练数据之后的事情它不知道二是幻觉不知道的事情它会编。RAG 就是来解决这两个问题的——先从你的私有知识库里检索相关内容把检索结果作为上下文塞进 Prompt让模型基于这些内容回答。举个实际场景你公司有一堆产品文档、FAQ、历史工单想让 AI 客服能准确回答用户问题。直接问大模型它不知道你公司的产品细节只能瞎编。用 RAG先把用户问题转成向量去向量库里检索最相关的文档片段再把片段和问题一起发给模型模型就能基于真实文档回答了。RAG 的核心流程是文档加载 → 文本切分 → 向量化 → 存储 → 检索 → 增强生成。每一步都有讲究下面逐个拆。4.2 文档切分的策略选择文本切分看着简单实际上对检索效果影响巨大。切得太碎语义不完整切得太大检索精度下降。常见的策略有固定长度切分按字符数或 Token 数切简单粗暴适合格式统一的文档递归切分按段落、句子、字符逐级切分尽量保持语义完整LangChain4j 的DocumentSplitters.recursive()就是这种语义切分用模型判断语义边界效果最好但成本高结构化切分针对 Markdown、HTML、代码等有结构的文档按标题层级切我的经验是大部分场景用递归切分就够了chunk size 设 500-800 Tokenoverlap 设 50-100 Token。overlap 的作用是防止关键信息刚好被切在边界上导致丢失。如果是技术文档按标题层级切效果更好因为每个章节本身就是语义完整的单元。DocumentSplitter splitter DocumentSplitters.recursive(800, 100); ListTextSegment segments splitter.split(document);4.3 向量化与存储的实操细节切分完之后要转成向量。Embedding 模型的选择很关键它直接决定检索质量。常见的有 OpenAI 的 text-embedding-3-small、BGE 系列、通义千问的 embedding 模型等。选型时关注两个指标向量维度和检索准确率。维度越高表达能力越强但存储和计算成本也越高。向量数据库的选择数据库特点适用场景PgVectorPostgreSQL 扩展跟业务库共用已有 PG数据量中等Milvus专业向量库性能强大规模向量检索Redis内存存储速度快实时性要求高数据量可控Chroma轻量级易上手开发和原型阶段Elasticsearch支持混合检索已有 ES需要全文向量混合我一般推荐PgVector因为大部分 Java 项目本来就有 PostgreSQL加个扩展就能用省去维护独立向量库的成本。数据量上千万级别再考虑 Milvus。4.4 检索策略从朴素检索到混合检索最简单的检索就是向量相似度搜索取 Top-K 个最相似的片段。但实际用下来纯向量检索有几个问题对关键词不敏感、对专有名词效果差、容易召回语义相近但实际不相关的内容。改进方案有几种混合检索向量检索 关键词检索BM25结果融合。对专有名词和精确匹配场景效果好很多重排序先召回较多候选比如 20 个再用重排序模型精排取 Top-5。能显著提升精度查询改写用户问题往往口语化先用模型改写成更适合检索的形式多路召回从不同角度生成多个查询分别检索后合并LangChain4j 对这些策略支持比较完善Spring AI 的基础检索够用但高级策略需要自己实现。我实测下来混合检索 重排序的组合能把检索命中率从 60% 左右提升到 85% 以上值得投入。4.5 一个完整的 RAG 代码骨架用 LangChain4j 搭一个最小可用的 RAG// 1. 加载文档 Document document FileSystemDocumentLoader.loadDocument( Paths.get(/docs/product-manual.md)); // 2. 切分 DocumentSplitter splitter DocumentSplitters.recursive(800, 100); ListTextSegment segments splitter.split(document); // 3. 向量化并存储 EmbeddingModel embeddingModel new AllMiniLmL6V2EmbeddingModel(); EmbeddingStoreTextSegment store new InMemoryEmbeddingStore(); EmbeddingStoreIngestor ingestor EmbeddingStoreIngestor.builder() .embeddingModel(embeddingModel) .embeddingStore(store) .build(); ingestor.ingest(segments); // 4. 构建检索增强的对话服务 ContentRetriever retriever EmbeddingStoreContentRetriever.builder() .embeddingStore(store) .embeddingModel(embeddingModel) .maxResults(5) .minScore(0.7) .build(); Assistant assistant AiServices.builder(Assistant.class) .chatLanguageModel(chatModel) .contentRetriever(retriever) .build(); // 5. 提问 String answer assistant.chat(产品支持哪些支付方式);这段代码跑通之后你就有了一个能基于私有文档回答问题的 AI 服务。生产环境把 InMemoryEmbeddingStore 换成 PgVector 或 Milvus加上文档更新时的增量索引逻辑即可。5. Agent 开发让 AI 能调用你的 Java 方法5.1 Agent 和普通对话的本质区别普通对话是你问我答Agent 是你给目标它自己规划步骤并执行。区别在于 Agent 能调用工具Function Calling、能做多步推理、能根据中间结果调整策略。举个例子用户问帮我查一下上个月销售额最高的产品然后看看它的库存够不够。普通对话模型只能瞎编Agent 可以第一步调用销售查询接口拿到数据第二步调用库存查询接口第三步综合两个结果给出回答。这就是 Agent 的价值。5.2 Function Calling 的实现方式LangChain4j 里定义工具非常简单用注解就行public class SalesTools { Tool(查询指定月份的销售额最高的产品) public String topProduct(P(月份格式 yyyy-MM) String month) { // 实际查询数据库 return 产品A销售额 120 万; } Tool(查询指定产品的库存数量) public int stock(P(产品名称) String productName) { // 实际查询库存系统 return 350; } } Assistant assistant AiServices.builder(Assistant.class) .chatLanguageModel(chatModel) .tools(new SalesTools()) .build();模型会根据用户问题自动决定调用哪个工具、传什么参数。你只需要把业务方法用Tool注解暴露出去剩下的交给框架。5.3 Agent 编排的常见模式实际项目里 Agent 的编排模式主要有几种ReAct 模式推理-行动循环模型先思考需要做什么调用工具观察结果再思考下一步。适合探索性任务Plan-and-Execute先制定完整计划再逐步执行。适合步骤明确的复杂任务多 Agent 协作多个 Agent 各司其职比如一个负责检索、一个负责计算、一个负责汇总LangChain4j 对 ReAct 模式支持最好其他模式需要自己组合。我的建议是先从单 Agent 几个工具开始跑通了再考虑复杂编排。很多场景其实单 Agent 就够了多 Agent 反而增加调试难度。5.4 Agent 开发中最容易踩的坑说几个我实际踩过的坑工具描述写得太模糊。模型靠工具描述来决定调不调用、怎么调用。描述写查询数据模型根本不知道查什么数据要写根据产品名称查询当前库存数量返回整数。工具返回值太大。如果工具返回几千字的文本会迅速消耗上下文窗口还会干扰模型判断。工具返回值要精简只返回关键信息。没有设置最大迭代次数。Agent 可能陷入循环反复调用同一个工具。一定要设置最大步数限制比如 10 步超过就强制结束。错误处理不完善。工具调用失败时要把错误信息返回给模型让它决定是重试还是换方案而不是直接抛异常中断整个流程。6. 把 AI 能力集成进 Spring Boot 项目6.1 集成架构的设计思路AI 能力集成到现有 Spring Boot 项目核心原则是解耦。不要把 AI 调用逻辑散落在各个 Service 里而是封装成独立的模块通过接口对外暴露。这样模型切换、Prompt 调整、降级策略都不会影响业务代码。我通常的架构是ai-core 模块封装模型客户端、Prompt 模板、RAG 检索、Agent 编排ai-api 模块定义对外的 AI 服务接口业务模块通过接口调用 AI 能力不关心底层实现这样业务代码里只有aiService.answer(question)这样的调用底层用 Spring AI 还是 LangChain4j、用哪个模型业务方完全无感。6.2 配置管理与多环境适配AI 相关的配置项比较多API Key、模型名称、超时时间、重试次数、向量库连接等。建议用ConfigurationProperties统一管理ConfigurationProperties(prefix app.ai) Data public class AiProperties { private String provider; private String apiKey; private String model; private Duration timeout Duration.ofSeconds(30); private int maxRetries 3; private RagConfig rag new RagConfig(); }不同环境用不同的配置文件开发环境可以用本地 Ollama生产环境用云端 API。API Key 绝对不能硬编码走配置中心或环境变量。6.3 稳定性保障重试、熔断、降级模型 API 的不稳定性远超普通 HTTP 服务必须做好防护重试网络抖动、限流导致的失败可以重试但要注意幂等性。用 Spring Retry 或 Resilience4j 配置指数退避。熔断连续失败达到阈值就熔断避免雪崩。Resilience4j 的 CircuitBreaker 很好用。降级模型不可用时返回兜底答案比如当前 AI 服务繁忙请稍后再试或走规则引擎。超时控制大模型响应可能很慢必须设置合理超时。流式输出场景要单独处理。Bean public ChatClient chatClient(ChatClient.Builder builder, AiProperties props) { return builder .defaultOptions(ChatOptions.builder() .model(props.getModel()) .timeout(props.getTimeout()) .build()) .build(); }6.4 可观测性监控什么指标AI 服务的监控跟普通服务不太一样除了常规的 QPS、延迟、错误率还要关注Token 消耗按模型、按接口统计直接关系到成本检索命中率RAG 场景下检索到的内容是否真的被用上了首 Token 延迟流式输出场景下用户体验的关键指标Prompt 长度分布异常长的 Prompt 可能意味着上下文管理有问题这些指标通过 Micrometer 埋点Prometheus 采集Grafana 展示。我一般会做一个 AI 服务专属的 Dashboard把上面这些指标都放上去。6.5 成本控制的几个实用手段Token 就是钱成本控制是绕不开的。几个有效的手段缓存相同或相似的问题直接返回缓存结果用语义缓存效果更好模型分级简单问题用小模型复杂问题才用大模型Prompt 精简去掉冗余的指令和示例能省不少 Token上下文裁剪多轮对话时只保留最近几轮或者做摘要压缩流式输出虽然不省 Token但能提升用户体验让用户感觉更快我实测下来加上语义缓存和模型分级之后整体成本能降 40% 左右。7. 学习路线与资源推荐7.1 分阶段的学习路径根据我带团队的经验Java 开发者入门 AI 可以分三个阶段第一阶段1-2 周搞懂核心概念跑通第一个 Demo。用 Spring AI 或 LangChain4j 接一个云端模型实现一个简单的对话接口。这个阶段的目标是建立信心知道 AI 集成没那么神秘。第二阶段3-4 周深入 RAG。搭一个本地知识库把公司文档灌进去实现基于文档的问答。这个阶段会遇到切分策略、检索精度、幻觉处理等实际问题是成长最快的阶段。第三阶段1-2 个月Agent 和工程化。实现 Function Calling让 AI 能调用业务接口把 AI 能力封装成稳定的服务加上重试、熔断、监控、成本控制。这个阶段完成后你就具备了独立负责 AI 应用开发的能力。7.2 值得投入的学习资源Spring AI 官方文档虽然还比较新但示例代码质量高跟着敲一遍就能上手LangChain4j 官方文档和 Examples 仓库RAG 和 Agent 的示例很全直接抄改就能用Ollama 官方文档本地跑模型的最简方案零基础也能搞定各大模型厂商的 API 文档了解不同模型的参数和限制对选型有帮助不建议一上来就看论文和数学推导那是第二阶段之后的事情。先把应用跑起来有了体感再深入原理。7.3 几个容易走弯路的地方最后说几个我见过很多人踩的坑盲目追求最新模型。新模型不一定适合你的场景而且 API 可能不稳定。生产环境选成熟稳定的版本。忽视 Prompt 工程。很多人觉得 Prompt 就是随便写写实际上同样的模型Prompt 优化前后效果差距巨大。花时间打磨 Prompt 是值得的。不做评估就上线。AI 应用的效果很难用传统测试覆盖需要建立评估集定期跑回归测试。没有评估就没有优化方向。低估数据质量的重要性。RAG 的效果上限取决于知识库的质量。文档格式混乱、内容过时、重复冗余再好的检索策略也救不回来。忽略安全合规。用户输入可能包含敏感信息模型输出可能不合规这些都需要在架构层面考虑过滤和审核机制。我自己从 Java 后端转到 AI 应用开发最大的体会是工程能力是底座AI 能力是增量。你不需要推翻过去积累的一切只需要在原有的技术栈上叠加 AI 这一层。Spring AI 和 LangChain4j 这两个框架本质上就是把 AI 能力包装成了 Java 开发者熟悉的形式——依赖注入、接口抽象、配置管理。用你已有的工程思维去理解它们上手会比想象中快得多。真正需要花时间的是对 AI 应用特有问题的理解检索质量怎么评估、Prompt 怎么迭代、Agent 怎么调试、成本怎么控制。这些东西没有捷径只能在项目里一个个踩过来。