我最早做检索增强生成的时候，最轻视的环节就是文档切割，结果被现实教育得最狠。当时把一堆商品手册丢进知识库，心想只要塞进向量库、跑一遍嵌入，检索效果自然就出来了。第一次跑评测就被打脸：用户问“续费后多久生效”，系统返回的结果只有“续费说明”的前半句话，后半句“次日零点生效”被切到了下一个块里，彻底孤立。后来把排查顺序掉了个个，不看模型不看提示词，先看切割逻辑，才发现这一层才是整个RAG流水线的七寸。
这些年和Spring AI打交道多了，我越来越觉得文档切割不是工具链里的配角。你用固定长度切，检索结果就处处体现着暴力切割的笨拙；你用语义边界切，召回质量会肉眼可见地变稳。这篇文章想完整记录一条从“暴力分割”到“语义智能”的进阶路径，包括我在实际项目中踩过的坑、调过的参数，以及最终沉淀下来的一套可复用的改造流程。不管你是刚上手Spring AI，还是已经在做生产级知识库，这都应该能提供一些直接能用的参考。
1. 为什么文档切割是RAG的七寸
1.1 检索效果从来不是模型单独决定的
很多人误以为检索能力强是因为嵌入模型选得好。我一开始也这样想，直到对比实验推翻了这个念头。同一个嵌入模型、同一个向量库、同一套提示词，只改动文档切割策略，检索命中率就能上下浮动三四个百分点。更极端的情况里，切分方式错了，好模型也挽不回局面。
原因是显而易见的：RAG的检索单位是“块”而不是整篇文档。用户查询进来之后，三元组也好、向量相似度也好，都是在这些块上做匹配。如果块本身切得七零八落，语义信息就会断裂，检索到的自然是不完整的碎片；如果块切得太大，又把不相关的主题混装进同一个向量，召回结果就会被噪声污染。
在Spring AI的架构里，文档从原始文件解析成Document对象之后，下一步就是经过DocumentSplitter接口拆分。很多项目把精力放在prompt调优和模型选型上，却对这一步一笔带过，结果上线后一问一个不准。我现在的习惯是：任何RAG项目启动第一周，主要精力全部花在“切得对不对”上，而不是急着调模型。
1.2 切分错误会直接污染下游的生成结果
切割问题不会停留在检索阶段，它一定会传导到生成阶段。有一回我排查一个客服问答应用，用户反复问“退换货政策”，系统答非所问。我把检索结果打印出来一看，匹配到的块里除了退换货条款，还混进了一段“物流配送范围”。原因就是这两个主题在原文里连在一起，又正好落进同一个500 token的固定窗口里，嵌入后的向量把两件事揉成了一团。模型拿到这样的上下文，自然无法分辨用户真正问的是哪一部分。
这让我意识到：文档切割不只是“怎么切”，更是“我能交给模型哪些信息”。切得合理，模型拿到的是主题聚焦的上下文；切得随意，模型被迫从混乱中猜答案。长期做下来，我甚至能用生成质量反向推断切割方案对不对，但这属于事后补救，成本很高。
还有一个容易被忽略的点：数据块数量会直接影响检索时的计算开销和延迟。暴力分割往往产生大量碎片，多到向量库需要扫描的候选数量翻倍。如果不做重排，延迟上来了，准确率却不见得提升。这也是我后来拥抱语义切割的另一个现实原因。
1.3 做一个简单的小实验：感受切割对检索的影响
如果想快速验证“切割影响真实存在”，不必等生产数据。我建议拿一份结构完整的说明文档，比如某个软件的用户手册，分别用两种方案切分：一种按固定800字硬切，一种按章节标题和自然段落语义切。然后构造10个问题，逐个检索对比。你会发现固定硬切的问题几乎全部都出现两类现象：参考答案跨块、引入无关段落。
这个小实验成本很低，价值却很高。它能把“文档切割重要”这种抽象认知变成真实的体感。一个Team里的新同学做完这个实验，再回去看RAG代码，立刻就知道应该先动哪一块了。
2. 暴力分割的起与落：看起来省事，后患无穷
2.1 定长切割的逻辑与陷阱
暴力分割最典型的实现是定长切割：按固定字符数或token数把文档切成连续片段，常见做法还有设置一定重叠区域。Spring AI内置的TokenTextSplitter走的就是这条路，它按token数量切分文本，配合keepSeparator等参数控制分隔符保留方式，用起来非常省事，几乎没有上手成本。
省事是它最大的优点，也是它最大的陷阱。任何定长策略都有一个先天缺陷：它完全不看文本内容。段落边界、标题结构、主题转折点，在切割器眼里都是透明的。于是“产品优势”和“常见问题”会被硬生生拼进同一块，“注意事项”那一章被拦腰截断分到三个块里，检索结果可想而知。
我用个生活化的类比：这就像你拿到一本菜谱，不管三七二十一，每100页装订成一册。做红烧肉的时候，你可能翻到的是佐料页搭配炖煮页的一半，但糖色那一段在上一册结尾。信息全都在书里，可你就是没法一次拿到完整步骤。
定长切割还有一个隐蔽问题：语言模型的tokenizer不是均匀切字符的，不同的语言、不同的标点密度会导致同样的token数对应完全不同的内容量。中文尤其明显，同一个defaultChunkSize下，一份技术文档可能被切成两千块，另一份对话记录却只切出八百块。切出来的块边界完全是随机的，稳定性很差。
2.2 基于换行和空行的切割：看似聪明，条件苛刻
比定长切割稍微进步一点的，是基于换行符、空行、章节标记的切分。Spring AI早期实践和很多文档里都会提到按行扫描，遇到空行或标题就断开。这个方案的思路是对的：至少在尝试尊重文本的物理结构。但它成立有个前提——原始文档的排版必须规整。
真实业务里的文档远没有那么听话。PDF转换来的文本经常丢失换行，表格被压成一行，列表项缩进混乱；导出自某些在线编辑器的Markdown更是满屏空行；OCR出来的文档连段落边界都要靠猜。在这些情况下，基于换行的切割会和定长切割一样产生错切，而且因为“看起来有逻辑”，排查时更容易让人误以为问题出在检索或模型上。
所以我对这个方案的评价是：作为回归基线可以用，作为生产方案则太脆弱。你需要写大量的清洗逻辑去修文档格式，而这个清洗成本很快会超过切割本身的成本，得不偿失。
2.3 暴力分割的风险清单与典型故障画像
做了一年多文档切割之后，我把暴力分割引发的典型故障整理成了一份速查画像，分享给团队后排查效率提升很明显：
| 故障现象 | 常见原因 | 典型场景 |
|---|---|---|
| 检索结果只有答案的一半 | 答案内容跨块，上下文被切断 | 问题涉及“前因后果”，前半在A块后半在B块 |
| 返回内容主题混杂 | 两个不相关主题被塞进同一块 | 固定窗口跨过章节边界 |
| 同样的查询结果不稳定 | 重叠区域导致同一内容被多次索引 | 多个块命中同一片段，得分被重复累积 |
| 相似查询检索到完全不同块 | 块边界随机变化，向量语义不稳定 | 固定token切分在敏感文本上产生随机位移 |
这些故障归结起来就一句话：切割边界没有跟随语义边界。暴力分割省下来的那几分钟，全都会在调试和提示词修补里连本带利还回去。
3. 语义智能切割的核心思路：让边界有意义
3.1 什么是真正意义上“有语义”的切割
语义切割并不是什么神秘魔法，它的目标只有一个：让每一个被切出来的块，尽可能对应一个完整的语义单元。一个语义单元可以是“某个功能的完整说明”、“某个问题的完整解答”、“某个概念的完整论述”。它应该有明确的主题，内部信息自洽，且与相邻块之间有清晰的边界。
这个定义听起来简单，落地时最大的难点是“语义单元的大小不固定”。有的主题一句话就能说完，只有几十个token；有的主题洋洋洒洒上千字。真正意义上的语义切割器，必须能动态识别这些大小不一的边界，而不是套一个固定窗口。
在Spring AI生态里，官方的DocumentSplitter接口给了我们足够的扩展空间。你完全可以实现自己的语义切割器，也可以组合现成的策略去做多级切割。关键是意识到：官方内置实现解决的是通用场景，生产系统的语义切割通常需要自定义。
3.2 基于嵌入向量的语义边界检测
我目前最常用的语义切割方法是基于嵌入向量的边界检测，它的原理很容易理解：把文档先切成细粒度的基础单元，比如句子或小段；然后逐个计算嵌入向量；如果相邻两个单元之间的语义相似度足够高，就认为它们属于同一个主题，反之则是一条边界。最后按边界把基础单元聚合起来，形成有语义意义的块。
你可以把它理解成用“向量距离”来代替“空白字符”来寻找自然边界。这个思路本质上是在文本的语义空间里做分段，不受物理排版的影响，特别适合那些格式混乱、但内容逻辑清晰的文档。
一个简化的特征算法大致是这样：
sentences = split_into_sentences(text) embeddings = embed_sentences(sentences) # 拿到每个句子的向量 boundaries = [] for i in range(1, len(embeddings)): similarity = cosine_similarity(embeddings[i-1], embeddings[i]) if similarity < threshold: boundaries.append(i) chunks = group_sentences_by_boundaries(sentences, boundaries)阈值的选择是这个方案的关键。设得太高，块会越切越碎，退化和暴力分割差不多；设得太低，块会越合越大，又混入无关主题。实践里我一般先用一小批标注好的文档做阈值扫描，画一条“块数-相似度阈值”的曲线，然后选曲线拐点的位置。
3.3 结合结构解析与LLM辅助的高级做法
向量相似度方法已经能解决大部分问题，但它也有弱点：有时文本的语义是渐变的，相邻句子相似度都很高，整体主题却在慢慢漂移。针对这种情况，我引入了结构解析和LLM辅助的两条补充路径。
结构解析，是先把文档还原成树状结构。PDF或者HTML可以提取标题层级，Markdown可以直接解析章节。切割时先按最大的结构单元切，再在每个结构单元内部做语义聚合。这样既保住了文档本身的逻辑，又兼顾了块的主题内聚。Spring AI生态里对Markdown格式的支持也在慢慢完善，可以拿来配合使用。
LLM辅助则更直接：让模型读一段文本，然后输出一个建议的切割位置。比如给模型提示“请从下面文本中找出完整的语义边界，并只输出边界位置的编号”。这个方法精准度高，但成本也高。我通常只把它用在那些高价值、结构复杂的文档上，比如法律合同、技术白皮书，而不会让它跑全量数据。
这三种手段叠加起来，才能形成一套真正抗打的语义切割体系。向量相似度负责主体，结构解析负责骨架，LLM负责精细校准。三者的组合，才是我理解的“语义智能”，而不是单纯在某一个环节上做花活。
4. Spring AI 文档切割的落地实践与参数调优
4.1 Spring AI内置切割器：先了解家底
开始定制之前，建议先盘点一下Spring AI自带的能力。DocumentSplitter接口是核心扩展点，所有内置切割器都实现它。常见的有TokenTextSplitter、LineBasedTextSplitter、ContentTextSplitter，以及可组合的DocumentSplitter链。在我接触过的项目里，直接使用TokenTextSplitter是最普遍的开局方式。
一段典型的Spring AI配置是这样：
@Bean public DocumentSplitter documentSplitter() { return TokenTextSplitter.builder() .defaultChunkSize(800) .minChunkSizeChars(350) .minChunkLengthToEmbed(5) .keepSeparator(true) .build(); }这里的参数虽然少，每个背后都有讲究。defaultChunkSize控制在token维度上的目标块大小，取值范围和你的嵌入模型最大输入长度、LLM上下文窗口都有关系；minChunkSizeChars是一个防碎片保险丝，避免切出过短的无意义块；keepSeparator决定是否在切分时保留分隔符，这个参数在高密度文档上影响很大。
内置切割器当基线用是合格的，但不要指望它一步到位。它的逻辑本质还是“按长度找断点”，最多加入行、内容变化的启发式判断。生产系统做了语义定制之后，内置的通常只用来做第一级粗切。
4.2 自己动手实现一个语义切割器
Spring AI的自定义切割器写起来并不复杂，核心是实现DocumentSplitter接口，在split方法里返回一组新的Document。我的典型做法是：先用ContentTextSplitter把文档切碎成细粒度片段，再做嵌入计算和边界检测，最后按检测结果重新组装。
一个参考骨架长这样：
public class SemanticDocumentSplitter implements DocumentSplitter { private final DocumentSplitter baseSplitter; private final EmbeddingModel embeddingModel; private final double similarityThreshold; @Override public List<Document> split(Document document) { List<Document> fragments = baseSplitter.split(document); List<float[]> embeddings = fragments.stream() .map(f -> embeddingModel.embed(f.getText())) .toList(); List<Document> chunks = new ArrayList<>(); // 计算相邻片段相似度，低于阈值时闭合当前chunk // 合并时做好文本拼接与metadata保留 return chunks; } }这个骨架里最值得注意的不是相似度计算，而是metadata的保留。Spring AI的Document对象支持metadata，切割后如果丢掉来源页码、章节号、标题等信息，后续引用溯源和过滤检索都得返工。我见过太多自定义切割器在这里翻车，合并文本时用字符串拼接还好，把metadata丢了就麻烦了。
此外，嵌入计算是有成本的。长文档逐句子嵌入会非常耗时，所以我在设计时会把细切粒度控制在句子或短段级别，而不是单词级别，并且在批处理时复用已经计算好的嵌入结果。
4.3 参数选择：从模型约束倒推切割参数
切割参数的设置，最忌讳拍脑袋。我的思路是倒推，先看清楚自己和下游模型的硬约束：
- 嵌入模型的最大输入token数，决定单个块的上限；
- LLM的上下文窗口，决定喂给生成模型的总token预算；
- 检索重排模型对块长度的偏好，决定块是否需要进一步压缩；
- 业务本身对答案粒度的要求，决定块大小的下限。
举个例子，如果使用的嵌入模型单次最多支持512个token，那你把块切到800个token纯属自找麻烦。很多向量库和Spring AI的默认配置都写在512以内，但项目里总有人会改大，等线上出现嵌入被截断或检索效果下降时才回头检查。
我自己常用的推荐区间是：块大小控制在200到500个token之间，重叠控制在块大小的10%到20%之间。小于200个token，块会失去足够的上下文信息；大于500个token，主题混杂的概率明显上升。但这个区间不是死的，结构清晰、段落分明的文档可以适当放宽，而FAQ类、条款类文档则需要更小更聚焦的块。
4.4 什么时候用重叠，什么时候不该用
固定窗口切割里，重叠是一种常见的补救手段，目的就是为了避免语义刚好被切断在边界上。TokenTextSplitter也支持设置numOverlap之类的能力。但在语义切割里，重叠的作用明显下降，因为边界本身就是按语义找出来的，重叠反而会造成冗余。
我现在的习惯是：纯定长切割的过渡期，保留10%到20%的重叠，用来缓解边界生硬的问题；一旦切换到语义切割，重叠直接清零，靠边界检测来保证块间衔接。如果切换到语义切割后仍然出现跨块信息断裂，优先检查的是基础单元切分粒度，而不是加重叠。
此外，还有一类特殊文档——法规条文、合同条款——它们天然具有“一条一义”的结构，这种情况下甚至不需要嵌入模型，按条切割加人工规则就是最好的方案。这也是我常提醒团队的：语义切割不是银弹，先看文本本身的规律。
5. 实操全过程：一次从暴力分割到语义切割的完整改造
5.1 场景重现：一个被切割拖垮的知识库
我用一个印象很深的案例来演示完整改造过程。某公司内部有一个基于Spring AI的知识库系统，接入的是产品手册和维修指南，约有一万多个原始文档片段。上线初期用的是TokenTextSplitter，块大小设为800，结果线上检索命中率只有六成左右。
我接手后的第一步不是改代码，而是拉了一批失败的查询样本，逐个查看召回结果。大概看了五十个案例就找到了规律：失败几乎都集中在两种情况。第一种是某个维修步骤跨块，第二步开头被切到下一个块；第二种是整个操作说明被切割成没有上下文的动作碎片，导致用户问“为什么要这样做”时检索到的是孤立的步骤句。
基于这些样本，我定了改造目标：把检索命中率从六成拉到八成以上，同时保证平均检索延迟不上升。
5.2 分步改造：从粗切到语义聚合
整个改造分了三步走，每一步都做了充分验证。
第一步，把原来的单层TokenTextSplitter换成“粗切+细切”两级结构。先用结构解析把文档按章节标题切成大段，再把每段内部分成句子级片段。这一步的价值是为下一步的嵌入计算提供合适粒度的输入。粗切用ContentTextSplitter，细切按句子标点和换行规则来做，Spring AI的DocumentSplitter组合模式在这里发挥了作用。
第二步，接入嵌入模型做语义边界检测。对句子级片段逐个计算嵌入，按相似度阈值聚合。这里我用的是余弦相似度，阈值初始设0.78，后来在小样本上微调到了0.82。聚合过程中严格控制块大小上限，超过500个token强制截断，截断位置优先选择当前集合中相似度最低的相邻边界。
第三步，加入LLM辅助校准，只针对顶层章节做。每章选取开头的几段和结尾的几段，让模型判断边界切得是否干净。这个校准不是全量跑，只跑抽样，成本可控，却能找出向量方法漏掉的边界漂移问题。
改造后的切割器长这样：
List<Document> chunks = new ArrayList<>(); // 结构粗切 Document[] sections = contentSplitter.split(originalDocument); for (Document section : sections) { // 句子级细切 List<Document> sentences = sentenceSplitter.split(section); // 嵌入计算 double[] scores = computeSimilarityScores(sentences); // 按阈值聚合 Chunk current = new Chunk(); for (int i = 0; i < sentences.size(); i++) { current.append(sentences.get(i)); if (shouldBreak(current, scores, i, sentences)) { chunks.add(buildDocument(current)); current = new Chunk(); } } // 每章抽样做LLM边界校准 if (chapterNeedsReview(section)) { adjustBoundaryByLLM(current, section); } }5.3 改造效果：用数据说话
改造完成后，我在同一批测试集上重新跑了一遍评测，结果比预想还乐观。检索命中率从六成左右提到了八成五，跨块断裂问题的出现频率下降了接近一半。更意外的是，因为块数变少了，向量检索的候选集缩小，平均查询延迟反而降低了约三成。
这个结果再次印证了那条被反复验证的经验：切割做对了，RAG系统的后续组件都会变得更轻松。调用更少的块、更精准的上下文、更少的噪声，这些红利不是靠调模型能拿到的。
当然，要说明的是，这次改造依赖于文档本身的特征。产品手册和维修指南有清晰的章节结构，所以结构解析才能发挥作用。如果你手头是大量无结构的客服会话记录，方案还要调整。这也是语义切割最需要“因材施教”的地方。
6. 常见问题与排查技巧实录
6.1 检索结果半对半错：先查块边界
遇到检索结果“有关联但不对”的情况，不要急着改提示词，第一步永远是打印召回块，看边界是不是恰好把关键信息切开了。发现这种情况后，再用原始文档比对一下：如果答案确实跨块，就直接证明切割边界有问题。
我排查过大量此类问题，结论很一致：一个精心调过的提示词，根本救不了把答案拦腰切断的检索上下文。先把边界修干净，再去看生成效果。
6.2 语义切割后效果反而变差怎么办
语义切割不是保证火箭，切完效果变差的情况我遇到过好几回。最典型的原因是基础单元切得太粗或太细。太粗，比如直接把整段作为单元，语义边界根本检测不出来；太细，比如按单字切，嵌入计算出来的相似度曲线噪声太大，阈值形同虚设。
第二个原因是阈值没有按文档类型区分。不同来源的文档，语义粒度分布完全不同。把技术文档调好的0.82，套到销售话术文档上很可能碎成渣。现在我会按文档类型维护多个阈值配置，而不是追求一个“万能阈值”。
此外，嵌入模型的领域匹配度也要复查。拿通用嵌入模型切专业医疗文档，相似度分心的幅度会变小，边界自然不清晰。换个领域适配的模型，效果往往是立竿见影的。每次有团队反馈切割没效果，我第一句话就是：你的嵌入模型和文档领域一样吗？
6.3 保留一份“脏文档样本集”
我强烈建议在项目里长期维护一份“脏文档样本集”，专门收录那些结构混乱、换行丢失、标题错乱的文档。每周用新切割策略跑一遍，看这些难啃的骨头有没有被消化。这个样本集比任何测试集都有价值，因为生产环境里让你崩溃的从来不是规整文档，而是那些从各种工具导出后格式全乱的文稿。
我个人的体会是，文档切割做的是“边界工程”。这项工作没有一劳永逸的答案，不同的业务、不同的文档来源、不同的模型约束，都会走向不同的参数组合。但如果能把切割这件事从“随便切切”提升到“让每个块自己讲一个完整的小话题”，RAG系统的质感会上升一个明确的台阶。希望这篇文章里的踩坑记录和改造思路，能让你少走我走过的弯路。
