RAG文档加载与清洗实战：把脏文档洗成净菜

可视化演示

展示归并排序的分治策略：递归拆分数组至单元素，再逐层合并有序子数组，通过步进控制观察每个阶段的数组状态变化。

加载器选型：采购要用对工具

菜市场里的西红柿带着泥巴和蒂把，直接用手去撕，只会把灶台弄得一塌糊涂。老师傅带小林看了墙上挂的三把刀：斩骨刀、剔骨刀、削皮刀。斩骨刀什么都能砍，但切豆腐会压碎；剔骨刀专门对付骨骼关节，削皮刀则只处理去了粗皮的净菜。选对工具，菜才完整，手上也不沾泥。

RAG 里的“采购工具”就是文档加载器（Loader）。不同文档格式就像不同食材，需要不同刀具。通用加载器（如 Unstructured）像斩骨刀，什么格式都能读，但精细度有限；HTML 专用工具（如 BeautifulSoup 配合自写解析）像剔骨刀，专门拆解网页骨架；Markdown 解析器（如 markdown-it、python-markdown）像削皮刀，轻量、精准、适合结构本来就规整的文档。

选加载器时看三个维度：一是格式适配，HTML 用 BeautifulSoup/lxml，Markdown 用对应解析库，PDF 用 PyMuPDF；二是结构保留能力，好的加载器会把标题、列表、表格暴露成结构对象，而不是拍平成纯文本；三是性能与批量，企业文档动辄上万份，加载器要支持流式读取和并行处理。落地前先拿一批真实文档试跑，用成功率说话。

$$\text{加载成功率} = \frac{\text{成功解析文档数}}{\text{候选文档总数}} \times 100\%$$

1. 统计成功解析数：分子是加载过程中无异常、文本完整读出的文档数量，反映加载器对格式的兼容程度。

$$\text{成功解析文档数}$$

2. 统计候选总数：分母是本次要入库的全部文档，包括损坏、加密、格式不支持的“带病食材”。

$$\text{候选文档总数}$$

3. 换算为百分比：乘 100% 得到直观通过率，一般以 95% 作为验收线，低于则换加载器或加补偿清洗。

$$\times 100\%$$

小林把三把刀都试了一遍，发现没有哪把刀是万能的——HTML 页面用剔骨刀拆得干干净净，批量导出的 Markdown 用削皮刀效率最高。选加载器，本质就是选对“刀”。

标签噪声清洗：洗去泥土与烂叶

洗菜是备菜的基本功。菜叶上的泥巴，是 <div>、<span> 这类布局标签——它们只负责“摆放位置”，不承载语义；根须上的烂叶，是 <script>、<style> 标签里的内容——它们是植株的一部分，但做菜用不上。小林起初把整颗菜直接放进筐里，结果大厨炒菜时满嘴沙子。

HTML 文档里，标签字符合计往往能占到全文的三成以上。如果原样喂给大模型，token 被白白消耗，检索时还会被导航栏、广告位等噪音干扰。清洗的目标很明确：去掉一切“不影响语义”的标签与符号，只留下干净的文本和结构。

清洗有两条路：其一是解析式清洗，用 HTMLParser 或 BeautifulSoup 解析 DOM，只取文本节点，稳但不快；其二是正则粗清洗，用规则直接删标签，快但不稳。具体动作包括：剔除 <div>、<span> 等布局标签；整段跳过 script/style 内容；把连续空白压缩成单个空格；统一编码，处理 & 之类的 HTML 实体和乱码。洗好的文本里，不应该再看到尖括号和残留属性。

$$\text{干净度} = \left(1 - \frac{\text{残留标签与符号数}}{\text{原始字符数}}\right) \times 100\%$$

1. 记录原始字符数：清洗前统计总字符数，作为基准分母，相当于称一下带泥蔬菜的重量。

$$\text{原始字符数}$$

2. 统计残留噪音：清洗后仍残留的标签、HTML 实体、多余空白等，分子，相当于洗完后搓下来的沙砾。

$$\text{残留标签与符号数}$$

