RAG，全称 Retrieval-Augmented Generation，检索增强生成。过去一年这个词几乎成了知识库问答的代名词，但真正用 LangChain4j 动手落地的人，多半会经历一个共同的尴尬：流程全跑通了，答案为什么还是不对。我搭内部文档问答 Demo 时的体会是，RAG 的问题绝大多数不出在模型生成环节，而是出在“检索”这两个字上——文档没切好、向量没选对、检索参数拍脑袋，后面模型再强也是拿到一堆无用上下文硬答。这篇文章把 LangChain4j 里 RAG 相关的链路完整拆一遍，从原理到代码再到调优，适合已经跑通基础聊天功能、准备往知识库场景深入的 Java 开发者。过程中我不会逐个罗列官方 API，重点放在“为什么这么设计”和“实际落地怎么选”上。
1. 先想清楚为什么要加RAG：模型在知识问答面前的三个短板
1.1 知识截止日期和私有数据：模型“没学过”就是没学过
大语言模型的知识边界由训练语料决定，这是一个非常朴素的结论，但很多人落地时会不自觉忘掉。某个新流程这个月刚上线，模型训练语料里根本不存在，你直接让它回答“这个流程具体怎么走”，它只能根据历史类似流程去猜。内部文档更是这样：产品报价、项目复盘、团队 SOP，这些内容大概率不会出现在任何公开语料里，模型是真不会。
这里的本质是：模型是一个“记忆有限”的答题手，不是一个能实时查资料的人。你要么把知识塞进它的记忆，也就是微调；要么把知识摆在它面前让它现场看，这就是 RAG 的思路。对我个人来说，真正理解这一点之后，就不再纠结“为什么模型连公司内部制度都答不上来”这种问题了——它没学过，答不上来才正常。
1.2 幻觉不是 bug，是概率生成的自然结果
模型生成每个词都是基于前面的词算概率，当“正确答案”不在训练数据里，它依然会按最连贯的方式编一个。很多情况下编出来的内容流畅、自信、结构完整，这就是所谓幻觉。幻觉在开放闲聊里不算致命，但在知识库问答里是致命的——用户要的是内部流程，你给一个看起来合理的流程，实际执行时会出问题。
RAG 的价值不是让模型“更聪明”，而是让模型回答问题时“有据可查”，从机制上减少无依据编造的机会。打个比方：传统问答是闭卷考试，RAG 是开卷考试。开卷考也不能保证你答对，因为你还得知道去翻哪一页、翻到之后能不能找到关键信息。但相比闭卷全靠记忆硬编，开卷考的上限显然高得多。
1.3 微调能解决吗？能，但不划算
提到外部知识，总会有人说“那微调模型不就行了”。微调确实可以把特定领域的表达方式和少量知识注入模型，但它的成本和使用场景都和 RAG 不同。一次微调需要准备高质量数据集、训练环境、模型版本管理，整个周期按天甚至按周算，而业务文档可能每天都在变。更关键的是，微调对精确事实的记忆并不可靠，你很难控制模型“准确记住某条规则”而不是“学了感觉后自由发挥”。
所以我会把微调和 RAG 的关系理解成：微调负责风格和能力的底座，RAG 负责动态知识的输入。两者不是替代关系。但做知识问答这类场景，RAG 是性价比高得多的方案。基于 LangChain4j 实现 RAG，不需要训练资源，不需要改模型权重，只需要准备好文档、选好嵌入模型、配好检索链路，就能把企业私有知识接进来。
1.4 RAG 适合什么场景，不适合什么场景
适合的场景很典型：文档问答、客服知识库、产品使用手册、内部制度查询、企业搜索。共同点是有相对稳定、可切分、语义明确的文本，答案可以在一段话里找到依据。不适合的场景也不少：如果文档本身很烂、内容互相矛盾，RAG 只是把烂材料递给了模型；如果问题需要跨多文档归纳推理、对比分析，简单检索再拼接的效果通常一般；如果场景要求绝对实时的数据，比如订单状态，RAG 再快也不如直接调接口。
先判断场景，再决定要不要上 RAG。这是我后来反复强调的一件事。很多人拿着一个会议室预定系统就非要套 RAG，其实那种问题用传统接口查询就够了，没必要让模型来发挥。
2. RAG链路拆开看：切分、向量化、检索、组装各管什么
2.1 文档切分：检索颗粒度的第一道关卡
RAG 的第一步是把原始文档切分成片段。这里有个核心矛盾：片段越大，语义越完整，但混入的无关信息越多，检索精度下降；片段越小，检索越精准，但单个片段往往表达不完整，模型很难从中读出完整逻辑。
常用做法是按句子或段落切分，并保留重叠窗口。比如按句子切分、目标长度 500 字符、重叠 100 字符。为什么需要重叠？因为文档里一句关键信息很可能跨在两个片段的边界上，没有重叠就会被一切为二，检索哪个片段都不完整。中文场景尤其要注意按中文标点切句子，按英文空格切会得到一堆残句，这是很多人第一次跑效果差的原因之一。
| 切分策略 | 优点 | 缺点 | 建议使用场景 |
|---|---|---|---|
| 按段落切 | 语义完整，上下文关系保留得好 | 长段落检索噪声大 | 规章制度、条款类文档 |
| 按句子切 | 检索精准，命中更直接 | 单句信息有限，需靠重叠补全 | 操作手册、问答对、流程步骤 |
| 固定长度切 | 实现简单，长度可控 | 容易切断语义，边界问题严重 | 紧急原型、纯测试环境 |
切分没有银弹，我更习惯的做法是：先用按句子切分配合重叠窗口跑一轮，观察哪些问题检索不到，再看是不是切分粒度的问题。如果经常出现“检索到的片段读上去上下文缺失”，就把片段调大；如果经常检索到一长段但只有一句有用，就调小。
2.2 向量化：嵌入模型决定“语义理解”的上限
切好的文本要变成向量才能被检索。嵌入模型把一段文本映射成一个高维数值数组，语义相近的文本映射后在向量空间里距离也更近。比如“入职流程”和“新员工报到流程”字面不同，但向量距离很近，这样用户用口语化方式提问也能召回相关文档。
选型上有一个大方向需要想清楚：云端接口效果好但数据会出网，内部敏感文档要慎重；本地部署的嵌入模型隐私可控，但需要自己维护推理服务。维度也不是越高越好。高维度向量在存储、计算上的开销更大，实际效果还要看模型对中文语义的适配度。我用过一个通用英文嵌入模型，在处理中文制度文档时，同义改写召回表现明显不如中文微调过的模型，换模型之后指标立刻改善。
这里额外提醒一句：嵌入模型和对话模型是两回事。很多人误以为对话能力强，嵌入能力就强，其实它们训练目标和评估方式完全不同。选择嵌入模型时，要看它在目标语言和目标领域的检索评测表现，而不是看它聊天有多自然。
2.3 相似度检索：TopK、score阈值和元数据过滤
检索时，用户问题先转成向量，然后在向量库里找最近邻。LangChain4j 的 EmbeddingStoreContentRetriever 主要暴露两个参数：maxResults 决定取回多少片段，minScore 决定相似度低于多少不要。这两个参数要配合着调：maxResults 太小会漏关键片段，太大又会在上下文里塞进一堆不相关内容干扰模型；minScore 太高可能一个结果都查不到，太低则召回一堆垃圾。
另外，实际项目里要有“底库”概念，不要一上来就全库检索。给文档打上元数据，比如部门、版本、时间、文档类型，检索时用元数据过滤掉明显无关的分区，效果比单纯靠向量相似度稳定得多。举例来说，某团队的制度文档里有“报销流程”和“采购流程”两种内容，如果用户问题是报销，而数据库里采购文档占了大多数，纯向量召回很容易把采购相关内容混进来。提前用元数据把范围限定在财务相关文档，干扰会小很多。
2.4 增强生成：上下文组装和 Prompt 设计
检索到片段之后，要把片段和用户问题拼成新的 Prompt 交给模型。这一步看起来简单，但 Prompt 写不写清楚差别很大。至少要明确几件事：模型只能根据提供的资料回答；资料中没有的信息要承认不知道，不能编；答案最好标注引用来源编号。
我常用的一句话是：“请基于以下资料回答问题。如果资料无法支持答案，请直接说明资料中没有相关信息，不要自行推断。”这套组合拳能显著压低幻觉，也让答案可溯源。RetrievalAugmentor在 LangChain4j 里就是干这个的，它把检索结果动态拼进 Prompt，开发者只需要配置好检索器和模型。
在多轮对话场景，用户第二句往往带着指代。比如第一句问“报销流程”，第二句问“发票要求是什么”，其实想查的是“报销的发票要求”。这时候如果不做处理，直接拿“发票要求是什么”去检索，很难命中。这就要靠查询压缩组件，把历史对话压缩成独立查询词，这也是QueryTransformer这类组件存在的意义。
3. LangChain4j走一遍完整流程：从文档入库到返回答案
3.1 工程准备：依赖、模型服务和基础配置
以一个真实项目里最常见的配置为例。Maven 工程引入 LangChain4j 主模块和对应模型适配器，版本号不要死盯我下面写的，以你构建时的最新稳定版为准：
<dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j</artifactId> <version>1.0.0</version> </dependency> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-open-ai</artifactId> <version>1.0.0</version> </dependency>对话模型我一般用 gpt-4o-mini 这类成本低、响应快的型号；嵌入模型用 text-embedding-3-small。如果你走的是本地模型方案，换成对应的 Ollama 或 HuggingFace 适配器，后面的代码逻辑几乎不用改。API Key 建议通过环境变量注入，不要写死在代码里，项目里迟早要接配置中心，至少从第一天就不要给自己挖坑。
3.2 索引构建：加载、切分、向量化、入库
索引构建就是把知识库文档变成可检索向量的过程。先用FileSystemDocumentLoader加载文档，它会根据扩展名自动选择合适的解析器，Markdown、TXT、PDF 都能处理。然后切分，再交给EmbeddingStoreIngestor。这个组件是一条完整 pipeline：DocumentSplitter负责切分，EmbeddingModel负责向量化，EmbeddingStore负责存储。
// 加载文档，支持 md、txt、pdf 等格式 Document document = FileSystemDocumentLoader.loadDocument(Paths.get("docs/onboarding.md")); // 切分：按句子切，目标 500 字符，重叠 100 字符 DocumentSplitter splitter = new DocumentBySentenceSplitter(500, 100); // 嵌入模型，负责把文本转成向量 EmbeddingModel embeddingModel = OpenAiEmbeddingModel.builder() .apiKey(System.getenv("OPENAI_API_KEY")) .modelName("text-embedding-3-small") .build(); // 向量存储，这里用内存实现做演示 EmbeddingStore<TextSegment> embeddingStore = new InMemoryEmbeddingStore<>(); // 统一入口：切分 -> 向量化 -> 入库 EmbeddingStoreIngestor ingestor = EmbeddingStoreIngestor.builder() .documentSplitter(splitter) .embeddingModel(embeddingModel) .embeddingStore(embeddingStore) .build(); ingestor.ingest(document);上面这段是 LangChain4j 1.x 里比较标准的用法。注释里也能看出每行代码负责什么。EmbeddingStoreIngestor这个类名字很直白，它就是把文档“吃进去、存下来”。有个细节值得注意：如果文档很大，一次 ingest 多个文档是很正常的，可以循环加载整个目录，而不是只加载一个文件。真实项目里我一般会写一个目录扫描，把 docs 目录下所有支持的文档批量 ingest。
内存向量存储在 Demo 阶段完全够用，但它不支持重启保留，项目重启后索引就没了。可以这样持久化：
InMemoryEmbeddingStore<TextSegment> store = new InMemoryEmbeddingStore<>(); // 入库后保存到本地文件 store.serializeToFile("embedding_store.json"); // 下次启动时加载 InMemoryEmbeddingStore<TextSegment> loadedStore = InMemoryEmbeddingStore.fromFile("embedding_store.json");这个特性在原型验证阶段非常方便，不必为了跑通流程就去部署一个向量数据库。当然，生产环境还是建议上专业向量库，后面第五章我会细说。
3.3 问答链路：ContentRetriever 与 RetrievalAugmentor 怎么配合
索引建好之后，就是问答链路。这一步的核心是定义 Assistant 接口，再用AiServices做代理封装。用户调用 chat 方法，框架内部自动完成检索、增强、生成三步。
interface Assistant { String chat(String message); } // 检索器：用向量存储和嵌入模型完成召回 ContentRetriever retriever = EmbeddingStoreContentRetriever.builder() .embeddingStore(loadedStore) .embeddingModel(embeddingModel) .maxResults(5) .minScore(0.5) .build(); // 检索增强器：把检索结果拼进 Prompt RetrievalAugmentor augmentor = DefaultRetrievalAugmentor.builder() .contentRetriever(retriever) .build(); // 对话模型 ChatLanguageModel chatModel = OpenAiChatModel.builder() .apiKey(System.getenv("OPENAI_API_KEY")) .modelName("gpt-4o-mini") .build(); // 组装成服务代理 Assistant assistant = AiServices.builder(Assistant.class) .chatLanguageModel(chatModel) .retrievalAugmentor(augmentor) .build(); // 测试问答 String answer = assistant.chat("新员工的入职流程是什么？"); System.out.println(answer);这段代码的调用顺序是：用户问题先进ContentRetriever，向量化后到向量库里找最接近的片段；RetrievalAugmentor拿到这些片段，按内部 Prompt 模板组装进上下文字段；最终整个 Prompt 发给ChatLanguageModel生成答案。AiServices把这些串起来，对上层来说就是一个普通的聊天接口。
第一次跑通这种链路的人，很容易产生一种“就这么简单？”的错觉。是的，框架层就是这么简单。真正拉开差距的是后面这些细节：文档切得合理吗？嵌入模型合适吗？maxResults和minScore配得对吗？这些参数直接决定了检索质量。
3.4 一次真实的参数调试记录
我有一份模拟制度文档，包含网络报修、请假审批、会议室预定、采购申请几个板块。拿“网络故障怎么报修”这个问题去测，第一次配置是maxResults=3, minScore=0.7，结果返回的是“抱歉，资料中没有关于网络故障报修的信息”。其实是有的，但 minScore=0.7 太高，所有相关片段相似度都低于阈值，被过滤光了。
把 minScore 降到 0.4，能召回了，但把 maxResults 从 3 调到 10 之后，答案质量反而下降——因为第 4、第 5 个以后召回的基本是“IT 系统使用规范”这类边缘内容，模型把这些内容也当成相关上下文用，开始东拉西扯。
最终稳定的组合是maxResults=5, minScore=0.5。这个教训我反复讲：不要一上来就追求高阈值，先看召回率，再看答案质量。理想状态是日志里能看到召回的片段确实和问题相关，多出来的片段不影响答案走向。如果你看不到“召回了什么”，就等于闭眼调参。
4. 检索质量上不去，先别怪模型：重排序、多路召回与查询改写
4.1 为什么粗排之后还要重排序
向量检索本质是“粗排”。它用嵌入模型把问题和文档分别编码成向量，然后算相似度。这种方式速度快，适合从海量文档里快速捞一批候选，但它有一个天生弱点：问题编码和文档编码是分开做的，它们之间的交互非常浅。
重排序的思路是换一种模式：把问题和文档片段拼接在一起，输入一个专门的模型（交叉编码器），逐对计算相关性。这种模式的精度更高，因为它让问题和文档在模型内部充分交互了。代价是速度慢，所以不能拿它对全库做排序，只能先把候选集缩小到比如 50 条，再精排取前 5 条。
LangChain4j 新版本提供了重排序相关的组件，用法大致是给RetrievalAugmentor配置一个包装过的ContentRetriever，它内部先做一轮粗召回，再对召回结果做精排。如果你用的版本还没有现成组件，手写也不难：先拿到粗排结果，把问题与每个片段拼接，请求重排序模型打分，最后按分数降序取前 N 条。这个模式在正式项目里基本是标配。
4.2 多路召回：向量检索和关键词检索互补
向量检索擅长处理“没记住准确用词但知道大概意思”的查询，比如用户把“报销”说成“费用申请”。但它也有软肋：精确关键词和专有名词。比如MDM-2301这种产品编码，向量召回经常翻车，因为编码和普通词在语义空间里的关系不稳定。
关键词检索（比如 BM25）刚好相反，它按词频和精确匹配打分，对专有名词、型号、缩写极其敏感。所以很多生产级 RAG 会做多路召回：一路向量检索，一路关键词检索，两路结果做融合。融合方式可以很简单，比如取并集后按归一化分数加权平均。LangChain4j 本身没有强制这一层，但ContentRetriever是接口，你可以实现一个组合检索器，内部调用多个检索器再合并结果。
这个改造不复杂，但对知识库问答的召回提升非常明显。我的经验是：只要你的文档里存在公司缩写、产品型号、项目代号这类词，多路召回几乎必然优于单路向量检索。
4.3 查询改写：把“用户的话”翻译成“能检索的话”
用户提问往往口语化、带指代、甚至带错别字。直接拿原始问题去向量库检索，效果通常一般。查询改写就是把用户的话转换成更适合检索的形式。
单轮场景可以用查询扩展：把一个问题改写成多个不同表述，分别去检索，汇总结果。比如用户问“怎么别再忘带工卡”，就可以扩展成“门禁卡补办流程”“工卡补办流程”等多路查询。
多轮场景更常见的是查询压缩。用户先问“报销流程是什么？”，得到回复后再问“发票要求呢？”，这里的“发票要求”实际指“报销的发票要求”。CompressingQueryTransformer就是干这个的，它把整段对话历史理解后，压缩成一条独立的检索查询。
QueryTransformer queryTransformer = CompressingQueryTransformer.builder() .chatLanguageModel(chatModel) .build(); RetrievalAugmentor augmentor = DefaultRetrievalAugmentor.builder() .queryTransformer(queryTransformer) .contentRetriever(retriever) .build();类名和构造方式以你用的版本 API 为准，但思路是通用的。加了查询转换之后，多轮问答的检索命中率会明显提升，用户感知就是聊天更自然了，不用每次都把完整问题重复一遍。
4.4 元数据与权限隔离：企业级 RAG 绕不开的环节
我在前面的检索部分已经提到元数据过滤，这里展开说。企业知识库通常按部门、文档类型、密级、适用范围划分。如果所有文档混在一个向量库里，检索结果里很容易出现用户不该看到的片段，或者跨部门内容干扰答案。
解决方案是“向量检索 + 元数据条件”组合。入库时给每个片段附带元数据，比如：
{ "source": "IT-SOP-2024", "department": "信息技术部", "docType": "操作手册", "version": "3.2" }检索时，根据当前用户的身份和上下文确定可访问范围，把这些条件传给向量库的过滤参数。不同向量数据库 API 不一样，但 LangChain4j 的EmbeddingStoreContentRetriever普遍支持按元数据过滤。权限模型越早设计越好，一旦索引建完才发现结构不合理，重建成本很高。
还要提一句：元数据不等于权限。元数据过滤是让模型不把不该用的文档当上下文，真正的数据安全还要在向量库访问层、接口层做校验。这是另外一套系统工程，但 RAG 阶段至少要能够按范围隔离，避免跨部门内容互相污染。
5. 生产环境里的那些坑：从嵌入模型选型到评估集建设
5.1 嵌入模型选型对最终效果的影响
很多团队把精力花在调对话模型上，却对嵌入模型不闻不问。这是典型的误区。RAG 的上限，有一半由检索决定；检索的上限，很大程度由嵌入模型决定。我用通用英文嵌入模型处理中文制度时，同义改写召回表现很差，用户说“薪资”但文档里写“工资”，向量距离就是不近。换成中文微调的嵌入模型之后，这类问题的召回率明显上升。
选型时还要考虑向量维度和成本。高维度不一定更准，但一定更费存储和计算。我建议直接在你自己的文档集上做对比测试：挑 20 条有代表性的问题，分别用候选嵌入模型召回，看召回的前 5 条里面有多少条是真正有用的。这种小样本评测比看榜单排名更靠谱。
5.2 InMemoryEmbeddingStore 只适合演示，生产要换专业向量库
InMemoryEmbeddingStore在教程里随处可见，因为它零依赖、开箱即用，还支持序列化到本地文件。但它本质上是一个进程内存中的集合，所有向量都放在 JVM 堆里。文档量大了之后，内存占用和检索性能都会成为问题。并发访问、增量更新、故障恢复这些能力也基本没有。
生产环境建议切到专业向量数据库。LangChain4j 官方适配了多款，选择时主要看几点：持久化能力、是否支持元数据过滤、检索性能能否满足并发量、运维成本。很多团队的现状是关系型数据库里存文档、业务数据也在里面，那选带向量能力的 PostgreSQL 插件可能比再引入一个独立向量库更省心。没有标准答案，但一定要清楚：Demo 用的内存方案和线上需要的是两套东西。
5.3 评估集：没有量化指标，调优就是玄学
RAG 调参最怕什么？凭感觉。今天把 maxResults 从 5 改成 6，感觉答案好一点；明天把切分长度从 500 改成 800，又觉得差了一点。两周下来，参数改了一轮，你不知道到底哪个改动是有效的。
我后来养成的习惯是维护一个评估集：30 到 50 条典型问题，每条问题标注期望命中的文档片段和期望答案覆盖的要点。每次改动链路参数，都用这组问题跑一遍回归，记录三个指标：召回命中率、答案正确率、引用来源完整率。这样调参就有据可依了。刚开始建评估集有点费时间，但对知识库类项目来说，这是性价比最高的一笔投入。
5.4 我最后悔没早点做的事：先把检索结果可视化
排错过程中，我最后悔的是前中期没有把“检索到了什么”可视化出来。很多“答案不对”的案例，本质上都是“检索结果不对”，但人看到答案时下意识会怪模型。后面我把每次问答的检索片段直接打印到日志，或者做一个小接口把检索结果返回给前端调试面板，问题定位立刻变快了。
如果你现在刚搭好第一个 RAG Demo，建议直接做这一步：在日志里输出用户问题、检索到的每个片段、每个片段的相似度分数、最终答案。这四个信息能让你快速判断问题出在检索还是生成。没有这个链路，调参只能靠猜。
最后再分享一个体会：RAG 链路里，模型是答题手，检索才是题库管理员。题库没给对卷子，答题手再优秀也是白搭。先把文档切分、嵌入模型、检索参数这些基本功做到位，再回头看模型表现，你会发现很多“模型不行”的结论都为时过早。
