企业官网建设流程全解析

简介：这份源码资源面向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_size=500, overlap=50): """ 固定长度切片：按字符数切分，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_size=500, separators=None): """ 递归切片：按分隔符优先级逐层降级 separators 默认从段落 -> 换行 -> 句号 -> 空格 """ if separators is None: separators = ["\n\n", "\n", "。", "！", "？", " ", ""] # 找到第一个能切出合适大小的分隔符 for sep in separators: if sep == "": # 兜底：直接按字符切 return [text[i:i+chunk_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_size=800): """ 按 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_name="all-MiniLM-L6-v2", threshold_percentile=90): """ 语义切片：按句子 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[i+1]) / ( np.linalg.norm(embeddings[i]) * np.linalg.norm(embeddings[i+1]) ) 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[i+1]] else: current.append(sentences[i+1]) 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( vectors=vectors, metadata=[c["metadata"] for c in all_chunks], texts=texts ) 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_k=5, header_filter=None): """ 混合检索：向量相似度 + 元数据过滤 header_filter: 可选，按 header 关键词预过滤 """ query_vector = embedder.encode([query])[0] # 如果指定了 header 过滤，先缩小候选集 if header_filter: candidates = vector_store.search( query_vector, top_k=top_k * 3, # 多召回一些，过滤后再截断 filter={"header": {"$contains": header_filter}} ) else: candidates = vector_store.search(query_vector, top_k=top_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(key=lambda x: x["final_score"], reverse=True) 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_size=cs, overlap=ov) 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_k=5) # 检查检索结果里是否有来自 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(key=lambda x: x["recall"], reverse=True) return results

这个脚本的价值在于把“调参”从玄学变成实验。我一般会先跑一轮粗调（chunk_size 从 200 到 1000，步长 200；overlap 从 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），导致只有相似度极低的点才切分，大部分句子都被切开了。

解决：语义切片的阈值建议从 70～80 开始试，且要结合最小 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, bonus=0.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, idx+1]} }) 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(key=lambda x: x["rerank_score"], reverse=True) return reranked

这个技巧在长文档问答里特别有用。比如一份 50 页的技术手册，答案分散在连续三个 chunk 里，初始检索可能只召回了中间那个，但通过邻居加分，可以把前后两个也拉上来，拼出完整上下文。

另一个实用技巧是答案溯源：检索到 chunk 后，用metadata里的doc_id和chunk_index反查原文，把 chunk 在原文中的位置高亮出来。源码里traceback.py提供了一个简单的实现，根据start_char和end_char从原始文档里截取上下文，展示给用户。这样用户不仅能看到答案，还能看到答案在原文里的位置，信任度会高很多。

我自己的习惯是：每次上线新的知识库之前，先跑一遍tune_chunk_size.py，用 20～30 个标注问答对做一轮粗调，确定 chunk_size 和 overlap 的合理区间，然后再用RerankByChunkContext做一轮重排序验证。这套流程走下来，召回率通常能从 60% 左右提到 80% 以上。从那以后我每次搭 RAG 知识库，都强制走一遍切片调参和邻居重排序，不再凭感觉设参数。希望这份源码和上面的拆解能帮你少走点弯路。

本文还有配套的精品资源，点击获取