3. 取补集并转百分比：用 1 减去噪声占比得到“干净度”，乘 100% 便于与验收标准对比。

$$\left(1 - \frac{\text{残留标签与符号数}}{\text{原始字符数}}\right) \times 100\%$$

小林把洗好的青菜递给大厨，大厨捏起一片叶子在灯下照了照：没有沙砾、没有烂叶、水珠滚落干净——这才是合格的备菜。

结构信息保留：像剥洋葱一样分清层次

洋葱一层裹着一层，标题就是洋葱的层。切菜的时候如果不管不顾一刀拍扁，表层、中层、里层全混在一起，大厨根本分不清哪些是引言、哪些是细节、哪些是结论。小林发现，文档的标题层级（h1 到 h6）就是这样的洋葱层，拆掉了，文本就成了一锅粥。

在 RAG 里，标题层级、列表缩进、链接引用是“文本的骨架”。如果清洗时把骨架全拆掉，切块时就会把不属于同一主题的内容混在一起，检索时明明命中了关键词，却答非所问。保留结构，是为了让每个知识块都能“溯源”到它在原文里的位置。

具体的做法：h1 转成单 #、h2 转成 ##，这是明确的“层级信号”而不是 Markdown 语法残留；列表保留缩进（- 加空格），让嵌套关系可读；链接保留其文字内容作为引用线索；元数据（标题、作者、日期、来源 URL）抽出来放在知识块前缀，检索命中后能一路回溯到它的“洋葱层”。

$$\text{结构保真度} = \frac{\text{清洗后保留的结构块数}}{\text{原始文档结构块总数}}$$

1. 统计原始结构块：原始文档中 h1~h6、有序无序列表、表格等有语义的结构总数，相当于洋葱的总层数。

$$\text{原始文档结构块总数}$$

2. 统计保留结构块：清洗后仍保留为层级记号或独立块的数量，相当于完整剥下来的洋葱层。

$$\text{清洗后保留的结构块数}$$

3. 求比值：保真度越接近 1，检索时命中的内容越能回溯到正确层级，回答越有据可依。

$$\frac{\text{清洗后保留的结构块数}}{\text{原始文档结构块总数}}$$

小林把剥好的洋葱一层层码在保鲜盒里，每层都贴着标签：表皮、中层、芯。大厨取用时只需要看一眼盒盖上的层级记号，就能精准下刀。

表格代码处理：豆腐切块，牛排保鲜

嫩豆腐要切块保型，一刀拍碎就全完了；带血牛排要原封不动地用保鲜膜包好，不能提前调味。小林做表格时图省事把整张表压成一段话，结果“包名”和“版本号”全串了位；转头又把代码块的换行全删了，大厨看了一眼直接摔锅铲：“程序都废了。”

表格和代码块是清洗流水线上最娇气的食材。表格一旦失去行列关系，单元格就会乱跑，切块后检索到的信息是错位的；代码块一旦被压缩换行，语法就被破坏，喂进知识库只会误导模型。

