简介这份源码资源面向RAG应用开发者与AI大模型学习者聚焦长文档切片这一检索增强生成流程中的关键环节帮助解决切片方式选择困难、检索质量不稳定等问题。资源包共5个文件以Python脚本为主辅以txt依赖说明与工程配置文件压缩包约13KB轻量易读便于直接运行与二次修改。内容围绕五种切片策略展开改进的固定长度切片、语义切片、LLM语义切片、层次切片与滑动窗口切片逐一说明核心思想、工作流程、优缺点及适用场景并给出结合FAISS搭建本地知识库的流程图与选型指南。读者可据此对照自身文档规模与算力条件快速定位合适的切片方案理解参数调整对检索与生成效果的影响同时获得从理论到实践的AI大模型学习路径参考。目前已有201人学习下载适合希望系统掌握RAG切片技术的中级开发者。1. RAG 切片策略指南源码为什么你的知识库总在“答非所问”如果你搭过 RAG 知识库大概率遇到过这种场景文档明明喂进去了用户问一个跨段落的问题模型却答得驴唇不对马嘴。排查一圈 embedding 模型、向量库、prompt 都没问题最后发现根因在切片——把一份带层级标题的技术手册按固定 500 字硬切标题和正文被拦腰截断检索出来的 chunk 全是半截话。这份《RAG 切片策略指南》源码包解决的就是这个最容易被忽视、却最影响召回质量的环节。它不是又一个 RAG 框架而是一套可复用的切片策略实现集合覆盖固定长度、递归字符、语义分块、按文档结构切分等常见方案附带可跑的 Python 代码和参数配置。适合正在调 RAG 召回率、被 chunk 边界问题折磨的开发者也适合想系统理解切片选型逻辑的从业者。下面我按“策略原理 → 代码落地 → 参数调优 → 踩坑排查”的顺序把这份源码拆开讲透。2. 切片策略的选型逻辑四种方案到底该用哪个2.1 固定长度切片为什么是基线而不是终点固定长度切片Fixed-size Chunking是所有 RAG 教程的起点按字符数或 token 数切设一个 chunk_size 和 overlap。它的优点是实现简单、chunk 大小均匀、对向量库友好。但问题也很明显——它完全不理解文本语义一个完整的论证可能被切成两半检索时两半各自都拿不到完整信息。源码里fixed_size_chunker.py的实现大概是这个逻辑def fixed_size_chunk(text, chunk_size500, overlap50): 固定长度切片按字符数切分overlap 为相邻 chunk 的重叠字符数 chunk_size: 每个 chunk 的目标字符数 overlap: 重叠部分防止边界信息丢失 chunks [] start 0 while start len(text): end start chunk_size chunk text[start:end] chunks.append(chunk) # 下一次从 end - overlap 开始保证边界内容被两个 chunk 覆盖 start end - overlap return chunks这里overlap是关键参数。设太小边界信息丢失设太大冗余 chunk 增多检索时重复命中。经验值是 chunk_size 的 10%20%。但固定长度切片的根本缺陷不在参数而在于它假设“文本是均匀的”而真实文档有标题、段落、列表、代码块这些结构信息一旦被切碎就再也找不回来。2.2 递归字符切片按分隔符优先级逐层降级递归字符切片Recursive Character Text Splitting是目前工程上最常用的折中方案。它的思路是先尝试用最高优先级的分隔符如\n\n段落切如果切出来的块还是太大就降级用\n切再不行用句号、逗号直到块大小满足要求。源码里recursive_chunker.py的核心逻辑def recursive_chunk(text, chunk_size500, separatorsNone): 递归切片按分隔符优先级逐层降级 separators 默认从段落 - 换行 - 句号 - 空格 if separators is None: separators [\n\n, \n, 。, , , , ] # 找到第一个能切出合适大小的分隔符 for sep in separators: if sep : # 兜底直接按字符切 return [text[i:ichunk_size] for i in range(0, len(text), chunk_size)] if sep in text: parts text.split(sep) chunks [] current for part in parts: # 如果当前累积 新部分不超过 chunk_size就合并 if len(current) len(part) len(sep) chunk_size: current part sep else: if current: chunks.append(current) current part sep if current: chunks.append(current) # 检查是否有超大的块需要继续降级 if all(len(c) chunk_size for c in chunks): return chunks return [text]这个实现里separators的顺序就是优先级。中文场景下句号、问号、感叹号应该排在空格前面因为中文句子以标点断句空格反而少见。很多人直接套英文的[\n\n, \n, , ]结果中文文档切出来全是半句话这是血泪经验。递归切片的优势是尽量保持语义单元的完整性但它仍然不理解“这段在讲什么”只是机械地按符号切。对于结构清晰的文档Markdown、HTML更好的方案是按结构切。2.3 按文档结构切片Markdown 标题层级怎么用如果你的知识库来源是 Markdown、HTML 或带标题层级的文档按结构切片Structure-aware Chunking往往效果最好。核心思路是以标题为边界切分每个 chunk 自带标题路径作为上下文。源码里markdown_chunker.py的做法import re def markdown_structure_chunk(text, max_chunk_size800): 按 Markdown 标题层级切片 每个 chunk 保留其所属的标题路径如 ## 安装 ### 依赖 lines text.split(\n) chunks [] current_headers [] # 标题栈 current_content [] header_pattern re.compile(r^(#{1,6})\s(.*)) for line in lines: match header_pattern.match(line) if match: # 遇到新标题先把之前的内容存为一个 chunk if current_content: content \n.join(current_content).strip() if content: header_path .join(current_headers) chunks.append({ header: header_path, content: content }) current_content [] level len(match.group(1)) title match.group(2) # 维护标题栈弹出比当前层级深的标题 current_headers current_headers[:level-1] current_headers.append(title) else: current_content.append(line) # 处理最后一段 if current_content: content \n.join(current_content).strip() if content: chunks.append({ header: .join(current_headers), content: content }) return chunks这个实现的关键是header_path——每个 chunk 都带着从一级标题到当前标题的完整路径。检索时即使正文里没出现关键词标题路径里的词也能帮助命中。比如用户问“安装依赖”某个 chunk 正文只写了pip install xxx但它的 header 是“安装 依赖”embedding 时把 header 拼进 content 一起编码召回率会明显提升。但要注意如果某个章节内容特别长超过 max_chunk_size还需要在章节内部再做二次切分。源码里对这种情况做了递归处理先按标题切再对超长章节用递归字符切。2.4 语义切片用 embedding 相似度找边界值不值语义切片Semantic Chunking是这几年的热门方向先按句子切然后计算相邻句子的 embedding 相似度在相似度骤降的地方切一刀。理论上它能找到真正的语义边界但实际用起来有几个问题。源码里semantic_chunker.py的实现思路import numpy as np from sentence_transformers import SentenceTransformer def semantic_chunk(text, model_nameall-MiniLM-L6-v2, threshold_percentile90): 语义切片按句子 embedding 相似度找边界 在相似度低于阈值的句子之间切分 model SentenceTransformer(model_name) # 按句号、问号、感叹号分句 sentences [s.strip() for s in re.split(r[。], text) if s.strip()] if len(sentences) 2: return [text] embeddings model.encode(sentences) # 计算相邻句子的余弦相似度 similarities [] for i in range(len(embeddings) - 1): sim np.dot(embeddings[i], embeddings[i1]) / ( np.linalg.norm(embeddings[i]) * np.linalg.norm(embeddings[i1]) ) similarities.append(sim) # 相似度低于阈值的点作为切分点 threshold np.percentile(similarities, 100 - threshold_percentile) chunks [] current [sentences[0]] for i, sim in enumerate(similarities): if sim threshold: chunks.append(。.join(current) 。) current [sentences[i1]] else: current.append(sentences[i1]) if current: chunks.append(。.join(current) 。) return chunks这个方案的问题在于第一它需要额外跑一遍 embedding切片阶段就消耗算力第二threshold_percentile这个参数很玄学不同文档分布差异大很难有一个通用值第三对于本身语义连贯的长段落它可能切出很多碎块。我的建议是语义切片适合对召回精度要求极高、且文档量不大的场景日常工程用递归切片 结构切片组合就够了。3. 把切片策略接进 RAG 流程代码怎么串起来3.1 切片器与向量库的对接方式切片只是第一步切完的 chunk 要编码、入库、检索。源码里提供了一个统一的ChunkPipeline类把切片器和后续流程串起来class ChunkPipeline: def __init__(self, chunker, embedder, vector_store): chunker: 切片器实例需实现 chunk(text) 方法 embedder: embedding 模型需实现 encode(texts) 方法 vector_store: 向量库客户端需实现 add(vectors, metadata) 方法 self.chunker chunker self.embedder embedder self.vector_store vector_store def ingest(self, documents): documents: [{id: doc1, text: ..., source: ...}] all_chunks [] for doc in documents: chunks self.chunker.chunk(doc[text]) for i, chunk in enumerate(chunks): # 每个 chunk 保留来源和序号方便溯源 metadata { doc_id: doc[id], source: doc.get(source, ), chunk_index: i, total_chunks: len(chunks) } # 如果 chunk 是 dict结构切片把 header 拼进文本 if isinstance(chunk, dict): text f{chunk[header]}\n{chunk[content]} metadata[header] chunk[header] else: text chunk all_chunks.append({text: text, metadata: metadata}) # 批量编码 texts [c[text] for c in all_chunks] vectors self.embedder.encode(texts) # 入库 self.vector_store.add( vectorsvectors, metadata[c[metadata] for c in all_chunks], textstexts ) return len(all_chunks)这个类里metadata的设计很关键。doc_id和chunk_index让你在检索到某个 chunk 后能回溯原文header字段在结构切片时特别有用——检索时可以按 header 过滤比如用户问“安装步骤”可以先筛 header 包含“安装”的 chunk再在里面做向量检索。3.2 检索时怎么利用切片元数据很多人切片时保留了元数据检索时却只用向量相似度白白浪费了结构信息。源码里retriever.py给了一个混合检索的示例def hybrid_retrieve(query, vector_store, embedder, top_k5, header_filterNone): 混合检索向量相似度 元数据过滤 header_filter: 可选按 header 关键词预过滤 query_vector embedder.encode([query])[0] # 如果指定了 header 过滤先缩小候选集 if header_filter: candidates vector_store.search( query_vector, top_ktop_k * 3, # 多召回一些过滤后再截断 filter{header: {$contains: header_filter}} ) else: candidates vector_store.search(query_vector, top_ktop_k * 3) # 对候选做重排序向量相似度 header 匹配加分 results [] for cand in candidates: score cand[score] if header_filter and header_filter in cand[metadata].get(header, ): score 0.1 # header 命中加分 results.append({**cand, final_score: score}) results.sort(keylambda x: x[final_score], reverseTrue) return results[:top_k]这里的header_filter不是必须的但在结构清晰的文档里它能显著提升精度。比如用户问“怎么配置超时时间”如果某个 chunk 的 header 是“配置 超时”即使正文里没出现“超时”这个词也能被召回。3.3 参数怎么调chunk_size 和 overlap 的实验方法chunk_size 和 overlap 没有万能值但有一套可复现的调参方法。源码里附带了一个tune_chunk_size.py脚本思路是用一组标注好的问答对遍历不同的 chunk_size 和 overlap 组合看哪个组合的召回率最高。def evaluate_chunk_config(documents, qa_pairs, chunk_sizes, overlaps): documents: 原始文档列表 qa_pairs: [{question: ..., answer: ..., source_doc: doc1}] chunk_sizes: 待测试的 chunk_size 列表 overlaps: 待测试的 overlap 列表 results [] for cs in chunk_sizes: for ov in overlaps: if ov cs: continue # overlap 不能大于等于 chunk_size chunker RecursiveChunker(chunk_sizecs, overlapov) pipeline ChunkPipeline(chunker, embedder, vector_store) pipeline.ingest(documents) # 对每个问题检索看正确答案所在的 chunk 是否被召回 hit_count 0 for qa in qa_pairs: retrieved hybrid_retrieve(qa[question], vector_store, embedder, top_k5) # 检查检索结果里是否有来自 source_doc 的 chunk if any(r[metadata][doc_id] qa[source_doc] for r in retrieved): hit_count 1 recall hit_count / len(qa_pairs) results.append({chunk_size: cs, overlap: ov, recall: recall}) # 按召回率排序 results.sort(keylambda x: x[recall], reverseTrue) return results这个脚本的价值在于把“调参”从玄学变成实验。我一般会先跑一轮粗调chunk_size 从 200 到 1000步长 200overlap 从 0 到 100步长 50找到最优区间后再细调。注意召回率高不代表最终回答质量高还要看 chunk 是否包含完整答案。有时候 chunk_size 太小召回率高但答案不完整chunk_size 太大召回率低但一旦召回信息全。需要结合具体场景权衡。4. 避坑与排查切片环节最常见的五个翻车点4.1 中文文档用英文分隔符切出来全是半句话现象检索时经常召回不完整的句子比如“请确保系统已安装”后面没了。原因递归切片的分隔符列表沿用了英文默认值[\n\n, \n, , ]中文句子之间没有空格所以降级到空格分隔符时切不动最后按字符硬切。解决把中文标点加进分隔符列表且优先级要高于空格。推荐顺序[\n\n, \n, 。, , , , , , ]。源码里recursive_chunker.py已经内置了中文分隔符直接调用即可。4.2 overlap 设得比 chunk_size 还大死循环现象切片脚本跑着跑着卡死或者 chunk 数量爆炸。原因start end - overlap这行代码如果overlap chunk_size那么end - overlap start下一次循环的 start 没有前进陷入死循环。解决在切片函数入口加参数校验overlap必须小于chunk_size建议不超过chunk_size的 30%。源码里fixed_size_chunker.py和recursive_chunker.py都加了assert overlap chunk_size。4.3 结构切片时标题层级跳级header 路径错乱现象某个 chunk 的 header 显示“安装 配置 超时”但原文里“超时”是“配置”的下一级不是同级。原因Markdown 标题层级不连续比如从##直接跳到####中间缺了###。标题栈维护时按 level 截断跳级会导致栈里残留错误的父标题。解决维护标题栈时不要直接current_headers[:level-1]而是记录每个标题的实际 level遇到跳级时补空或按实际层级处理。源码里markdown_chunker.py用了header_stack列表存(level, title)元组弹出时比较 level 而不是位置。4.4 语义切片阈值设太高chunk 碎成渣现象语义切片后每个 chunk 只有一两句话检索时召回一堆碎片拼不出完整答案。原因threshold_percentile设得太大比如 95导致只有相似度极低的点才切分大部分句子都被切开了。解决语义切片的阈值建议从 7080 开始试且要结合最小 chunk 长度限制——如果切出来的 chunk 小于 100 字就和相邻 chunk 合并。源码里semantic_chunker.py加了min_chunk_size参数做后处理。4.5 切片后没保留原文位置检索到答案却找不到出处现象用户问了一个问题模型答对了但想点进原文看详细内容时不知道这个 chunk 来自哪份文档的哪一段。原因切片时只存了文本没存doc_id、chunk_index、字符偏移量等元数据。解决切片时至少保留doc_id和chunk_index最好再存start_char和end_char。源码里ChunkPipeline.ingest方法默认写入这些字段。如果用的是结构切片header字段也要存方便定位到章节。5. 进阶技巧用切片元数据做检索重排序与答案溯源切片策略的终极价值不只是“切得准”而是让检索结果可解释、可溯源。源码里有一个RerankByChunkContext的示例思路是利用 chunk 的邻居信息做重排序如果一个 chunk 被召回但它的前后邻居也包含相关关键词说明这个位置确实是答案所在可以加分。def rerank_with_neighbors(query, retrieved_chunks, vector_store, embedder, bonus0.05): 利用 chunk 的邻居信息重排序 retrieved_chunks: 初始检索结果每个包含 metadata.chunk_index query_vector embedder.encode([query])[0] reranked [] for chunk in retrieved_chunks: score chunk[score] doc_id chunk[metadata][doc_id] idx chunk[metadata][chunk_index] # 取前后各一个邻居 neighbors vector_store.get_by_metadata({ doc_id: doc_id, chunk_index: {$in: [idx-1, idx1]} }) for neighbor in neighbors: # 计算邻居与 query 的相似度 neighbor_vec embedder.encode([neighbor[text]])[0] sim np.dot(query_vector, neighbor_vec) / ( np.linalg.norm(query_vector) * np.linalg.norm(neighbor_vec) ) if sim 0.7: # 邻居也相关给当前 chunk 加分 score bonus reranked.append({**chunk, rerank_score: score}) reranked.sort(keylambda x: x[rerank_score], reverseTrue) return reranked这个技巧在长文档问答里特别有用。比如一份 50 页的技术手册答案分散在连续三个 chunk 里初始检索可能只召回了中间那个但通过邻居加分可以把前后两个也拉上来拼出完整上下文。另一个实用技巧是答案溯源检索到 chunk 后用metadata里的doc_id和chunk_index反查原文把 chunk 在原文中的位置高亮出来。源码里traceback.py提供了一个简单的实现根据start_char和end_char从原始文档里截取上下文展示给用户。这样用户不仅能看到答案还能看到答案在原文里的位置信任度会高很多。我自己的习惯是每次上线新的知识库之前先跑一遍tune_chunk_size.py用 2030 个标注问答对做一轮粗调确定 chunk_size 和 overlap 的合理区间然后再用RerankByChunkContext做一轮重排序验证。这套流程走下来召回率通常能从 60% 左右提到 80% 以上。从那以后我每次搭 RAG 知识库都强制走一遍切片调参和邻居重排序不再凭感觉设参数。希望这份源码和上面的拆解能帮你少走点弯路。本文还有配套的精品资源点击获取