LangChain4j 实战指南：Java 开发者如何快速接入大模型

1. 从零认识 LangChain4jJava 开发者的大模型接入起点很多 Java 后端同学最近都在琢磨同一件事怎么把大模型能力接进现有的 Spring Boot 项目里。Python 那边生态确实热闹但咱们手里的系统大多是 Java 写的总不能为了调个模型就把整个技术栈换掉。LangChain4j 就是在这个背景下进入视野的——它是 LangChain 理念在 Java 世界的落地实现专门解决 Java 应用与大语言模型之间的对接问题。说白了LangChain4j 干的事情就是帮你把调用大模型这件事标准化。没有它的时候你得自己封装 HTTP 请求、自己处理流式返回、自己管理对话历史、自己拼 Prompt 模板每个模型厂商的接口格式还不一样换一个模型就得改一遍代码。有了它之后这些脏活累活都被抽象成了统一的 API你只需要面向接口编程底层换模型对业务代码几乎透明。这个教程适合谁看如果你是有 Java 基础、想快速把大模型能力集成到项目里的后端开发或者你之前用过 Spring AI 但觉得生态还不够成熟想换个方案试试再或者你是技术负责人正在做技术选型评估那这篇内容都能给你一个可落地的参考。我下面会从环境搭建一路讲到实战踩坑尽量把每个为什么这么选都讲清楚而不是只丢一堆代码让你抄。需要提前说明的是LangChain4j 本身迭代很快不同版本之间 API 有变动。我写这篇内容时参考的是相对稳定的版本区间你在实操时如果发现某个方法签名对不上先去官方仓库的 Release Notes 里确认一下版本差异这是使用快速演进类库的基本习惯。2. 动手之前环境准备与依赖选型的那些门道2.1 JDK 版本与构建工具的选择逻辑LangChain4j 对 JDK 的最低要求是 17这一点没有太多商量余地。为什么是 17 而不是 8 或 11因为它的很多实现用到了 record、sealed interface、模式匹配这些较新的语言特性这些在 17 之前要么没有要么是预览状态。你如果手上还有跑在 JDK 8 上的老项目想接入 LangChain4j 的话要么单独起一个服务做模型网关要么就得推动升级——后者在真实项目里往往比技术本身更难。构建工具方面Maven 和 Gradle 都支持我个人更推荐 Maven原因是 LangChain4j 的模块拆分比较细Maven 的依赖树排查起来更直观遇到版本冲突时mvn dependency:tree一眼就能看出问题。Gradle 当然也能用只是团队协作时如果成员水平参差Maven 的约定优于配置反而省心。依赖引入有个关键点LangChain4j 是模块化设计的你不要一上来就把所有模块都引进来。核心模块langchain4j-core提供了基础抽象但具体对接哪个模型需要引入对应的集成模块。比如对接 OpenAI 风格的接口用langchain4j-open-ai对接国内某些兼容 OpenAI 协议的模型服务也用这个。这种设计的好处是按需引入不会把一堆用不上的东西打进包里。2.2 模型服务接入方式的对比与取舍接入大模型有几种常见路径我列个表帮你快速判断接入方式适用场景优点注意事项官方云服务 API快速验证、中小流量开箱即用无需运维按量计费注意配额和延迟兼容 OpenAI 协议的第三方服务成本敏感、需要特定模型切换成本低协议统一确认协议兼容程度本地部署模型数据敏感、离线场景数据不出内网硬件成本高需要运维能力自建模型网关多模型统一管理灵活可控便于治理开发维护成本高对于新手入门我建议先用云服务 API 把链路跑通别一上来就折腾本地部署。本地部署涉及显存分配、量化精度、推理框架选型一大堆事很容易在环境问题上卡住还没摸到 LangChain4j 的门就放弃了。等链路跑通、对 API 有感觉了再根据实际需求决定要不要往本地部署迁移。配置 API 密钥时有个安全习惯必须养成绝对不要把密钥硬编码在代码里也不要在测试类里写死。正确做法是通过环境变量或者配置中心注入本地开发用.env文件配合读取工具生产环境走配置管理。我见过太多项目把密钥提交到代码仓库的案例一旦仓库权限管理有疏漏就是事故。2.3 第一个可运行的最小示例环境准备好之后先跑一个最小闭环。核心步骤就三步构建模型实例、构建对话链、发起调用。// 构建模型实例baseUrl 和 apiKey 从配置读取 ChatLanguageModel model OpenAiChatModel.builder() .baseUrl(System.getenv(MODEL_BASE_URL)) .apiKey(System.getenv(MODEL_API_KEY)) .modelName(gpt-3.5-turbo) .temperature(0.7) .timeout(Duration.ofSeconds(60)) .build(); // 直接调用 String answer model.generate(用一句话解释什么是依赖注入); System.out.println(answer);这段代码里几个参数值得说道。temperature控制输出的随机性0 到 2 之间值越低输出越确定做代码生成、数据抽取这类任务时建议调到 0.2 以下做创意文案可以调到 0.8 以上。timeout一定要设大模型响应时间波动很大不设超时的话遇到服务端卡顿你的线程就挂在那里了生产环境这是大忌。跑通这个示例之后你会对 LangChain4j 的基本调用模式有个直观感受。接下来才是真正有意思的部分——怎么把这种调用能力组织成可维护、可扩展的工程结构。3. 核心抽象拆解ChatModel、Prompt 与 Chain 的协作方式3.1 ChatLanguageModel 与 StreamingChatLanguageModel 的区别LangChain4j 里最基础的两个接口是ChatLanguageModel和StreamingChatLanguageModel。前者是同步阻塞式调用你发一个请求线程等着拿到完整结果再返回。后者是流式调用模型生成一个字就推一个字适合做打字机效果的对话界面。什么时候用哪个如果你的场景是后台批处理比如批量给商品生成描述文案用同步的就行逻辑简单。如果是面向用户的实时对话强烈建议用流式因为大模型生成一段几百字的回复可能要好几秒同步调用用户会盯着空白屏幕等体验很差流式的话用户能看到文字一个个蹦出来感知延迟低很多。流式调用的代码结构不太一样它用的是回调或者响应式流的方式StreamingChatLanguageModel streamingModel OpenAiStreamingChatModel.builder() .baseUrl(System.getenv(MODEL_BASE_URL)) .apiKey(System.getenv(MODEL_API_KEY)) .modelName(gpt-3.5-turbo) .build(); streamingModel.generate(写一段关于春天的散文, new StreamingResponseHandlerAiMessage() { Override public void onNext(String token) { // 每生成一个片段就推给前端 System.out.print(token); } Override public void onComplete(ResponseAiMessage response) { System.out.println(\n--- 生成完毕 ---); } Override public void onError(Throwable error) { // 错误处理不能省 error.printStackTrace(); } });这里有个容易忽略的点onError回调必须认真处理。流式调用过程中网络抖动、服务端限流都可能触发错误如果你不处理用户看到的就是文字生成到一半突然没了也不知道发生了什么。生产环境里我通常会在onError里记录日志、给前端推一个错误事件、并且考虑是否要重试。3.2 Prompt 模板把变量和指令分离直接拼字符串写 Prompt 是新手最容易犯的错。比如你要做一个翻译功能可能会写成把下面这句话翻译成英文 userInput。这样写短期没问题但当你需要调整指令、增加 few-shot 示例、或者做多语言支持时代码里到处散落的字符串拼接就会变成维护噩梦。LangChain4j 提供了 Prompt 模板机制核心思路是把固定指令和动态变量分离PromptTemplate template PromptTemplate.from( 你是一名专业的{{role}}请将以下内容翻译成{{targetLanguage}}\n{{content}} ); MapString, Object variables new HashMap(); variables.put(role, 技术文档翻译); variables.put(targetLanguage, 英文); variables.put(content, 这个接口用于查询用户订单状态); Prompt prompt template.apply(variables); String result model.generate(prompt.text());模板的好处在于指令的调整集中在一个地方改一处全局生效。而且模板可以外部化配置比如放到数据库或者配置文件中运营人员不用改代码就能调整 Prompt这在需要频繁调优 Prompt 的场景下非常实用。3.3 Chain 的组装思路与适用边界Chain 是 LangChain 体系里的核心概念本质是把多个处理步骤串起来前一步的输出作为后一步的输入。LangChain4j 里虽然没有 Python 版那么丰富的 Chain 类型但基础的顺序链、条件链是支持的。举个实际场景用户输入一段产品反馈你需要先做情感分析如果是负面情绪就生成安抚话术如果是正面就生成感谢话术。这个逻辑用 Chain 表达就很清晰// 伪代码示意链式组装思路 ChainString, String sentimentChain Chain.of(model) .map(input - 判断以下文本的情感倾向只回答positive或negative input); ChainString, String responseChain Chain.of(model) .map(sentiment - { if (negative.equals(sentiment.trim())) { return 用户情绪负面生成一段诚恳的安抚和解决方案说明; } else { return 用户情绪正面生成一段感谢和邀请继续反馈的话术; } });不过我要泼一盆冷水不是所有场景都适合用 Chain。如果你的逻辑就是调一次模型拿结果那直接调model.generate()最清晰硬套 Chain 反而增加理解成本。Chain 的价值在于多步骤、有依赖关系的流程编排步骤少于两步的基本没必要用。我见过一些项目为了看起来架构先进把简单调用包装成好几层 Chain结果调试的时候链路追踪都费劲这是典型的过度设计。4. 对话记忆与上下文管理让模型记住聊过什么4.1 为什么大模型本身没有记忆这是新手最容易困惑的地方我上一轮告诉模型我叫什么下一轮问我叫什么它就不记得了。原因在于大模型的 API 调用是无状态的每次请求都是独立的模型不会自动保存你之前的对话。所谓记忆其实是每次请求时把历史对话一起发给模型让它基于完整上下文来回答。理解这一点非常关键因为它直接决定了你的架构设计。对话历史存在哪里、存多长、怎么裁剪这些都是你要做的决策而不是模型帮你搞定的。4.2 ChatMemory 的几种实现与选择LangChain4j 提供了ChatMemory抽象常见实现有基于内存的MessageWindowChatMemory和基于持久化的实现。内存版适合开发测试和单机小流量场景它用一个滑动窗口保存最近 N 条消息超出窗口的自动丢弃。ChatMemory memory MessageWindowChatMemory.withMaxMessages(20); Assistant assistant AiServices.builder(Assistant.class) .chatLanguageModel(model) .chatMemory(memory) .build(); // 第一轮 assistant.chat(我叫张三在做电商系统); // 第二轮模型能记住上面的信息 String reply assistant.chat(我叫什么做什么的);withMaxMessages(20)这个参数需要根据实际情况调。窗口太小模型记不住稍早的信息窗口太大每次请求携带的 token 数量暴涨成本和延迟都上去了。我的经验值是客服类对话 10 到 20 条够用长文档分析类可能需要 50 条以上但这时候更推荐用摘要压缩而不是单纯扩大窗口。4.3 持久化记忆的工程实现要点生产环境的对话记忆肯定不能只放内存服务重启就丢了。持久化方案通常是存数据库每次对话前加载历史对话后追加保存。这里有几个工程细节值得注意。第一是存储结构设计。不要只存一个拼接好的大字符串要按消息维度存每条记录包含角色user/assistant/system、内容、时间戳、会话 ID。这样你才能做灵活的查询和裁剪。第二是并发问题。同一个用户可能在多个设备上同时对话如果两个请求同时读写同一个会话的历史可能出现覆盖。简单做法是给会话加锁或者用乐观锁版本号控制。高并发场景下更推荐把同一会话的请求路由到同一节点处理。第三是历史裁剪策略。除了按条数裁剪还可以按 token 数裁剪因为不同消息长度差异很大按条数裁可能裁完还是超长。LangChain4j 提供了 token 计数相关的工具可以估算消息的 token 消耗据此做更精确的裁剪。// 按 token 数控制记忆窗口的思路 ChatMemory memory TokenWindowChatMemory.withMaxTokens(2000, new OpenAiTokenizer());4.4 多轮对话中的常见陷阱有个坑我踩过把系统提示词System Message也放进了滑动窗口。系统提示词通常很长而且每轮都需要如果它被窗口挤出去了模型的行为就会突然变得不符合预期。正确做法是把系统提示词单独管理每次请求都固定带上不参与窗口裁剪。另一个坑是历史消息里的敏感信息。用户可能在对话里输入了手机号、身份证号这些如果原样存进数据库就涉及数据安全问题。稳妥的做法是在存储前做脱敏处理或者在系统提示词里明确要求模型不要复述敏感信息同时后端做一层过滤。5. AiServices 声明式编程把接口变成 AI 能力5.1 声明式接口的设计哲学前面我们都是手动构建模型、手动拼 Prompt、手动管理记忆代码写起来还是有点繁琐。LangChain4j 提供了一个更优雅的方式AiServices。你只需要定义一个 Java 接口用注解描述每个方法要做什么框架会自动帮你生成实现。这种声明式风格的好处是业务代码极其干净你面向的就是普通的 Java 接口调用方完全感知不到背后是大模型。这对于把 AI 能力嵌入现有业务系统特别友好因为业务代码不需要引入任何 LangChain4j 的类型。interface CustomerServiceAssistant { SystemMessage(你是一名电商客服语气友好专业回答简洁) String answer(UserMessage String question); }5.2 注解体系详解与参数绑定SystemMessage定义系统角色UserMessage标记用户输入这两个是最基础的。除此之外还有MemoryId用于区分不同会话V用于模板变量绑定。interface OrderAssistant { SystemMessage(你是订单查询助手根据订单号回答用户问题) String queryOrder(MemoryId String userId, UserMessage String question); }MemoryId的作用是让框架知道这条消息属于哪个会话从而加载对应的历史记忆。如果你不做多用户隔离所有对话混在一起那模型就会串台。这个注解配合ChatMemoryProvider使用可以为每个用户创建独立的记忆实例。参数绑定方面V注解可以把方法参数注入到 Prompt 模板里interface Translator { SystemMessage(你是翻译助手) UserMessage(把 {{text}} 翻译成 {{language}}) String translate(V(text) String text, V(language) String language); }5.3 结构化输出让模型返回对象而不是字符串大模型默认返回的是自然语言文本但业务代码往往需要结构化数据。比如你要从用户的一段话里抽取订单号、商品名、数量返回一个 Java 对象比返回一段文字好用得多。LangChain4j 支持让模型输出 JSON 并自动映射到 Java 对象interface OrderExtractor { UserMessage(从以下文本中提取订单信息{{text}}) OrderInfo extract(V(text) String text); } class OrderInfo { String orderId; String productName; int quantity; }这里的关键是模型要能稳定输出符合格式的 JSON。实测下来指令里明确给出 JSON schema 示例、把 temperature 调低、必要时用 few-shot 示例都能显著提升结构化输出的成功率。但即便如此也要做好解析失败的兜底——模型偶尔会加一些解释性文字导致 JSON 解析失败这时候要么重试要么用更宽松的解析策略。5.4 工具调用让模型能执行你的代码工具调用Function Calling是让模型从只会说变成能做事的关键能力。你定义一些工具方法模型在需要的时候会主动调用它们。class WeatherTools { Tool(查询指定城市的天气) String getWeather(P(城市名称) String city) { // 实际调用天气 API return 晴25度; } } interface WeatherAssistant { String chat(String question); } WeatherAssistant assistant AiServices.builder(WeatherAssistant.class) .chatLanguageModel(model) .tools(new WeatherTools()) .build(); // 模型会自动判断是否需要调用 getWeather assistant.chat(北京今天天气怎么样);工具调用的价值在于打通了模型和真实系统的边界。模型可以查数据库、调接口、执行计算而不只是基于训练数据回答。但要注意工具方法的描述Tool里的文字非常关键模型是根据描述来判断什么时候调用哪个工具的。描述写得含糊模型就可能该调不调、不该调乱调。6. 实战踩坑记录那些文档里不会写的问题6.1 超时与重试别让一次抖动拖垮整个请求大模型服务的响应时间波动很大同样的请求可能这次 2 秒返回下次 20 秒还没动静。如果不设超时你的线程池很快就会被占满。我的做法是设置一个合理的超时一般 30 到 60 秒超时后触发重试但重试次数要限制通常 2 次就够了再多就是浪费资源。重试还有个细节不是所有错误都值得重试。网络超时、服务端 5xx 可以重试但如果是 4xx 比如参数错误、鉴权失败重试多少次都没用反而增加无效请求。所以重试策略要区分错误类型。// 配置超时和重试的思路 OpenAiChatModel model OpenAiChatModel.builder() .baseUrl(...) .apiKey(...) .timeout(Duration.ofSeconds(45)) .maxRetries(2) .build();6.2 Token 超限长文本处理的正确姿势每个模型都有上下文长度限制超出限制的请求会直接报错。处理长文档时这个问题特别突出。常见的应对策略有几种分段处理再汇总、用摘要压缩历史、或者选用上下文更长的模型。分段处理听起来简单但实际做的时候要考虑分段边界。按固定字数切可能把一句话切断影响语义。更好的做法是按段落或按语义单元切分。汇总阶段也要注意如果分段结果太多汇总本身又可能超限这时候需要做多级汇总。6.3 流式输出的前端对接问题流式输出在后端是回调但前端通常用 SSEServer-Sent Events或 WebSocket 接收。这里有个常见问题代理服务器或网关可能会缓冲响应导致前端收不到实时推送而是等全部生成完才一次性收到。排查这类问题时先确认网关的缓冲配置再看后端是否正确 flush。另外流式输出和对话记忆的配合也要注意。流式过程中如果用户刷新页面或者断开连接这次对话的内容要不要存进记忆我的做法是只有onComplete回调触发后才保存中途断开的对话不保存避免记忆里出现半截内容。6.4 成本控制别让账单吓到你大模型调用是按 token 计费的输入和输出都算钱。新手容易忽略的是对话历史每次都全量发送轮次多了之后输入 token 会快速增长。一个 20 轮的对话第 20 轮可能要发送前面 19 轮的全部内容输入 token 是累加的。控制成本的手段有几个合理设置记忆窗口、对历史做摘要压缩、把不必要的信息从 Prompt 里去掉、对简单任务用小模型。我一般会在项目里加一个 token 消耗的监控按用户或按接口维度统计发现异常增长能及时定位。7. 从 Demo 到生产还需要补齐哪些能力7.1 可观测性建设Demo 阶段你只关心能不能跑通生产阶段你必须知道每次调用花了多少 token、耗时多久、成功率多少。这些指标要接入现有的监控体系。LangChain4j 提供了监听器接口可以在请求前后插入埋点逻辑。ChatModelListener listener new ChatModelListener() { Override public void onRequest(ChatModelRequestContext context) { // 记录请求开始时间、模型名称 } Override public void onResponse(ChatModelResponseContext context) { // 记录耗时、token 消耗 } Override public void onError(ChatModelErrorContext context) { // 记录错误类型、错误信息 } };7.2 降级与熔断大模型服务不是 100% 可用的可能限流、可能故障。生产系统必须有降级方案。简单场景可以返回预设的兜底话术复杂场景可能需要切换到备用模型。熔断机制也要有当错误率超过阈值时自动切断请求避免雪崩。7.3 Prompt 版本管理Prompt 是 AI 应用的核心资产之一但很多团队把它散落在代码里改了就改了没有版本记录。我建议把 Prompt 当作配置来管理每次修改都有记录方便回溯和 A/B 测试。LangChain4j 的模板机制支持从外部加载配合配置中心就能实现动态调整。8. 一些个人体会LangChain4j 这个库我用了有一段时间最大的感受是它把 Java 接入大模型的门槛确实降下来了。以前要写一堆胶水代码现在用声明式接口几行就能搞定。但它也不是银弹很多工程问题——记忆管理、成本控制、错误处理——框架只能帮你一部分剩下的还得靠自己对业务的理解来设计。新手最容易犯的错是贪多求全一上来就想把 RAG、Agent、工具调用全用上结果每个都半生不熟。我的建议是先跑通最简单的对话把模型调用、记忆管理、错误处理这几个基础环节吃透再逐步往上叠加能力。基础打牢了后面加什么都是水到渠成的事。还有一点别迷信 Prompt 能解决所有问题。有些需求用传统代码实现更可靠、更便宜比如格式校验、数值计算这些交给代码做把模型的精力留给真正需要语义理解的任务。模型和代码各司其职系统才稳。