LangChain4j 实战：Java 工程师从零搭建 RAG 与 Agent 应用

Java 生态里做 AI 应用，绕不开的一个库就是 LangChain4j。我最早接触它是在一个内部知识库问答项目上，当时团队想用 Java 把 RAG 链路跑通，试过自己手写 HTTP 调模型、自己拼 Prompt、自己管向量检索，代码写到后面维护成本高得离谱。后来换成 LangChain4j，才发现它把模型接入、Prompt 模板、Embedding、向量库、Agent 这些环节都做了统一抽象，Java 工程师不用切语言就能把一套 AI 应用搭起来。这篇内容就是把我从零上手 LangChain4j 的完整过程拆开讲，包括环境怎么配、RAG 链路怎么搭、多路召回怎么做、Agent 怎么接，以及我踩过的那些坑。适合有 Java 基础、想往 AI 应用方向走的开发者，也适合正在做 RAG 项目、被召回效果和工程结构折磨的同行参考。

1. 为什么 Java 工程师值得花时间在 LangChain4j 上

1.1 从"手搓 HTTP 调模型"到统一抽象

我最早做 AI 功能的时候，思路很朴素：用HttpClient发请求，把 API Key 塞进 Header，JSON 拼一拼就完事。单次对话确实能跑，但一旦要做多轮对话、要接不同厂商的模型、要加检索增强，代码就开始失控。每个模型厂商的请求体格式不一样，返回结构也不一样，切换模型等于重写一遍调用层。更麻烦的是 Prompt 管理，散落在各个 Service 里，改一个提示词要全局搜。

LangChain4j 解决的核心问题就是把这些重复劳动抽象掉。它提供了一套统一的ChatLanguageModel接口，不管你底层接的是哪家模型，上层调用方式基本一致。Prompt 可以用模板管理，Embedding 有统一接口，向量库有标准适配层。你可以把它理解成 Java 版的"AI 应用脚手架"，但它不是框架绑架，而是按需组合，用哪个模块引哪个依赖。

这里有个认知上的转变很重要：很多人以为 LangChain4j 是"另一个大模型 SDK"，其实它更像是一个编排层。模型调用只是它的一小部分，真正有价值的是它把 RAG、Agent、记忆管理这些模式固化成了可复用的组件。你不需要从零设计一套检索流程，它已经把常见套路封装好了。

1.2 和 Python 方案对比，Java 侧的取舍

网上讨论最多的就是"做 AI 到底用 Python 还是 Java"。我的实际体会是：如果只是跑个 Demo、做实验性研究，Python 生态确实更丰富，很多新论文的复现都是 Python 优先。但如果是企业级应用，尤其是已经有 Java 技术栈的团队，硬切 Python 的代价很大——部署链路、监控体系、团队技能都要重建。

LangChain4j 的价值就在这里：它让 Java 团队能在现有工程体系内做 AI 应用。你的 Spring Boot 服务、MyBatis 数据层、现有的权限和日志体系都能直接复用。RAG 里最耗工程能力的部分其实是数据接入、切分、存储、检索这些"脏活"，而这些恰恰是 Java 工程师的强项。模型调用本身反而不复杂，真正难的是把 AI 能力嵌进业务系统，这块 Java 侧有天然优势。

当然也要承认差距：一些最新的 Agent 架构、实验性的检索策略，Python 侧更新更快。但 LangChain4j 的迭代速度这两年明显加快，主流的 RAG、Agent、工具调用能力都已经覆盖。对于绝大多数业务场景，够用了。

1.3 先搞清楚 LangChain4j 的能力边界

上手之前我建议先把它的模块划分搞清楚，不然容易在依赖里迷路。核心模块大致分几块：模型接入层（对接各家对话模型和 Embedding 模型）、Prompt 层（模板、消息角色管理）、记忆层（多轮对话上下文）、检索层（文档加载、切分、向量存储、检索器）、Agent 层（工具调用、任务编排）。

新手最容易犯的错是一上来就想做 Agent，结果连基础的 RAG 都没跑通。我的建议是分阶段：先跑通单轮对话，再加多轮记忆，然后做 RAG 检索，最后才是 Agent。每一层都跑稳了再往上叠，出问题的时候才好定位。下面这张表是我总结的学习路径和对应的核心类，照着走不容易乱：

2. 环境搭建与第一个可运行 Demo

2.1 依赖引入：别一次性全引进来

