★ FEATURED ARTICLE 做 Java 后端的人看 LangChain 生态多多少少会有点眼馋。Python 那边搭一个带知识库的问答机器人几行代码就能跑起来换到 Java 这边却连个像样的官方 SDK 都难找。LangChain4j 的出现算是把这块短板补齐了它做的是 Java 生态里的大语言模型集成框架对接对话模型、嵌入模型、向量存储、工具调用、RAG 这些能力API 设计贴合 Java 开发习惯Spring Boot 项目里引入一个依赖就能开始写业务逻辑。这篇教程就是给新手准备的实战入门我会把搭环境、写第一个对话、做结构化输出、接知识库、调工具函数这一整套流程完整串一遍再附上我实际踩过的坑和排查思路。适合刚接触 LLM 应用开发的后端工程师也适合从 Python 生态转过来的朋友快速建立对应关系。1. 为什么 Java 开发者需要 LangChain4j1.1 从 Hello World 看 Java 与 Python 的差距先说说我自己的经历。第一次接触大模型应用开发是在一个内部工具项目里需求是让用户用自然语言查询数据库我把 Python 版的 LangChain 示例改写成 Java前前后后踩了三天的坑。最直接的问题是 Python 生态里的一切都帮你封装好了而 Java 这边你要自己处理 HTTP 调用、JSON 序列化、异步回调、重试策略这还只是连接层面的事再往上走还有 Prompt 管理、上下文记忆、向量检索这些逻辑全部手写的话工作量非常可观。当时我就在想Java 这边缺的不只是一个能调用模型的客户端库缺的是像 LangChain 那样的一套完整工具链。LangChain4j 出现之后这个问题算是有了标准答案。它的模块化设计很有意思核心模块只负责对话模型和消息流转上层按需扩展嵌入模型、向量存储、文档解析器等能力你用多少引多少不用担心依赖臃肿。另外优雅的一点是它内置了同步、流式、异步三种调用方式。同步调用适合接口场景流式输出适合聊天场景异步调用适合批处理场景同一个模型对象换一下方法名就能切换不需要改业务代码。Python 生态里这些东西往往是分散在不同库里的而 LangChain4j 选择把它们统一进同一个 API这对 Java 团队来说降低了学习和维护成本。1.2 Java 工程化场景中的真实痛点还有一批人是从企业级应用开发的视角看这个框架的。Java 的基盘在金融、电商、政务、制造这些领域这些场景对稳定性、可观测性、权限管控有硬性要求。Python 的 LLM 应用代码在原型阶段跑得很欢一旦要上生产接监控、配限流、做降级、管理 API Key每条路都得自己铺。我自己经历过的几个痛点LangChain4j 都给出了对应的解决方案。第一是 API Key 管理框架支持把 Key 配置在环境变量或配置中心代码里不写死密钥这符合企业安全审计的要求。第二是模型端点可配置你可以通过统一接口对接不同的模型服务商切换时只改配置不动代码这对那些想避免绑定单一供应商的团队很有吸引力。第三是回调机制框架里内置了 LLM 请求的监听接口你可以记录每次请求的耗时、token 消耗、响应内容为后续的成本分析和质量评估留数据。这些能力对于入门开发者来说可能感知不强但如果你在公司环境里负责落地一个 AI 功能就会发现它们直接决定了这个项目能不能顺利走完审批、测试、上线的流程。我在后面的案例部分会专门演示如何利用这些特性把一个 demo 级别的项目变成一个能上线的工程。2. 起步依赖引入与第一个对话2.1 Maven 依赖的选择与版本策略从一个最小可运行的工程开始讲。我使用的基础依赖是langchain4j主模块它以核心 API 和内存型组件为主适合学习和轻量使用。实际项目中你还会按需引入额外模块比如用于解析 PDF 的langchain4j-document-parser-apache-pdfbox用于向量检索的langchain4j-vectordb-pgvector用于对接某些模型服务商的langchain4j-open-ai风格的适配器选择逻辑可以类比 Spring Boot 的 starter 机制用哪个功能就引哪个依赖。这里有一个值得注意的经验项目里如果同时用到了 Spring Boot 和 LangChain4j版本上尽量选择能互相兼容的组合。我自己刚开始搭建环境时把 LangChain4j 的版本升到了最新结果它依赖的某个 HTTP 客户端库和 Spring Boot 内置版本冲突导致应用启动时直接报 NoSuchMethodError找了一晚上才定位到问题最后是降一个版本解决的。所以入门阶段建议不要追新而是选一个稳定版本组合等到项目稳定后再考虑升级。依赖坐标放在 pom.xml 里的形式大致是这样dependency groupIddev.langchain4j/groupId artifactIdlangchain4j/artifactId version0.35.0/version /dependency这里我没有写具体的最新版本号因为框架迭代很快你直接在依赖仓库搜索langchain4j就能看到当前可用的版本。新手容易犯的错是同时引了多个不同版本的模块比如核心模块用的版本 A向量模块用的版本 B然后出现各种奇怪的不兼容行为。建议在同一项目的 LangChain4J 相关依赖上使用同一个版本号避免混淆。2.2 也许是最短的对话模型 Demo依赖配好后第一个代码示例我们的目标是调用一个大模型让它回答一句话。先看完整的最小样例import dev.langchain4j.model.chat.ChatLanguageModel; import dev.langchain4j.model.openai.OpenAiChatModel; public class QuickStart { public static void main(String[] args) { ChatLanguageModel model OpenAiChatModel.builder() .apiKey(System.getenv(LLM_API_KEY)) .modelName(gpt-4o-mini) .temperature(0.7) .build(); String answer model.generate(用一句话解释什么是数据库索引); System.out.println(answer); } }这段代码做的事情很直白构造一个对话模型对象调用generate方法传入用户消息拿到字符串结果打印出来。如果你用的是其他模型服务商大概率也能找到对应的适配器类构造方式大同小异核心是ChatLanguageModel这个接口抽得足够好模型提供商不同业务代码层几乎感知不到差异。不过到这一步有一些细节值得新手留意。第一API Key不要硬编码在代码里我用的是从环境变量读取的方式这在任何场景下都是安全的做法。第二temperature参数默认是 0.7这个值影响输出的随机性如果做的是分类、抽取这类对准确性要求高的任务建议调低到 0.1 甚至 0如果是闲聊或创意写作可以提高。第三modelName要填模型服务商提供的实际模型标识不同服务商的命名规则不同填错了会直接报错。2.3 预算控制与 Token 计算构造模型时经常被忽略的是 token 限制和成本控制。一次对话的输入加上输出超出模型上下文窗口就会报错。LangChain4j 的ChatLanguageModel接口里没有强制的 token 计算工具但每个模型都有maxTokens配置项限制生成的最大 token 数这能在相当程度上避免费用失控。以我团队的实践为例我们在内部工具里统一做了三层限制第一层在模型配置里设置maxTokens第二层在业务代码里限制了单轮对话的历史轮数只保留最近五轮消息第三层在接入层做了用户级每日调用次数限制。这些策略在 LangChain4j 里都有对应的实现方式例如拆分 MessageWindowChatMemory 来控制上下文长度。虽然入门阶段你可能用不上这些但建议在设计架构时预留位置避免后期改动成本过高。3. 核心能力拆解Prompt 模板、结构化输出与工具调用3.1 用 PromptTemplate 替代字符串拼接大多数新手刚开始会写出这样的代码用字符串拼接把用户输入塞进 prompt 里然后发给模型。这种做法不是不行但一旦 prompt 变复杂拼接处特意空出来的格式、给模型看的注意事项、示例对答等内容混在一起可读性会很糟糕改起来也容易不小心破坏上下文结构。LangChain4j 提供了一套模板机制让你以声明式的方式管理 prompt。举个例子我要做一个商品评论情感分析模板可以这样组织PromptTemplate template PromptTemplate.from( 你是电商平台的评论分析师。请判断下面这条评论的情感倾向是正面、中性还是负面。 只输出情感词不要输出其他内容。 \n评论内容{{text}} ); Prompt prompt template.apply(Map.of(text, 物流很快但是包装有破损商品本身质量不错));模板变量用{{text}}的方式占位你只需要传参数即可。这个机制参照了常见模板引擎的思路但内置在框架里省掉了再多引一组依赖的麻烦。实际使用时它帮我们解决了几个常见问题第一所有 template 可以在代码库里统一管理方便 review第二变量的注入天然规避了拼错引号、转义等低级错误第三测试时可以单独针对模板写用例。3.2 让模型输出干净的结构化数据很多时候我们想要的不是一个“看起来像 JSON”的字符串而是一个可以直接映射成 Java 对象的实例。LangChain4j 里可以通过.json()方法做这一点也可以依赖几种 Java 序列化工具配合实现。关键在于你给模型设定清楚的角色与输出格式约束。我用一个用户意图识别的场景来说明这个需求是判断用户发来的话是想查订单、退换货、投诉还是其他。先定义一个 Java 类public class IntentResult { public String intent; public String confidence; public String params; }然后给出 Prompt 让其输出 JSON并指明字段说明。LangChain4j 会尝试把模型输出解析成目标类型解析失败时会给出原始内容或抛异常。这里有个实际问题大多数模型输出 JSON 时偶尔会带一些多余的说明性文字比如“好的以下是分析结果”开头的废话这会导致反序列化报错。我的解决思路是两方面一是在模板中重复明确“只输出 JSON 对象不要输出任何解释性文字”二是解析时对字符串做预处理截取第一个{到最后一个}之间的内容。3.3 函数调用Function Calling让模型能替你干活学生时代靠规则匹配做聊天气象查询如果对方换一句话术就失效这估计很多人有同感。大模型的 Function Calling 解决的问题就是把意图识别、参数抽取交给大模型把实际的动作交给代码执行。LangChain4j 中函数调用需要借助一个Tool注解的方法。模型在生成响应时会先判断是否需要调用某个工具如果需要就会以 JSON 格式输出一个函数调用请求框架负责把这个请求路由到对应的方法上。给一个例子我想让模型具备查询天气能力只需要定义这样的工具方法Tool(查询指定城市的当前天气) public String getWeather(P(城市名称) String city) { // 这里是模拟数据实际项目里换成你的数据源 return city 晴25℃微风; }把工具放入 AiServices 并绑定给模型之后用户说“北京天气怎么样”模型会自动识别意图并调用getWeather(北京)方法拿到返回值后组织自然语言回复。这套机制的实际意义在于你可以把已有的业务接口封装成工具暴露给模型也就是说大模型成了交互层的新入口但你的核心业务系统并不需要改动太大。4. 实战做一个智能工单分类系统4.1 需求与设计案例选型时我特意挑了一个不太复杂但能串起前面所有知识点的场景客服工单自动分类。典型场景是电商或 SaaS 公司日常会收到大量用户反馈内容五花八门人工分拣成本高所以希望先用大模型自动打上标签例如“物流问题”、“质量投诉”、“退款申请”、“账号异常”同时提取用户 ID、订单号、问题简述等信息方便后续分派给对应组处理。这个需求在引入 LLM 之前我能想到的是训练一个短文本分类模型但样本标注成本很高新类目出现后还得迭代训练。换成 LangChain4j 后整个分类逻辑变成了一段声明式代码加一个结构化输出类人工能快速校验正确率不依赖大量训练样本。整体流程设计成简单的一条链路接收工单内容 → 构造分类 Prompt → 调用模型 → 解析出结构化结果 → 写入工单表。核心的工程点有两处一是把分类标准写清楚二是把输出格式约束好这两点做好效果基本就有保障了。4.2 代码实现与关键配置第一步是定义工单结果类包含类别和提取的信息字段。第二步是写模板把工单原文和分类选项一起传给模型明确要求摘要提取关键信息并输出 JSON。第三步是用AiServices绑定模型与工具实际项目中可能还会在此环节加入向量检索让模型只能从企业资料库中找答案避免胡说八道。我简化后的核心代码大致是这个样子ChatLanguageModel model OpenAiChatModel.builder() .apiKey(System.getenv(LLM_API_KEY)) .modelName(gpt-4o-mini) .temperature(0.0) .build(); ClassifierAgent agent AiServices.builder(ClassifierAgent.class) .chatLanguageModel(model) .build(); TicketClassifyResult result agent.classify(workerContent);注意这里我把temperature设成 0因为工单分类是确定性任务容不得随机发挥。如果你的场景是对话生成可以保持到 0.7 左右抽样式任务则保持更低。值得展开的是 Prompt 部分我会把分类选项逐个写上并补上每种分类的判定要点比如“如果用户提到运费贵应归为物流问题而不是价格投诉”。这个分类规则的清晰程度直接影响模型判断的准确性写的时候可以采用“选项关键词规则说明”的方式并在末尾加上要求只输出 JSON 的约束。4.3 效果验证与优化历程我拿了一百条真实脱敏工单做验证第一版跑出来的准确率大约在 80%。逐个看错误例子主要问题是类别之间的混扰例如质量问题和物流问题经常因为包装破损同时出现而误判。后来我把模板改写得更具体并在每个分类的说明里增加实际场景示例准确率提升到了 92%。这个过程说明大模型应用和传统规则系统不一样它更依赖 prompt 的质量而非代码逻辑的复杂度。错误分析时同样要关注输出解析的异常率排查思路是先打印模型原始输出看 JSON 格式是否正常再判断解析失败是模型问题还是代码问题。为了让结果更有说服力我还在流程里加入了人工确认环节分类置信度高的工单自动流转低的进入人工审核队列。这个策略来源于我的经验大模型应用上生产时不要追求神化全自动设置好置信度护栏能显著降低业务方的信任阻力。5. 常见问题与排查技巧实录5.1 依赖冲突与 NoClassDefFoundError新手最容易碰到的坑集中在依赖冲突上。常见报错是NoClassDefFoundError或NoSuchMethodError根因是多个库引入了不同版本的同一类比如一些 HTTP 客户端库或 JSON 序列化框架。排查思路很直接用依赖树命令把冲突打印出来然后逐个看版本号。比如执行 Maven 的dependency:tree命令检索出相关包的版本再在 pom 里用dependencyManagement锁定一个统一版本即可。我的建议是 LangChain4j 的模块在升级时要保持版本一致我经历过一次只更新了核心模块而没更新相近依赖的模块结果运行时接口签名不匹配排查了较长时间才发现是版本错位。另外Spring Boot 项目注意统一管理 BOM减少内部传递依赖的冲突面。5.2 慢响应、超时与流式输出对话模型的响应时间通常在秒级如果你的业务场景需要控制页面响应建议使用流式接口。LangChain4j 里stream方法可以把生成的 token 逐字推送到客户端用户看到打字效果的同时后端也不必长时间占用同步连接。超时问题需要合理配置底层 HTTP 客户端的连接超时和读取超时。有些模型服务在高峰期的响应可能较慢设置的读取超时太短会导致频繁失败的体验。我在实际项目中遇到的例子是默认超时设置导致批量测试时约 15% 的请求超时后来将读取超时调整到 120 秒并配合重试策略后失败率降到低个位数。注意当用maxRetries时还要考虑接口幂等性避免重复调用造成系统重复写入。5.3 结构化输出解析失败的有效对策模型输出 JSON 时偶尔会在前面加解释、或者多出结尾语气词这类问题很难通过改模型彻底消除。常规做法有两层第一层是模板约束把“只输出 JSON”这一要求写得更严厉一点并且在变量文本前后都标明边界。第二层是代码兜底解析前先对字符串做清洗比如从内容中提取符合条件的 JSON 子串再交给序列化工具。我这里提供一个较为稳健的兜底函数优先尝试整体解析失败则截取大括号范围后重新解析再不行就抛出自定义异常并记录原始内容方便事后分析。记得在日志里输出模型原始回答否则排查时没有数据可供定位。5.4 上下文管理引发的“失忆”问题如果你的应用是多轮对话场景就不能每次只把当前问题发给模型而是要把历史消息一并送入。单纯把历史消息全部拼接在一起很快会超出模型的上下文长度限制导致越用越贵响应也越慢。我在项目里用MessageWindowChatMemory来管理会话记录它按窗口保留最近 N 条消息并自动裁剪更早的内容。这里的 N 需要根据业务场景调整比如客服系统可以保留最近 20 条辅助写作场景则可能需要 50 条甚至更多。需要注意LangChain4j 的 ChatMemory 按 chatId 隔离记忆如果你有多个并发用户在同时对话务必给每个会话分配独立且稳定的 chatId否则会出现串场问题。5.5 成本、延迟与精度三者权衡的真话最后说点不常被教程提到的实际情况。大模型接入业务系统后成本是业务方首先关注的项之一。对于分类、抽取这类高频任务每次请求都走一次大模型接口日调用量上万时成本相当可观。我的建议是考虑分级策略简单规则能过滤的先过滤确定性高的用轻量模型完成复杂场景才调用大模型。延迟同理接入大模型后接口平均响应时间会从原来的几十毫秒变成几秒这在有些业务里是不可接受的。如果你做的是内部工具几秒的等待尚可接受如果是面向 C 端用户的实时查询则需要设计异步化处理并结合缓存与结果预生成机制。在我的实际体会里最值得投入精力的地方是 prompt 设计。同样的模型能力好的 prompt 能让准确率从 70% 提到 95%而不好的 prompt 即使换更贵的模型也未必有明显帮助。LangChain4j 的价值在于把模型调用和业务代码解耦让你可以快速迭代 prompt 而不用频繁改动客户端逻辑但框架本身并不会替你优化 prompt这部分功夫只能靠实践和数据的反馈慢慢磨。
阅读完成 · 觉得有帮助？
