做 RAG 的人基本都同意一句话：检索效果的上限，在入库那一刻就定死了。我在 Langchain4j 系列里已经拆过对话记忆、结构化输出、工具调用，这一篇终于到了 RAG 最容易被轻视、也最值得花心思的环节——Indexing（索引构建）。所谓 Indexing，就是把原始文档变成“可供相似度检索的向量片段”的整条流水线：加载、切分、向量化、入库。它解决的核心问题，不是“怎么回答问题”，而是“回答问题时，系统能从知识库里捞出什么”。
适合谁看？已经用 Langchain4j 写过简单问答、但总觉得检索结果不准的人；以及正准备把知识库接进 Java 服务、想一次把地基打对的开发者。这篇不聊花哨的检索技巧，只把索引这一步从头到尾讲透，包括每个参数为什么要这么设、每个坑是怎么踩出来的。
1. 先理清：RAG 的 Indexing 到底在解决什么问题
1.1 从完整链路看 Indexing 的位置
RAG（检索增强生成）的标准链路分两段：第一段叫 Indexing，负责把知识源变成可检索的向量索引；第二段叫 Retrieval + Generation，负责在用户提问时从索引里召回相关片段并生成答案。很多人一上来就研究怎么调 prompt、怎么选大模型，其实真正决定系统能力的往往是第一段。
Indexing 这一侧的事情看起来不复杂，就是四步：
- 文档加载：把 TXT、PDF、HTML 等原始资料读进来，变成统一的 Document 对象
- 文本切分：把一篇长文档拆成若干小片段（chunk）
- 片段向量化：用 Embedding 模型把每个片段转成向量
- 写入向量库：把“向量 + 原文片段 + 元数据”一起存进 EmbeddingStore
到了检索侧，系统要做的是把用户的 query 也转成同一个向量，然后在向量库里做相似度搜索，取 top-k 片段拼进上下文，最后交给大模型生成答案。看起来检索侧更“智能”，但它能捞回什么，完全取决于索引侧把知识库整理成了什么样。
打个比方。Indexing 就像图书馆把新书编目、贴索书号、上架；Retrieval 就像你根据索引卡去书架上找书。找书的技巧当然重要，但如果书一开始就乱放、书目张冠李戴，再熟练的馆员也找不到。RAG 里“书放得对不对”，指的就是切分是否保留语义、向量化是否表达准确、入库是否去重合理。
1.2 为什么说 Indexing 决定检索质量的上限
检索系统有句老话：召回决定上限，排序决定下限。放到 RAG 里，Indexing 负责的正是“召回上限”这件事。向量库检索本质上是“在候选池里找最像的”，它永远不可能返回不在候选池里的内容。如果你的知识库切片是残的、向量是偏的、库里塞满了重复数据，那么无论你之后用什么重排策略、用什么厉害的生成模型，拿到的上下文已经是歪的，答案自然也跟着歪。
这也能解释为什么很多人折腾了很久，换了大模型、调整了 prompt，效果还是原地踏步。问题根本不在生成端，而在“喂给生成端的东西本来就不对”。而且索引问题有个迷惑性：它不是那种一上线就报错的问题，而是“检索结果看起来好像相关，仔细一看根本不相关”的隐性病。因为大多数情况下，系统能给你返回“某段看起来很像那么回事的文本”，你很难第一时间意识到是切片切坏了。
我见过一个典型的例子：有人把一份几十页的合同文档整段丢给系统去问答，检索到的“相关片段”永远是一大坨混着不同条款的正文，回答里甚至出现了前一条款的内容。这不是模型笨，而是根本没做切分，或者说切分粒度太粗。这类问题从 Indexing 阶段调整就能解决，而且解决成本比在生成端打补丁低得多。
2. 拆解 Langchain4j 的 Indexing 核心组件
2.1 组件全景
Langchain4j 把索引流程抽象成几个边界清晰的对象，这是它比很多“自己拼流程”的写法舒服的地方。先记住这一组名词，后面实操全部围绕它们展开：
- Document：一条原始文档，包含正文 text 和元数据 metadata
- DocumentSplitter：把长 Document 拆成多个 TextSegment
- TextSegment：最终入库的最小单元，同样带 text 和 metadata
- EmbeddingModel：把文本转成向量
- EmbeddingStore：向量的存储与相似度检索
- EmbeddingStoreIngestor：编排“切分 → 向量化 → 入库”的入口
这一节相当于整篇的骨架。你在网上搜 Langchain4j RAG 的资料，翻来覆去看到的也就是这几个类，把它们的职责和边界弄清楚，索引这块基本就通了一半。
2.2 Document：一切从加载开始
Document 在 Langchain4j 里就是一个很朴素的类：一段 text，一个 metadata Map。凡是“文档本身内容之外的信息”，都适合放在 metadata 里：来源文件、文档分类、上传时间、权限标识、甚至你在业务里的自定义标签。很多人忽略 metadata，但实际上它是后面做过滤检索的重要原料。没有 metadata，检索就只能是“全局相似度”，有了 metadata，你才能回答“只从这批文档里找”这类业务问题。
加载方面，Langchain4j 提供了文件系统加载器、URL 加载器，以及针对 PDF 等格式的解析模块。最常用的还是从本地文件系统加载：
Document document = FileSystemDocumentLoader.loadDocument("data/rag-source.txt");拿到 Document 之后，我建议立刻把基本信息写进 metadata，否则后面做的任何过滤都会没有抓手：
document.metadata().put("source", "rag-source.txt"); document.metadata().put("category", "manual"); document.metadata().put("version", "v1.2");这里有个小建议：凡是你能事先确定的稳定字段，都在这一层加好，别等到入库后再补。因为向量库里已经存在的片段，改 metadata 往往需要重新跑一遍入库，成本比想象中高。
2.3 TextSegment 与 DocumentSplitter：切分策略是灵魂
为什么要切分，从根本上说是两个原因。第一，模型上下文窗口有限，你的文档可能十万字，不可能整段塞进 prompt；第二，检索粒度问题，向量检索需要“语义单一的片段”才能精准命中。你想让系统回答“这个产品支持哪些部署方式”，它需要的不是整本手册，而是手册里讲部署的那几段。
Langchain4j 的 DocumentSplitters 提供多种切法，各有各的适用场景：
- byCharacter：按固定字符数硬切，最快，但最容易把句子拦腰截断
- byParagraph：按段落切，对中文文章很友好，能保住段落语义
- byLine：按行切，适合代码、配置文件这类“一行一个意义”的内容
- bySentence：按句子切，适合问答类、条款类文档
- recursive：递归式切分，优先按大分隔符切，段太长再往细切，最推荐
切分器的核心参数有三个：chunkSize（目标片段大小）、overlap（相邻片段重叠量）、maxChunks（最多产出片段数）。overlap 很多人不理解，为什么要让相邻片段重复一部分内容？因为文档本身是有上下文承接的，比如第 2 段开头引用了第 1 段的某个概念，如果不重叠，第 2 段被检索到时可能缺关键前提。重叠相当于给“边界信息”上了保险。
实际代码很简单：
DocumentSplitter splitter = DocumentSplitters.recursive(500, 50); List<TextSegment> segments = splitter.split(document);切完一定要抽样检查。我每次切完都会打印前三个片段看一眼，如果看到一句话被从中间切开，说明 chunkSize 或分割策略不对。这一步 30 秒，能省掉后面几小时的排障。
2.4 EmbeddingModel 与 EmbeddingStore
Embedding 模型的工作是“把文本变成向量”。原理可以概括为：一段文字的语义被压缩进一个 N 维浮点数组，语义相近的文本，向量在多维空间里距离更近。如果你没接触过这个概念，可以类比成用“身高 + 体重 + 鞋码”三个数字描述一个人，三个数组成一个人物坐标，身材接近的人坐标就接近；文本向量也是这个道理，只是维度从三维变成了几百上千维。
选型有两条主线：一条是调用云端商用 API，效果稳定、省心，但按量计费；另一条是本地部署开源模型，数据不用出内网，但需要 GPU 资源和运维投入。中小团队我建议先从云端 API 起步，效果跑通了再考虑本地化。这里有一条硬约束：同一个知识库里，入库用的模型和检索用的模型必须一致。换个模型意味着向量的“坐标系”变了，旧向量全部失效，必须重建索引。
EmbeddingStore 负责存向量和执行相似度检索。Langchain4j 的接口统一，底下可以接多种实现：
- 内存实现：进程内存储，适合原型和测试，可以序列化到本地文件
- 关系型数据库的向量扩展：中小项目首选，复用已有的数据库设施，能和业务数据一起管理
- 专用向量数据库：数据量大、并发高、需要复杂过滤和运维能力时再上
接口层面的统一是 Langchain4j 做得最舒服的地方：你写业务代码时只依赖 EmbeddingStore 接口，底层换实现不用动业务逻辑。后面实操先拿内存库跑通，你自己换生产库时只需替换一个对象。
2.5 EmbeddingStoreIngestor：一站式入库入口
Ingestor 就是那条流水线的总装车间。它做的事情一看就懂：把 Document 交给 Splitter，得到片段；把每个片段交给 EmbeddingModel，得到向量；再把“向量 + 片段”一起交给 EmbeddingStore 写入。你不用关心它内部怎么循环、怎么处理异常，只需要装配好三个组件。
EmbeddingStoreIngestor ingestor = EmbeddingStoreIngestor.builder() .documentSplitter(splitter) .embeddingModel(embeddingModel) .embeddingStore(store) .build();这里要特别提醒：ingest 方法是有返回值的，返回的是每个片段入库后的 EmbeddingMatch 列表。这个返回值在测试时特别有用——你可以立刻看到入库了哪些片段、每个片段的向量是什么，也可以把它当成初期验证手段。很多人以为 ingest 是 void，白白丢掉了一个调试入口。
3. 完整实操：从文本文件到向量索引库
这一节写一个最小可跑通的例子。目标很简单：把一个 txt 文件经过切分、向量化、入库，然后伸手查一句，验证索引真的能捞回相关内容。整个流程跑通以后，后面换向量库、换模型、调参数，都只是替换组件的问题。
3.1 环境与依赖
环境要求不复杂：JDK 17 以上，Maven 或 Gradle 都行。依赖方面，核心只要 langchain4j 主模块，再加一个你实际使用的 Embedding 服务的集成模块。因为厂商产品比较多，我不会把某个产品写死在示例里，你用任何一家基本都是同一个写法：builder 设置 apiKey 和 modelName。如果你先用内存向量库，连额外的存储依赖都不需要。
<dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j</artifactId> <version>0.35.0</version> </dependency> <!-- 你实际使用的 Embedding 服务的集成模块，示例仅作示意 --> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-xxx</artifactId> <version>0.35.0</version> </dependency>提示：不同小版本之间个别方法签名有微调（例如 embedding 方法返回类型的差异），示例写法按当前主流的 0.3x 版本为准，个别地方以你实际引用的版本兼容。
3.2 加载文档并写入 metadata
先准备一份 rag-source.txt 放在 data 目录下，内容随便写点产品介绍、操作说明之类。加载代码很直接：
Document document = FileSystemDocumentLoader.loadDocument( "data/rag-source.txt", StandardCharsets.UTF_8); document.metadata().put("source", "rag-source.txt"); document.metadata().put("category", "manual");这里有个细节：加载文本文件时最好显式指定字符集。我们总免不了和中文打交道，不指定编码在某些系统上会拿到乱码，而这种乱码问题在向量化阶段很难被发现，因为它不报错，只会让向量变得很奇怪。
3.3 配置切分器
先用一组保守的参数起步：目标片段 500 个字符，重叠 50 个字符，用递归切分。500 这个值不算大也不算小，对大多数说明类文档都友好；50 是大概 10% 的重叠，既能覆盖边界上下文，又不会产生太多冗余片段。
DocumentSplitter splitter = DocumentSplitters.recursive(500, 50); List<TextSegment> segments = splitter.split(document); System.out.println("切分得到片段数: " + segments.size());如果你发现片段数异常（比如只有一个片段，或者多达几百个），先别急着入库，回头看看原始文档规模和分隔符结构，大概率是 chunkSize 和文档实际体量不匹配。
3.4 配置 EmbeddingModel 与 EmbeddingStore
Embedding 服务的配置代码各家大同小异。强烈建议通过环境变量读取密钥，别把 apiKey 硬编码进代码仓库，这个习惯在团队协作时尤其重要：
EmbeddingModel embeddingModel = YourProviderEmbeddingModel.builder() .apiKey(System.getenv("EMBEDDING_API_KEY")) .modelName("embedding-model-name") // 换成你供应商支持的型号 .build(); EmbeddingStore<TextSegment> store = InMemoryEmbeddingStore .withTextSegmentPersistent("data/my-store.json");内存库的持久化变体很实用，它会在启动时读文件、退出时写文件，原型阶段防止“服务一重启索引全丢”。如果只是想快速跑通，直接new InMemoryEmbeddingStore<>()也行，数据不落盘。
3.5 组装 Ingestor 并执行入库
把前面三个组件装到 Ingestor 里，调用一次 ingest，整条流水线就跑完了：
EmbeddingStoreIngestor ingestor = EmbeddingStoreIngestor.builder() .documentSplitter(splitter) .embeddingModel(embeddingModel) .embeddingStore(store) .build(); List<EmbeddingMatch<TextSegment>> matches = ingestor.ingest(document); System.out.println("实际入库片段数: " + matches.size());注意一下这里返回值的数量。它和前面 splitter 切出的 segments 数量理论上一致。如果这里数量对不上，说明 ingest 过程中有片段被过滤或失败，后面排障时这就是第一条线索。
3.6 检索验证：确认索引真的生效
入库不是目的，能捞回来才是。写一个最简单的检索验证：
Embedding queryVector = embeddingModel.embed("这个产品支持哪些部署方式").content(); List<EmbeddingMatch<TextSegment>> hits = store.findRelevant(queryVector, 3); for (EmbeddingMatch<TextSegment> hit : hits) { System.out.println("相似度: " + hit.score()); System.out.println("片段: " + hit.embedded().text()); }运行以后，如果命中列表里有和你问题明确相关的片段，索引基本就是通的。这里的 score 表示相似度评分，数值越高越相关，具体取值范围和所选距离度量有关。这个验证动作，我建议每次改索引配置都跑一遍，比对着最终答案反推快得多。检索侧完整链路（ContentRetriever、Retriever 怎么接入生成流程）系列前面几篇已经聊过，这里不再展开，重点只放在验证索引本身。
4. 参数调优与经验值
4.1 chunkSize 与 overlap 怎么选
参数没有绝对标准，但经验区间是有的。我按文档类型整理了一份参考表，实测下来可以作为起步值：
| 文档类型 | 建议 chunkSize | 建议 overlap | 理由 |
|---|---|---|---|
| 通用知识文章 | 400~600 字符 | 10%~20% | 平衡语义完整与定位精度 |
| 合同、条款类 | 300~500 字符 | 20% 左右 | 条款间引用关系强，边界敏感 |
| 代码、日志 | 150~300 字符 | 少量或不设 | 避免跨代码块语义污染 |
| 长文、叙事类 | 600~800 字符 | 10% | 上下文连续性强，切小反而丢剧情 |
chunkSize 不是越小越好。太小，一条完整信息被拆散，检索自然会丢上下文；太大，片段语义太杂，命中精度下降。本质上是在“精确命中”和“上下文完整”之间取平衡。overlap 也一样，太大会导致索引冗余、检索结果里出现大量重复片段，反而浪费 prompt 的上下文窗口。
4.2 向量库与距离度量怎么选
存储方案的选择，直接跟着场景走。下面这张表是我在选择时的判断框架：
| 方案 | 适合场景 | 注意点 |
|---|---|---|
| 内存库 | 原型、测试、数据量小 | 注意持久化；重启不丢是关键 |
| 关系型数据库向量扩展 | 中小项目、已有数据库设施 | 事务、权限、SQL 过滤都可复用 |
| 专用向量数据库 | 海量文档、高并发、实时更新 | 功能强，运维成本也上升 |
还有一个容易踩的坑：距离度量。文本语义最常用的是余弦相似度，但有些 Embedding 模型官方推荐点积或欧氏距离。更换向量库时，一定要确认库侧配置的索引算法和距离度量，与模型文档建议保持一致。否则会出现一种很诡异的现象：配置看着没问题，检索结果却是乱的，查了半天才发现是度量不匹配。
4.3 metadata 过滤提升精准度
索引阶段埋好 metadata，检索阶段就能做过滤。这个能力类似 SQL 里的 where 条件，当你需要“只搜索产品手册”或“只搜索运营文档”时，过滤比单纯靠向量相似度可靠得多。
Langchain4j 的检索接口支持传 MetadataFilter：
MetadataFilter filter = MetadataFilter.builder() .equals("category", "manual") .build(); List<EmbeddingMatch<TextSegment>> hits = store.findRelevant(queryVector, 3, filter);注意，这个用法要求你在入库时已经把 category 写进 metadata。所以索引阶段多花半分钟埋字段，检索阶段就能省掉大量后处理逻辑。这也是我在前面反复强调 metadata 重要性的原因。
4.4 增量更新与幂等入库
真实业务里文档会更新、会新增，索引不能总是“清空重建”。重复入库同一个文件会生成内容相同或近似的向量，检索时结果冗余，挤占上下文窗口。要避免这个问题，核心是做幂等控制。
我常用的做法是在 metadata 里放一个全局唯一的 docId，入库前先查“已索引清单”，存在就跳过。这个清单可以是数据库表，也可以是一个简单的存储文件。
// 伪代码：入库前检查该 docId 是否已索引 if (!indexRepository.exists(docId)) { ingestor.ingest(document); indexRepository.save(docId, fileHash, createdAt); }这里保存 fileHash 还有个额外好处：文件内容变了但 docId 没变时，可以通过 hash 对比决定是否需要重建这条索引。这个习惯在知识库频繁更新的项目里能省下大量重复计算。
5. 常见问题与排查实录
5.1 检索结果明显不相关
遇到这种情况，按下面的顺序排查比瞎试参数有效得多。第一，先把实际入库的片段打印出来看，确认是不是切分把语义切碎了；第二，确认入库和检索用的是同一个 Embedding 模型；第三，检查检索时是不是带了不该带的 metadata 过滤，把正确的候选全过滤掉了；最后，再看 query 本身，单字、过短的 query 往往区分度不够，检索结果飘是正常的。
5.2 向量维度不匹配报错
症状很直接：调用检索时报维度错误。原因大多是入库时用模型 A（比如 1536 维），检索时换成了模型 B（比如 1024 维）。解决方式没有捷径：统一模型，并且对已经入库的旧向量重建索引。不要试图做维度拼接或截断，那是给自己埋雷。
5.3 中文文档效果差
中文场景有三个高频坑。第一个是按字符硬切，把一句话从中间切开，语义直接裂开，建议改成按段落或句子切；第二个是用了对中文支持不够好的 Embedding 模型，这类模型的向量对中文语义表达很弱，建议换多语言优化过的模型；第三个是切分后实体被拆散，比如“自助服务”被切成了“自助服”和“务”，检索匹配自然乱掉。解决思路都是同一个：切分粒度尊重语言边界，模型选择尊重语种适配。
5.4 入库速度慢
入库慢，瓶颈几乎都在 Embedding 调用上。云端 API 有并发和速率限制，串行调用几千个片段确实会等很久。几个方向供参考：并发入库，但要做好重试和指数退避，别把厂商接口打爆；优先使用批量接口，一次传入多段文本；生产环境入库做成离线批任务，别放在用户请求链路上。
5.5 问题速查表
| 症状 | 可能原因 | 排查/解决方向 |
|---|---|---|
| 检索结果答非所问 | 切分破坏语义 / 模型不匹配 | 查看切分后的实际片段；统一并更换更合适的模型 |
| 报向量维度错误 | 入库和检索模型不一致 | 统一模型，必要时重建索引 |
| 中文内容效果差 | 切分刻板 / 模型适配不足 | 按句子或段落切；选多语言模型 |
| 返回大量重复片段 | 重复入库 / overlap 过大 | 维护 docId 幂等；降低 overlap |
| 检索能召回但定位不准 | chunk 过大 | 调小 chunkSize 后再验证 |
5.6 两个曾经踩过的坑
第一个坑：有一回我贪方便用裸的内存向量库跑原型，塞了几万个片段，服务一重启全没了，现场验证时对着空索引一脸懵。后来换成带持久化的内存库，才稳定下来。这个教训是：原型阶段也要想清楚存储边界，别把“临时方案”当成“不用考虑”。
第二个坑：中文文本按字符 500 硬切，把“自助服务”切成“自助服”和“务”，检索“自助服务”时召回了一堆乱七八糟的片段。改成按段落切以后，同样的问题立刻消失。从那以后，我切完任何文档都会肉眼抽查几个片段，确认没有断句断词再入库。
6. 一点自己的体会
最后分享一个私货：在 RAG 项目里，我习惯把索引阶段当成“先胜后战”的环节。每次改动知识库或者调切分策略，我都会先做一轮检索验证——不看生成答案，只盯检索回来的片段是不是真的相关。检索这关过了，生成那边的效果通常水到渠成；检索这关没过，调多少次提示词都是白搭。
还有一个小技巧：在拿不准参数的时候，优先使用内存库 + 500 字符 chunk + 10% overlap 起步，先把链路整体跑通，再逐步换上生产用向量库和更精细的策略。把变化隔离在配置层，业务代码不动，后续调优会顺利很多。这一篇把索引侧讲完，系列后面继续拆检索和重排的部分，到时候我们再见。