Maven 项目里引 LangChain4j，最常见的错误是把所有模块一股脑加进去，结果依赖冲突、版本对不上。正确做法是按需引入。基础对话只需要核心包加对应模型的适配包。我一般会先引langchain4j-core和具体模型的 starter，比如对接 OpenAI 兼容接口的模块。

版本管理上，LangChain4j 提供了 BOM（Bill of Materials），强烈建议用 BOM 统一版本，避免各个子模块版本打架。这一点和 Spring Boot 的依赖管理思路一样，用熟了很省心。如果你用的是 Spring Boot，还有专门的 starter 可以简化配置，把模型参数直接写进application.yml。

<dependencyManagement> <dependencies> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-bom</artifactId> <version>0.35.0</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement>

提示：版本号请以官方最新稳定版为准，不同版本 API 有差异，尤其是 0.3x 到 1.x 之间有不少破坏性变更，升级前先看迁移说明。

2.2 API Key 与模型配置的安全做法

API Key 绝对不能硬编码在代码里，这是底线。我见过有人把 Key 直接写进main方法提交到仓库，结果被扫出来盗刷。正确做法是通过环境变量或配置中心注入。本地开发用环境变量，生产环境走配置中心或密钥管理服务。

模型配置上，几个关键参数要理解清楚。temperature控制输出的随机性，做知识问答建议调低（0.1 到 0.3），做创意生成可以调高。maxTokens限制单次输出长度，设太小会导致回答被截断，设太大浪费成本。timeout一定要设，默认值有时候偏长，网络抖动时会把线程挂住。

ChatLanguageModel model = OpenAiChatModel.builder() .apiKey(System.getenv("MODEL_API_KEY")) .baseUrl(System.getenv("MODEL_BASE_URL")) .modelName("gpt-4o-mini") .temperature(0.2) .timeout(Duration.ofSeconds(30)) .maxRetries(2) .build();

maxRetries这个参数容易被忽略，但很实用。模型服务偶尔会返回 429 或 5xx，自动重试能显著提升稳定性。不过要注意重试次数别设太高，否则故障时会放大请求量。

2.3 第一个对话 Demo 与常见报错

跑通第一个 Demo 其实就几行代码，但新手经常卡在几个地方。第一个是网络问题，如果模型服务在境外，请求超时是常态，这时候要么换国内可访问的服务，要么检查网络配置。第二个是模型名称写错，不同厂商的模型名格式不一样，写错了会返回 404。第三个是返回内容解析失败，通常是响应格式和预期不符。

public class FirstDemo { public static void main(String[] args) { ChatLanguageModel model = OpenAiChatModel.builder() .apiKey(System.getenv("MODEL_API_KEY")) .baseUrl(System.getenv("MODEL_BASE_URL")) .modelName("gpt-4o-mini") .build(); String answer = model.generate("用一句话解释什么是向量检索"); System.out.println(answer); } }

跑通之后别急着往下走，先做一件事：把日志打开。LangChain4j 支持请求和响应的日志记录，能看到实际发出去的 Prompt 和拿回来的原始响应。这个在调试 RAG 的时候是救命稻草，因为很多时候问题出在 Prompt 拼接上，不看原始请求根本发现不了。

3. RAG 链路搭建：从文档到可检索知识库

3.1 RAG 到底解决了什么问题

先说清楚 RAG 的定位。大模型的知识是训练时固化的，它不知道你公司内部的文档、不知道最新的业务规则。你直接问它，它要么答不上来，要么一本正经地胡说。RAG（检索增强生成）的思路是：先从你的知识库里检索出相关内容，把这段内容作为上下文塞进 Prompt，再让模型基于这段上下文回答。

这样做的好处很明显：知识可以随时更新，不用重新训练模型；回答有据可查，能给出引用来源；成本比微调低得多。但 RAG 不是银弹，它的效果高度依赖检索质量。检索不准，模型再强也白搭。这也是为什么"RAG 瓶颈"成了热词——很多人搭完发现效果不好，问题基本都出在检索环节。

3.2 文档加载与切分：粒度决定召回质量

文档切分是 RAG 里最容易被低估的环节。我一开始图省事，按固定长度硬切，结果一句话被切成两半，检索出来的片段语义不完整，模型理解不了。后来改成按段落和语义边界切分，效果明显好转。

切分粒度要平衡两件事：片段太大，检索时噪声多，一个片段里混了好几个主题；片段太小，语义不完整，模型拿到的上下文不够。我的经验值是每段 300 到 500 字，同时设置一定的重叠（overlap），避免边界处的信息丢失。重叠比例一般设 10% 到 20%。