处理表格：把每一行转成一行文本，单元格用分隔符（| 或制表符）隔开，保持行列对应；表格太大时独立成块，避免与其他段落混切。处理代码块：识别 <pre>/<code> 或 Markdown 的 `` 围栏，内部原样保留，不压缩空白、不改换行，最好打上语言标签（如 lang=python`）。换行规范要区分场景：正文按段落换行，代码按语法换行，两者标准不同，不能一刀切。

$$\text{表格信息损失率} = 1 - \frac{\text{能还原的单元格数}}{\text{原始单元格总数}}$$

1. 统计原始单元格：一个 m 行 n 列的表格，格子总数是 m×n，这是表格完整度的基准，相当于一整块豆腐的体积。

$$\text{原始单元格总数} = \text{行数} \times \text{列数}$$

2. 统计还原单元格：转换后仍能按行列关系读出的格子数，相当于完整切出的豆腐块。

$$\text{能还原的单元格数}$$

3. 求损失率：用 1 减去还原比例，损失率越高，说明表格串位越严重，需要调整分隔符策略。

$$1 - \frac{\text{能还原的单元格数}}{\text{原始单元格总数}}$$

小林把表格切成六块豆腐码齐，把代码块用保鲜膜包好放进冷柜。大厨满意地点点头：“豆腐还是豆腐，牛排还是牛排。”

图片链接取舍：装饰与引用的去留

后厨里有一盆萝卜雕花，好看但炒不熟，上菜时只能当摆盘。菜谱上写“酱汁参考隔壁老王”，这句话必须记下——客人问起来，你得说得出出处。小林对着文档里的图片和链接犯了难：删了怕丢信息，留着又不知道怎么处理。

图片和链接，一个占地方、一个不占地方，但处理原则相通：留下“语义线索”，丢掉“物理实体”。模型是文本模型，看不了二进制图片，但图片的 alt 文本描述的是“图里讲了什么”，这正是可检索的语义。

图片处理策略：优先保留 alt 文本，转成 [图片：alt] 占位符放回原文位置；alt 缺失时看周围上下文，能概括就概括，纯装饰性图片直接删除。链接处理：保留链接文字（anchor text），必要时标注 [链接] 和目标 URL 摘要；对外链打上“外部引用”标记，提示该知识点可能涉及站外内容。取舍的目标，是让视觉信息尽量转成可检索的文本。

$$\text{语义增量} = \frac{\text{保留的 alt 与链接标注条数}}{\text{图片与链接总条数}}$$

1. 统计视觉元素总数：文档中图片与链接的总条数，相当于所有需要决策的摆盘和引用。

$$\text{图片与链接总条数}$$

2. 统计有效线索数：保留的 alt 文本、链接文字和引用标注条数，相当于真正写进菜谱的备注。

$$\text{保留的 alt 与链接标注条数}$$

3. 求语义增量：比值越高，视觉信息流失越少，检索时越容易通过图片描述命中知识。

$$\frac{\text{保留的 alt 与链接标注条数}}{\text{图片与链接总条数}}$$

小林把萝卜雕花扔进垃圾桶，却把“酱汁参考隔壁老王”这句话工工整整记在了菜谱的备注栏。装饰可以丢，出处必须留。

实战最佳实践：开市前的出品检查

开市前 15 分钟，老师傅会把备好的菜抽查三盘：没有头发丝、没有沙砾、摆盘整齐。小林问：“我们不是按流程做完了吗？”老师傅说：“按流程做完了，不代表做对了。检查，是流程的一部分。”

清洗流程搭好之后，必须有“出品检查”的闭环，否则坏料进了冷柜，后面全盘皆输。RAG 的文档清洗也是如此，脚本不报错不代表结果合格。

最佳实践有四件事：一是固定加载器选配标准，HTML 走 BeautifulSoup/Readability，Markdown 走统一解析库，避免每个人各自为政；二是流水线清洗，加载 → 去噪 → 结构提取 → 表格与代码保护 → 分块，每一步都留中间产物，方便出问题时回溯定位；三是抽样质检，随机抽 10~20 份文档，人工核对标题是否保留、表格是否串位、代码块是否完整；四是性能与缓存，抓取时加缓存、多进程并行解析，避免同一份文档反复清洗。用质检通过率量化成果，低于阈值就加规则再跑一轮。

$$\text{质检通过率} = \frac{\text{抽样核对无误的样本数}}{\text{抽样样本总数}} \times 100\%$$

1. 确定抽样样本数：随机抽取 10~20 份清洗结果作为样本，相当于随机抽查三盘菜。

$$\text{抽样样本总数}$$

2. 统计无误样本数：人工核对标题层级、表格、代码块均正确的份数，相当于三盘里几盘合格。

$$\text{抽样核对无误的样本数}$$

3. 换算通过率：乘 100% 与阈值（如 95%）对比，达标才允许批量入库。

$$\frac{\text{抽样核对无误的样本数}}{\text{抽样样本总数}} \times 100\%$$

开市铃响，大厨站在灶台前，看着冷柜里码得整整齐齐的净菜，对小林竖起大拇指：“备菜无小事。检查过了，我才敢放心下锅。”

AI 应用场景

Python 演示

import refrom html.parser import HTMLParser  class DocCleaner(HTMLParser):    """把 HTML 洗成保留结构的纯文本，便于 RAG 分块"""     def __init__(self):        super().__init__()        self.lines = []        self.skip_depth = 0        self.in_code = False        self.code_buf = []        self.in_row = False        self.cells = []     def handle_starttag(self, tag, attrs):        if self.skip_depth:            self.skip_depth += 1            return        if tag in ("script", "style"):            self.skip_depth = 1            return        if tag in ("pre", "code"):            self.in_code = True            return        if re.fullmatch(r"h[1-6]", tag):            self.lines.append("#" * int(tag[1]) + " ")        elif tag == "li":            self.lines.append("- ")        elif tag == "tr":            self.in_row = True            self.cells = []        elif tag in ("td", "th"):            self.cells.append("")     def handle_endtag(self, tag):        if self.skip_depth:            self.skip_depth -= 1            return        if tag in ("pre", "code"):            self.in_code = False            self.lines.append("".join(self.code_buf))            self.code_buf = []            return        if tag == "tr":            self.lines.append(" | ".join(self.cells))            self.in_row = False            return        if tag in ("p", "div", "li") or re.fullmatch(r"h[1-6]", tag):            self.lines.append("")     def handle_data(self, data):        if self.skip_depth:            return        text = re.sub(r"\s+", " ", data).strip()        if not text:            return        if self.in_code:            self.code_buf.append(data)        elif self.in_row and self.cells:            self.cells[-1] += text        else:            self.lines.append(text)     def clean(self, html):        self.lines = []        self.code_buf = []        self.cells = []        self.skip_depth = 0        self.in_code = False        self.feed(html)        return "\n".join(self.lines)  def split_by_heading(text, max_chars=200):    chunks = []    current = ""    for line in text.splitlines():        if re.match(r"^#{1,6} ", line) and current:            chunks.append(current.strip())            current = ""        current += line + "\n"        if len(current) >= max_chars and current.count("\n") > 2:            chunks.append(current.strip())            current = ""    if current.strip():        chunks.append(current.strip())    return chunks  def main():    sample = """    <html><head><style>body{color:red}</style></head>    <body><h1>部署指南</h1><p>先安装依赖</p>    <table><tr><td>包名</td><td>版本</td></tr>    <tr><td>langchain</td><td>0.1</td></tr></table>    <pre><code>pip install langchain</code></pre></body></html>    """    cleaner = DocCleaner()    text = cleaner.clean(sample)    print(text)    print("---- 分块结果 ----")    for i, chunk in enumerate(split_by_heading(text)):        preview = chunk[:40] + "..." if len(chunk) > 40 else chunk        print("[块 %d] %s" % (i, preview))  if __name__ == "__main__":    main()

1. self.skip_depth = 1遇到 script/style 后进入“跳过模式”，把里面的内容整段当烂叶扔掉。
2. re.fullmatch(r"h[1-6]", tag)识别 h1~h6 标题标签，把它转成 # 数量的层级记号，这就是保洋葱层。
3. self.lines.append("#" * int(tag[1]) + " ")用 # 重复次数表达标题深度，检索时能按层级切块。
4. self.cells.append("")每遇到 td/th 就登记一个格子，为表格的行列对应做准备。
5. " | ".join(self.cells)在行结束时用分隔符把单元格拼成一行，保住行列关系，豆腐不碎。
6. self.code_buf.append(data)代码块内的数据原样进缓冲，不压缩空白不拆换行，牛排保鲜。
7. split_by_heading(text)按 # 标题 切分知识块：遇到新标题就把上一块收尾，防止跨主题混切。
8. if len(current) >= max_chars and current.count("\n") > 2块太长时兜底切分，避免超大块撑爆向量库。
9. print(text)先看清洗结果再分块，相当于开市前的抽样检查。

常见误区

面试题