RAG数据导入：txt与Markdown文本清洗与结构化解析实战

RAG项目里最容易被低估、却又最容易翻车的一环，就是从原始文件到能被检索的内容切片之间那条“最后一公里”。我自己做过几个知识库之后最深的感觉是：模型选型、向量库调参都是显性问题，真正卡脖子的往往是数据刚进来时的那道解析工序——搞不定txt的编码混乱，Markdown的层级被拍扁，后面检索质量根本无从谈起。

这篇系列第一篇就先聚焦一个最通用、也最绕不开的组合：txt 和 Markdown 这两种纯文本格式，怎么在 RAG 的数据导入阶段做通用文本清洗与结构化解析。文章不聊抽象架构，只给落地细节和可直接复用的 Python 处理思路，适合正在搭知识库的朋友、被 chunk 质量折腾的开发者，以及好奇“文档结构化到底在结构化什么”的入门读者。

1. 内容整体设计与思路拆解

1.1 为什么数据导入阶段才是 RAG 的上限

很多人把 RAG 项目的重心放在 embedding 模型和向量检索上，这没有错，但有一个很基础的事实：召回的上限由 chunk 本身的质量决定，而 chunk 的质量基本是在数据导入与解析环节就被写死的。如果原始文档是一团乱麻，后面再好的向量模型也只是在乱麻里捞针。

从实际项目看，RAG 数据导入的核心链路可以拆成四步：读取原始文件、做文本清理、按结构切分、附加元数据。这里每一步都有“看起来简单、做起来全是坑”的特征。txt 文件没有统一编码规范，Markdown 文件有各种扩展语法和嵌套结构，如果不做针对性处理，轻则检索到乱码片段，重则整个 chunk 语义断裂、检索命中率直线下降。

另外要意识到的是，很多人分不清“文本切分”和“结构化解析”之间的区别。文本切分是机械地按长度或标点切，结构化解析则是先理解文档的层级关系，再按语义边界切。前者快但糙，后者慢但准。RAG 项目里两者不是二选一，而是要根据文件类型用不同策略，甚至在同一条 pipeline 里先识别格式、再走不同分支。

1.2 txt 与 Markdown 的分工：通用文本与结构化文本

txt 和 Markdown 看起来都是纯文本，但在 RAG 解析的语境下，它们的定位完全不同。

txt 是“无结构”的典型代表，它可能是一本小说的一章、一段日志、一个导出文本、甚至是一堆乱码种下的雷。对 txt 的处理思路是通用文本规范化：编码识别、乱码修复、段落切分、噪声过滤。目标不是还原它的什么结构，而是得到干净的、语义连贯的文本块。

Markdown 则是“轻结构”文本，它天然带有标题层级（#、##）、列表（-、1.）、引用（>）、代码块（```）、表格（|...|）等语义信号。对 Markdown 的处理思路是结构化解构与重建：把格式剥掉、把结构留下来，让最终生成 chunk 不仅能看到文本内容，还能知道这段文字属于哪个二级标题、哪张表格、哪段代码。

从项目实战角度看，这一步的价值经常被低估。同样是切成 500 字的块，直接从 txt 切，块之间没有上下文关联，检索时只靠向量相似度硬碰硬；而先按 Markdown 标题结构切，chunk 自带“章节坐标系”，语义边界和文档逻辑高度对齐，召回效果明显更稳。

2. 核心细节解析与实操要点

2.1 txt 文件读取中的编码问题与处理方案

txt 解析第一个拦路虎就是编码。Windows 上常见的 GBK/GB2312、macOS 和 Linux 常见的 UTF-8、历史遗留的 UTF-16 / BOM 标记、还有部分文件带着 UTF-8-sig 的编码头，如果统一用 UTF-8 去读，轻则稍后写入丢失字符，重则直接 UnicodeDecodeError 把整个导入流程打断。

我最常用的方案是两步走：先探测编码，再做兜底读取。Python 里chardet和charset-normalizer都能做编码检测，实测下来charset-normalizer在速度和准确率上更均衡一些，但无论用哪个，都不能保证 100% 准确。所以更稳妥的做法是写一个分级处理函数：

from charset_normalizer import from_bytes def smart_read_text(file_path: str) -> str: raw = open(file_path, "rb").read() # 第一步：用检测库识别编码 best = from_bytes(raw).best() if best is not None: try: return best.output().decode("utf-8", errors="replace") except Exception: pass # 第二步：兜底尝试常见编码 for enc in ["utf-8-sig", "utf-8", "gb18030", "utf-16"]: try: return raw.decode(enc) except UnicodeDecodeError: continue # 第三步：最后保底，替换不可见字符 return raw.decode("utf-8", errors="replace")