DocumentSplitter splitter = DocumentSplitters.recursive(500, 50); List<Document> documents = FileSystemDocumentLoader.loadDocuments( Paths.get("/data/docs"), splitter);

recursive切分器会优先按段落、句子这些自然边界切，实在不行才硬切，比纯按字符数切要合理得多。如果你的文档是 Markdown 或 HTML，还有专门的解析器能保留结构信息，检索时能利用标题层级做过滤。

3.3 Embedding 模型选型与向量存储

Embedding 就是把文本转成向量，语义相近的文本向量距离也近。选 Embedding 模型主要看几个维度：维度大小、支持的语言、检索效果、调用成本。维度越高表达能力越强，但存储和计算成本也越高。中文场景要特别注意模型对中文的支持，有些英文模型在中文上效果会打折。

向量存储这块，LangChain4j 支持多种实现。开发阶段我建议先用内存版，跑通流程再说。生产环境再换成专业的向量数据库。选型时重点看：是否支持元数据过滤、是否支持混合检索、性能和扩展性如何。

3.4 检索器配置与召回效果调优

检索器负责把用户问题转成向量，去向量库里找最相似的片段。最基础的配置是设置返回条数（topK），一般设 3 到 5 条。设太少可能漏掉关键信息，设太多会引入噪声，还会撑爆上下文窗口。

光靠向量检索有个问题：它对关键词匹配不敏感。比如用户问一个具体的产品编号，向量检索可能找不准，但关键词匹配一找一个准。这就是为什么"多路召回"很重要——同时用向量检索和关键词检索，把两路结果合并去重，召回率能明显提升。

EmbeddingStore<TextSegment> store = new InMemoryEmbeddingStore<>(); EmbeddingStoreIngestor ingestor = EmbeddingStoreIngestor.builder() .documentSplitter(DocumentSplitters.recursive(500, 50)) .embeddingModel(embeddingModel) .embeddingStore(store) .build(); ingestor.ingest(documents); ContentRetriever retriever = EmbeddingStoreContentRetriever.builder() .embeddingStore(store) .embeddingModel(embeddingModel) .maxResults(5) .minScore(0.6) .build();

minScore这个参数很关键，它设定了相似度阈值，低于这个分数的片段直接丢弃。不设的话，即使库里没有相关内容，也会硬塞几条不相关的进去，反而误导模型。阈值设多少要实测，一般 0.6 到 0.7 是个起点。

4. 多路召回与检索质量优化实战

4.1 单一向量检索的天花板在哪

我做过一个测试：拿一批真实业务问题去检索，纯向量检索的召回率大概在 70% 左右。漏掉的那 30% 有个共同特点——问题里包含专有名词、编号、缩写，这些词向量模型没见过，转出来的向量和文档里的向量对不上。这就是纯向量检索的天花板。

另一个问题是语义漂移。用户问"退款流程"，向量检索可能召回"退货政策""售后处理"这些语义相近但主题不同的内容。语义相近不等于答案相关，这是两回事。要解决这个问题，得引入更多检索信号。

4.2 向量加关键词的混合召回设计

混合召回的核心思路是：向量检索负责语义匹配，关键词检索负责精确匹配，两路结果合并后重新排序。关键词检索可以用传统的倒排索引，也可以用 BM25 这类算法。LangChain4j 本身对关键词检索的支持相对基础，实际项目里我一般会结合现有的搜索组件来做。

合并策略有两种：一种是简单加权，给两路结果各打一个分，按加权总分排序；另一种是倒数排名融合（RRF），只看排名不看绝对分数，对分数尺度不一致的情况更鲁棒。我实测下来 RRF 更省心，不用反复调权重。

// 伪代码示意：两路召回后融合 List<TextSegment> vectorResults = vectorRetriever.retrieve(query); List<TextSegment> keywordResults = keywordRetriever.retrieve(query); List<TextSegment> merged = reciprocalRankFusion(vectorResults, keywordResults);

4.3 重排序：把真正相关的顶上来

召回之后还有一步很关键：重排序（Rerank）。召回阶段追求的是"不漏"，所以会多召回一些；重排序阶段追求的是"精准"，用更强的模型对候选片段重新打分。重排序模型通常比 Embedding 模型更重，但只对少量候选做计算，成本可控。

加了重排序之后，我那个测试的召回率从 70% 提到了 85% 以上。代价是每次查询多了一次模型调用，延迟增加几百毫秒。对于知识问答这种对准确性要求高的场景，这个代价值得。如果对延迟极其敏感，可以只在召回结果置信度低的时候才触发重排序。

