ARTICLE · 1374644
文档解析与分块:RAG 质量的第一道坎
同一个问题,两个团队给出了两种答案。制度文档是同一份 PDF,问「定制商品能不能无理由退货」,A 团队的助手准确引用了第二页的例外条款,B 团队的助手套用了第一页的通用七天规则,答错了。排查下来,模型是同一个,提示词几乎一样,差别只有一个:A 团队按页切分、页脚单独剔除,B 团队整本 PDF 喂给默认切分器,例外的关键句恰好被切在了两个片段的边界上。
这个案例里模型没有任何发挥空间——答案对不对,在入库那一刻就定了。检索阶段再怎么调,也调不回一段被切碎或没被解析出来的文字。这篇文章拆开 RAG 链路的最上游:文档怎么读、片段怎么切、元数据怎么设计,以及四处最隐蔽的失败方式。
一、解析:失败是静默的
Spring AI 把入库流程抽象成 ETL 三件套:DocumentReader 读取、DocumentTransformer 切分、DocumentWriter(即 VectorStore)写入。先看读这一段,常见 Reader 按格式对号入座:
spring-ai-pdf-document-reader | ||
spring-ai-tika-document-reader | ||
spring-ai-markdown-document-reader | ||
解析阶段最需要建立的心理预期是:它失败的时候不报错。三类典型:
扫描件没有文字层。 PDF 看着有字,实际是图片,Reader 提取出来是空字符串或残缺乱码——入库照样成功,向量照样生成,只是嵌的是垃圾。后续所有检索都在垃圾里捞,永远不会有人从日志里看到一声异常。所以入库流水线的第一站应该是「格式预检」:按扩展名和内容特征分流——有文字层的 PDF 走正常 Reader,扫描件先转 OCR(识别结果同样要抽检,OCR 错一个数字,答案就错一个数字),Word 走 Tika,邮件和 PPT 这类异构来源先统一转成带结构的中间文本再入库。预检这一步做在了最上游,后面每一站拿到的都是干净输入。
页脚页眉混进正文。 每页都有的「第 X 页 / 机密文件」被当成正文切片、算向量,成了检索时的高频噪声。PagePdfDocumentReader 提供 withPageBottomMargin 之类的边距配置来跳过页脚,但这个值跟着 PDF 版式走,换文件就要重新核对。
元数据缺失。 PDF Reader 会带 page_number,Tika 读 Word 不给页码。不做统一补齐,「这个答案出自哪份文件第几页」就答不上来,用户无法回溯核对,RAG 的可信度直接掉一档。
所以解析完成的判定标准不是「没抛异常」,是抽人核对:随机抽几页,对照原文看文字全不全、页脚进没进来、表格还在不在。这一步花十分钟,能省掉之后查不完的 bad case。 如果文档量大到抽不过来,至少按文件来源分层抽:扫描件单独一批,普通 PDF 一批,Word 一批——出问题的往往集中在某一类来源上。
二、分块:两个失败方向和一组参数
切分的核心矛盾是:块太大稀释语义,块太小丢失上下文。一段五百字的规则里混着三个主题,向量取平均,哪个主题都不突出;切成一句话一片,「不支持无理由退货」的主语留在上一片,检索命中了却答不对。
Spring AI 的 TokenTextSplitter 默认按 token 数切,但默认参数对中文不友好——它按英文的句读习惯断句。中文文档要显式给标点:
TokenTextSplittersplitter= TokenTextSplitter.builder() .withChunkSize(180) // 每片目标 token 数 .withMinChunkSizeChars(60) // 片内最小字符数,防碎片 .withMinChunkLengthToEmbed(5)// 中文按句切,别让它一刀切在词中间 .withPunctuationMarks(List.of('。', '?', '!', ';', '\n')) .build();List<Document> chunks = splitter.apply(documents);这组数没有标准答案,但有一个必须守的原则:先看内容再定参数。制度文档一句一规则,切小些;操作手册步骤连贯,切大些并靠重叠保边界。上线前拿真实文档跑一遍,人工翻十几个片段看边界断得对不对,比任何博客推荐的「最佳分块大小」都可靠。
量化上有个粗略的账可以算:top-k 取 5、每片 200 token,检索就占了 1000 token 的上下文——片段翻倍,每次问答的输入成本直接翻倍,而收益往往在某个区间之后急剧递减。所以调分块不是越大越好,是「检索命中率」和「单次问答成本」一起看:先从每片 150 到 250 token 起步,命中率不够再加大片长或改用父子块,别一上来就 1000 token 一片。
分块会保留原有元数据,所以第一节的页码、来源在切片上还在——这是后面过滤和溯源的基础。
还有一个常被默认存在、实际不存在的能力:重叠。很多教程讲分块时会说「片段之间留 10% 到 20% 的重叠,避免关键句落在边界上」,思路本身是对的,但 Spring AI 的 TokenTextSplitter 是纯按 token 数切,不加重叠。依赖重叠保边界的文档(操作手册、长论述),要么接受按中文标点切分后的自然断句,要么自己实现一版带滑窗的 Transformer——把「默认有重叠」当成事实去调参,边界问题永远调不好。
结构化文档值得多一道前置切分。 Markdown、Confluence 导出的手册本来就有标题层级,直接按 token 切等于把结构扔了:一章讲退货总则、下一章讲例外,切成等长片段后两章的内容混在一片里,向量取平均,答出来必然是「大概都对、细节全错」。
做法是先按标题切、再按长度切:
一级标题 → 一段二级标题 → 一段(带上所属一级标题作为前缀)某段仍超过 300 token → 交给 TokenTextSplitter 再切,父标题继续挂在 metadata 上切出来的每一片都自带「它属于哪一章」这层语义,检索命中后模型也知道自己在读哪一节。代价是多写一个 Transformer,收益是长文档问答不再张冠李戴——尤其是制度类文档,例外条款和通用条款往往就隔着一个标题。
三、检索小块、返回大块:父子块的配合
分块的两难有一个工程化解法:索引和返回用两个粒度。入库时把长段落切成小块(语义集中,检索准),命中后返回它所属的父块(上下文完整,模型读得懂)。这就是父子块策略:子块负责被找到,父块负责被读懂。
Spring AI 里没有开关一键打开这个策略,但搭起来不难:入库时在子块 metadata 里记下 parent_id,检索命中后按 ID 取回父块内容拼进上下文。多花的是一层映射的存储,省回来的是「命中了答不对」这类最冤的 bad case。
父子块不是万能的,它有明确的适用边界:内容长、段落间强依赖的文档(制度、手册、论文)收益最大;本身就是短条目的内容(FAQ、故障case 卡片)一个条目就是一片,父子块纯属多余。给 FAQ 库上父子结构,是拿复杂度换了个寂寞。
配套的还有两个现成的元数据增强器:KeywordMetadataEnricher 抽关键词进 metadata,SummaryMetadataEnricher 用一次模型调用给每片生成摘要。它们改善的是「用元数据辅助检索」的场景,代价是入库更慢、多花 token——知识库一次性建,这笔钱值得;频繁全量重建的库要掂量。
四、元数据在入库前定好,不是用到时再补
元数据决定了 RAG 三个能力:过滤(只搜本部门文档)、溯源(答案出自哪份文件)、版本管理(新制度上线旧制度作废)。这三件事的共同点是,都要求数据在写入时就带着正确的标记——事后补,等于全量重嵌。
入库前就把键定下来:
Documentdoc=newDocument(content, Map.of("tenantId", kb.getTenantId(), // 多租户过滤"source", file.getName(), // 来源回溯"version", doc.getVersion(), // 制度版本"page", pageNumber)); // 页码溯源键名一旦定下就是契约:检索代码、过滤逻辑、前端展示全都引用它。上线后改键名,代价是重新入库。所以宁可第一版多想几个键用不上,也别等「按部门过滤」的需求来了才发现当时没存部门字段。
metadata 里还应该有一个稳定的 docId——注意是「文档内容的身份」,不是「某次写入的身份」。它决定第五节的更新流程能不能做幂等:同一份文件重复入库,靠 docId 先删后写,结果可重放;docId 用随机 UUID,同一次重试就会留下两份一样的切片,检索结果里同一段话出现两次,top-k 的名额被白白占掉一半。
另外一条安全边界:别把用户上传的任意 URL 直接丢给 Reader。Reader 会顺着地址读内容,这是教科书级的 SSRF 面——上传先落受控存储,服务端选 Reader,读取范围自己说了算。
五、四处解析分块的静默灾难
一、扫描件直接入了库。 没有文字层的 PDF 提取出空内容或乱码,流程一路绿灯走完,库里多了一批「看起来存在、永远检索不出来」的文档。防御很简单:入库前检查提取文本长度和字符分布,低于阈值就转 OCR 流程,别让它混进正常队列。
二、跨页表格被拦腰切断。 表格是 PDF 解析的重灾区:跨页的表格被切成两半,每半的行列关系都断了,嵌出来的向量描述的是一张不存在的残表。财务制度、配置清单这类文档要人工核对表格解析结果,复杂表格考虑先转结构化数据(存表、按行生成文字描述)再入库,别指望向量检索理解表格结构。
三、更新文档只 add 不删旧版。 制度改版,新文档 add 进去,旧文档还在库里躺着。用户问到的可能是作废规则,而且新旧两版在检索结果里打擂台,答案随机。文档更新必须走「按 source 或 version 删旧、再写新」的完整流程,写入接口只给 add 权限,删除链路单独管理。
四、参数从示例复制,断句没跟着语言走。 英文示例里的切分参数原样搬到中文库,标点列表还是英文句号逗号,结果一片中文在词中间被硬切。这个错误检索阶段看不出来,只有人工翻片段才看得见——又是那句话:抽检,在入库完成的那一刻做。
六、答不准时,先分清是「没检到」还是「没读懂」
「RAG 答不准」是个太笼统的抱怨。它至少对应三种完全不同的故障,处理方式也完全不同:
分不清这三层,最常见的浪费是:拿一个分块问题去调提示词,调一周,答案质量纹丝不动。
第一步,绕开检索,直接问库。 把 bad case 里那句关键原文(比如「定制品不支持七天无理由」)拿去库里做一次字面匹配:
-- 注意:这是排障用的,别在生产大表上这么查SELECT id, page, length(content) AS lenFROM knowledge_chunksWHERE content LIKE'%定制品不支持七天无理由%';三种结果对应三条路:
• 查到一行,且这句话完整:解析和分块都没问题,往第二层查——这条记录为什么没进 top-k?把它的向量和查询向量算一下距离,比第 5 名差多少。 • 查到,但句子被切成两截:典型的分块事故,两片都不含完整语义,谁也召不回。回第二节调参数或上父子块。 • 查不到:要么解析阶段就没读出来(扫描件、表格、页脚覆盖),要么被切得更碎、连关键词都拆开了。用更短的关键词(比如只查「定制品」)再搜一次,能定位到是哪一种。
第二步,绕开检索直接喂给模型。 把上一步查到的那段原文原样塞进 prompt,问同一个问题:
• 模型答对了:说明知识在、模型也行,问题 100% 在检索链路,别再去改提示词。 • 模型还是答错:知识在、模型不用,问题在上下文组织和指令表达——这时候才轮到提示词出场。
这个「两侧夹逼」的做法,比看日志猜快得多。它之所以有效,是因为 RAG 的链路是串行的:任何一环坏了,最终都是同一个症状「答得不对」,只有从两端往里收,才能把故障点夹在一个环节上。
第三步,把 bad case 存下来。 每修一个,就把「问题 + 正确答案 + 出处页码」记进一份回归集。这份集子积累到三五十条之后,任何一次分块参数调整、换 embedding 模型、换 rerank 策略,跑一遍就知道是变好还是变坏。没有回归集的调优,本质是在凭手感改参数。
七、一份入库验收清单
解析和分块没有「调好一次管终身」的参数,只有一套每次入库都该过的检查:
• 抽样核对:随机抽 5% 的文档,对照原文检查文字完整性、页脚是否混入、表格是否完整; • 边界检查:人工翻 10 个片段,确认没有在词中间硬切、例外条款没有被切散; • 溯源抽查:任选一条检索结果,能回答「出自哪份文件第几页」; • 版本核对:同一份文档的新旧版本不会同时出现在检索结果里; • 规模记录:本次入库的文档数、切片数、平均片长记下来——下次答案质量突变时,这是第一个对照的基线。
最后补一条实操建议:把「解析 → 抽检 → 分块 → 抽检 → 入库 → 溯源抽查」固化成一段脚本或一个后台任务,让每次入库自动走完并输出报告。人工抽检只需要在报告异常时介入,而不是每次都从头翻文档。流程不固化,抽检一定会在某个加班的晚上被跳过,然后静默灾难准时上岗。
RAG 的答案质量有个残酷的上限:模型只能基于检索到的东西作答,检索不到的它只能编。而检索得到的每一片,都来自这篇文章讲的这段最不起眼的管道。把第一道坎守住了,后面调检索、调提示词才有意义;守不住,下游所有优化都是在噪声上调信号。
下次有人抱怨「RAG 答不准」,先别动模型和提示词——去翻翻向量库里到底存了什么。










































