这里有个容易被忽略的细节：为什么用gb18030而不是gbk？因为gb18030是 GBK 的超集，能覆盖更多生僻字和特殊符号，兜底时成功率高很多。另外utf-8-sig一定要放在utf-8前面试，否则带 BOM 的文件会在开头留下一个\ufeff字符，污染后面的文本清洗。

2.2 文本清洗：比想象中更重要的噪声过滤

编码问题解决后，真正的文本清洗才刚刚开始。txt 文件里常见的噪声包括：多余的全角/半角空格、行尾的残留制表符、页眉页脚残留（比如“第 X 页 共 Y 页”）、URL 链接、连续换行造成的空行堆积。

清洗的目的不是把文本变得干巴巴，而是让后续的切分算法不会被无意义的字符干扰。例如，如果一个 chunk 因为换行符的分布不均匀而断在了一句完整的话中间，向量化之后这段文本的语义就不完整，检索命中率就会下降，这是很实际的问题。

清洗策略可以按优先级排列：先把空白符统一（全角空格转半角、多个空格压缩）、再根据正则规则去掉页眉页脚噪声、然后处理空行。有一种容易踩的坑是：过度清洗会把代码块里的缩进空格也给压缩掉，导致后续 Markdown 解析时代码块缩进被破坏。所以清洗必须和文件类型绑定，不能一个函数打天下——纯 txt 可以大刀阔斧，Markdown 就得做“结构感知”的清洗。

2.3 Markdown 结构解析：从正则到 AST

处理 Markdown 最核心的决策是：用正则硬匹配，还是用解析器生成 AST（抽象语法树）？早期我自己写过正则解析 Markdown 标题，那时候只是提取一级和二级标题（也就是#和##），似乎还挺好用。直到遇到嵌套列表、代码块内部的#字符串、表格分隔符包含的|这些情况时，正则方案就全面崩盘了。

Markdown 中的#在代码块里只是普通文本，|在行内代码中不代表表格分隔符。正则很难在全局层级上理解这些上下文。所以现在做 RAG 结构化解析，我不会从零写正则，而是直接用成熟解析器生成 AST。Python 生态里常用的有markdown-it-py、mistune、markdown标准库，其中markdown-it-py的 token 流输出比较适合做结构化信息提取。

from markdown_it import MarkdownIt md = MarkdownIt("commonmark", {"html": False}) tokens = md.parse(markdown_text) for token in tokens: if token.type == "heading_open": level = int(token.tag[1]) # tag 是 h1, h2, ... print(f"发现标题层级: {level}") elif token.type == "fence": print("发现代码块，语言:", token.info) elif token.type == "table_open": print("发现表格开始")

解析后要做的不是简单把 token 转成纯文本，而是要重建文档的树状结构。比如一个二级标题下的所有段落和三级标题，都应该归属于该二级标题的语义范围。后续做 chunk 切分时，这个“归属关系”就是决定 chunk 边界的最重要依据。

3. 实操过程与核心环节实现

3.1 解析链路总览与代码骨架

在实际项目中，我已经把 txt 和 Markdown 的解析提取成了一套统一的 pipeline，流程大致是：读取原始字节流 → 编码探测与文本还原 → 格式识别（按扩展名和内容特征）→ 格式分支处理（txt 走通用清洗，Markdown 走结构化解构）→ 生成统一的基础块（Chunk）→ 附加元数据 → 输出给后续 embedding 环节。

这个过程中最重要的设计原则是：不管源文件是 txt 还是 Markdown，最终产出的 chunk 结构要尽量一致。这样下游切分算法、向量化服务和存储层就不用关心上游文件类型，整个链路各司其职。

下面是一个精简版的 pipeline 代码，演示了 txt 和 Markdown 两种文件分别走向不同解析器后统一输出的核心思路：

def parse_document(file_path: str) -> list[dict]: text = smart_read_text(file_path) if file_path.endswith(".md"): return parse_markdown(text) return parse_plain_text(text)

实际项目中还可以在这个骨架之上加缓存、批处理、增量导入等能力，但核心不变：编码还原在前、格式分支在后。

3.2 通用文本解析器的完整实现

纯 txt 文件的解析目标很明确：把长篇大论分割成语义相对完整的段落级数据块。这里最忌讳的就是不看内容结构、只按固定字符数硬切。虽然固定字符数切分实现简单、速度也快，但经常会把一句完整的话拦腰截断，造成向量化后的文本语义残缺。