4.4 检索效果评估：别凭感觉调参

调 RAG 最忌讳凭感觉。改了个参数，随便问几个问题觉得"好像好点了"，这种优化不可靠。正确做法是建一个评估集：准备一批真实问题和对应的标准答案，每次调整后跑一遍，看命中率和答案质量的变化。

评估指标我一般看两个：召回率（相关文档有没有被检索出来）和答案准确率（最终回答对不对）。前者反映检索质量，后者反映端到端效果。有了量化指标，调参才有方向，也才能判断一次改动到底是真优化还是碰运气。

5. 用 AiServices 把 RAG 封装成接口

5.1 声明式接口的写法与好处

LangChain4j 有个很好用的特性叫 AiServices，能把 AI 能力声明成 Java 接口。你定义一个接口，加几个注解，它自动帮你生成实现。这样业务代码里调 AI 就像调普通 Service 一样自然，不用到处写模型调用的样板代码。

interface Assistant { @SystemMessage("你是一个严谨的技术助手，只基于提供的上下文回答，不知道就说不知道。") String chat(@UserMessage String question); } Assistant assistant = AiServices.builder(Assistant.class) .chatLanguageModel(model) .contentRetriever(retriever) .build();

这个写法的好处是关注点分离：Prompt 定义在注解里，检索配置在构建时注入，业务代码只管调接口。团队协作时，Prompt 的修改集中在一处，不会散落各处。

5.2 系统提示词的设计要点

系统提示词（System Message）决定了模型的行为边界。做知识问答，我一般会明确几条规则：只基于给定上下文回答、上下文没有就说不知道、不要编造、回答要简洁。这几条能显著降低幻觉。

"不知道就说不知道"这条特别重要。不写的话，模型倾向于硬答，哪怕上下文里没有相关信息，它也会编一个看起来合理的答案。这在企业场景里是灾难，用户分不清哪句是真的。明确要求它承认不知道，反而提升了可信度。

5.3 多轮对话与记忆管理

多轮对话需要维护上下文。LangChain4j 提供了 ChatMemory 组件，可以按窗口大小或 Token 数保留历史消息。窗口设太小，模型记不住前文；设太大，上下文超长会导致请求失败或成本飙升。

我的做法是设置一个合理的消息窗口（比如最近 10 轮），同时对历史做摘要压缩。超出窗口的旧消息不直接丢弃，而是让模型压缩成一段摘要保留。这样既控制了长度，又不丢关键信息。生产环境还要注意内存管理，每个会话的记忆要能过期清理，不然会话一多内存就爆了。

6. Agent 与工具调用：让模型能"动手"

6.1 Agent 和普通对话的本质区别

普通对话是"你问我答"，Agent 是"你给目标，它自己决定怎么做"。区别在于 Agent 能调用工具——查数据库、调接口、执行计算。模型根据任务需要，自己决定调哪个工具、传什么参数，拿到结果后继续推理，直到完成任务。

这个能力很强大，但也更容易出问题。工具描述不清，模型会乱调；没有终止条件，模型可能陷入循环；工具执行失败，模型不知道怎么处理。所以做 Agent 比做 RAG 要更谨慎，边界要划清楚。

6.2 工具定义与参数描述的技巧

定义工具时，描述文字的质量直接决定调用准确率。我见过有人工具描述就写一句"查询数据"，模型根本不知道什么时候该用。好的描述要说清楚：这个工具做什么、什么场景用、参数是什么含义、返回什么。

class OrderTools { @Tool("根据订单号查询订单状态，订单号格式为 ORD 开头的 12 位字符串") String queryOrderStatus(@P("订单号") String orderId) { return orderService.query(orderId); } }

参数描述也要具体。模型是根据描述来决定传什么值的，描述模糊它就会瞎猜。如果参数有格式要求，一定要写清楚，最好给个例子。

6.3 工具调用的边界与安全控制

Agent 能调工具意味着它能产生副作用，这块必须做安全控制。我的原则是：读操作可以放开，写操作必须加确认或权限校验。比如查询类工具随便调，但涉及下单、退款、删除这类操作，要么不让 Agent 直接调，要么加一层人工确认。

另外要设调用次数上限，防止模型陷入循环疯狂调工具。还要做超时控制，单个工具执行太久要能中断。这些防护措施看着繁琐，但线上出过一次事故你就知道值了。

6.4 一个可落地的 Agent 场景拆解

