做了十来年Java后端说句实话天天跟CRUD、Spring Boot、数据库事务打交道这两年看着AI应用铺天盖地心里多少有点慌。不是怕写代码而是大模型应用开发的主流姿势似乎都被Python占了——打开GitHub随便一个像样的AI项目都是Python写的想转向又舍不得Java这边的家底。LangChain4J就是来解决这个尴尬的它是LangChain家族在Java生态的官方实现把大模型接入、上下文管理、工具调用、检索增强这些能力全部封装成了Java工程师一看就懂的API。你只要会用Maven、写过Spring Boot不用切语言十几行代码就能让系统具备聊天、总结、结构化抽取这类AI能力。这篇文章不聊玄学全程讲实操。我会从为什么Java工程师必须重视它讲起拆解核心的编程模型给出一套能从零跑通的完整案例最后把我踩过的生产环境里的坑一次性倒出来。适合三类人看想给后端系统加AI功能的Java工程师、准备面试时拿AI项目当差异化亮点的开发者、以及正在做技术选型、想评估Java系AI方案的负责人。1. 为什么Java开发者的下一个技能点必须是LangChain4J1.1 Python一统AI江湖Java工程师的困境与机会先讲个现实处境。你去搜AI应用开发示例代码几乎全是Python原版LangChain的文档默认也是给Python用户看的。Java工程师想做AI功能最常见的路径是公司后端用JavaAI部分却不得不让Python组写一个独立服务两边靠HTTP对接。这个方案能跑但代价不低你要维护两套部署环境、两套监控体系还要处理跨语言调用的超时、鉴权、数据格式不一致问题。我见过不少团队为了一个简单的内容摘要功能愣是搭了一条Python微服务链路最后维护成本比功能本身还高。更尴尬的方案是直接用HttpClient裸调大模型API。做demo可以做产品就麻烦了——流式输出的SSE解析得自己写Token用量要自己统计多轮流式上下文要自己拼某个模型厂商接口升级了要自己跟着改。这些活不是不能干但每项都是纯体力活而且非常容易在细节上出错。LangChain4J把这些脏活累活全都标准化了Java工程师不需要转语言在自己熟悉的生态里就能把AI能力落地。再说机会层面。现在企业里的现状是存量系统绝大多数是Java写的Spring Boot管理着用户体系、订单数据、权限模型。AI功能想要真正产生业务价值恰恰需要接进这些存量系统——AI不是独立跑在云端的玩具而是需要读你的数据库、调你的订单接口、理解你的业务流程。谁能把这些数据源和能力以受控的方式交给大模型谁就能在企业里做出真正的AI产品。而Java工程师天然掌握这些数据源缺的只是一个好用的AI编排框架。LangChain4J补上的正是这块拼图。1.2 LangChain4J的定位不是Python移植是Java原生很多人第一次看到LangChain4J会本能地问一句这是不是把Python的LangChain翻译过来。实际上LangChain4J更像是一次基于Java生态习惯的重写。它在设计上有几个很明显的Java思维第一类型安全。Java里一切都是对象模型返回的不再是随手拼的Map而是可以映射到POJO上的结构化对象。写代码时IDE能自动补全编译期就能发现类型错误这在Python那种鸭子类型世界里很难体验到。第二Builder模式遍布每个组件。LangChain4J从模型的配置到AI服务的组装清一色使用Builder。用过Spring Boot的人对这种风格应该非常亲切配置项集中、可读性强、上手几乎没有学习成本。第三面向接口编程。所有模型都实现ChatLanguageModel接口所有向量存储都实现EmbeddingStore接口。这意味着你的业务代码只需要依赖抽象厂商切换只影响装配层。举个实际场景你昨天用的OpenAI今天因为合规要求换成了Azure OpenAI或者本地Ollama业务代码一行都不用动只在创建模型实例的地方换个Builder实现即可。第四和Spring生态无缝融合。AiServices创建出来的对象天然就是一个可以扔进IOC容器的组件可以直接作为Controller层的Service使用。这种融合程度是Python的AI框架很难给Java团队的体验。所以准确说LangChain4J给Java开发者带来的不是又一个开源库而是一整套标准的AI应用编程模型。从这个角度看它确实配得上Java必备技能这个标签。2. 快速理解LangChain4J的五个核心能力2.1 统一模型接入ChatLanguageModel与StreamingChatLanguageModelLangChain4J整个体系的基石是ChatLanguageModel接口。这个接口定义了给一段输入返回模型生成结果的抽象能力不管背后接的是OpenAI、Google Gemini、通义千问还是本地Ollama业务侧拿到的都是同一个方法的返回值。先看一个最基础的用法ChatLanguageModel model OpenAiChatModel.builder() .apiKey(System.getenv(OPENAI_API_KEY)) .modelName(gpt-4o-mini) .temperature(0.7) .timeout(Duration.ofSeconds(60)) .logRequests(true) .logResponses(true) .build(); String answer model.generate(请用一句话介绍你自己); System.out.println(answer);这段代码里logRequests(true)和logResponses(true)是我特别建议打开的配置调试期能直接看到发送给模型的HTTP请求体和返回体。LangChain4J底层用的是Java HttpClient这些日志对排查问题非常有帮助。与之配套的还有StreamingChatLanguageModel。大模型生成内容需要时间如果是逐字返回的流式响应用户看到的是打字机效果等待体验和一次性等完整回复完全不同。LangChain4J对流式的抽象做得不错订阅者模式用起来也很顺手StreamingChatLanguageModel streamingModel OpenAiStreamingChatModel.builder() .apiKey(System.getenv(OPENAI_API_KEY)) .modelName(gpt-4o-mini) .build(); streamingModel.generate(用50个字解释一下TCP三次握手) .onPartialResponse(System.out::print) .onCompleteResponse(response - { System.out.println(); System.out.println(Token用量: response.tokenUsage().totalTokenCount()); }) .onError(Throwable::printStackTrace);我自己的体会是凡是面向用户的聊天场景务必走流式凡是后台批处理的场景用一次性调用就行。两种接口分开设计避免把复杂线程模型强加给业务方这个设计值得点赞。目前官方维护的适配比较多我简单列一张表供选型参考模型来源Maven模块典型使用场景OpenAI / Azure OpenAIlangchain4j-open-ai通用对话、结构化输出、嵌入Google Geminilangchain4j-google-ai-gemini多模态、大上下文Ollama本地langchain4j-ollama私有化部署、离线环境、开发调试Anthropic Claudelangchain4j-anthropic长文本、深度推理Hugging Facelangchain4j-hugging-face开源模型接入贴一下Maven坐标dependency groupIddev.langchain4j/groupId artifactIdlangchain4j/artifactId version0.36.2/version /dependency dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-open-ai/artifactId version0.36.2/version /dependency注意LangChain4J版本迭代很快1.0系列已经进入候选阶段部分API包路径有调整。建议以Maven中央仓库最新release为准升级时留意官方release notes。2.2 AiServices把大模型变成你的业务Bean如果说ChatLanguageModel是能用那AiServices就是好用。它的核心思想异常简单你定义一个Java接口LangChain4J在运行期帮你生成实现把接口方法调用翻译成对大模型的调用。这种接口即AI服务的模式让LLM接入变得和在Spring里注入一个Service一样自然。示例interface ChatAssistant { String chat(String message); } ChatAssistant assistant AiServices.builder(ChatAssistant.class) .chatLanguageModel(model) .build(); String reply assistant.chat(你好帮我写一段欢迎语);就这么简单。AiServices.builder()会返回一个该接口的动态代理你调方法、传参数后面所有和模型交互的细节都被框架消化了。这个模式的价值在于你的业务层不用感知我在调用大模型它只知道自己调了一个叫ChatAssistant的接口。在接口方法上还能通过注解控制提示词interface CustomerSupportAssistant { UserMessage( 你是某电商平台的客服助手回答请简洁、礼貌。 客户的提问{{userMessage}} ) String answer(V(userMessage) String userMessage); }这种写法把提示词模板和Java方法绑定在一起比在业务代码里拼字符串干净太多。模板里的{{userMessage}}会自动绑定方法参数。当你的系统里有一堆AI能力——客服、摘要、审核——每个能力定义一个接口再让Spring管理这些接口的实现整个AI层就变得非常模块化。2.3 结构化输出让大模型按你的POJO返回JSON企业应用最麻烦的一点是LLM输出的是自由文本而业务系统需要的是JSON、POJO、数据库字段。LangChain4J把从自然语言到结构化对象的转换做成了第一公民能力直接这样写class SentimentResult { public String sentiment; // 正面 / 负面 / 中性 public Double confidence; // 置信度 } SentimentResult result model.generate(这款产品我很喜欢推荐给大家, SentimentResult.class); System.out.println(result.sentiment / result.confidence);model.generate(text, SomeClass.class)这一行背后做了两件事一是让模型以指定结构输出二是把模型返回的内容反序列化到你的类里。设计POJO时有两个硬性要求字段必须是public的或者提供标准的getter/setter类必须有无参构造。这两个要求踩过坑的人都知道忘了哪一个运行期直接给你抛JsonMappingException。结构化输出背后的实现路径有两条一条是让模型开启JSON mode输出合法JSON另一条是借助函数调用机制把输出对象伪装成一次工具调用让模型通过填写参数来完成结构化输出。我实测下来第二种在多模型之间的兼容性更好LangChain4J在不断迭代中也更偏向这条路径。如果你遇到结构化输出不稳定优先检查模型是否支持函数调用。2.4 工具调用给大模型装上一双能抓数据的手这是LangChain4J里最有价值的能力没有之一。有了工具调用大模型就不再只是一个聊天生成器它变成一个能查数据库、能调业务接口、能执行计算的任务执行者。Java端的实现极其优雅核心就一个注解public class OrderTools { Tool(根据用户ID查询最近订单状态) String queryOrderStatus(ToolParam(用户ID) String userId) { // 这里实际上会去查业务库 return 订单已发货预计明天送达; } } ChatAssistant assistant AiServices.builder(ChatAssistant.class) .chatLanguageModel(model) .tools(new OrderTools()) .build(); String reply assistant.chat(帮我查一下123456这个用户的订单状态);当用户问查订单时模型不会凭空编一个答案而是先申请调用queryOrderStatus方法LangChain4J把参数123456传进去执行真实查询再把结果交回给模型模型基于真实结果组织语言回复用户。整个流程是一个模型请求-框架执行-结果回填-生成答复的闭环。用工具调用时有几个经验工具方法的返回值不要太长。模型会把工具返回的内容再塞进上下文如果一次查出几百行数据Token消耗会迅速膨胀。方法参数尽量用基本类型或简单POJO。复杂嵌套对象在参数组装时容易出错能拆成多个简单方法就别用一个复杂方法。工具方法必须能被实例化。tools(new OrderTools())传的是对象方法本身最好别依赖Spring容器里的状态需要访问数据库时直接在构造器里注入Service或者Repository即可。给工具写清晰的中文描述。Tool里的描述就是模型理解该方法用途的信息来源描述越具体模型越不会乱调。2.5 记忆与上下文从单轮对话到多轮会话默认情况下model.generate(你好)和model.generate(刚才我说什么了)是两段互不相关的请求。要做到多轮对话必须把聊天历史带给模型。LangChain4J把这块抽象成ChatMemory接口最常用的实现是MessageWindowChatMemory它内部维护一个消息队列按最大条数滑动窗口淘汰旧消息ChatMemory chatMemory MessageWindowChatMemory.withMaxMessages(20); ChatAssistant assistant AiServices.builder(ChatAssistant.class) .chatLanguageModel(model) .chatMemory(chatMemory) .build(); String reply1 assistant.chat(你好我叫张三); String reply2 assistant.chat(我叫什么名字); // 它能答上来withMaxMessages(20)意味着最多保留20条消息10轮一来一回超出后最老的会被丢弃。这个滑动窗口机制合理控制了上下文长度也限制了Token成本。这里有一个我在生产环境反复踩过的坑必须提醒ChatMemory不是线程安全的会话隔离容器。如果你把同一个ChatMemory实例注入给所有用户共用就会出现用户A问了一句用户B接着问的时候模型莫名其妙提到A的话题。正确做法是每个会话一个ChatMemory最简单的方式是维护MapSessionId, ChatMemory或者结合Spring Web的SessionScope管理。这是多用户AI系统最容易翻车的地方没有之一。3. 15分钟快速上手从零跑通第一个对话程序3.1 环境准备与依赖引入动手之前先确认本机环境JDK 17及以上LangChain4J较新的版本要求JDK 17Maven 3.6或Gradle 7一个可用的模型API Key。如果暂时没有OpenAI的Key用Ollama在本地起一个小模型也能跑通不影响体验核心API。新建一个Maven项目在pom.xml里加入核心依赖dependencies dependency groupIddev.langchain4j/groupId artifactIdlangchain4j/artifactId version0.36.2/version /dependency dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-open-ai/artifactId version0.36.2/version /dependency /dependencies然后设置环境变量export OPENAI_API_KEY你的key如果你用的是Ollama把依赖换成langchain4j-ollama模型创建换成ChatLanguageModel model OllamaChatModel.builder() .baseUrl(http://localhost:11434) .modelName(qwen2.5:7b) .build();注意Ollama方案要求本地已经拉取了对应模型镜像适合不想注册云端API的开发者。3.2 第一个对话程序创建一个主类代码如下import dev.langchain4j.model.chat.ChatLanguageModel; import dev.langchain4j.model.openai.OpenAiChatModel; import java.time.Duration; public class FirstAiApp { public static void main(String[] args) { ChatLanguageModel model OpenAiChatModel.builder() .apiKey(System.getenv(OPENAI_API_KEY)) .modelName(gpt-4o-mini) .timeout(Duration.ofSeconds(30)) .logRequests(true) .logResponses(true) .build(); String answer model.generate(用三句话介绍LangChain4J要求带点幽默感); System.out.println(answer); } }直接运行main方法等待几秒就能看到输出。控制台里会打印出完整的请求和响应报文这正是前面打开logRequests和logResponses的用处——第一次跑通后你能亲眼看到这个框架底层是怎么和模型交互的这对建立直觉非常有帮助。跑通这个demo后你可以试着改几点换modelName、调temperature、把问题从中文换成英文。感受一下不同参数对输出风格的影响。temperature我一般习惯控制在0.2到0.8之间太高回答发散太低显得呆板。3.3 流式输出改造一次性generate适合后台任务但如果是给用户交互页面用等待感太强。建议尽早切到流式接口。把上面的代码稍微改一下import dev.langchain4j.model.chat.StreamingChatLanguageModel; import dev.langchain4j.model.openai.OpenAiStreamingChatModel; public class StreamingDemo { public static void main(String[] args) { StreamingChatLanguageModel model OpenAiStreamingChatModel.builder() .apiKey(System.getenv(OPENAI_API_KEY)) .modelName(gpt-4o-mini) .build(); model.generate(写一首五言绝句主题是初春) .onPartialResponse(System.out::print) .onCompleteResponse(response - { System.out.println(); System.out.println(总Token数: response.tokenUsage().totalTokenCount()); }) .onError(Throwable::printStackTrace); } }跑通流式版本后你会明显感受到打字机效果对体验的提升。在Spring Boot项目里还可以直接把onPartialResponse的内容通过SSE推给前端。这里有个小建议把流式线程和WebSocket/SSE线程的关系理清楚别在回调里做耗时操作回调函数越轻量越好。4. 进阶实战打造一个Spring Boot知识库问答机器人4.1 先看整体架构单独的对话demo价值有限真正在企业里落地最多的是基于私有知识的问答系统。比如把产品文档、历史工单、操作手册喂给系统然后让用户用自然语言提问系统基于文档内容给出回答。这个模式叫RAG检索增强生成LangChain4J对它的支持已经到了开箱即用的程度。整个流程我拆成六个步骤步骤环节核心组件1文档加载Document.from() 读取文本/PDF/Markdown2文档切分DocumentSplitters.recursive(窗口大小, 重叠)3向量化EmbeddingModel 把切块转成向量4向量存储EmbeddingStore 存入向量库5相似检索根据用户问题召回TopN相关切片6生成回答把切片作为上下文交给ChatLanguageModel这个流程里的核心思想是不把整个文档库塞给大模型而是先检索出和用户问题最相关的几段内容用它们作为回答依据。这样既控制了Token成本又让回答有据可查还能在回答下方给出资料来源。4.2 文档切分与向量化落地先准备一份测试文档假设是一段产品使用手册。加载并切分的代码import dev.langchain4j.data.document.Document; import dev.langchain4j.data.document.splitter.DocumentSplitters; import dev.langchain4j.data.segment.TextSegment; Document document Document.from( 这里放入你的产品文档正文。文档越长越好实际项目中可以是几十页的PDF 也可以把数据库里的历史工单拼接成文本再喂进来。 ); ListTextSegment segments DocumentSplitters.recursive(300, 50) .split(document); System.out.println(切分出了 segments.size() 个片段);recursive(300, 50)两个参数的含义是每个切块约300个token相邻切块保留50个token的重叠。重叠的作用非常关键——如果某句话恰好被切在边界上重叠区域能保证这句话的信息不会被丢掉。这个参数配比是我常用的起点长文档适当加大窗口短文档可以调小。然后做向量化并存入内存向量库import dev.langchain4j.data.embedding.Embedding; import dev.langchain4j.model.embedding.EmbeddingModel; import dev.langchain4j.model.openai.OpenAiEmbeddingModel; import dev.langchain4j.store.embedding.EmbeddingStore; import dev.langchain4j.store.embedding.inmemory.EmbeddingStoreInMemory; EmbeddingModel embeddingModel OpenAiEmbeddingModel.builder() .apiKey(System.getenv(OPENAI_API_KEY)) .modelName(text-embedding-3-small) .build(); // 说明有多个切块时分别向量化 ListEmbedding embeddings embeddingModel.embedAll(segments).content(); EmbeddingStoreTextSegment embeddingStore new EmbeddingStoreInMemory(); embeddingStore.addAll(embeddings, segments);内存版EmbeddingStoreInMemory适合demo和中小数据量场景。生产环境建议换Chroma、Pinecone、Milvus或PgVector之类的专用向量库接口是一样的只是实现类和运维方式不同。一个小经验先把内存版跑通整个链路再考虑替换存储不要一开始就引入分布式向量数据库那是给自己加不必要的复杂度。4.3 检索与Prompt拼接用户提问后需要把问题向量化然后去向量库召回最相关的切片Embedding queryEmbedding embeddingModel.embed(如何配置数据库连接?).content(); ListEmbeddingMatchTextSegment matches embeddingStore.findRelevant(queryEmbedding, 3); String context matches.stream() .map(match - match.embedded().text()) .collect(Collectors.joining(\n---\n)); String prompt 请只基于下面的资料回答问题。如果资料里没有相关内容直接说资料中未找到。 资料 %s 问题 %s .formatted(context, 如何配置数据库连接?); ChatLanguageModel chatModel OpenAiChatModel.builder() .apiKey(System.getenv(OPENAI_API_KEY)) .modelName(gpt-4o-mini) .build(); String answer chatModel.generate(prompt); System.out.println(answer);这里有几个经验点值得说findRelevant(queryEmbedding, 3)里的3代表取Top3切片。这个数字不是拍脑袋定的TopK太小可能召回不全太大把无关内容塞进上下文反而干扰回答我一般先取3调试观察后再微调。提示词里明确写了只基于资料回答资料中没有就直说。这一步是为了约束模型不要编造、不要依赖训练数据里的旧知识。RAG场景下提示词对边界感的要求越清晰幻觉越少。切片内容之间用---分隔有助于模型区分多条独立资料。你也可以在每段开头加上资料1资料2的编号让回答能引用具体来源。把上面的代码整合成两个方法——buildKnowledgeBase()和answer(String question)一个负责初始化文档库一个负责问答一个最简的知识库问答系统就算落地了。4.4 与Spring Boot整合的推荐姿势到了正式项目里别再写成静态方法了推荐用Spring的配置类把组件管理起来Configuration public class LlmConfig { Value(${llm.api-key}) private String apiKey; Bean ChatLanguageModel chatLanguageModel() { return OpenAiChatModel.builder() .apiKey(apiKey) .modelName(gpt-4o-mini) .timeout(Duration.ofSeconds(30)) .build(); } Bean EmbeddingModel embeddingModel() { return OpenAiEmbeddingModel.builder() .apiKey(apiKey) .modelName(text-embedding-3-small) .build(); } Bean KnowledgeBaseService knowledgeBaseService(EmbeddingModel embeddingModel, ChatLanguageModel chatLanguageModel) { return new KnowledgeBaseService(embeddingModel, chatLanguageModel); } }Controller层就能直接注入使用了。这里再强调一次之前的坑如果涉及多用户、多会话ChatMemory不要做成全局单例要么每个用户建一个要么用一个带锁的MapSessionId, ChatMemory管理。生产项目里我推荐把会话ID和用户身份绑定这样即使前端刷新页面后端也可以按用户维度恢复上下文。5. 生产落地避坑手册并发、超时与成本控制5.1 并发与线程池隐患LangChain4J底层调用模型API走的是Java HttpClient这意味着每次模型请求都会占用一个IO线程。如果你的接口QPS一高又没有合理配置线程池线程耗尽、连接超时马上就来了。我在实际项目中见过的最常见错误是每个请求都new OpenAiChatModel(...)一次导致连接没有被复用性能惨不忍睹。正确的做法是把Model实例设计成Spring单例Bean整个应用只创建一次内部连接池统一复用。业务代码只依赖ChatLanguageModel接口框架会处理好连接复用和请求调度。如果你的应用用的还是JDK 21的虚拟线程可以关注下LangChain4J对虚拟线程的适配情况。简单说纯IO密集的LLM调用场景和虚拟线程非常契合但在切换之前先做好压力测试别被框架日志里的线程名欺骗。关于并发度我自己常用的估算方式是单用户一次对话平均耗时3到5秒要支撑100个并发用户系统至少要能同时处理接近100个在途请求。LLM调用是典型的IO密集型线程池核心数不需要很大但队列要够深配合超时和熔断使用。5.2 超时、重试与降级大模型API是外部依赖而且是不太稳定的外部依赖。网络抖动、服务端限流、模型过载都是常态。我在生产里稳定运行下来总结了三道防线防线手段说明超时构建Model时配置timeout建议30秒写文案场景60秒也不算过分重试对429、5xx做指数退避重试最多重试3次间隔从1秒、2秒、4秒递增熔断用Resilience4j或Sentinel包装调用连续失败超过阈值直接降级返回兜底文案Model构建时配置超时OpenAiChatModel.builder() .apiKey(apiKey) .modelName(gpt-4o-mini) .timeout(Duration.ofSeconds(30)) .build();重试和熔断建议放在服务层用CircuitBreaker或者编程式的方式包裹你的AI服务调用。降级兜底文案很关键比如当前AI服务繁忙请稍后再试。用户宁可看到一个诚实提示也不想看到30秒的白屏。这三件事一定要在功能上线之前测好别等问题被用户骂出来了再补。5.3 Token与成本控制Token就是钱一个不经控的AI功能月底账单会教你做人。我见过有人把整个知识库文档不分青红皂白全拼进Prompt一次请求几千Token一个月下来成本高到吓人。控制成本我一般从四个方向使劲选对模型。文本分类、摘要、抽取类任务用gpt-4o-mini这类轻量模型就够了只有复杂推理才值得上旗舰模型。控制上下文长度。设置MessageWindowChatMemory的最大消息数别让聊天记忆无限膨胀。做预检索过滤。RAG场景下先用标题、标签或时间范围粗筛再向量检索减少无效切片的输入。记录Token用量。每次响应的tokenUsage()都打印到日志配合监控告警让成本波动第一时间暴露。LangChain4J在AiServices上有日志和监听器机制我建议至少输出每个请求的totalTokenCount和响应时长。有了这份数据成本优化才不是拍脑袋。6. 常见问题与排障实录6.1 结构化输出频繁失败怎么办这是AI服务接入时最高频的问题。模型能生成内容但一执行model.generate(text, MyClass.class)就报错或者返回的字段全是null。排查顺序我一般是这样先确认POJO设计。类必须有无参构造字段要有公开访问方式。用record也行但要注意版本对record的支持细节。再确认模型能力。不是所有模型都支持JSON输出模式如果模型列表里没有明确支持JSON mode或函数调用结构化输出会不稳定。OpenAI的gpt-4o-mini没问题但一些老模型、轻量开源模型就不一定。最后精简输出结构。字段越多、嵌套越深失败率越高。能把10个字段压到5个就压到5个能用String代替嵌套对象就用String。LangChain4J会尽量修正返回格式但尽量毕竟不是保证。还有一种更稳的思路用AiServices 工具调用代替直接生成。把输出结构化结果定义成一次工具调用如实测下来成功率高很多。6.2 工具调用不生效的排查方法工具方法写了、也在AiServices里挂了但模型就是不去调它。这个问题我排查过很多次原因无非这么几类工具类必须是public的方法也要public。如果工具方法所在类是包私有动态代理拿到的方法列表就是空的。检查方法参数如果用了自定义POJO作为参数模型可能不知道如何填值。工具方法和Tool描述冲突时模型也会困惑描述写得太模糊不如不写。还有一个容易被忽视的点模型本身不支持function calling。本地部署的一些老模型对工具调用的支持不完善换一个支持工具调用的模型版本就解决了。排查时可以在日志里看模型返回的JSON如果模型已经在响应里塞了函数调用结构说明链路是通的问题多半出在框架解析或者工具类实例化上。6.3 中文乱码、依赖冲突与版本升级中文乱码在老旧Spring项目里偶尔出现LangChain4J本身对UTF-8处理没有特殊问题但如果你把外部文件读进Document时用了GBK编码输出就会乱。统一使用UTF-8别把这个只当成编码问题它还会影响Token统计。依赖冲突是Java项目永恒的话题。LangChain4J依赖Jackson和SLF4J如果你的项目里还有其他框架带着老版本Jackson可能出现反序列化异常。用mvn dependency:tree检查必要时候在pom.xml里排除传递依赖。版本升级要特别小心。LangChain4J还在快速演进阶段某些注解的包路径从agent.tool挪到了service.toolBuilder方法也可能改名。我建议每次升级都去GitHub看release notes并且用一个小模块做冒烟测试别一把梭升级。最后说点个人的体会用过一段时间LangChain4J之后我最大的感受是它不是什么黑魔法本质上就是帮你把和大模型对话这个工序标准化了让你不需要天天和HTTP协议打交道。真正的业务价值其实出在工具调用和RAG这两个环节——让模型能访问你的数据、能调用你的系统能力它才从一个会聊天的玩具变成能帮忙干活的助手。如果你想验证这个框架到底行不行别急着搞大项目先找一个真实的小功能试水把团队历史工单整理成RAG问答或者给后台加一个AI内容审核助手两周时间就能看到效果。踩过几次坑之后你会同意AI应用开发在Java这头确实已经翻篇了。