我常用的是多级回退切分策略：优先按段落（连续换行分隔）切，如果段落过长再按句子边界（句号、问号、感叹号）二次切分，最后才按字符数硬切兜底。这样的好处在于，尽量保证每个 chunk 的语义完整度，同时控制 chunk 数量不会过多。

import re def split_long_text(text: str, max_chunk_size: int = 800) -> list[str]: # 先按段落粗分 paragraphs = [p.strip() for p in re.split(r"\n\s*\n", text) if p.strip()] chunks = [] current = "" for para in paragraphs: if len(current) + len(para) > max_chunk_size and current: chunks.append(current) current = "" # 如果单段就超过上限，再按句子细分 if len(para) > max_chunk_size: parts = re.split(r"(?<=[。！？；])", para) for part in parts: if len(current) + len(part) > max_chunk_size and current: chunks.append(current) current = "" current += part else: current += para + "\n" if current.strip(): chunks.append(current.strip()) return [c for c in chunks if len(c) > 30]

这里有两个参数值得根据项目调整：max_chunk_size要根据 embedding 模型的 max token 限制来定，不能随便填。比如用 OpenAI 的 text-embedding-3-small，上限是 8191 token，但实际建议 chunk 保持在 500-1000 token 之间，因为向量检索的精度和 chunk 大小不是线性关系，太小丢语义、太大带噪声；min_chunk_size则是为了过滤掉那些过短的碎片，比如页眉残留、单行标题之类。

3.3 Markdown 结构化解析的完整实现

Markdown 的结构化解析比 txt 复杂一个量级。我们要做的不是把 Markdown 变成纯文本，而是把标题层级变成元数据、把列表和表格变成有结构的段落、把代码块标记出来以避免和正文混在一起。

我最终用到的解析流程是：用markdown-it-py生成 token 流，遍历 token 构建一个“标题栈”，遇到heading_open就更新当前标题层级上下文；遇到段落文本就把当前标题栈信息附带上；遇到代码块就单独标记语言类型和内容；遇到表格就按行组装成结构化的 Markdown 源码片段，而不是只取纯文本。

def extract_sections(markdown_text: str) -> list[dict]: md = MarkdownIt("commonmark", {"html": False}).enable("table") tokens = md.parse(markdown_text) sections = [] current_section = {"title": "", "level": 0, "content": ""} heading_stack = [] for token in tokens: if token.type == "heading_open": # 先把上一节收尾 if current_section["content"].strip(): sections.append(current_section) level = int(token.tag[1]) current_section = {"title": "", "level": level, "content": ""} elif token.type == "inline" and current_section["title"] == "": current_section["title"] = token.content.strip() elif token.type in ["paragraph_open", "list_item_open"]: pass # 标记边界用 elif token.type == "inline": current_section["content"] += token.content + "\n" elif token.type == "fence": lang = token.info current_section["content"] += f"\n```{lang}\n{token.content}\n```\n" if current_section["content"].strip(): sections.append(current_section) return sections

这样提取出的 section 天然自带标题路径和层级信息，比如["第二章", "2.3 实现方法"]，这些信息直接作为元数据传给向量存储后，即可在检索时按标题维度过滤，也可以在展示时把更适合的上下文反馈给大模型。我自己在实际项目中做过对比，同样一批 Markdown 文档，结构化解析出的 chunk 比纯文本切分在检索命中率上能高出 10%-20%，这个提升在知识库场景下是相当可观的。

3.4 元数据设计与输出格式

解析完成后，每个 chunk 应该携带哪些元数据，是决定检索能力上限的关键。我不建议把解析结果简单存成一行字符串就完事，至少要保证以下字段：

• source_file：来源文件路径，便于溯源。
• chunk_type：是段落、代码块、表格还是标题。
• heading_path：标题层级路径，例如["第 2 章", "2.3 实战"]。
• chunk_index：在文档内的顺序，便于做上下文拼接。
• length：字符数或 token 数，便于后续动态调度。

把这个东西输出成 JSON Lines 格式是通用做法，每条一行，方便逐条写入向量库，也方便出问题时逐条排查。

{"source_file": "docs/rag-guide.md", "chunk_type": "paragraph", "heading_path": ["第 2 章", "2.3 实战"], "content": "...", "chunk_index": 3, "length": 312}

4. 常见问题与排查技巧实录

4.1 Markdown 代码块被误解析为正文

