AI Agent / 系统课时

切分与清洗文档

切分与清洗文档

RAG 的检索质量很大程度上取决于入库前的文档处理。本节按 Markdown 结构识别已知导航和内容边界,保留代码缩进和原文位置,并切成带少量重叠的片段,最终得到可直接送入向量化或全文索引的结构化数据。

学习目标

  • 清理会干扰检索的噪声、空白和重复内容
  • 按文档结构切分内容,并在过长段落中继续分块
  • 为每个片段保留来源、章节和稳定编号等元数据

先清理会污染检索的内容

清洗的目标不是把文本“改写得更漂亮”,而是删除不承载知识的信息,同时保留原始语义。常见噪声包括页眉页脚、导航菜单、版权声明、重复面包屑、空标题、连续空白,以及从网页抓取后残留的按钮文字。

不要随意删除代码、表格、参数名和否定词。它们往往正是用户查询时需要命中的信息。对于重复内容,可以优先在同一文档内部做精确去重;跨文档的近似去重应更谨慎,因为不同版本的相似段落可能代表有效差异。

按结构边界再控制片段大小

优先利用标题、段落、列表或自然章节作为边界,因为这些位置通常对应完整语义。只有某个章节仍然过长时,再按字符数或 token 数继续切分。这样比“全文每 500 字硬切一次”更不容易把问题和答案、定义和解释拆开。

片段不能无限增大。过大会让一个向量混入多个主题,召回后也会把大量无关文本塞进上下文;过小则容易丢失指代关系。工程上通常先选择一个可解释的初始范围,再通过真实查询集评估召回质量,而不是把某个固定数字当成通用最佳值。

用一个最小管道完成清洗与切分

把代码保存为 rag_chunks.py。它处理顶层二级标题、普通正文和顶层围栏代码。只移除已确认的站点噪声整行,并保留每块在未清洗原文中的字符区间 [start, end)。超限的正文以字符窗口拆分,代码块作为整体保留。过长代码块会报错,调用方可以改用按语法拆分的代码解析器。

python
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))

预期输出

text
安装 正文
安装 代码
编号唯一: True

生产入库使用支持完整 Markdown 语法的解析器,保留列表、表格和源位置。字符上限只用于课堂,实际按嵌入模型的 tokenizer 计数。先按段落、句子等结构边界拆分,再对仍超限的片段施加上限。保留查询用文本和来源对应的原文区间,以支持引用和更新。

检查切分质量而不是只看长度

切分完成后,至少抽查三类问题:片段开头是否大量出现“它”“上述方法”这类失去指代的信息;代码块或表格是否被从中间截断;同一知识点是否因为重叠策略产生过多重复片段。发现这些问题时,应优先调整结构解析规则,再调节块大小。

对于 Markdown、HTML、PDF 或代码仓库,最好分别使用适合其结构的解析器。统一转成纯文本虽然实现简单,却会丢掉标题层级、表格边界和代码块等高价值信号。

为后续索引保留稳定元数据

片段进入嵌入模型之前,应尽量把“内容”和“身份信息”分开保存。正文用于生成向量,元数据用于过滤、排序、去重和引用。片段编号由租户、文档、版本和原文区间派生。相同版本与切分规则可复现该编号。重新切分或更新内容时使用新版本,旧片段按活动版本过滤或清理。

清洗与切分的最终验收标准不是得到多少块,而是:每个片段语义相对完整、来源可追踪、噪声足够少,并且能在真实检索问题下稳定命中所需知识。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

切分与清洗文档

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通