AI Agent / 系统课时
切分与清洗文档
切分与清洗文档
RAG 的检索质量很大程度上取决于入库前的文档处理。本节按 Markdown 结构识别已知导航和内容边界,保留代码缩进和原文位置,并切成带少量重叠的片段,最终得到可直接送入向量化或全文索引的结构化数据。
学习目标
- 清理会干扰检索的噪声、空白和重复内容
- 按文档结构切分内容,并在过长段落中继续分块
- 为每个片段保留来源、章节和稳定编号等元数据
先清理会污染检索的内容
清洗的目标不是把文本“改写得更漂亮”,而是删除不承载知识的信息,同时保留原始语义。常见噪声包括页眉页脚、导航菜单、版权声明、重复面包屑、空标题、连续空白,以及从网页抓取后残留的按钮文字。
不要随意删除代码、表格、参数名和否定词。它们往往正是用户查询时需要命中的信息。对于重复内容,可以优先在同一文档内部做精确去重;跨文档的近似去重应更谨慎,因为不同版本的相似段落可能代表有效差异。
按结构边界再控制片段大小
优先利用标题、段落、列表或自然章节作为边界,因为这些位置通常对应完整语义。只有某个章节仍然过长时,再按字符数或 token 数继续切分。这样比“全文每 500 字硬切一次”更不容易把问题和答案、定义和解释拆开。
片段不能无限增大。过大会让一个向量混入多个主题,召回后也会把大量无关文本塞进上下文;过小则容易丢失指代关系。工程上通常先选择一个可解释的初始范围,再通过真实查询集评估召回质量,而不是把某个固定数字当成通用最佳值。
用一个最小管道完成清洗与切分
把代码保存为 rag_chunks.py。它处理顶层二级标题、普通正文和顶层围栏代码。只移除已确认的站点噪声整行,并保留每块在未清洗原文中的字符区间 [start, end)。超限的正文以字符窗口拆分,代码块作为整体保留。过长代码块会报错,调用方可以改用按语法拆分的代码解析器。
import json
import re
from hashlib import sha256
NOISE = {"首页", "返回顶部", "版权所有"}
FENCE = re.compile(r"^ {0,3}(`{3,}|~{3,})(.*)$")
HEADING = re.compile(r"^ {0,3}##[ \t]+(.+)")
def spans(text):
section = "正文"
offset = prose_start = 0
fence = None
for raw in text.splitlines(keepends=True):
end = offset + len(raw)
line = raw.rstrip("\r\n")
marker = FENCE.fullmatch(line)
heading = HEADING.fullmatch(line)
if fence is not None:
if (
marker and marker[1][0] == fence[0]
and len(marker[1]) >= len(fence) and not marker[2].strip()
):
yield section, prose_start, end, True
prose_start, fence = end, None
elif marker and (marker[1][0] == "~" or "`" not in marker[2]):
yield section, prose_start, offset, False
prose_start, fence = offset, marker[1]
elif heading or line.strip() in NOISE:
yield section, prose_start, offset, False
if heading:
section = heading[1].strip()
prose_start = end
offset = end
yield section, prose_start, offset, fence is not None
def chunk_document(text, tenant_id, doc_id, revision, size=160, overlap=24):
if type(size) is not int or type(overlap) is not int or not 0 <= overlap < size:
raise ValueError("require integer limits with 0 <= overlap < size")
chunks = []
for section, start, end, atomic in spans(text):
if not text[start:end].strip():
continue
if atomic and end - start > size:
raise ValueError("code block exceeds chunk limit")
while start < end:
stop = min(start + size, end)
content = text[start:stop]
if content.strip():
key = json.dumps([tenant_id, doc_id, revision, start, stop], separators=(",", ":"))
chunks.append({
"chunk_id": sha256(key.encode("utf-8")).hexdigest(),
"section": section, "start": start, "end": stop, "text": content,
})
if stop == end:
break
start = stop - overlap
return chunks
if __name__ == "__main__":
source = "首页\n## 安装\n安装前检查 Python 版本。\n## 安装\n```python\n print(1)\n## 这行在代码块里\n```\n"
chunks = chunk_document(source, "acme", "setup", "v2", size=50, overlap=5)
for chunk in chunks:
assert source[chunk["start"]:chunk["end"]] == chunk["text"]
print(chunk["section"], "代码" if chunk["text"].startswith("```") else "正文")
print("编号唯一:", len({chunk["chunk_id"] for chunk in chunks}) == len(chunks))预期输出
安装 正文
安装 代码
编号唯一: True生产入库使用支持完整 Markdown 语法的解析器,保留列表、表格和源位置。字符上限只用于课堂,实际按嵌入模型的 tokenizer 计数。先按段落、句子等结构边界拆分,再对仍超限的片段施加上限。保留查询用文本和来源对应的原文区间,以支持引用和更新。
检查切分质量而不是只看长度
切分完成后,至少抽查三类问题:片段开头是否大量出现“它”“上述方法”这类失去指代的信息;代码块或表格是否被从中间截断;同一知识点是否因为重叠策略产生过多重复片段。发现这些问题时,应优先调整结构解析规则,再调节块大小。
对于 Markdown、HTML、PDF 或代码仓库,最好分别使用适合其结构的解析器。统一转成纯文本虽然实现简单,却会丢掉标题层级、表格边界和代码块等高价值信号。
为后续索引保留稳定元数据
片段进入嵌入模型之前,应尽量把“内容”和“身份信息”分开保存。正文用于生成向量,元数据用于过滤、排序、去重和引用。片段编号由租户、文档、版本和原文区间派生。相同版本与切分规则可复现该编号。重新切分或更新内容时使用新版本,旧片段按活动版本过滤或清理。
清洗与切分的最终验收标准不是得到多少块,而是:每个片段语义相对完整、来源可追踪、噪声足够少,并且能在真实检索问题下稳定命中所需知识。