1. 为什么Java团队需要自己的RAG知识库系统1.1 从一次内部技术分享的尴尬说起上个月我在团队内部做了一次技术分享主题是“如何让大模型回答我们自己的业务问题”。演示环节我随手问了一句“咱们订单系统的超时补偿逻辑是怎么设计的”模型洋洋洒洒回答了一大段听起来头头是道但在座的几个老同事面面相觑——它说的补偿阈值、重试次数、幂等键设计跟我们系统里实际跑的完全对不上。那一刻我意识到通用大模型的“知识”再广也覆盖不到我们内部沉淀了五六年的业务细节。这就是RAGRetrieval-Augmented Generation检索增强生成要解决的核心问题。简单说RAG就是给大模型配一个“外挂知识库”用户提问时系统先从知识库里检索出最相关的几段资料再把这些资料连同问题一起塞给大模型让它基于真实资料来回答而不是凭记忆瞎编。这个思路听起来不复杂但真正落地到Java技术栈里坑比想象中多得多。我选择用LangChain4j LangGraph4j这套组合来构建原因很直接团队是清一色的Java后端Spring Boot、Maven、MyBatis这套东西闭着眼睛都能写你让我为了做个RAG去学Python生态的LangChain学习成本和维护成本都太高。LangChain4j是LangChain的Java移植版API设计思路一脉相承但完全贴合Java开发者的习惯LangGraph4j则把“多步骤编排”这件事用图的方式表达出来特别适合RAG这种“检索→重排→生成→校验”的多阶段流程。这篇文章适合谁看如果你是有一定Java基础、想在自己项目里落地RAG的后端开发或者正在技术选型阶段纠结用Spring AI还是LangChain4j再或者你已经用Python跑通过Demo但想迁移到Java生产环境那接下来的内容应该能帮你少走不少弯路。我会从整体架构讲到每个环节的具体实现包括我踩过的坑和实测有效的参数配置。1.2 RAG到底解决了大模型的哪些硬伤在动手之前得先把RAG的价值边界想清楚不然很容易做成一个“看起来能用但实际不好用”的玩具。大模型有三个绕不过去的硬伤RAG分别对应解决知识时效性问题。模型的训练数据有截止日期你问它上个月刚发布的内部规范它不可能知道。RAG把最新文档实时检索进来模型就能回答。私有知识缺失问题。公司内部的接口文档、数据库表结构、业务规则这些永远不会出现在公开训练语料里。RAG把这些私有资料作为检索源模型就能“读懂”你的业务。幻觉问题。模型在不确定的时候会编造看似合理的答案这在业务场景里是致命的。RAG通过“基于检索到的原文回答”这个约束大幅降低幻觉概率——注意是降低而不是消除后面我会讲怎么进一步校验。但RAG不是银弹。它解决不了模型本身的推理能力上限也解决不了检索质量差导致的“垃圾进垃圾出”。我见过太多团队兴冲冲搭了个RAG Demo结果检索命中率惨不忍睹最后归咎于“RAG不行”。其实问题往往出在文档切分、向量化策略、检索重排这些细节上这些恰恰是本文的重点。1.3 技术选型LangChain4j、LangGraph4j与Spring AI的取舍热词里有个问题被反复提到“现在到底用Spring AI还是LangGraph4j”我的答案是看你的流程复杂度。如果你的RAG流程是线性的——用户提问、检索、拼Prompt、调模型、返回那Spring AI足够用它的API更简洁和Spring Boot集成更丝滑适合快速验证。但一旦你的流程出现分支、循环、条件判断比如“检索结果置信度低就换个查询重试”“生成后要过一遍事实校验不通过就重新生成”Spring AI的链式调用就会变得很别扭这时候LangGraph4j的图编排优势就出来了。LangGraph4j的核心概念是“状态图”你定义一个共享的State对象然后定义若干Node节点和Edge边每个节点读取State、处理、写回State边决定下一步走哪个节点。这跟工作流引擎的思路很像但更轻量专门为LLM应用设计。我实测下来用LangGraph4j把RAG流程拆成“查询改写→向量检索→关键词检索→结果融合→重排→生成→校验”七个节点每个节点独立可测出问题能精确定位比一坨链式调用好维护太多。至于LangChain4j和LangChain的关系可以理解为“同源不同实现”。LangChain4j不是简单翻译它针对Java生态做了不少适配比如用Maven管理依赖、用Builder模式构建组件、和Spring Boot的自动配置集成。它的开发文档质量不错但更新速度偶尔跟不上LangChain遇到文档没覆盖的API直接看源码比翻文档快。2. 环境搭建与核心依赖配置2.1 Maven依赖清单与版本选择逻辑先把依赖理清楚。LangChain4j的模块化做得比较细你需要什么功能就引什么包不要一股脑全引进来不然依赖冲突会让你怀疑人生。下面是我实测稳定的一套组合properties langchain4j.version0.35.0/langchain4j.version langgraph4j.version0.0.3/langgraph4j.version java.version17/java.version /properties dependencies !-- LangChain4j核心 -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j/artifactId version${langchain4j.version}/version /dependency !-- 对接OpenAI兼容接口的模型 -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-open-ai/artifactId version${langchain4j.version}/version /dependency !-- 向量存储这里用内存版做演示生产换PGVector -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-embeddings-all-minilm-l6-v2/artifactId version${langchain4j.version}/version /dependency !-- LangGraph4j图编排 -- dependency groupIdorg.bsc.langgraph4j/groupId artifactIdlanggraph4j-core/artifactId version${langgraph4j.version}/version /dependency !-- 文档解析PDF和Word -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-document-parser-apache-pdfbox/artifactId version${langchain4j.version}/version /dependency dependency groupIdorg.apache.poi/groupId artifactIdpoi-ooxml/artifactId version5.2.5/version /dependency /dependencies版本选择上有个经验LangChain4j的0.35.0是我目前用下来最稳的版本0.36.x开始有些API做了不兼容调整如果你不是追新党建议锁在0.35.0。LangGraph4j还比较年轻0.0.3版本基本够用但要注意它的API可能在小版本间有变动生产环境务必锁死版本号。Java版本我强烈建议17起步。LangChain4j大量使用了Record、Sealed Class、Pattern Matching这些新特性用Java 8会各种报错。而且17是LTS虚拟线程在21才正式但17的生态兼容性最好。2.2 模型接入OpenAI兼容接口的通用配置不管你用的是哪家的模型服务只要它提供OpenAI兼容的接口LangChain4j都能对接。配置方式如下ChatLanguageModel chatModel OpenAiChatModel.builder() .baseUrl(https://你的模型服务地址/v1) .apiKey(System.getenv(MODEL_API_KEY)) .modelName(你的模型名称) .temperature(0.1) .timeout(Duration.ofSeconds(60)) .maxRetries(2) .build(); EmbeddingModel embeddingModel OpenAiEmbeddingModel.builder() .baseUrl(https://你的模型服务地址/v1) .apiKey(System.getenv(MODEL_API_KEY)) .modelName(你的向量模型名称) .build();这里有几个参数值得说道。temperature设0.1因为RAG场景要的是忠实于检索内容不是发挥创造力温度越低输出越稳定。timeout设60秒RAG的Prompt通常比较长塞了好几段检索结果生成时间会比普通对话长设太短容易超时。maxRetries设2网络抖动时自动重试但别设太多不然一个请求卡住会拖垮整个线程池。API Key千万别硬编码在代码里用环境变量或者配置中心。我见过有人把Key提交到Git仓库第二天就被刷爆了额度。用System.getenv是最低要求生产环境建议走配置中心加密存储。2.3 向量存储选型从内存到PGVector的平滑迁移开发阶段用内存向量存储最方便重启数据就没了适合快速迭代。但生产环境必须用持久化的向量数据库。我的建议是PostgreSQL pgvector扩展理由很实在你们团队大概率已经有PG了不用额外维护一套数据库pgvector的检索性能对于百万级向量完全够用而且它支持SQL过滤和向量检索混合查询这在RAG里非常实用。LangChain4j对PGVector的支持很完善EmbeddingStoreTextSegment embeddingStore PgVectorEmbeddingStore.builder() .host(localhost) .port(5432) .database(ragdb) .user(raguser) .password(yourpassword) .table(knowledge_vectors) .dimension(384) // 必须和embedding模型维度一致 .build();dimension这个参数是重灾区。它必须和你用的向量模型输出维度严格一致all-minilm-l6-v2是384维OpenAI的text-embedding-3-small是1536维。维度对不上插入数据时直接报错。更坑的是如果你中途换了向量模型维度变了之前存的所有向量都得重新生成所以选模型要慎重别频繁换。3. 知识库构建从原始文档到可检索向量3.1 文档加载与解析的实战细节知识库的原料可能是PDF、Word、Markdown、HTML甚至数据库里的工单记录。LangChain4j提供了DocumentLoader体系但实际用起来解析质量参差不齐。我的经验是PDF解析是最容易出问题的环节。Apache PDFBox解析出来的文本经常出现段落错乱、表格内容混在一起、页眉页脚重复出现的问题。我处理过一份产品需求文档解析后每页的“机密”水印都混进了正文检索时经常把水印当内容返回。解决办法是在解析后加一层清洗Document document FileSystemDocumentLoader.loadDocument( Paths.get(/data/docs/需求文档.pdf), new ApachePdfBoxDocumentParser() ); // 清洗去掉页眉页脚、多余空白、特殊字符 String cleanedText document.text() .replaceAll(机密|内部资料|第\\d页, ) .replaceAll(\\s{3,}, \n) .replaceAll([\\x00-\\x08\\x0B\\x0C\\x0E-\\x1F], ); Document cleaned Document.from(cleanedText, document.metadata());Word文档用POI解析相对靠谱但要注意.doc和.docx是两套API.doc用HWPF.docx用XWPF。热词里有人问“java poi word能生成图表吗”答案是能但那是生成方向解析方向我们只关心文本和表格。表格内容建议单独提取出来转成Markdown表格格式再拼回正文这样检索时表格的语义更完整。3.2 文档切分策略为什么固定长度切分是个坑文档切分Chunking是RAG里最容易被低估的环节。很多人直接用固定长度切比如每500字符一刀结果把一句话从中间切断检索出来的片段语义不完整模型看了也懵。我的策略是递归字符切分 语义边界优先。LangChain4j的DocumentSplitters.recursive方法支持按优先级依次尝试分隔符DocumentSplitter splitter DocumentSplitters.recursive( 500, // 目标块大小 50, // 块间重叠 new RecursiveCharacterTextSplitter( List.of(\n\n, \n, 。, , , , ) ) );逻辑是这样的先按空行段落切如果某段还是超过500字符再按换行切再超就按句号切以此类推。重叠50字符是为了防止关键信息刚好落在切分边界上前后两块都各带一点检索时至少有一块能命中。但递归切分也不是万能的。对于结构化文档比如API文档、数据库表说明更好的做法是按语义单元切分一个接口的说明作为一个块一张表的字段说明作为一个块。这样检索出来的片段自包含不需要前后文就能理解。我处理接口文档时会先用正则把每个接口的段落提取出来再单独向量化。3.3 向量化与入库批量处理的性能优化向量化是调用Embedding模型把文本转成向量这一步是IO密集型操作批量处理能显著提升效率。LangChain4j的EmbeddingStoreIngestor封装了完整流程EmbeddingStoreIngestor ingestor EmbeddingStoreIngestor.builder() .documentSplitter(splitter) .embeddingModel(embeddingModel) .embeddingStore(embeddingStore) .build(); ingestor.ingest(document);但默认配置下它是逐条调用Embedding接口的文档多了会很慢。优化方法是批量向量化把切分后的文本按每批20-50条打包一次性调接口。大多数Embedding服务都支持批量输入能减少网络往返次数。我实测下来批量处理比逐条处理快5-8倍。入库时还有个细节metadata的设计。每个向量块除了文本内容还要存来源文件名、章节标题、页码、更新时间等信息。这些metadata在检索时可以用来过滤比如“只在最近半年的文档里搜”“只搜产品部的文档”。LangChain4j的TextSegment支持附加metadata检索时通过Filter条件筛选。4. 用LangGraph4j编排RAG流程4.1 为什么线性链式调用不够用先说说我为什么从LangChain4j的链式API迁移到LangGraph4j。最初的版本很简单用户提问→向量检索→拼Prompt→调模型→返回。跑通没问题但上线后问题来了用户问“订单超时补偿的重试次数是多少”向量检索返回了三个片段其中两个讲的是支付超时一个讲的是订单超时。模型把三个片段混在一起回答给出了错误的数字。如果我在检索后加一个“重排”步骤把最相关的片段排前面再让模型只基于Top1回答准确率会高很多。但链式API里加这个步骤代码会变得很臃肿。更复杂的是条件分支如果检索结果的相似度分数都低于阈值说明知识库里可能没有相关内容这时候应该走“兜底回复”而不是硬让模型编。链式API处理这种分支很别扭而LangGraph4j的图结构天然支持条件边。4.2 定义StateRAG流程的共享上下文LangGraph4j的核心是State它是一个贯穿整个流程的共享对象。我定义的RAG State包含这些字段public class RagState extends AgentState { // 用户原始问题 private String question; // 改写后的查询用于检索 private String rewrittenQuery; // 向量检索结果 private ListTextSegment vectorResults; // 关键词检索结果 private ListTextSegment keywordResults; // 融合重排后的结果 private ListTextSegment rerankedResults; // 最终生成的答案 private String answer; // 校验是否通过 private boolean validated; // 重试次数 private int retryCount; }State用AgentState作为基类它内部维护了一个Map支持动态存取。每个节点从State里读自己需要的字段处理完写回。这种设计的好处是节点之间完全解耦我可以单独测试“重排节点”的逻辑不用把整个流程跑一遍。4.3 节点设计检索、重排、生成、校验四步走我把RAG流程拆成四个核心节点每个节点职责单一检索节点负责双路召回。一路走向量检索用Embedding相似度找语义相近的片段一路走关键词检索BM25或全文索引找字面匹配的片段。为什么要双路因为向量检索对语义理解好但可能漏掉包含精确术语的片段关键词检索对术语敏感但理解不了同义表达。两路结果融合召回率明显提升。重排节点负责精排。双路召回的结果可能有几十条直接塞给模型会超长且引入噪声。重排用Cross-Encoder模型或者简单的相似度打分对每条结果重新打分取Top3-5条。LangChain4j内置了ReRankingModel接口可以对接Cohere等重排服务也可以用本地的轻量模型。生成节点负责拼Prompt和调模型。Prompt模板很关键我用的模板是这样的你是一个严谨的技术助手。请仅基于以下参考资料回答问题。 如果参考资料中没有相关信息请明确说“根据现有资料无法回答”不要编造。 参考资料 {{context}} 问题{{question}} 回答要求 1. 引用具体资料时标注来源 2. 不确定的内容要说明 3. 保持简洁不要展开无关内容校验节点负责事实核查。生成完答案后再调一次模型或者用规则检查答案里的关键数字、术语是否都能在检索结果里找到出处。找不到出处的部分标记为“待确认”。这个步骤能进一步降低幻觉但会增加一次模型调用延迟会上升。我的做法是对准确性要求高的场景开启校验对响应速度要求高的场景关闭。4.4 条件边让流程学会“知难而退”LangGraph4j的条件边让流程能根据State动态决定下一步。我定义了两个关键分支第一个分支在检索之后如果重排后的最高相似度分数低于0.6说明知识库里大概率没有相关内容直接跳到“兜底回复”节点告诉用户“这个问题我暂时没有找到相关资料建议联系XX”。这比让模型硬编一个答案要诚实得多。第二个分支在校验之后如果校验不通过且重试次数小于2回到生成节点重新生成可以调整Prompt或换模型如果重试两次还不通过返回当前答案并附上“此回答未经完全验证”的提示。graph.addConditionalEdges( rerank, state - { double topScore state.getTopScore(); return topScore 0.6 ? fallback : generate; }, Map.of(fallback, fallbackNode, generate, generateNode) );这种“知难而退”的设计在实际使用中比“强行回答”体验好很多。用户宁可听到“我不知道”也不愿意被一个自信的错误答案误导。5. 检索质量优化从能用到好用5.1 查询改写让用户的问题更适合检索用户提问往往很口语化“那个订单超时了怎么办”。直接拿这句话去检索向量模型可能抓不住重点。查询改写Query Rewriting就是用模型把口语化问题转成更适合检索的查询。我用的改写Prompt将以下用户问题改写为3个适合知识库检索的查询每个查询聚焦一个关键概念。 用户问题{{question}} 输出格式每行一个查询不要编号。比如“订单超时了怎么办”会被改写成“订单超时处理流程”“订单超时补偿机制”“订单超时告警配置”。三个查询分别检索结果合并去重召回率比单查询高不少。但改写会增加一次模型调用延迟上升。我的折中方案是简单问题不改写复杂问题才改写。判断标准是问题长度和是否包含多个实体。这个判断逻辑本身也可以用规则实现不一定非要调模型。5.2 混合检索向量与关键词的互补前面提了双路召回这里展开说融合策略。向量检索和关键词检索的结果怎么合并最简单的是加权融合给两路结果分别打分归一化后按权重相加。我实测下来向量检索权重0.7、关键词权重0.3是个不错的起点具体要根据你的文档特点调。更精细的做法是RRFReciprocal Rank Fusion。热词里有人提到“langchain和langchain4j的默认rrf实现去重逻辑存在缺陷”这个我确实遇到过。RRF的思路是不看具体分数只看排名每条结果的得分是1/(krank)k通常取60。两路结果按这个公式算分再相加排名靠前的自然得分高。但默认实现有个问题去重逻辑不完善。同一个文档片段可能被两路都召回如果不去重它会占两个名额。更隐蔽的是不同切分块可能内容高度重叠因为切分时有重叠区这些也应该去重。我的做法是在RRF之前先用文本相似度比如Jaccard相似度做一轮去重相似度超过0.9的只保留一个。5.3 重排模型的选择与本地化部署重排是提升检索质量最有效的手段之一。Cross-Encoder重排模型会把“查询候选片段”一起输入输出一个相关性分数比向量相似度准确得多。但Cross-Encoder计算量大不适合对全量文档做只适合对召回后的几十条做精排。商用重排服务如Cohere Rerank效果好但按量收费长期用成本不低。本地化部署可以用BGE-Reranker系列LangChain4j可以通过ONNX Runtime加载。我实测BGE-Reranker-Base在中文技术文档上的重排效果比纯向量相似度提升明显Top1命中率从62%提升到81%。如果不想引入重排模型也有轻量替代方案用LLM做重排。把查询和候选片段列表给模型让它输出相关性排序。效果也不错但延迟更高适合对延迟不敏感的场景。6. 常见问题与排查实录6.1 检索命中率低的排查思路检索命中率低是最常见的问题。排查顺序应该是先看切分再看向量模型最后看检索策略。切分问题的典型表现是检索出来的片段语义不完整或者关键信息被切到了相邻块。排查方法是把切分后的块打印出来人工看如果发现大量块以逗号或半个句子结尾说明切分粒度太细或分隔符优先级不对。向量模型问题的典型表现是语义相近但用词不同的查询检索不到。比如搜“如何配置超时”找不到“超时参数设置指南”。这说明向量模型对同义表达的理解不够。解决办法是换更强的向量模型或者在检索前做查询扩展把同义词加进查询。检索策略问题的典型表现是明明知识库里有相关内容但就是排不到前面。这时候要检查是不是只用了单路检索加上关键词检索和重排通常能解决。6.2 模型回答“胡编乱造”的抑制手段即使有RAG模型还是可能编造。抑制手段分三层Prompt层明确要求“仅基于参考资料回答”“没有相关信息就说不知道”。这个约束能挡掉大部分幻觉。检索层提高检索质量确保塞给模型的资料确实相关。如果检索结果本身就不相关模型只能靠编。校验层生成后做事实核查把答案里的关键实体和数字提取出来逐个在检索结果里找出处。找不到的标记出来。这个步骤可以用规则实现字符串匹配也可以用模型实现让模型判断每句话是否有依据。我实测下来三层都开启的情况下幻觉率能从15%左右降到3%以下。代价是延迟增加约40%需要根据场景权衡。6.3 性能瓶颈定位与优化RAG系统的延迟主要花在三个地方检索、重排、生成。定位方法是在每个节点前后打时间戳看哪一步最慢。检索慢通常是向量数据库的问题。检查索引是否建好pgvector要建IVFFlat或HNSW索引检查是不是全表扫描。百万级向量用HNSW索引检索能在毫秒级完成。重排慢是Cross-Encoder的通病。优化方法是减少候选数量召回阶段别取太多或者用更小的重排模型。生成慢取决于模型服务。优化手段包括减少Prompt长度少塞几条检索结果、用流式输出用户感知延迟降低、换更快的模型。下面这张表是我在实际项目中总结的常见问题速查现象可能原因排查方法解决方向检索结果不相关切分粒度过粗/细打印切分块人工检查调整切分参数或改语义切分同义查询搜不到向量模型能力不足用同义句测试检索换模型或加查询扩展答案与资料矛盾Prompt约束不够检查Prompt模板强化“仅基于资料”约束响应时间过长某节点耗时异常节点前后打时间戳定位瓶颈针对性优化重复内容占名额去重逻辑缺失检查召回结果加文本相似度去重表格内容检索不到表格解析丢失结构检查解析后文本表格转Markdown保留结构6.4 数据一致性知识库更新的坑热词里有人问“java怎么保证数据一致性”在RAG场景里这个问题具体化为知识库更新时怎么保证向量库和原始文档一致。我踩过的坑是文档更新了但向量库里还是旧版本检索出来的是过时信息。解决办法是给每个文档块打上docId和version更新时先按docId删除旧向量再插入新向量。LangChain4j的EmbeddingStore支持removeAll按条件删除。但删除和插入不是原子的如果中间失败会出现部分旧向量残留。更稳妥的做法是双写切换新版本写入新表写完后原子切换表名。或者用软删除标记检索时过滤掉已删除的。还有一个隐蔽问题Embedding模型升级。如果你换了向量模型所有历史向量都得重新生成因为新旧模型的向量空间不兼容。这个操作很重建议在低峰期做并且做好回滚预案。7. 一些实测有效的经验参数最后分享几个我调了很久才找到感觉的参数供参考切分块大小500字符、重叠50字符。这个组合在中文技术文档上表现最均衡。块太小语义不完整块太大检索精度下降。500是我试了300、500、800、1000之后的选择。向量检索TopK10关键词检索TopK10融合后取Top5做重排重排后取Top3给模型。这个漏斗式设计兼顾了召回率和精度。直接给模型太多片段它会抓不住重点。相似度阈值0.6。低于这个分数就触发兜底回复。这个阈值需要根据你的向量模型和文档特点微调方法是拿一批已知相关和不相关的问题测试看分数分布。重试次数上限2。校验不通过时最多重新生成两次再多就是浪费资源而且往往说明检索结果本身有问题重试也解决不了。温度0.1TopP 0.9。低温度保证输出稳定TopP 0.9保留一点多样性避免死板。这套参数在我的项目里跑了三个月覆盖了大约两万次查询人工抽检准确率在85%左右。剩下的15%主要是知识库本身缺失或问题超出知识范围属于预期内的失败。如果你刚开始搭建议先用内存向量库和小规模文档跑通全流程把每个节点的输入输出都打印出来看确认逻辑对了再换生产级存储。RAG的调试很依赖对中间结果的观察黑盒调参效率极低。