这是 Markdown 解析中最常见的坑之一。很多自写的正则解析器会把代码块内部的#当成标题符号，把|当成表格分隔符，导致代码块里的内容被硬生生切碎。如果使用markdown-it-py这类 AST 解析器，这个问题基本可以规避，但前提是正确设置了fence判定逻辑。

排查技巧：解析完成后要单独统计一下代码块的数量和语言分布。和源文件一对，看有没有明显变少。我一般会在 pipeline 里加一个校验脚本，专门检查“应该存在的 fenced code block 是否都保留了”。你也可以把代码块语言列表打出来，比如print(all_fence_languages)，一眼就能看出是不是有大量代码块被吞了。

4.2 chunk 过短或过长导致检索效果差

如果你发现检索结果里经常出现无关片段，多半是 chunk 划分出了问题。在小知识库里，我见过最典型的情况是：所有段落都被切成了很小的碎片，结果召回时只能靠单句的向量去匹配，无法引入上下文语义，导致相似度虚高。

另一种情况是超长文档（比如几万字的研发文档）被整块丢进去，embedding 后的向量把所有句子平均到了一起，信息稀释严重。我的经验是给max_chunk_size设置一个合理的范围，再配合重叠窗口（overlap）——也就是相邻 chunk 之间保留一小段重复文本，保证切分边界处的语义不断裂。重叠大小一般是 chunk 的 10%-20%，太小起不到衔接作用，太大浪费 token 额度。

4.3 编码检测失败导致乱码入库

即使先用charset-normalizer做了探测，依然有小概率遇到检测失败的情况，尤其是混合编码的文本（比如一段 GBK 夹着 UTF-8 片段）。最直接的兜底策略是：在入库前对文本做一次乱码特征检查，比如统计替换符\ufffd的占比，一旦超过阈值（我一般定在 0.5%），就标记为异常文件，转人工处理，绝不硬塞进知识库。

replacement_ratio = text.count("\ufffd") / max(len(text), 1) if replacement_ratio > 0.005: print(f"疑似乱码文件: {file_path}，建议人工检查")

入库是脏数据不可怕，可怕的是脏数据会在检索时被反复命中，最后用户对知识库的整体信任度会急剧下降。这个关卡守住，比后面任何调参都重要。

4.4 常见问题速查表

5. 工具选型与扩展建议

5.1 解析器选型对比

Python 生态里做 Markdown 解析的选择其实不少，我整理了一个简单对比：

我的建议是 RAG 项目优先选markdown-it-py，因为它的 token 流解析非常适合做结构提取，而且插件生态能覆盖表格、数学公式等扩展语法。如果你要处理大量.docx、.pdf转 Markdown 的中间产物，pandoc做离线转换工具倒是很香，但放进实时 pipeline 里会有点重。

5.2 从 txt/Markdown 走向 PDF、HTML 的结构化之路

虽然这篇主角是 txt 和 Markdown，但很多知识库项目最大的痛点其实是 PDF。PDF 解析通常需要先走 OCR 或版面分析，再转成结构化文本，逻辑上和 Markdown 不同——PDF 是“物理排版”驱动，Markdown 是“逻辑结构”驱动。后续如果要做多格式支持，建议先把同一套输出 schema（JSON Lines chunk）沉淀下来，PDF、HTML、docx 解析完后都统一接这一个出口。这套思路稳定之后，你会发现新增文件格式只是多写一个解析器，不动下游链路，整个 RAG 数据导入系统天然就是可扩展的。

5.3 后续系列的方向预告与我的完整规划

这篇文章只是数据导入与解析系列的开篇，接下来我打算按这个顺序继续填坑：第二篇重点讲 Markdown 进阶玩法，包括数学公式怎么保留 LaTeX 语义、代码块怎么按函数或类做语义切分而不是只会按行切；第三篇讲 PDF 解析的实战，重点对比PyMuPDF、pdfplumber、marker这些工具的适用场景和翻车案例；第四篇会做整个数据导入管线的工程化收尾，比如增量更新、版本管理、解析失败告警这些离了生产环境就没法验证的细节。

如果你在做类似项目，建议不要一上来就追求全格式通吃。先把 txt 和 Markdown这两类最基础的文件解析扎实，它们能帮你跑通全链路——编码识别、文本清洗、结构化切分、元数据设计、检索评测。打通一次后，再去啃 PDF 和其他复杂格式时，你会清楚地知道每个环节的问题到底出在解析器身上，还是出在自己的数据流设计上。这也是我为什么把“通用文本与结构化解”放在系列第一篇的原因：它看起来基础，但整个知识库的底层地基就是从这里打起的。