1. 整合方案与前置思路1.1 为什么要用Spring整合LangChain4j先聊点实际的。如果你是Java后端开发者业务系统里想接入大模型能力比如让用户用自然语言查数据、让系统自动生成报告、做一个带记忆的智能客服那你大概率会遇到一个选择直接调HTTP接口还是引入一个专门做LLM集成的框架直接调接口看起来最省事写个工具类封装一下请求解析一下返回完事。但项目一旦复杂起来痛点会特别明显上下文管理要自己写、模型厂商切换要改代码、结构化输出要手撸JSON解析、多轮对话记忆得自己维护更别说工具调用这种复杂交互逻辑了。写到最后你会发现自己其实在重复造轮子而且造得还不一定好。LangChain4j就是来解决这个问题的。它是Java生态里的一套LLM集成框架参考了Python生态里LangChain的设计思路但又不是简单照搬——它在Java的语言习惯上做了很多适配比如用接口声明式地定义AI服务、用注解配置提示词模板、原生支持Spring Boot的starter方式接入。它的核心价值在于把和大模型打交道那些杂活对话、记忆、工具调用、RAG检索、输出解析、多模型切换全部封装好让Java开发者用自己熟悉的方式去写AI功能。在Spring的体系里整合LangChain4j优势就更明显了。Spring本身的依赖注入、配置管理、AOP、事务这些能力加上LangChain4j的LLM抽象能力组合起来之后你可以做到在大模型对接这一层的配置全部外置化业务代码里不需要写死任何一个模型参数想换模型就改配置文件。同时整个AI服务模块可以像普通Spring服务一样被管理和测试这对那种已经在用Spring Boot做微服务的团队来说几乎是无缝接入。1.2 这个整合适合什么场景我实际做过不少项目总结下来Spring LangChain4j这套组合最适用的场景有这几类第一类是智能客服和问答系统。Spring Boot做Web服务天然顺手加一个AI服务层处理语义理解和答案生成整个链路非常顺。配合LangChain4j的消息记忆能力可以做出上下文连贯的对话体验。第二类是业务数据智能查询。把数据库schema、业务文档灌给模型用自然语言对话的方式查询数据或者生成报表。这块LangChain4j的RAG检索增强生成链路帮助很大我自己用它对过几千页的内部文档召回效果和准确性比直接硬问模型好很多。第三类是内容生成和处理类工具。比如自动生成商品描述、新闻摘要聚合、邮件起草。这种需求往往是后端的定时任务或者接口服务天然长在Spring生态里。第四类是带工具调用的Agent类应用。比如让模型自己决定调用查询订单的接口然后根据结果回答用户问题。LangChain4j对Tool Calling的支持比较成熟Spring里只要把Bean方法暴露给模型就行这个后面我会细讲。如果你是做Python的可能觉得LangChain那一套更熟但目前Java技术栈里要做LLM集成LangChain4j这块确实没什么对手。结合Spring Boot来承接Web层、管理生命周期这套方案在老牌的Java团队落地的难度是最低的。2. 环境准备与依赖配置2.1 Spring Boot版本与JDK选型先说版本。LangChain4j本身对Spring Boot的版本有要求目前主流的1.x版本支持Spring Boot 3.x系列我自己用的是Spring Boot 3.2.x配JDK 17实测下来很稳。JDK 17已经不是可选项而是默认项了Spring Boot 3.x在class文件版本上强制要求JDK 17起跳这个要注意。如果你还在JDK 8上那基本只能放弃这个方案或者考虑先用Spring Boot 2.x过渡但LangChain4j的官方Spring Boot starter大多绑定3.x硬要搞的话就得自己写自动装配了不太推荐。Maven项目的话在pom.xml里加上Spring Boot父依赖然后是LangChain4j的starter。我的做法是在dependencyManagement里统一管理版本避免子模块版本漂移。parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.2.5/version relativePath/ /parent properties java.version17/java.version langchain4j.version1.0.0-beta1/langchain4j.version /properties dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-spring-boot-starter/artifactId version${langchain4j.version}/version /dependency !-- 这里根据你实际用的模型厂商选一个后面细说 -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-open-ai/artifactId version${langchain4j.version}/version /dependency /dependencies如果用的是国内可以直连的模型厂商比如对接OpenAI兼容接口的中转服务或者国产大模型的OpenAI兼容模式就把对应的依赖拉进来。LangChain4j对OpenAI兼容接口的支持很友好大部分时候不需要额外开发。2.2 关键配置项逐项解释配置上老规矩放在application.yml里。我习惯把所有模型相关配置集中在一个前缀下方便后期统一调整。langchain4j: open-ai: model-name: gpt-4o-mini api-key: ${OPENAI_API_KEY:sk-xxx} base-url: ${OPENAI_BASE_URL:https://api.openai.com} temperature: 0.7 timeout: 60s max-tokens: 2048如果你用别的模型比如国内某家的OpenAI兼容接口那base-url改成对方提供的网关地址就行apikey换成你自己的。temperature建议在0.3到0.8之间选做问答任务我一般取0.5需要创造性的内容生成调到0.8要求结果稳定的话调到0.2以下。还有一个很关键的配置langchain4j.open-ai.log-requests和log-responses这两个开关默认是false我强烈建议调试阶段打开。开了之后控制台会打印完整的请求体、响应体模型到底收到了什么、返回了什么一目了然。排查问题的时候你就会知道这个开关有多救命。langchain4j: open-ai: log-requests: true log-responses: true注意日志级别要是DEBUG否则可能不输出。这个我踩过坑配置对了但看不到日志最后发现是logback的level没放出来。2.3 为什么建议先用Beta版本LangChain4j的版本迭代很快0.x到1.0.0-beta1我都在用。早期版本API变动比较频繁类和方法的命名会有调整网上教程不一定对得上你本地版本的情况。如果你照着文档写、发现编译不过大概率不是代码写错而是版本API变化。我建议直接上最新的beta版API相对稳定且功能全社区活跃度也高。还有一个点LangChain4j的starter包名跟旧版本不一样老教程里有的写langchain4j-spring-boot-starter有的写langchain4j-spring不同小版本下包名有变动。建议以你实际拉下来的依赖为准通过IDE查看依赖树别死磕教程。3. 核心功能开发与Spring整合细节3.1 用AiService注解定义AI接口LangChain4j整合Spring之后最有代表性的一个能力就是AiService注解。它让你声明一个接口框架自动帮你生成实现类方法上只要定义好提示词模板和参数剩下的调用模型、解析输出全部交给框架。举个例子我要做一个旅游推荐助手AiService public interface TravelAssistant { SystemMessage(你是一个专业的旅行规划顾问请根据用户的偏好给出合理的推荐方案语言风格友好且简洁。) UserMessage(我想去{{place}}旅行偏好{{preference}}预算大概是{{budget}}请给我一个三日游的行程建议。) String recommend(V(place) String place, V(preference) String preference, V(budget) String budget); }这个接口不用写实现类。Spring启动的时候LangChain4j会自动扫描带有AiService的接口生成动态代理实现注入到容器里。你用的时候直接注入接口就行RestController public class TravelController { private final TravelAssistant travelAssistant; public TravelController(TravelAssistant travelAssistant) { this.travelAssistant travelAssistant; } GetMapping(/recommend) public String recommend(RequestParam String place, RequestParam String preference, RequestParam String budget) { return travelAssistant.recommend(place, preference, budget); } }我用生活化的方式解释一下SystemMessage和UserMessage的区别SystemMessage是给模型设定的角色和规矩——相当于你上岗前公司发的《员工手册》里面写着“你是谁、什么话能说什么话不能说”UserMessage就是用户具体的问题——相当于用户实际向你提的需求中间留了{{变量}}的占位符运行时替换成真实参数。这里有个实用技巧SystemMessage不只是写角色还可以把业务规则塞进去。比如客服场景下把售后政策、回复规范都写进去模型回答时会严格遵循这些规则比后制裁剪输出自然多了。3.2 ChatMemory让AI记住上下文多轮对话的本质是历史消息的管理。LangChain4j提供了ChatMemory接口几种实现可以选择。我实际最常用的是MessageWindowChatMemory——它像一个滑动窗口只保留最近N条消息防止上下文无限膨胀导致Token超限。在Spring里注册一个Bean给AiService用Configuration public class AssistantConfig { Bean ChatMemory chatMemory() { return MessageWindowChatMemory.withMaxMessages(20); } }然后在AiService上通过chatMemory属性绑定AiService(chatMemory chatMemory) public interface ChatAssistant { UserMessage({{message}}) String chat(V(message) String userMessage); }这里chatMemory对应的是Spring容器里的Bean名称。框架会在每次方法调用时自动把历史消息和当前输入拼在一起发给模型模型回答之后再自动把这段交互存入记忆。不过要特别提醒这个ChatMemory是单例的意味着所有用户共用一份记忆。实际项目里肯定不行你得自己按会话维度管理记忆对象。我做过的一个方案是用Map缓存每个会话ID对应的ChatMemory实例会话结束时清理并且加上过期时间防止内存泄漏。Component public class SessionMemoryManager { private final MapString, ChatMemory memoryMap new ConcurrentHashMap(); public ChatMemory getMemory(String sessionId) { return memoryMap.computeIfAbsent(sessionId, k - MessageWindowChatMemory.withMaxMessages(20)); } public void clear(String sessionId) { memoryMap.remove(sessionId); } }对应地AiService接口的方法上手动传入一个ChatMemory参数框架会优先使用方法参数里的实例而不是Bean里那个共享的。3.3 Function Calling把Spring Bean方法暴露给模型这是LangChain4j真正拉开体验差距的地方。它的基本原理是给模型描述一组Java方法的存在模型在回答过程中如果需要调用外部能力比如查数据库、验库存、下发指令它会先请求调用这个方法框架把这个请求分发到Spring容器里的实际方法上执行然后把结果返回给模型模型基于结果继续组织回答。整个交互是循环的对开发者来说你不需要写循环逻辑框架全包了。在Spring里定义一个Bean方法加上Tool注解Component public class OrderTools { Tool(根据订单号查询订单状态) public String queryOrderStatus(String orderId) { // 调用订单服务查库 return orderService.getStatusByOrderId(orderId); } Tool(根据用户ID查询最近订单金额) public BigDecimal getRecentOrderAmount(String userId) { return orderService.getRecentAmount(userId); } }然后在AiService接口上声明使用哪些工具AiService public interface CustomerServiceAssistant { SystemMessage(你是电商平台的客服助手请根据工具返回的订单数据回答用户问题不要臆造信息。) UserMessage({{message}}) String chat(V(message) String userMessage); }启动之后框架会自动扫描容器中带Tool注解的方法并把它们注册给模型。用户如果问“帮我查一下订单20240813001的物流状态”模型会解析出意图调用queryOrderStatus方法返回结果后又把自然语言的回答输出出来。这里有个经验之谈Tool方法的描述信息一定要写得详实清楚因为模型要依赖描述来判定“这个问题该不该调用这个方法、应该传什么参数”。描述模糊的话模型要么不调要么参数传错。一个好的工具描述应该包含方法用途、参数含义、返回值含义。我见过最坑的情况是一个方法叫query()描述就写“查询”模型完全不知道它能干什么最后干脆不调用直接编答案。3.4 RAG检索增强让模型基于你的知识库说话RAG检索增强生成听起来玄乎核心就是三件事把文本切碎、向量化入库、用户提问时先检索最相关的片段再交给模型生成。LangChain4j对这段流程封装得很完善Spring整合更是把整条链路变成了几个Bean的事。第一步准备嵌入模型。我用的是OpenAI兼容的嵌入接口langchain4j: open-ai: embedding-model-name: text-embedding-3-small第二步定义一个EmbeddingStore用来存向量。生产环境建议用专业的向量数据库本地开发可以直接用内存版Configuration public class EmbeddingStoreConfig { Bean EmbeddingStoreTextSegment embeddingStore() { return new InMemoryEmbeddingStore(); } }第三步把文档灌进去。这一步通常是离线执行的比如服务启动时读取一个目录下的所有文本文件Component public class KnowledgeBaseInitializer { private final EmbeddingStoreTextSegment embeddingStore; private final EmbeddingModel embeddingModel; public KnowledgeBaseInitializer(EmbeddingStoreTextSegment embeddingStore, EmbeddingModel embeddingModel) { this.embeddingStore embeddingStore; this.embeddingModel embeddingModel; } PostConstruct public void init() { // 读取resources/docs下的所有txt文件 // 每个文件按固定大小切段向量化后存入store } }第四步在AiService中启用RAGAiService public interface KnowledgeAssistant { UserMessage(请基于检索到的资料回答{{message}}) RetrievalRetriever(store embeddingStore) String answer(V(message) String message); }RetrievalRetriever这个注解会触发检索逻辑用户问题向量化在store里做相似度检索取top-3的片段拼进上下文然后模型基于这些片段来回答问题。RAG这个过程中最影响效果的是切段策略。切块太大检索不精准模型会被无关内容干扰切块太小上下文信息不完整答案可能残缺。文本类内容我一般取300到500个字符一段并带有一定的重叠区域这样既能保证语义完整又不会让上下文超长。具体数值要根据你的文档风格来调法律合同类的句子长段落大切法就要相应调整。4. 完整实操从零写一个知识库问答接口4.1 搭建项目骨架这个环节我们从头到尾走一遍。假设你要做一个内部IT运维知识库的问答接口员工提问“打印机连不上怎么办”或“VPN账号怎么申请”接口返回运维手册中的对应内容。第一步在start.spring.io初始化一个Spring Boot项目Java 17依赖选择Spring Web和Spring Boot Actuator调试方便然后手动加入LangChain4j相关的依赖。第二步写配置类把上面提到的ChatMemory、EmbeddingStore、EmbeddingModel这些Bean配置好。第三步写文档加载的工具类。我实际项目里常用的方式是用一个简单的文本读取器Component public class DocsLoader { Value(${knowledge.docs-path:classpath:docs}) private String docsPath; public ListTextSegment loadSegments() { ListTextSegment segments new ArrayList(); // 读取该路径下的所有.txt/.md文件 // 按段落切分保留文件名前缀作为来源标记 return segments; } }切分时保留来源标记对后面很有用模型回答时可以顺便给出“参考了哪个文档”用户对回答的信任度会高很多。4.2 实现检索增强问答核心的AiService按之前的方式定义好写一个Controller暴露HTTP接口RestController RequestMapping(/api/assistant) public class AssistantController { private final KnowledgeAssistant assistant; private final SessionMemoryManager memoryManager; public AssistantController(KnowledgeAssistant assistant, SessionMemoryManager memoryManager) { this.assistant assistant; this.memoryManager memoryManager; } PostMapping(/query) public Result query(RequestBody QueryRequest request) { String sessionId request.getSessionId(); ChatMemory memory memoryManager.getMemory(sessionId); String answer assistant.answer(request.getQuestion(), memory); return Result.ok(answer); } }这段代码里有一个细节值得注意我把ChatMemory作为参数传给了assistant.answer()。当方法参数中出现ChatMemory类型时LangChain4j会优先使用这个参数而不是接口默认绑定的Bean。这是实现多会话隔离的关键点。然后验证整个链路启动应用确认日志中显示模型连接正常。发送请求{sessionId: s001, question: 打印机无法连接网络怎么办}。观察控制台日志确认检索命中了哪些文档片段。确认模型给出了基于文档内容的回答。4.3 模拟项目X的实测指标我在模拟项目X里放了大约50份运维文档实测效果有几个数据可以给你参考普通问题首次响应的耗时大约1.8到3秒之间其中约0.3秒是文档检索剩余的是模型生成时间。取top-3片段时回答准确度明显优于只取top-1模型在回答时引用了正确的文档来源。但是当问题比较冷门、文档里没有对应信息的时候模型还是会给出泛泛的答案而不是直接承认不知道——这需要额外加约束比如在SystemMessage里写明“检索不到相关资料时明确告诉用户未收录不要猜测”。顺带提一个我踩过的坑文件编码。文档如果是GBK编码的直接读出来是乱码向量化效果也奇差。后来我统一在加载时指定UTF-8并且加载完做一个简单校验如果乱码比例过高就报警。5. 常见问题与排查技巧5.1 高频问题速查表问题现象根因解决办法依赖拉不下来或启动报NoClassDefFoundError版本冲突LangChain4j与Spring Boot版本不匹配统一用BOM管理版本查看依赖树排查冲突接口注入报找不到beanAiService接口没被扫描到确认接口所在包被Spring启动类扫描覆盖控制台没有请求日志日志级别不够logback配置里加DEBUG确认log-requests为true模型返回内容被截断max-tokens设太小调大到预期回答长度的1.5倍工具方法没有被调用Tool描述不清晰重写工具描述说清用途和参数含义多轮对话串台用了默认单例ChatMemory按会话隔离管理见上文SessionMemoryManager模型回答问题张冠李戴检索片段不相关调试检索结果调整切段大小或top-k值连接超时网络链路或timeout太小timeout调到60s起步排查网络连通性输入Token过长报错上下文窗口超限减少记忆窗口条数文档切段调小本地方向向量相似度不准嵌入模型与检索场景不匹配换嵌入模型或考虑微调/重排名5.2 定位问题的调试三板斧我排查这类问题的顺序基本是固定的。第一板斧开日志。把log-requests、log-responses打开看模型实际收到什么、返回什么。这一步能解决80%的问题。模型没调工具看日志里工具定义有没有发出去。胡说八道看SystemMessage送到没有。第二板斧查依赖树。mvn dependency:tree看一下LangChain4j相关的版本是否一致有没有被意外的依赖传递替换掉版本。版本不一致轻则API方法找不到重则运行期诡异的空指针。第三板斧最小复现。把问题从Spring环境里抽出来写一个独立的main方法直接构建模型对象发一个最简单的消息。如果能跑通说明Spring整合配置有问题如果还是不通那问题在模型配置或网络本身。5.3 生产环境的额外建议如果这个整合方案要上生产有几件事我在实际项目里都做过建议你也别省。第一API Key一定要走配置中心或环境变量不要写死在配置文件里。项目里加解密配置是常态LangChain4j本身没有密钥管理能力这块要依赖Spring的配置体系。第二对LLM接口做好限流和熔断。模型服务的稳定性远不如普通HTTP接口尤其是高峰期响应时间可能从2秒拉垮到15秒。我用过Spring的CircuitBreaker注解来包一层AiService调用效果还可以另外在网关层做简单的并发限流避免突发流量打爆模型配额。熔断的阈值我一般设成5秒内失败3次就切断恢复等待30秒。第三建议加一层缓存。同样的或者高度相似的问题完全可以让模型再答一遍但其实缓存命中率相当可观。我用简单的短文本哈希加Redis做过大概能有20%左右的命中率这些流量可以不花钱。第四监控埋点。AiService调用的成功/失败、耗时、Token消耗都可以埋出来。它和普通数据库调用没有本质区别该有的监控都要有。我自己的做法是拦截ChatLanguageModel.chat()方法在外面包一层计时器和计数器。第五内容安全问题。模型输出必须做合规过滤和审核。正规的做法是模型输出先过一层敏感词过滤再走内容审核服务。这块不要只依赖模型自己的安全对齐毕竟你无法控制所有场景和输入。6. 实操心得与后续扩展建议6.1 几个让我印象深刻的坑先说Ajax调用的并发问题。模型接口的响应耗时相比于普通HTTP接口要高一个数量级如果你在Web层没有合适的异步处理机制很可能会占满Servlet线程池。我起初没注意压测时发现Tomcat线程被模型调用占满其他请求全部排队。后来把AiService的调用放到虚拟线程里跑才算解决。Spring Boot 3.2上spring.threads.virtual.enabledtrue开一下就好没有太多额外成本。实测模型等待期间不再阻塞Web请求线程整体吞吐上了一个台阶。然后是流式输出。一开始没考虑流式所有回答都要等模型全文生成完才返回接口响应时间普遍4到8秒对用户来说体验很糟糕。后来切到流式输出用FluxString对接SSE用户感知的响应速度大幅改善。LangChain4j的StreamingChatLanguageModel接口专门干这个。如果你是面向真实用户的产品强烈建议上流式。还有一个是成本控制。RAG场景下每次对话都要传文档片段和完整历史Token消耗比单纯问答高出一截账单涨得也快。尽量控制历史轮数别无限累积文档片段在做检索之后加上一个相似度阈值过滤低于阈值的片段宁可不传。6.2 这个方案的边界在哪里得实话实说Spring整合LangChain4j不是万能的。它解决了“把LLM能力集成进Java后端”的工程化问题但以下这些场景它不算最佳解超级复杂的Agent多步骤编排LangChain4j支持Agent调用但编排逻辑还是得自己手写。如果业务逻辑是十几个工具来回调度流程分支特别多那这套方案还不如用流程引擎加规则配置来写。大规模微调训练LangChain4j本身不负责训练这块要交给专门的模型训练链路。超低延迟场景比如实时语音交互Java后端经过Spring和模型调用的开销不小如果要求端到端Latency在300ms以内这种写法可能不适合得考虑更底层的接入方式或者边缘推理。我另外要说一句的是目前LangChain4j的社区资料和教程密度还是比不上Python的LangChain很多问题需要你自己去翻GitHub源码和官方示例。但好处是代码风格贴近Spring生态遇到问题基本能在自有代码里排查不用去啃一堆陌生概念。6.3 后续可以怎么玩整合跑通之后可以做的扩展很多。最简单的在现有基础上接一个WebSocket把知识库问答变成实时聊天界面也在Spring里注册多个不同用途的AiService比如一个处理订单查询、一个处理售后回答、一个处理内容审核彼此之间完全隔离管理起来也清晰。更强一点的玩法是把LangChain4j接入到你的工作流引擎里让AI成为流程中的一个节点。比如审批流程中上一个节点填写的信息转成自然语言让AI提取成结构化字段然后继续流转。这种能力在实际业务系统里非常有价值能让复杂表单的填写体验提升一个档次。目前在AI应用开发这个领域Java生态的成熟度确实在快速追赶。像LangChain4j整合Spring这种方案最大的意义是让后端团队可以用已经得心应手的技术栈去做AI功能不需要推翻重来也不需要另起炉灶学一套全新的体系。Java开发者原来会的东西——依赖注入、Bean管理、配置外置、面向接口编程——这些能力全都保留并复用AI只是在做增量。我自己操作下来的整体感受是这套组合的学习曲线不会太陡你只需要理解模型API的基本行为模式请求什么、响应什么剩下的工程化问题Spring和LangChain4j会把绝大多数杂活处理干净。真正需要花心思的是结合自己的业务场景去设计好提示词、工具方法和检索链路让模型发挥出它该有的价值。
1. 整合方案与前置思路1.1 为什么要用Spring整合LangChain4j先聊点实际的。如果你是Java后端开发者业务系统里想接入大模型能力比如让用户用自然语言查数据、让系统自动生成报告、做一个带记忆的智能客服那你大概率会遇到一个选择直接调HTTP接口还是引入一个专门做LLM集成的框架直接调接口看起来最省事写个工具类封装一下请求解析一下返回完事。但项目一旦复杂起来痛点会特别明显上下文管理要自己写、模型厂商切换要改代码、结构化输出要手撸JSON解析、多轮对话记忆得自己维护更别说工具调用这种复杂交互逻辑了。写到最后你会发现自己其实在重复造轮子而且造得还不一定好。LangChain4j就是来解决这个问题的。它是Java生态里的一套LLM集成框架参考了Python生态里LangChain的设计思路但又不是简单照搬——它在Java的语言习惯上做了很多适配比如用接口声明式地定义AI服务、用注解配置提示词模板、原生支持Spring Boot的starter方式接入。它的核心价值在于把和大模型打交道那些杂活对话、记忆、工具调用、RAG检索、输出解析、多模型切换全部封装好让Java开发者用自己熟悉的方式去写AI功能。在Spring的体系里整合LangChain4j优势就更明显了。Spring本身的依赖注入、配置管理、AOP、事务这些能力加上LangChain4j的LLM抽象能力组合起来之后你可以做到在大模型对接这一层的配置全部外置化业务代码里不需要写死任何一个模型参数想换模型就改配置文件。同时整个AI服务模块可以像普通Spring服务一样被管理和测试这对那种已经在用Spring Boot做微服务的团队来说几乎是无缝接入。1.2 这个整合适合什么场景我实际做过不少项目总结下来Spring LangChain4j这套组合最适用的场景有这几类第一类是智能客服和问答系统。Spring Boot做Web服务天然顺手加一个AI服务层处理语义理解和答案生成整个链路非常顺。配合LangChain4j的消息记忆能力可以做出上下文连贯的对话体验。第二类是业务数据智能查询。把数据库schema、业务文档灌给模型用自然语言对话的方式查询数据或者生成报表。这块LangChain4j的RAG检索增强生成链路帮助很大我自己用它对过几千页的内部文档召回效果和准确性比直接硬问模型好很多。第三类是内容生成和处理类工具。比如自动生成商品描述、新闻摘要聚合、邮件起草。这种需求往往是后端的定时任务或者接口服务天然长在Spring生态里。第四类是带工具调用的Agent类应用。比如让模型自己决定调用查询订单的接口然后根据结果回答用户问题。LangChain4j对Tool Calling的支持比较成熟Spring里只要把Bean方法暴露给模型就行这个后面我会细讲。如果你是做Python的可能觉得LangChain那一套更熟但目前Java技术栈里要做LLM集成LangChain4j这块确实没什么对手。结合Spring Boot来承接Web层、管理生命周期这套方案在老牌的Java团队落地的难度是最低的。2. 环境准备与依赖配置2.1 Spring Boot版本与JDK选型先说版本。LangChain4j本身对Spring Boot的版本有要求目前主流的1.x版本支持Spring Boot 3.x系列我自己用的是Spring Boot 3.2.x配JDK 17实测下来很稳。JDK 17已经不是可选项而是默认项了Spring Boot 3.x在class文件版本上强制要求JDK 17起跳这个要注意。如果你还在JDK 8上那基本只能放弃这个方案或者考虑先用Spring Boot 2.x过渡但LangChain4j的官方Spring Boot starter大多绑定3.x硬要搞的话就得自己写自动装配了不太推荐。Maven项目的话在pom.xml里加上Spring Boot父依赖然后是LangChain4j的starter。我的做法是在dependencyManagement里统一管理版本避免子模块版本漂移。parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.2.5/version relativePath/ /parent properties java.version17/java.version langchain4j.version1.0.0-beta1/langchain4j.version /properties dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-spring-boot-starter/artifactId version${langchain4j.version}/version /dependency !-- 这里根据你实际用的模型厂商选一个后面细说 -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-open-ai/artifactId version${langchain4j.version}/version /dependency /dependencies如果用的是国内可以直连的模型厂商比如对接OpenAI兼容接口的中转服务或者国产大模型的OpenAI兼容模式就把对应的依赖拉进来。LangChain4j对OpenAI兼容接口的支持很友好大部分时候不需要额外开发。2.2 关键配置项逐项解释配置上老规矩放在application.yml里。我习惯把所有模型相关配置集中在一个前缀下方便后期统一调整。langchain4j: open-ai: model-name: gpt-4o-mini api-key: ${OPENAI_API_KEY:sk-xxx} base-url: ${OPENAI_BASE_URL:https://api.openai.com} temperature: 0.7 timeout: 60s max-tokens: 2048如果你用别的模型比如国内某家的OpenAI兼容接口那base-url改成对方提供的网关地址就行apikey换成你自己的。temperature建议在0.3到0.8之间选做问答任务我一般取0.5需要创造性的内容生成调到0.8要求结果稳定的话调到0.2以下。还有一个很关键的配置langchain4j.open-ai.log-requests和log-responses这两个开关默认是false我强烈建议调试阶段打开。开了之后控制台会打印完整的请求体、响应体模型到底收到了什么、返回了什么一目了然。排查问题的时候你就会知道这个开关有多救命。langchain4j: open-ai: log-requests: true log-responses: true注意日志级别要是DEBUG否则可能不输出。这个我踩过坑配置对了但看不到日志最后发现是logback的level没放出来。2.3 为什么建议先用Beta版本LangChain4j的版本迭代很快0.x到1.0.0-beta1我都在用。早期版本API变动比较频繁类和方法的命名会有调整网上教程不一定对得上你本地版本的情况。如果你照着文档写、发现编译不过大概率不是代码写错而是版本API变化。我建议直接上最新的beta版API相对稳定且功能全社区活跃度也高。还有一个点LangChain4j的starter包名跟旧版本不一样老教程里有的写langchain4j-spring-boot-starter有的写langchain4j-spring不同小版本下包名有变动。建议以你实际拉下来的依赖为准通过IDE查看依赖树别死磕教程。3. 核心功能开发与Spring整合细节3.1 用AiService注解定义AI接口LangChain4j整合Spring之后最有代表性的一个能力就是AiService注解。它让你声明一个接口框架自动帮你生成实现类方法上只要定义好提示词模板和参数剩下的调用模型、解析输出全部交给框架。举个例子我要做一个旅游推荐助手AiService public interface TravelAssistant { SystemMessage(你是一个专业的旅行规划顾问请根据用户的偏好给出合理的推荐方案语言风格友好且简洁。) UserMessage(我想去{{place}}旅行偏好{{preference}}预算大概是{{budget}}请给我一个三日游的行程建议。) String recommend(V(place) String place, V(preference) String preference, V(budget) String budget); }这个接口不用写实现类。Spring启动的时候LangChain4j会自动扫描带有AiService的接口生成动态代理实现注入到容器里。你用的时候直接注入接口就行RestController public class TravelController { private final TravelAssistant travelAssistant; public TravelController(TravelAssistant travelAssistant) { this.travelAssistant travelAssistant; } GetMapping(/recommend) public String recommend(RequestParam String place, RequestParam String preference, RequestParam String budget) { return travelAssistant.recommend(place, preference, budget); } }我用生活化的方式解释一下SystemMessage和UserMessage的区别SystemMessage是给模型设定的角色和规矩——相当于你上岗前公司发的《员工手册》里面写着“你是谁、什么话能说什么话不能说”UserMessage就是用户具体的问题——相当于用户实际向你提的需求中间留了{{变量}}的占位符运行时替换成真实参数。这里有个实用技巧SystemMessage不只是写角色还可以把业务规则塞进去。比如客服场景下把售后政策、回复规范都写进去模型回答时会严格遵循这些规则比后制裁剪输出自然多了。3.2 ChatMemory让AI记住上下文多轮对话的本质是历史消息的管理。LangChain4j提供了ChatMemory接口几种实现可以选择。我实际最常用的是MessageWindowChatMemory——它像一个滑动窗口只保留最近N条消息防止上下文无限膨胀导致Token超限。在Spring里注册一个Bean给AiService用Configuration public class AssistantConfig { Bean ChatMemory chatMemory() { return MessageWindowChatMemory.withMaxMessages(20); } }然后在AiService上通过chatMemory属性绑定AiService(chatMemory chatMemory) public interface ChatAssistant { UserMessage({{message}}) String chat(V(message) String userMessage); }这里chatMemory对应的是Spring容器里的Bean名称。框架会在每次方法调用时自动把历史消息和当前输入拼在一起发给模型模型回答之后再自动把这段交互存入记忆。不过要特别提醒这个ChatMemory是单例的意味着所有用户共用一份记忆。实际项目里肯定不行你得自己按会话维度管理记忆对象。我做过的一个方案是用Map缓存每个会话ID对应的ChatMemory实例会话结束时清理并且加上过期时间防止内存泄漏。Component public class SessionMemoryManager { private final MapString, ChatMemory memoryMap new ConcurrentHashMap(); public ChatMemory getMemory(String sessionId) { return memoryMap.computeIfAbsent(sessionId, k - MessageWindowChatMemory.withMaxMessages(20)); } public void clear(String sessionId) { memoryMap.remove(sessionId); } }对应地AiService接口的方法上手动传入一个ChatMemory参数框架会优先使用方法参数里的实例而不是Bean里那个共享的。3.3 Function Calling把Spring Bean方法暴露给模型这是LangChain4j真正拉开体验差距的地方。它的基本原理是给模型描述一组Java方法的存在模型在回答过程中如果需要调用外部能力比如查数据库、验库存、下发指令它会先请求调用这个方法框架把这个请求分发到Spring容器里的实际方法上执行然后把结果返回给模型模型基于结果继续组织回答。整个交互是循环的对开发者来说你不需要写循环逻辑框架全包了。在Spring里定义一个Bean方法加上Tool注解Component public class OrderTools { Tool(根据订单号查询订单状态) public String queryOrderStatus(String orderId) { // 调用订单服务查库 return orderService.getStatusByOrderId(orderId); } Tool(根据用户ID查询最近订单金额) public BigDecimal getRecentOrderAmount(String userId) { return orderService.getRecentAmount(userId); } }然后在AiService接口上声明使用哪些工具AiService public interface CustomerServiceAssistant { SystemMessage(你是电商平台的客服助手请根据工具返回的订单数据回答用户问题不要臆造信息。) UserMessage({{message}}) String chat(V(message) String userMessage); }启动之后框架会自动扫描容器中带Tool注解的方法并把它们注册给模型。用户如果问“帮我查一下订单20240813001的物流状态”模型会解析出意图调用queryOrderStatus方法返回结果后又把自然语言的回答输出出来。这里有个经验之谈Tool方法的描述信息一定要写得详实清楚因为模型要依赖描述来判定“这个问题该不该调用这个方法、应该传什么参数”。描述模糊的话模型要么不调要么参数传错。一个好的工具描述应该包含方法用途、参数含义、返回值含义。我见过最坑的情况是一个方法叫query()描述就写“查询”模型完全不知道它能干什么最后干脆不调用直接编答案。3.4 RAG检索增强让模型基于你的知识库说话RAG检索增强生成听起来玄乎核心就是三件事把文本切碎、向量化入库、用户提问时先检索最相关的片段再交给模型生成。LangChain4j对这段流程封装得很完善Spring整合更是把整条链路变成了几个Bean的事。第一步准备嵌入模型。我用的是OpenAI兼容的嵌入接口langchain4j: open-ai: embedding-model-name: text-embedding-3-small第二步定义一个EmbeddingStore用来存向量。生产环境建议用专业的向量数据库本地开发可以直接用内存版Configuration public class EmbeddingStoreConfig { Bean EmbeddingStoreTextSegment embeddingStore() { return new InMemoryEmbeddingStore(); } }第三步把文档灌进去。这一步通常是离线执行的比如服务启动时读取一个目录下的所有文本文件Component public class KnowledgeBaseInitializer { private final EmbeddingStoreTextSegment embeddingStore; private final EmbeddingModel embeddingModel; public KnowledgeBaseInitializer(EmbeddingStoreTextSegment embeddingStore, EmbeddingModel embeddingModel) { this.embeddingStore embeddingStore; this.embeddingModel embeddingModel; } PostConstruct public void init() { // 读取resources/docs下的所有txt文件 // 每个文件按固定大小切段向量化后存入store } }第四步在AiService中启用RAGAiService public interface KnowledgeAssistant { UserMessage(请基于检索到的资料回答{{message}}) RetrievalRetriever(store embeddingStore) String answer(V(message) String message); }RetrievalRetriever这个注解会触发检索逻辑用户问题向量化在store里做相似度检索取top-3的片段拼进上下文然后模型基于这些片段来回答问题。RAG这个过程中最影响效果的是切段策略。切块太大检索不精准模型会被无关内容干扰切块太小上下文信息不完整答案可能残缺。文本类内容我一般取300到500个字符一段并带有一定的重叠区域这样既能保证语义完整又不会让上下文超长。具体数值要根据你的文档风格来调法律合同类的句子长段落大切法就要相应调整。4. 完整实操从零写一个知识库问答接口4.1 搭建项目骨架这个环节我们从头到尾走一遍。假设你要做一个内部IT运维知识库的问答接口员工提问“打印机连不上怎么办”或“VPN账号怎么申请”接口返回运维手册中的对应内容。第一步在start.spring.io初始化一个Spring Boot项目Java 17依赖选择Spring Web和Spring Boot Actuator调试方便然后手动加入LangChain4j相关的依赖。第二步写配置类把上面提到的ChatMemory、EmbeddingStore、EmbeddingModel这些Bean配置好。第三步写文档加载的工具类。我实际项目里常用的方式是用一个简单的文本读取器Component public class DocsLoader { Value(${knowledge.docs-path:classpath:docs}) private String docsPath; public ListTextSegment loadSegments() { ListTextSegment segments new ArrayList(); // 读取该路径下的所有.txt/.md文件 // 按段落切分保留文件名前缀作为来源标记 return segments; } }切分时保留来源标记对后面很有用模型回答时可以顺便给出“参考了哪个文档”用户对回答的信任度会高很多。4.2 实现检索增强问答核心的AiService按之前的方式定义好写一个Controller暴露HTTP接口RestController RequestMapping(/api/assistant) public class AssistantController { private final KnowledgeAssistant assistant; private final SessionMemoryManager memoryManager; public AssistantController(KnowledgeAssistant assistant, SessionMemoryManager memoryManager) { this.assistant assistant; this.memoryManager memoryManager; } PostMapping(/query) public Result query(RequestBody QueryRequest request) { String sessionId request.getSessionId(); ChatMemory memory memoryManager.getMemory(sessionId); String answer assistant.answer(request.getQuestion(), memory); return Result.ok(answer); } }这段代码里有一个细节值得注意我把ChatMemory作为参数传给了assistant.answer()。当方法参数中出现ChatMemory类型时LangChain4j会优先使用这个参数而不是接口默认绑定的Bean。这是实现多会话隔离的关键点。然后验证整个链路启动应用确认日志中显示模型连接正常。发送请求{sessionId: s001, question: 打印机无法连接网络怎么办}。观察控制台日志确认检索命中了哪些文档片段。确认模型给出了基于文档内容的回答。4.3 模拟项目X的实测指标我在模拟项目X里放了大约50份运维文档实测效果有几个数据可以给你参考普通问题首次响应的耗时大约1.8到3秒之间其中约0.3秒是文档检索剩余的是模型生成时间。取top-3片段时回答准确度明显优于只取top-1模型在回答时引用了正确的文档来源。但是当问题比较冷门、文档里没有对应信息的时候模型还是会给出泛泛的答案而不是直接承认不知道——这需要额外加约束比如在SystemMessage里写明“检索不到相关资料时明确告诉用户未收录不要猜测”。顺带提一个我踩过的坑文件编码。文档如果是GBK编码的直接读出来是乱码向量化效果也奇差。后来我统一在加载时指定UTF-8并且加载完做一个简单校验如果乱码比例过高就报警。5. 常见问题与排查技巧5.1 高频问题速查表问题现象根因解决办法依赖拉不下来或启动报NoClassDefFoundError版本冲突LangChain4j与Spring Boot版本不匹配统一用BOM管理版本查看依赖树排查冲突接口注入报找不到beanAiService接口没被扫描到确认接口所在包被Spring启动类扫描覆盖控制台没有请求日志日志级别不够logback配置里加DEBUG确认log-requests为true模型返回内容被截断max-tokens设太小调大到预期回答长度的1.5倍工具方法没有被调用Tool描述不清晰重写工具描述说清用途和参数含义多轮对话串台用了默认单例ChatMemory按会话隔离管理见上文SessionMemoryManager模型回答问题张冠李戴检索片段不相关调试检索结果调整切段大小或top-k值连接超时网络链路或timeout太小timeout调到60s起步排查网络连通性输入Token过长报错上下文窗口超限减少记忆窗口条数文档切段调小本地方向向量相似度不准嵌入模型与检索场景不匹配换嵌入模型或考虑微调/重排名5.2 定位问题的调试三板斧我排查这类问题的顺序基本是固定的。第一板斧开日志。把log-requests、log-responses打开看模型实际收到什么、返回什么。这一步能解决80%的问题。模型没调工具看日志里工具定义有没有发出去。胡说八道看SystemMessage送到没有。第二板斧查依赖树。mvn dependency:tree看一下LangChain4j相关的版本是否一致有没有被意外的依赖传递替换掉版本。版本不一致轻则API方法找不到重则运行期诡异的空指针。第三板斧最小复现。把问题从Spring环境里抽出来写一个独立的main方法直接构建模型对象发一个最简单的消息。如果能跑通说明Spring整合配置有问题如果还是不通那问题在模型配置或网络本身。5.3 生产环境的额外建议如果这个整合方案要上生产有几件事我在实际项目里都做过建议你也别省。第一API Key一定要走配置中心或环境变量不要写死在配置文件里。项目里加解密配置是常态LangChain4j本身没有密钥管理能力这块要依赖Spring的配置体系。第二对LLM接口做好限流和熔断。模型服务的稳定性远不如普通HTTP接口尤其是高峰期响应时间可能从2秒拉垮到15秒。我用过Spring的CircuitBreaker注解来包一层AiService调用效果还可以另外在网关层做简单的并发限流避免突发流量打爆模型配额。熔断的阈值我一般设成5秒内失败3次就切断恢复等待30秒。第三建议加一层缓存。同样的或者高度相似的问题完全可以让模型再答一遍但其实缓存命中率相当可观。我用简单的短文本哈希加Redis做过大概能有20%左右的命中率这些流量可以不花钱。第四监控埋点。AiService调用的成功/失败、耗时、Token消耗都可以埋出来。它和普通数据库调用没有本质区别该有的监控都要有。我自己的做法是拦截ChatLanguageModel.chat()方法在外面包一层计时器和计数器。第五内容安全问题。模型输出必须做合规过滤和审核。正规的做法是模型输出先过一层敏感词过滤再走内容审核服务。这块不要只依赖模型自己的安全对齐毕竟你无法控制所有场景和输入。6. 实操心得与后续扩展建议6.1 几个让我印象深刻的坑先说Ajax调用的并发问题。模型接口的响应耗时相比于普通HTTP接口要高一个数量级如果你在Web层没有合适的异步处理机制很可能会占满Servlet线程池。我起初没注意压测时发现Tomcat线程被模型调用占满其他请求全部排队。后来把AiService的调用放到虚拟线程里跑才算解决。Spring Boot 3.2上spring.threads.virtual.enabledtrue开一下就好没有太多额外成本。实测模型等待期间不再阻塞Web请求线程整体吞吐上了一个台阶。然后是流式输出。一开始没考虑流式所有回答都要等模型全文生成完才返回接口响应时间普遍4到8秒对用户来说体验很糟糕。后来切到流式输出用FluxString对接SSE用户感知的响应速度大幅改善。LangChain4j的StreamingChatLanguageModel接口专门干这个。如果你是面向真实用户的产品强烈建议上流式。还有一个是成本控制。RAG场景下每次对话都要传文档片段和完整历史Token消耗比单纯问答高出一截账单涨得也快。尽量控制历史轮数别无限累积文档片段在做检索之后加上一个相似度阈值过滤低于阈值的片段宁可不传。6.2 这个方案的边界在哪里得实话实说Spring整合LangChain4j不是万能的。它解决了“把LLM能力集成进Java后端”的工程化问题但以下这些场景它不算最佳解超级复杂的Agent多步骤编排LangChain4j支持Agent调用但编排逻辑还是得自己手写。如果业务逻辑是十几个工具来回调度流程分支特别多那这套方案还不如用流程引擎加规则配置来写。大规模微调训练LangChain4j本身不负责训练这块要交给专门的模型训练链路。超低延迟场景比如实时语音交互Java后端经过Spring和模型调用的开销不小如果要求端到端Latency在300ms以内这种写法可能不适合得考虑更底层的接入方式或者边缘推理。我另外要说一句的是目前LangChain4j的社区资料和教程密度还是比不上Python的LangChain很多问题需要你自己去翻GitHub源码和官方示例。但好处是代码风格贴近Spring生态遇到问题基本能在自有代码里排查不用去啃一堆陌生概念。6.3 后续可以怎么玩整合跑通之后可以做的扩展很多。最简单的在现有基础上接一个WebSocket把知识库问答变成实时聊天界面也在Spring里注册多个不同用途的AiService比如一个处理订单查询、一个处理售后回答、一个处理内容审核彼此之间完全隔离管理起来也清晰。更强一点的玩法是把LangChain4j接入到你的工作流引擎里让AI成为流程中的一个节点。比如审批流程中上一个节点填写的信息转成自然语言让AI提取成结构化字段然后继续流转。这种能力在实际业务系统里非常有价值能让复杂表单的填写体验提升一个档次。目前在AI应用开发这个领域Java生态的成熟度确实在快速追赶。像LangChain4j整合Spring这种方案最大的意义是让后端团队可以用已经得心应手的技术栈去做AI功能不需要推翻重来也不需要另起炉灶学一套全新的体系。Java开发者原来会的东西——依赖注入、Bean管理、配置外置、面向接口编程——这些能力全都保留并复用AI只是在做增量。我自己操作下来的整体感受是这套组合的学习曲线不会太陡你只需要理解模型API的基本行为模式请求什么、响应什么剩下的工程化问题Spring和LangChain4j会把绝大多数杂活处理干净。真正需要花心思的是结合自己的业务场景去设计好提示词、工具方法和检索链路让模型发挥出它该有的价值。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
