前阵子帮一个全Java技术栈的团队搭企业内部知识库问答系统方案评审时对方给了个硬约束不引入Python服务不新增运维组件所有代码必须能在现有Java工程里跑起来。我翻遍了GitHub上热门的RAG参考项目几乎清一色Python生态最终把技术选型落到了LangChain4j加LangGraph4j这套组合上。整套系统从0到1搭完文档加载、切片、向量化、检索、大模型生成再到用LangGraph4j做多轮任务编排全部在Java里完成。这篇实战总结就是按我当时的落地路径写的适合已经会Java、想了解或正在做RAG知识库的读者也适合处于技术选型阶段、想评估Java生态到底能走到哪一步的同学。1. Java开发者做RAG为什么绕不开LangChain4j1.1 技术选型的现实困境市面上绝大多数RAG开源项目默认假设你运行在Python环境。LangChain、LlamaIndex、向量数据库的官方示例甚至大多数技术博客里的代码都是Python。这个生态惯性对一个Java团队来说很致命不是因为Java写不了而是因为你需要额外维护一个Python微服务负责文档处理、嵌入、检索、调用大模型Java服务再用HTTP和它通信。两个服务两套日志两套监控踩坑时还要在两个语言栈里来回切。我见过不少团队就是因为这个原因宁愿先上一套土办法把文档灌进Elasticsearch用BM25做关键词检索再用大模型做摘要。但做到第二个月基本都会发现ES关键词检索对同义改写、意图理解、口语化问题完全招架不住。比如用户问最近报销政策有没有变化文档里写的是差旅费用报销细则调整关键词匹配根本命中不了这时候才意识到需要语义检索才回头看RAG应该是完整的召回重排生成链路。在这个背景下LangChain4j几乎是Java社区唯一的成熟选择。它是LangChain思想在JVM上的移植但并不是简单翻译代码而是针对Java开发习惯重新设计了API。它把RAG拆成了几个可以被组合的环节文档加载器、文档转换器、切分器、嵌入模型、向量存储、内容检索器、提示词模板、聊天记忆。这些组件全部支持Java接口你可以用原生Java代码串起来不需要学Python那一套。1.2 LangChain4j的组件体系到底管到了哪一层我用下来最大的感受是LangChain4j的定位很克制。它不像LangChain那样提供一个巨大的Agent框架让你在高层API上做文章而是把模型接入和RAG管道这两件高频事务彻底标准化。模型接入层它统一了ChatLanguageModel和EmbeddingModel两种抽象。无论你接OpenAI、通义、文心还是本地Ollama部署的Qwen、Llama改动都只是换一个构建类业务代码不用动。我后来帮客户把线上模型从云端API切到本地私有化部署只改了二十几行配置代码这个抽象帮了大忙。RAG管道层LangChain4j提供了一套模块化接口。我不需要自己去处理文本分块、向量化入库、相似度检索、拼接Prompt这些重复劳动。更重要的是它还提供了一个叫Easy RAG的模块直接基于文件目录自动完成加载-切分-入库-检索适合快速验证。但如果你想把知识库做成生产系统我建议还是自己拼接一遍这些模块因为你必须知道每一步发生了什么后面调优时才有抓手。1.3 为什么还要引入LangGraph4jLangChain4j解决的是单次RAG问答的问题你给我一个问题我检索、生成、返回答案。但真实的知识库系统不会只有这一步你还需要在多轮对话中判断什么时候该检索、什么时候直接用历史上下文回答你需要处理用户问题指代不清、第一次检索结果质量不佳等场景。这些需求本质上是一个流程编排问题而流程编排恰恰是LangChain4j不擅长的。LangGraph4j把LangGraph的状态图模型带到了Java世界。它允许你把RAG流程定义成一张有向图节点是你的处理逻辑边决定了执行顺序状态对象在节点间传递数据。你可以做条件分支比如判断问题是否需要检索可以做循环比如检索质量不好时重试还可以维护跨轮次的状态让Agent记住前几轮对话的内容。选型时我的判断是用LangChain4j管好单次RAG的零件用LangGraph4j管好整个问答系统的流程两者分工明确不重叠。这也是我最终力推这套组合的原因每一层都有清晰边界出了问题你知道去哪儿找。2. 跑通RAG前必须搞懂的三个底层概念2.1 检索增强的本质给大模型配一个可查的参考资料库RAG全称Retrieval-Augmented Generation核心思想非常朴素大模型训练完之后知识就冻结了而且它对私有数据一无所知。你直接问它咱们公司的请假流程是什么它只能靠训练数据里的通用知识瞎编。RAG做的事情是在它回答之前先从你维护的知识库里检索出与问题相关的内容片段把这些片段塞进提示词让模型基于这些内容组织答案。我用一个生活化类比来解释大模型像一个记忆力很好但容易自信过头的专家RAG相当于给他配了一位档案管理员。专家发言前管理员先翻出相关档案放在他桌上他照着档案讲就不会凭空发挥了。这个类比也说明了RAG的边界如果档案管理员没找到相关资料专家照样会瞎说所以检索质量是整个系统的上限。理解这个本质很重要。很多人刚开始搞RAG时疯狂调提示词发现效果就是不好。原因多半不在生成环节而是检索环节根本没召回有效内容。检索是源头源头没有水后面的Prompt写得再花哨也没用。2.2 切块策略决定知识库质量文档切块是把一份长文档拆成很多个小片段这一步看起来简单实际上直接决定检索质量。切块太大会导致每个片段包含太多无关信息向量化之后语义被稀释检索精度下降切块太小会导致语义不完整比如把一个结论和它的前提条件切开了检索到的片段逻辑上是残废的。常见的切块方式有几种固定字符数切块加重叠窗口比如每块500个字符、重叠50个字符按文档结构切块比如Markdown标题、段落边界按语义切块让模型或算法判断语义的自然边界。我实际测试下来纯固定字符切块在中文场景下效果最差因为中文字符密度高500个字符可能跨越了好几个话题。更好的做法是以段落为单位做基线切分太长的段落再按句子边界二次切分。我建议团队在这个环节多花时间做验证。不要只看检索到了什么要看检索到的片段是否恰好覆盖用户问题的答案。我会在测试集里找若干典型问题逐个看检索返回的Top 3片段如果答案通常出现在第2个或第3个片段说明切块粒度有问题需要调整。这比瞎调Embedding模型参数有效得多。2.3 Embedding与向量检索相似度计算的选型逻辑Embedding把文本映射成高维向量语义相近的文本在向量空间里距离也近。向量检索就是在候选向量里查找与查询向量最接近的若干条。但这里有个常见的认知误区向量检索不是万能的。它对同义改写表现好比如报销政策和费用报销细则能关联上但它对精确关键词的匹配反而弱比如产品型号ABC-100这种向量化之后可能被干扰。所以生产级RAG基本都采用混合检索向量检索负责语义召回关键词检索BM25负责精确匹配最后把两路结果合并去重后再进入生成环节。这个合并算法最常用的叫RRFReciprocal Rank Fusion思路是如果一条结果在多个检索来源里排名都靠前那它比只在一个来源里排名靠前的结果更值得被采纳。关于Embedding模型的选型我有一条实际经验优先选择针对你的文档语言做过优化的模型。中文知识库如果硬套通用英文Embedding模型召回效果会明显打折因为中英文向量空间的语义对齐训练量不均衡。目前国内几个开源中文Embedding模型在中文场景下表现都相当不错而且支持本地部署不依赖外网API。这一点在后文讲本地化部署时还会细说。3. 从空项目到一个能问答的知识库3.1 Maven依赖与项目骨架先建一个标准的Maven项目Java版本建议17以上。LangChain4j的核心依赖分成两层主包和具体模型接入包。以我用的版本为例核心依赖大致是这些dependency groupIddev.langchain4j/groupId artifactIdlangchain4j/artifactId version1.0.0-beta1/version /dependency实际版本号请以Maven Central上的最新稳定版为准它更新比较快我见过太多人卡在版本不一致导致的NoSuchMethodError上。如果你要用OpenAI的模型做实验还需要加dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-open-ai/artifactId /dependency如果用本地Ollama就加langchain4j-ollama。这个设计是LangChain4j比较舒服的地方模型接入是插件化的后面切换模型不用动业务代码。如果要用LangGraph4j做流程编排再加以下依赖。同样注意用最新稳定版本dependency groupIdorg.bsc.langgraph4j/groupId artifactIdlanggraph4j-core/artifactId version1.0.0/version /dependency我第一次搭建时在这里踩了个小坑LangGraph4j的groupId是org.bsc.langgraph4j不是dev.langchain4j它俩是不同组织维护的。搜Maven LangGraph4j时如果看错坐标会下载到完全无关的包。3.2 文档解析、切块与入库的完整代码先准备一些测试文档比如把公司制度、产品手册放到项目的一个目录下。用LangChain4j自带的文件加载器递归加载String documentsPath src/main/resources/knowledge-base; ListDocument documents FileSystemDocumentLoader.loadDocumentsRecursively(Path.of(documentsPath));这一步会读取目录下所有txt、md、pdf等格式的文件。注意如果是PDF依赖里需要额外引入PDF解析库可在官方文档找到适配器。然后做切块。我用的是基于结构的切分器先按段落边界切超过阈值的段落再按递归字符切分DocumentSplitter splitter DocumentSplitters.recursive(500, 50); ListTextSegment segments new ArrayList(); for (Document document : documents) { segments.addAll(splitter.split(document)); }切块之后要给每个TextSegment设置一个全局唯一的ID。这一步看起来多余但后文说RRF去重缺陷时你会知道它有多重要for (int i 0; i segments.size(); i) { segments.get(i).metadata().put(segmentId, String.valueOf(i)); }接下来初始化嵌入模型和向量存储。先用内存版跑通流程生产环境再换真正的向量数据库EmbeddingModel embeddingModel OpenAiEmbeddingModel.builder() .apiKey(你的API Key) .modelName(text-embedding-3-small) .build(); EmbeddingStoreTextSegment embeddingStore new InMemoryEmbeddingStore();入库就是遍历所有片段算好向量后存进去for (TextSegment segment : segments) { Embedding embedding embeddingModel.embed(segment.text()).content(); embeddingStore.add(embedding, segment); }到这里知识库就建立好了。整个过程不到一百行Java代码。第一次跑通时不要追求复杂架构先验证这条管道是通的再逐步加固。3.3 检索与生成的代码实现检索时把用户问题向量化然后在向量存储里查最相似的片段String question 最近报销政策有没有变化; Embedding queryEmbedding embeddingModel.embed(question).content(); ListEmbeddingMatchTextSegment matches embeddingStore.findRelevant(queryEmbedding, 5);findRelevant的第二个参数是Top K我初期设5。然后把这5个片段的文本拼成一个上下文塞进提示词模板String context matches.stream() .map(match - match.embedded().text()) .collect(Collectors.joining(\n\n)); PromptTemplate promptTemplate PromptTemplate.from( 请基于以下参考资料回答问题。 如果参考资料中没有答案请直接说明无法回答。 参考资料 {{context}} 问题 {{question}} ); Prompt prompt promptTemplate.apply(Map.of(context, context, question, question));最后调用大模型生成答案ChatLanguageModel chatModel OpenAiChatModel.builder() .apiKey(你的API Key) .modelName(gpt-4o-mini) .build(); ChatMemory chatMemory MessageWindowChatMemory.withMaxMessages(10); chatMemory.add(UserMessage.from(prompt.text())); ResponseAiMessage response chatModel.generate(chatMemory.messages()); System.out.println(response.content().text());到这个节点你的系统已经能回答基于知识库内容的问题了。但我建议你不要停在Demo阶段因为直接把内存向量存储和手写提示词扔到生产环境很快会踩到一堆更隐蔽的坑。3.4 结果溯源与提示词模板我在给客户做知识库时有一条铁律回答必须带引用来源。RAG模型依然有幻觉风险尤其是检索回来的片段本身有歧义时模型可能会强行圆成一个有逻辑但错误的答案。让模型输出引用来源用户就能自己判断答案是否可信也方便管理员发现知识库里的脏数据。具体做法是在提示词里要求模型标注每句话对应的片段出处片段的metadata里存了文档名和段落号拼上下文时把这些来源信息一起放进去。我在生产代码里是这样组织的String context matches.stream() .map(match - { TextSegment segment match.embedded(); String docName segment.metadata().getString(documentName); String segmentId segment.metadata().getString(segmentId); return [ docName / 片段 segmentId ] segment.text(); }) .collect(Collectors.joining(\n\n));提示词里补充一句回答时在每句话末尾标注来源片段标记模型基本能稳定执行。实测这个改动能让用户对系统的信任度提升一大截因为至少出了问题能查能追溯。4. LangGraph4j把RAG从单次问答升级为任务编排4.1 单次检索在哪些场景下不够用单纯问题进、答案出的RAG在两类场景下会失灵。第一类是多轮对话中的指代问题。用户先问咱们公司的年假制度是怎么规定的得到回答后接着问那加班能调休吗这个那字指向的是上一轮讨论的公司考勤制度但系统只拿当前这一句去检索上下文信息全丢了。第二类是检索质量需要动态决策的场景。有些问题根本不需要检索比如用户问你好或者你能做什么你去知识库里查只会带回一堆无关内容反而干扰回答有些问题则需要多跳检索比如去年的研发投入比前年增长了多少需要先检索出去年的数据再检索出前年的数据才能计算一次检索完全不够。这些问题用单链条代码写会很别扭你会在业务逻辑里塞满if-else而且每加一个分支代码就乱一层。这正是流程编排引擎存在的意义用状态图而不是瀑布流代码来组织行为。4.2 节点、边、状态LangGraph4j的核心抽象LangGraph4j沿用了LangGraph的三个核心抽象节点、边、状态。节点是实际执行逻辑的地方比如检索节点负责查知识库生成节点负责调用大模型边定义了节点之间的流转关系状态是一个在节点之间传递的数据对象通常用一个Map实现节点从里面取需要的数据再把处理结果放回去。我写了一个简单的LangGraph4j流程包含检索和生成两个节点public class RAGGraph { public static class State extends HashMapString, Object { public String question() { return (String) get(question); } public void setQuestion(String question) { put(question, question); } public void setContext(String context) { put(context, context); } public String getContext() { return (String) get(context); } public void setAnswer(String answer) { put(answer, answer); } } public State retrieve(State state) { // 向量检索结果拼成context放进state return state; } public State generate(State state) { // 调用模型结果放进state return state; } }然后构图StateGraphState graph new StateGraph(State::new); graph.addNode(retrieve, this::retrieve); graph.addNode(generate, this::generate); graph.addEdge(START, retrieve); graph.addEdge(retrieve, generate); graph.addEdge(generate, END); CompiledGraphState compiled graph.compile();执行时只需要构造初始状态并调用invokeState initialState new State(); initialState.setQuestion(question); State output compiled.invoke(initialState); System.out.println(output.getAnswer());这段代码看着比直接调用RAG管道多绕了一层但它的价值在于当你需要插入条件分支或循环时不需要重构业务代码只需要改图的拓扑结构。4.3 用条件边实现路由与Agentic RAG条件边是LangGraph4j里最值钱的概念。它允许你在两个节点之间插入一个判断函数根据状态里的数据决定走哪条边。这让我实现了比普通RAG更智能的Agentic RAG路由。先实现一个是否检索的判断节点用流式调用大模型把问题归类为需要检索或不需要检索。不需要检索时直接进入普通对话节点。需要检索时先走检索节点检索结果出来后加一个质量校验节点判断上下文与问题是否相关。如果相关性低可以进入查询改写节点改写后再重新检索形成一个循环。如果相关性高才进入生成节点。伪代码结构大致是这样graph.addNode(classify, this::classify); graph.addNode(retrieve, this::retrieve); graph.addNode(rewrite, this::rewrite); graph.addNode(generate, this::generate); graph.addConditionalEdge(classify, state - needs_retrieval.equals(state.get(intent)) ? retrieve : generate); graph.addConditionalEdge(retrieve, state - Boolean.TRUE.equals(state.get(contextRelevant)) ? generate : rewrite); graph.addEdge(rewrite, retrieve);这就是Agentic RAG的雏形让Agent根据问题内容自己决定什么时候、用什么方式使用检索工具而不是无脑每次检索。实际跑起来后最大的直观感受是闲聊类问题不再被知识库内容干扰回答自然很多复杂的多跳问题也会因为循环机制而更可能找到完整答案。需要注意的是图的状态对象在一次invoke里是共享的所以在改写节点里更新question字段后下游检索节点读到的必须是新值。我习惯把每个节点的输入输出约束好只取自己需要的字段不直接反向修改其他节点依赖的数据源避免状态被改乱后出诡异的并发问题。5. 生产环境里的坑与调优文档里查不到的细节5.1 RRF混合检索合并的去重缺陷与绕过方案这块内容值得单独立一节因为我在网上没搜到几篇讲清楚的。LangChain4j的模块化RAG接口里提供了一个叫CompositeContentRetriever的组件可以把多个检索器组合起来然后用RRF算法做结果合并。RAG的混合检索方案通常会用它一路向量检索一路BM25关键词检索最后RRF合并。我测试时发现一个奇怪现象Top 5结果里经常出现两条几乎一模一样的文本片段只是来源不同。多试几次后确认默认RRF合并对重复内容的处理逻辑并不可靠。它在合并时对同一文档的判定不够严格尤其是两路检索返回的片段ID格式不一致时相同的文本会被当成两个不同的结果都进入候选列表Rank分数各自累加后反而把重复内容顶到了更靠前的位置。排查路径是这样的我先打印两路检索各自的返回结果发现向量检索返回了片段ABM25检索也返回了片段A但两边返回的包含片段A的返回对象在去重判断时没有被识别为同一条。顺着代码往下看发现去重依赖的标识在两种来源里并不统一。这不是我们能直接改源码的问题所以我选择了绕过方案。我的做法是放弃直接用CompositeContentRetriever的默认合并逻辑改成自己拼装分别调用向量检索器和BM25检索器各自拿到Top 20结果。合并前先统一按预先设置的segmentId去重保留在任一路中排名靠前的那个。对去重后的结果列表计算RRF分数。按分数降序取Top 5。这套逻辑写成一个自定义的ContentRetriever替换掉默认组件问题立即消失。核心教训是当开源中间件在特定场景下行为不符合预期时不要硬调参数看清原理后在自己业务层绕过去反而更可控。LangChain4j至少把接口留得足够开自定义替换不费劲。5.2 中文场景的切块、编码与嵌入模型选择中文RAG有几个英文场景不太会遇到的坑。首先是切块中文字符没有天然空格固定按字符数切很容易把一个完整语义切碎。我建议至少以换行符和句号作为硬边界来切割再配合重叠窗口缓解边界切碎问题。编码问题是另一个容易被忽略的地方。Windows环境下读取文档时如果文件是GBK编码而程序默认按UTF-8读切出来的文本会出现乱码向量化后基本是噪声检索效果断崖式下降。我得在文档加载环节强制指定编码并且在入库前打印几个片段抽样检查。宁可多花几分钟检查也不要等上线后被用户反馈答非所问再排查。嵌入模型的选择上中文场景强烈建议用专门针对中文优化过的Embedding模型而不是直接沿用通用英文模型。基于字符还是基于词的训练方式会导致中文语义表达差异很大。我对比过同一套测试集在不同Embedding模型下的召回率中文优化模型明显领先。5.3 RAG不一定用API本地化部署的路径与成本很多Java团队做RAG时第一个疑问就是必须调用云上大模型API吗。答案是否定的。如果你的系统部署在隔离网络环境或者数据安全要求数据不出内网完全可以本地化部署整套RAG链路。本地化部署有两个开销点Embedding模型和Chat模型。Embedding模型参数量小普通CPU服务器就能跑几GB内存足够延迟在百毫秒级完全可接受。Chat模型开销大如果只是内部知识库问答不追求极致的生成质量7B到14B量级的量化模型配合中等配置的GPU服务器就能有可用的效果。我用Ollama部署过Qwen系列模型LangChain4j提供了Ollama接入适配器代码层面基本不需要改动只要把ChatLanguageModel的构建类换掉。但我要泼一盆冷水本地模型的效果和云上旗舰模型有肉眼可见的差距尤其在需要归纳长文档、处理复杂推理时特别明显。我的建议是分场景决策对外客服系统、人命关天的业务数据问答别省这个钱用云上模型内部知识检索、非关键决策支持本地化部署完全够用。先把流程跑通后续有预算再往更好的模型迁移RAG架构本身不绑死某一家模型。5.4 没有评测集调优就是碰运气我在这个项目里犯过最耗时间的错误就是凭感觉调优。当时改了切块大小用几个常见问题试了一下感觉回答还行就上线了。结果真实用户问法五花八门效果很不稳定。后来我痛定思痛专门建了一个评测集用几十个覆盖不同场景的问题每个问题标注了标准答案出自哪篇文档的哪个片段然后每次改动后批量跑一遍看召回率和最终回答的准确率。评测集不用很大50条左右足够发现问题。来源可以分为三类从真实用户会话里挑出来的高频问题、针对每份重要文档人工编写的文档核心问题、以及容易混淆的相似问题对。每次修改切块参数、Embedding模型、提示词模板后跑一遍评测集记录分数。没有这个基准你根本不知道改动到底是变好了还是变坏了。我后来还引入了LLM自动打分把模型生成答案和标准答案一起交给另一个大模型让它从事实准确性和完整性两个维度打分。人工只看打分异常的样本。这套机制帮我节省了大量时间和人力也让调优进入了可量化的循环。6. 进阶方向从RAG到Agentic RAG6.1 多轮对话的查询改写与上下文压缩多轮对话改写的核心思路是不要把用户的原始问题直接送进检索器而是先用大模型把历史对话当前问题转成一个独立的、完整的查询语句。比如用户先说我想了解一下公司年假政策再问那需要提前多久申请改写后的查询是公司年假需要提前多久申请这样检索器拿到的就是完整的语义单位。实现上我在LangGraph4j里加了一个rewrite_query节点放在classify之后、检索之前。这个节点用当前问题、最近两轮对话内容和一段改写指令调用Chat模型生成改写后的查询然后写入State的question字段。改写之后还顺带做上下文压缩把历史对话里冗余的寒暄语去掉只保留与当前问题相关的语义信息控制大模型的上下文窗口占用。实测这个节点带来的提升非常明显。没有改写时多轮问答的召回准确率大概只有单轮的六成加上改写后基本回到单轮水平。而且改写节点本身很轻量只调用一次模型对整体延迟影响不大。我强烈建议任何做知识库多轮问答的团队都加上这一步。6.2 RAG和MCP的关系别把它们搞混很多人会把RAG和MCP放在一起比较问有了MCP是不是就不用RAG了这是完全不同的两件事。MCP全称Model Context Protocol是模型与外部系统交互的标准化协议解决的是大模型如何调用外部工具、如何获取实时数据的问题。RAG解决的是大模型如何基于私有知识库回答问题的问题。一个实用的结合方式是把RAG问答能力封装成一个MCP服务上的工具。大模型在面对用户问题时可以自己决定是调用RAG工具还是调用其他业务API工具。比如用户问最近的天气适合户外活动吗大模型可以同时调用天气查询工具和活动规则知识库检索工具综合两边信息给出答案。从Agent的角度看RAG只是它众多工具中的一种。6.3 知识图谱与Ontology RAG的探索在基础RAG之上我还在测试用知识图谱增强检索效果也就是常说的Ontology RAG或Graph RAG。基础RAG的问题是每个片段都是孤立的片段之间的实体关系没有显式建模。比如张三是某项目负责人和该项目去年超支是两个片段实体层面有关联但向量检索时不一定能同时召回。引入知识图谱后可以从文档里抽取实体和关系构建一个轻量图谱。检索时先向量召回一批候选片段再顺着候选片段里的实体关系把关联的高价值上下文一起拉出来喂给模型。这个思路在处理多实体、多关系的综合性问题上效果明显但它对文档结构有要求真正实践时需要投入额外的实体抽取步骤。我觉得这是RAG下一步的重要演进方向但现阶段如果你的知识库文档是纯文本、非结构化程度高建议先把基础RAG打磨扎实再考虑图谱增强。最后说一点我个人的体会一套RAG系统能不能在生产环境站稳脚跟核心从来不是模型多强、框架多新而是你对自己数据有多了解你的检索链路每一环是否经得起评估集的检验。Java生态做RAG确实起步比Python晚但LangChain4j加LangGraph4j这套组合已经能覆盖从原型到生产的完整路径而且它逼着你用工程化的方式思考问题这反而是件好事。如果你正处在Java团队要上RAG知识库的节点我的建议是别等生态成熟现在就用一套小文档把链路跑通再逐步加深迭代这比观望和争论有价值得多。
