1. 为什么 Java 开发者现在该认真看一眼 LangChain4j如果你是一个写了几年 Java 的后端最近大概率会有一种微妙的焦虑隔壁做 Python 的同事三行代码就接上了大模型搞出了问答机器人、文档助手、智能客服而自己手里那套 Spring Boot 微服务好像跟这波 AI 应用开发隔了一层。不是不想学是生态确实不一样——Python 那边 LangChain、LlamaIndex 一抓一大把Java 这边能拿得出手的、真正为 Java 工程师设计的 LLM 应用框架其实并不多。LangChain4j 就是在这个缝隙里长出来的东西。它的定位很直接把大模型调用、提示词模板、对话记忆、工具调用、检索增强生成RAG这些能力用 Java 开发者熟悉的方式封装起来让你不用切语言、不用重搭技术栈就能在现有的 Java 项目里把 AI 功能做进去。它不是一个玩具库而是一套有清晰抽象层次的框架核心目标是让 Java 工程师用自己习惯的编程范式去构建 LLM 应用。这篇内容适合谁看三类人。第一类是有 Java 基础、想入门 AI 应用开发但不知道从哪下手的后端工程师第二类是在公司里被安排去调研“我们能不能用大模型做点什么”的技术负责人第三类是用过 Python 方案、但项目主体是 Java、想找一个能落地的 Java 侧方案的开发者。我会从整体设计思路讲到具体实操把每一步为什么这么做、参数怎么选、坑在哪里都讲清楚尽量让你看完能直接动手。需要先说明一点LangChain4j 这个生态迭代很快API 在不同版本之间会有调整。我下面讲的是基于常见稳定版本的实践思路具体到你用的版本类名和方法名可能有细微差异但核心概念和设计逻辑是相通的。你照着思路走遇到 API 变化自己对着官方文档微调即可这才是真正能带走的能力。2. LangChain4j 的整体设计与核心抽象拆解2.1 它到底解决了什么问题要理解 LangChain4j 的价值得先看清楚 Java 开发者接大模型时的原始痛点。最裸的写法是什么用 HttpClient 拼一个 JSON 请求体POST 到某个模型服务的接口然后解析返回的 JSON从一堆嵌套字段里把生成的文本抠出来。这个流程本身不难但一旦你要做稍微像样的应用问题就来了提示词要复用怎么办多轮对话的历史怎么管理模型返回的格式不稳定怎么兜底要接不同的模型供应商难道每个都写一套解析逻辑这些问题在 Python 生态里已经被 LangChain 这类框架解决过了LangChain4j 做的事情本质上是把这些成熟经验用 Java 的方式重新表达。它提供了几个关键抽象ChatLanguageModel统一了不同模型的调用入口PromptTemplate管理提示词模板ChatMemory负责对话记忆EmbeddingModel和EmbeddingStore支撑向量检索AiServices则把上面这些能力组合成一个可以直接调用的 Java 接口。我个人的理解是LangChain4j 最聪明的地方在于它的“声明式”设计。你定义一个 Java 接口加上几个注解框架就帮你把提示词拼接、模型调用、结果解析、记忆管理这一整套流程串起来了。你写的是接口跑起来的是完整的 LLM 交互链路。这种设计对 Java 工程师特别友好因为它贴合我们熟悉的面向接口编程思维。2.2 核心模块的分层逻辑把 LangChain4j 拆开看大致可以分成四层理解这个分层对你后续选型和排错很有帮助。最底层是模型接入层对应ChatLanguageModel、StreamingChatLanguageModel、EmbeddingModel这些接口。这一层负责跟具体的模型服务打交道屏蔽不同供应商的协议差异。你换模型理论上只需要换这一层的实现上层代码不用动。往上一层是能力组件层包括提示词模板、对话记忆、文档加载器、文本分割器、向量存储等。这些是可以独立使用的积木你也可以不用 AiServices自己手动把这些组件拼起来用灵活性更高但代码量更大。再往上是编排层核心就是AiServices。它把模型、记忆、检索器、工具等组装成一个可调用的服务接口是 LangChain4j 里最“魔法”也最省事的部分。最上层是应用层也就是你自己写的业务逻辑。理想情况下你的业务代码只依赖编排层暴露的接口底层的模型细节被完全隔离。这个分层带来的好处是你可以从最底层开始一点点往上用也可以直接用最上层快速出活。新手建议先从 AiServices 入手跑通全流程有了体感之后再往下钻理解每一层在干什么。2.3 为什么选它而不是自己造轮子有人会问这些封装我自己也能写为什么要用框架我的经验是自己写一个能跑的 demo 很容易但写一个能上生产的、考虑周全的方案很难。举几个 LangChain4j 已经帮你处理好的细节模型返回的 JSON 格式不稳定时怎么重试和纠正、对话历史超出上下文窗口时怎么截断、流式输出时怎么处理分块和异常、工具调用的参数怎么从模型输出里安全解析。这些坑你迟早会踩框架帮你踩过了你就能把精力放在业务上。当然用框架也有代价就是多了一层抽象出问题时排查链路变长。所以我的建议是先用框架快速验证同时理解它背后的原理等真正遇到框架解决不了的问题时你有能力绕过它自己实现。这也是我写这篇内容想达到的效果——不只教你调 API更让你理解这套东西是怎么转起来的。3. 环境准备与第一个可运行示例3.1 依赖引入与版本选择LangChain4j 是模块化的你不需要一次性引入所有东西。核心依赖是langchain4j-core但实际开发中你通常直接引入具体模型供应商的 starter。以常见的 OpenAI 兼容接口为例Maven 里大致是这样dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-open-ai/artifactId version0.35.0/version /dependency dependency groupIddev.langchain4j/groupId artifactIdlangchain4j/artifactId version0.35.0/version /dependency版本号这里我要提醒一句LangChain4j 迭代快不同版本 API 差异不小。0.3x 系列和更早的 0.2x 系列在 AiServices 的用法上就有变化。你引入依赖后第一件事是去确认你用的版本对应的文档别拿着旧教程硬套新版本那是最容易浪费时间的地方。如果你用的是 Spring Boot还有对应的langchain4j-spring-boot-starter能通过配置文件管理模型参数更适合生产项目。新手阶段我建议先不用 starter手动创建模型对象这样每一步发生了什么你都看得见。3.2 模型对象的创建与参数含义创建模型对象是第一步。以 OpenAI 兼容接口为例典型写法是这样ChatLanguageModel model OpenAiChatModel.builder() .baseUrl(https://your-model-endpoint/v1) .apiKey(your-api-key) .modelName(your-model-name) .temperature(0.7) .timeout(Duration.ofSeconds(60)) .build();这里几个参数值得展开说。baseUrl指向模型服务的地址很多兼容 OpenAI 协议的服务都可以用这个方式接入。modelName是你要调用的具体模型标识。temperature控制输出的随机性取值一般在 0 到 2 之间越低越确定、越高越发散。做事实性问答、信息抽取这类任务我一般设 0.1 到 0.3做创意文案、头脑风暴可以设到 0.8 以上。timeout一定要设大模型响应慢是常态不设超时你的线程可能一直挂着。注意apiKey 千万不要硬编码在代码里提交到仓库。用环境变量或者配置中心管理这是最基本的安全习惯我见过太多因为密钥泄露被刷爆额度的案例。3.3 跑通第一段对话模型对象建好之后最简单的调用就是发一条消息String answer model.generate(用一句话解释什么是向量数据库); System.out.println(answer);generate方法接收一个字符串返回模型生成的文本。这一步跑通说明你的网络、密钥、模型名都没问题。如果报错优先检查三件事baseUrl 是否可达、apiKey 是否有效、modelName 是否拼写正确。这三个是最常见的翻车点。跑通单轮之后你可以试试多轮。但这里有个关键认知generate是无状态的它不记得你上一句说了什么。要实现多轮对话你得自己把历史消息带上或者用 LangChain4j 的记忆组件。这就是下一节要讲的内容。4. 对话记忆与 AiServices 声明式开发4.1 为什么需要对话记忆大模型本身是无状态的每次调用都是独立的。你跟它说“我叫张三”下一句问“我叫什么”它答不上来因为第二次调用它根本没看到第一句。要实现连贯对话就得在每次请求时把之前的对话历史一起发过去。手动管理历史很烦你要维护一个消息列表每次调用前把历史拼进去还要控制总长度别超出模型的上下文窗口。LangChain4j 的ChatMemory就是干这个的。最常用的是MessageWindowChatMemory它保留最近 N 条消息ChatMemory memory MessageWindowChatMemory.withMaxMessages(20);withMaxMessages(20)表示最多保留 20 条消息超出的旧消息会被丢弃。这个数字怎么定取决于你的模型上下文窗口大小和单条消息的平均长度。上下文窗口是模型一次能处理的最大 token 数历史消息、当前问题、模型回答都算在里面。如果你保留太多历史可能挤占当前问题的空间保留太少对话又接不上。20 条是个常见的起步值实际用的时候根据场景调。4.2 AiServices 的声明式玩法手动拼记忆、调模型、解析结果代码写起来还是啰嗦。AiServices 把这套流程封装成了一个接口。你定义一个接口interface Assistant { String chat(String userMessage); }然后用 AiServices 把它组装出来Assistant assistant AiServices.builder(Assistant.class) .chatLanguageModel(model) .chatMemory(memory) .build();之后你就可以像调普通 Java 方法一样调它String reply assistant.chat(你好我叫张三); String reply2 assistant.chat(我叫什么名字);第二次调用时框架会自动把第一次的对话历史带上模型就能答出“你叫张三”。这就是声明式开发的威力——你只描述“我要一个能对话的助手”具体怎么拼提示词、怎么管记忆、怎么调模型框架全包了。我实测下来这套机制在快速原型阶段效率极高。但它也有代价你对底层流程的控制变弱了。所以我的建议是原型阶段用 AiServices 快速验证等需求明确、要精细化控制时再考虑手动组装组件。4.3 系统提示词与角色设定一个只会聊天的助手没什么用你得给它设定角色和边界。LangChain4j 支持通过注解或者系统消息来设定。用注解的方式interface Assistant { SystemMessage(你是一个专业的 Java 技术顾问只回答 Java 相关问题其他问题礼貌拒绝。回答要简洁多用代码示例。) String chat(String userMessage); }SystemMessage里的内容会作为系统提示词发给模型相当于给模型定规矩。这个提示词写得好不好直接决定助手的表现。我的经验是系统提示词要具体、可执行别写“你要专业”这种空话要写“回答控制在 200 字以内”“涉及代码时给出可运行的示例”“不确定的问题要说明不确定不要编造”。越具体模型越听话。提示系统提示词不是越长越好。太长的提示词会占用上下文空间还可能让模型抓不住重点。把最关键的约束放在前面次要的往后放。5. 检索增强生成RAG实战拆解5.1 RAG 要解决的核心问题大模型有两个硬伤一是知识有截止日期训练之后发生的事情它不知道二是它不知道你私有的数据比如你公司的内部文档、产品手册。你直接问它这些它要么答不上来要么一本正经地胡说八道。RAG 的思路很朴素既然模型不知道那我就在提问的时候把相关资料一起塞给它让它基于资料回答。具体流程是把文档切块、转成向量存起来用户提问时把问题也转成向量去向量库里找最相似的几块资料把这些资料和问题一起拼成提示词发给模型。模型看到资料就能给出有依据的回答。这个流程听起来简单但每一步都有讲究。切块切多大、向量模型选哪个、检索返回几块、怎么拼提示词都会影响最终效果。下面我拆开讲。5.2 文档加载与切分的关键参数第一步是把文档读进来。LangChain4j 提供了各种DocumentLoader能读文本、PDF、网页等。读进来之后是切分这一步最容易被忽视但影响巨大。为什么要切分因为模型上下文窗口有限你不可能把一整本书塞进去。而且检索的粒度太粗找出来的资料会包含大量无关内容干扰模型判断。切分的核心参数是块大小chunk size和重叠大小overlap。块大小一般设 300 到 800 个字符或 token看你的分割器按什么算。太小单块信息不完整太大检索精度下降。重叠大小一般设块大小的 10% 到 20%目的是让相邻块之间有内容重叠避免一个完整的句子被硬生生切断导致语义丢失。DocumentSplitter splitter DocumentSplitters.recursive(500, 50); ListDocument chunks splitter.split(document);这里recursive表示递归分割它会优先按段落分段落太大再按句子分句子还大再按字符分。这种策略比单纯按固定长度切要合理得多因为它尽量保持语义单元的完整。5.3 向量化与检索的实操要点切好的块要转成向量存起来。向量化用EmbeddingModel存储用EmbeddingStore。内存版的InMemoryEmbeddingStore适合测试生产环境一般用专门的向量数据库。EmbeddingModel embeddingModel new AllMiniLmL6V2EmbeddingModel(); EmbeddingStoreTextSegment store new InMemoryEmbeddingStore(); for (Document chunk : chunks) { Embedding embedding embeddingModel.embed(chunk.text()).content(); store.add(embedding, chunk.textSegment()); }检索的时候把用户问题转成向量去库里找最相似的Embedding queryEmbedding embeddingModel.embed(question).content(); ListEmbeddingMatchTextSegment matches store.findRelevant(queryEmbedding, 3);findRelevant的第二个参数是返回的匹配数量一般设 3 到 5。返回太多会塞进无关内容返回太少可能漏掉关键信息。这个值需要根据你的文档特点调没有万能答案。注意向量模型和检索必须用同一个模型。用 A 模型生成的向量拿 B 模型的问题向量去检索结果会完全错乱。这是新手常犯的错误一定要记住。5.4 把 RAG 接进 AiServices手动检索再拼提示词也可以但 LangChain4j 提供了ContentRetriever抽象能直接接进 AiServicesContentRetriever retriever EmbeddingStoreContentRetriever.builder() .embeddingStore(store) .embeddingModel(embeddingModel) .maxResults(3) .minScore(0.7) .build(); Assistant assistant AiServices.builder(Assistant.class) .chatLanguageModel(model) .contentRetriever(retriever) .build();这样配置之后你每次调用 assistant框架会自动去检索相关资料拼进提示词。minScore是相似度阈值低于这个分数的资料会被过滤掉避免把不相关的内容塞给模型。这个阈值设多少要看你的向量模型一般 0.6 到 0.8 之间试。我踩过的一个坑是一开始没设 minScore结果检索出来一堆勉强相关的块模型被这些噪音干扰回答质量反而下降。加上阈值过滤之后效果明显改善。所以别偷懒这个参数值得花时间调。6. 工具调用与常见问题排查6.1 让模型调用你的 Java 方法大模型再强也没法直接查你的数据库、调你的接口。工具调用Tool Calling就是解决这个问题的你把一些 Java 方法暴露给模型模型在需要的时候会告诉你“我要调这个方法参数是这些”你的代码执行完再把结果返回给模型模型基于结果继续回答。在 LangChain4j 里给方法加Tool注解就行class WeatherService { Tool(查询指定城市的当前天气) String getWeather(P(城市名称) String city) { // 实际查询逻辑 return 晴25度; } }然后在 AiServices 里注册Assistant assistant AiServices.builder(Assistant.class) .chatLanguageModel(model) .tools(new WeatherService()) .build();之后你问“北京天气怎么样”模型会识别出需要调用getWeather框架自动执行方法并把结果回传。Tool里的描述很重要模型靠它判断什么时候该用这个工具所以要写清楚工具是干什么的。P注解描述参数含义帮助模型正确填参。提示工具方法的描述要像写给同事看的接口文档一样清楚。模型不理解你的业务它只能靠描述来判断。描述模糊模型就会乱调或者不调。6.2 常见问题速查表实际开发中遇到的问题八成集中在下面这几类。我整理成表方便你对照排查。问题现象可能原因排查方向调用超时网络不通或模型响应慢检查 baseUrl 可达性调大 timeout返回 401/403密钥无效或权限不足核对 apiKey确认账号额度回答答非所问提示词不清晰或温度过高优化系统提示词降低 temperature多轮对话失忆记忆未配置或消息数太少检查 ChatMemory 配置调大窗口RAG 检索不准切块不合理或阈值不当调整 chunk size 和 minScore工具不被调用工具描述不清重写 Tool 描述说明使用场景中文乱码编码不一致统一用 UTF-8这张表覆盖了我遇到的大部分情况。排查的核心思路是先确认基础链路通不通网络、密钥、模型名再确认配置对不对记忆、检索、工具最后才是优化效果提示词、参数。6.3 几个我踩过的坑第一个坑是上下文窗口溢出。有一次我保留了很长的对话历史加上 RAG 检索的资料总 token 数超过了模型上限结果请求直接报错。后来我加了历史截断和资料数量限制问题解决。教训是任何往提示词里塞内容的地方都要考虑总量控制。第二个坑是流式输出的异常处理。流式输出体验好但分块传输过程中如果网络抖动处理起来比一次性返回麻烦。我的做法是给流式接口加完整的异常回调和超时控制别假设网络永远稳定。第三个坑是向量模型选型。一开始我随便选了个向量模型检索效果很差。换了一个针对中文优化的模型之后效果提升明显。向量模型对中文的支持差异很大做中文 RAG 一定要选中文效果好的别想当然。第四个坑是提示词里的变量注入。如果你把用户输入直接拼进提示词用户可能输入一些奇怪的内容干扰模型。虽然 LangChain4j 的模板机制有一定隔离但涉及敏感操作时还是要在业务层做输入校验。7. 从 Demo 到可用一些工程化建议跑通 demo 只是第一步真要放到项目里用还有几件事得考虑。第一是配置外置模型地址、密钥、参数都别写死在代码里用配置文件或配置中心管理方便切换环境。第二是降级方案模型服务可能不稳定要有兜底逻辑比如超时后返回缓存结果或友好提示别让整个功能挂掉。第三是成本控制大模型调用是按量计费的要监控调用量和 token 消耗设置合理的限流和预算告警。第四是日志与可观测把每次调用的输入输出、耗时、token 数记下来出问题时才有据可查。我个人的体会是LangChain4j 帮你解决了“怎么调模型”的问题但“怎么把 AI 功能稳定地跑在生产环境”这个问题框架只能帮你一部分剩下的得靠工程经验。这两件事分开看你就不会对框架有不切实际的期待。最后分享一个我常用的调试技巧当你觉得模型回答不对劲时先把实际发给模型的完整提示词打印出来看看。很多时候问题不在模型而在你拼进去的提示词本身就有问题。看到真实的输入问题往往一目了然。这个习惯帮我省了大量瞎猜的时间。