举个我实际做过的场景：智能客服助手。用户提问后，Agent 先判断问题类型——如果是查订单，调订单查询工具；如果是问政策，走 RAG 检索；如果是投诉，转人工。这个流程用 Agent 编排很自然。

实现上，我把订单查询、政策检索、工单创建都封装成工具，系统提示词里说明每种情况的处理方式。实测下来，简单问题 Agent 能自己搞定，复杂问题会转人工，整体分流效果不错。关键是要给它清晰的决策规则，规则越明确，行为越可控。

7. 上线前必须处理的工程问题

7.1 超时、重试与降级策略

AI 应用和传统接口最大的区别是延迟不稳定。模型响应可能几百毫秒，也可能好几秒。上线前必须设超时，并且要有降级方案。我的做法是：设一个合理的超时（比如 10 秒），超时后返回兜底话术或转人工，绝不能让请求无限等待。

重试要谨慎。模型调用不是幂等的场景（比如已经产生了副作用），重试可能造成重复操作。只对明确的网络错误重试，业务错误不重试。重试次数控制在 2 次以内，配合退避策略。

7.2 成本控制与 Token 管理

Token 就是钱，尤其是 RAG 场景，每次请求都要带上检索到的上下文，Token 消耗比普通对话大得多。控制成本有几个手段：精简 Prompt、控制检索条数、对历史做摘要压缩、缓存高频问题的答案。

我还会做 Token 用量监控，按接口、按用户统计消耗。发现异常增长能及时排查，比如某个 Prompt 改坏了导致上下文暴涨。这些监控数据也是后续优化的依据。

7.3 效果监控与持续迭代

上线不是终点。要监控几个关键指标：调用成功率、平均延迟、用户反馈（点赞点踩）、转人工率。这些数据能反映真实效果。我一般会定期抽样看对话记录，找badcase，分析是检索问题还是 Prompt 问题，然后针对性优化。

RAG 的优化是个持续过程。知识库在变，用户问题在变，Prompt 和检索策略也要跟着调。建一套评估和迭代机制，比一次性调好更重要。

8. 我踩过的几个典型坑

第一个坑是切分粒度。早期按固定 200 字切，结果检索出来的片段经常是半句话，模型理解困难。后来改成按语义边界切，粒度放到 500 字左右，效果立竿见影。这个教训是：切分不是越小越好，语义完整性比长度均匀更重要。

第二个坑是相似度阈值没设。一开始检索器不设minScore，不管相不相关都返回 topK 条。结果模型经常被不相关的上下文带偏，答非所问。加上阈值过滤后，虽然偶尔会"检索不到"，但整体准确率反而提升了。宁可说不知道，也别给错误答案。

第三个坑是 Prompt 里没写"不知道就说不知道"。这个前面提过，但值得再强调。不写这条，模型会硬答，而且答得很像真的，特别有迷惑性。加上这条之后，虽然"拒答率"上升了，但用户信任度反而提高了。

第四个坑是 Agent 工具描述太随意。有个工具描述写得太笼统，模型在不该调的时候也调，浪费了大量调用。后来把描述改具体，明确使用场景，误调率大幅下降。工具描述是给模型看的文档，得认真写。

第五个坑是没做超时和降级。有次模型服务波动，请求全部挂起，把线程池占满，整个服务雪崩。后来加了超时和熔断，模型服务出问题时能快速失败，不影响其他功能。AI 调用一定要当成不可靠的外部依赖来对待。

9. 给不同阶段开发者的上手建议

如果你刚接触 LangChain4j，我的建议是先别碰 Agent，老老实实把单轮对话和多轮记忆跑通。这两块是基础，跑通了再往上叠。RAG 是重点，值得多花时间，尤其是切分和检索调优，这两块决定了最终效果的上限。

如果你已经在做 RAG 项目但效果不理想，先别急着换模型。八成问题出在检索环节。检查切分粒度是否合理、有没有设相似度阈值、要不要加混合召回和重排序。把检索质量提上去，效果提升比换模型明显得多。

如果你要做 Agent，先把工具定义和边界想清楚。工具描述要具体，写操作要加防护，调用次数要设上限。Agent 的不可控性比 RAG 高，上线前一定要做充分的测试，尤其是异常路径。

最后说个心态问题：AI 应用的效果没有"一次到位"，都是迭代出来的。别指望调一次参数就完美，建好评估机制，持续观察、持续优化，这才是正道。我做了这么久，每次觉得"差不多了"，总能再找出优化点。保持这个心态，效果会越来越好。