做RAG项目的朋友应该都有同感整套链路里最不起眼的“导入文档”这一步反而最让人头疼。数据格式五花八门光一个txt就有各种编码更别说带层级、带表格、带代码块的复杂文档了。不少团队把大量精力砸在embedding模型调参、检索策略优化上结果上线一测召回质量差得离谱查了半天才发现根源在数据导入与解析阶段——脏数据、乱码、结构丢失直接让后面的RAG流程全部白做。这篇文章是“RAG数据导入与解析全攻略”系列的第一篇聚焦最基础的通用文本格式txt和Markdown。我要把从原始文档到结构化分块的完整链路讲透包括编码识别、文本清洗、标题层级抽取、Markdown转换规则、分块与元数据注入以及一系列真实踩坑记录。无论你是正在搭建RAG知识库还是想把内部文档接进大模型应用这篇都能直接照着做。1. RAG落地最容易翻车的环节文档导入与解析先说句扎心的实话RAG项目里被人反复讨论的embedding模型、向量数据库、重排序算法其实大多是在“上游已定”的情况下做调优。真正决定一个知识库能不能用的往往是最容易被低估的导入解析环节。所谓垃圾进垃圾出在RAG里体现得极其彻底——文档一个字没读对后面所有环节都帮你努力补救但怎么也补不回来。从流程看RAG的完整链路大概是文档导入 → 格式解析 → 文本清洗 → 分块chunking → 向量化 → 存储 → 检索 → 生成。前三步是数据侧的地基。我见过不少团队的失败现场有人直接把PDF用pypdf抽了一堆文本没做任何清洗就送进embedding接口结果检索时匹配到的全是乱码片段系统还一本正经地给出了离谱回答。还有人为了省事把所有文档统统转成纯文本表格、列表、标题层级全部丢失最后检索出来的上下文要么缺上下文要么堆了一堆无关的句段模型根本没法用。核心原因在于文本并不等于结构而RAG检索对结构非常敏感。标题层级决定了上下文的归属关系列表和表格决定了信息的逻辑边界代码块决定了特殊语法的完整性。如果我们把这一切拍平成一串连续字符串等于把文档的“骨架”抽掉了。检索系统拿到的是散落的句子缺少章节归属召回结果自然像一盘散沙。更麻烦的是不同来源的文档格式差异巨大解析策略如果不能通用项目后期每接入一种新文档都要重新写一套解析逻辑成本会一路失控。所以我的经验是解析阶段多花一倍精力后面检索和生成的坑至少少一半。而txt和Markdown恰好是所有格式里最基础、也最有代表性的两类。txt帮你解决“乱码和纯文本清洗”Markdown帮你解决“结构化语义”。把这两类吃透再去处理PDF、Word、HTML你会发现很多思路都是相通的。这也是我把这个系列的第一篇定位成通用文本与结构化解析的原因。2. 通用文本txt解析一套能扛住乱码的结构化清理流程2.1 编码识别是txt解析的第一道门槛很多人处理txt上来就open(path, encodingutf-8)遇到不支持的编码直接抛异常或者更隐蔽的是解码成功但全是乱码。编码问题是txt解析里翻车率最高的没有之一。国内环境尤其复杂历史文档有GB2312、GBK、GB18030还有各种带BOM的UTF-8Windows记事本默认可能存成ANSI在线下载的文档可能混着UTF-16。我的做法是二进制读取后先做编码检测再决定解码方式。Python下常用的库有两个chardet和charset-normalizer。前者老牌但更新慢后者在速度和准确率上都有优势而且对中文场景的识别更友好。实际项目中我推荐两者结合先用charset-normalizer检测如果置信度低再回退到多编码依次尝试解码。import charset_normalizer def read_text_with_fallback(path: str) - str: with open(path, rb) as f: raw f.read() # 方案一用检测库给出最可能的编码 best charset_normalizer.from_bytes(raw).best() if best and best.encoding: try: return raw.decode(best.encoding) except UnicodeDecodeError: pass # 方案二按优先级逐个尝试直到解码成功 for enc in (utf-8-sig, utf-8, gb18030, big5, utf-16, latin-1): try: return raw.decode(enc) except UnicodeDecodeError: continue # latin-1几乎永远能“成功”但大概率乱码只能作为最后兜底 return raw.decode(latin-1, errorsreplace)这段代码有两个细节值得说。一是把utf-8-sig放在最前面因为带BOM的UTF-8如果用普通utf-8解码BOM字符\ufeff会残留在正文开头后面清洗时容易忽略。二是latin-1兜底——它是唯一能把所有字节映射到字符的编码所以解码绝对不会抛异常但也意味着如果是中文GBK内容出来就是乱码。因此这里加了一个errorsreplace确保即使兜底也不会在后续流程中因为非法字符崩溃同时保留人工排查线索。另外不要迷信检测库的置信度。实践里经常遇到短文本比如只有几十个字的小段落编码检测准确率会明显下降。我的策略是对检测结果始终持怀疑态度清洗后再抽样看是否有明显乱码特征比如大量Ã、â€这类字符说明很可能把UTF-8按Latin-1解了。真遇到批量导入历史编码文档先做小样本盲测再决定统一处理规则。2.2 文本清洗与规范化处理编码问题解决后第二步是把文本内容标准化。这一步的目标不是“改意思”而是去掉一切会影响切块和embedding的噪声。常见问题包括控制字符、零宽字符、BOM遗留、Windows的\r\n换行、全角空格、行尾多余空格、连续空行过多。控制字符是隐藏的大坑。有些从数据库或老系统导出的txt里藏着\x00、\x01这类不可见字符肉眼看不出来但一旦进入向量化环节会生成异常向量检索时还会和其他文本纠缠在一起。我习惯用正则一次性清理import re CONTROL_CHARS_RE re.compile(r[\x00-\x08\x0b\x0c\x0e-\x1f]) ZERO_WIDTH_RE re.compile(r[\u200b-\u200f\u202a-\u202e\u2060-\u206f\ufeff]) LINE_SPACE_RE re.compile(r[ \t]) def normalize_text(text: str) - str: text text.replace(\ufeff, ) # 去掉UTF-8 BOM text CONTROL_CHARS_RE.sub(, text) # 去掉控制字符 text ZERO_WIDTH_RE.sub(, text) # 去掉零宽字符 text text.replace(\r\n, \n).replace(\r, \n) lines [] blank_count 0 for line in text.split(\n): line LINE_SPACE_RE.sub( , line).strip() if not line: blank_count 1 if blank_count 1: # 连续空行最多保留一个 lines.append() continue blank_count 0 lines.append(line) return \n.join(lines)这里每个替换都有明确意图。去掉控制字符是为了不让隐藏符号污染向量统一换行符是为了后续按行做结构识别时规则简单压缩行内连续空格是为了消除排版引入的噪声保留单个空行是为了让后续标题检测、段落合并有明确边界。全角空格我倾向于直接替换成普通空格因为中文排版里全角空格经常是手误或者从网页复制带下来的对语义没有帮助反而会增加分块时的字符噪声。清洗时还要注意一个反向风险过度清洗。比如把标点符号全部删除、把英文大小写全部归一化、把所有换行合并成一行——这些激进操作会把文档语义破坏掉。我见过有人为了让embedding更“干净”把中文标点全换成英文标点结果检索里“什么是RAG”和“什么是RAG”匹配效果差异极大。清洗要克制只清无意义噪声不动语义边界。2.3 文档结构感知与章节切分txt虽然常被当作“无结构文本”但大部分真实txt在视觉上是分章节的只是这些结构需要靠排版规则去推断。常见信号包括章节编号1.、1.1、第X章、行长短标题通常短、句末是否有标点标题一般不以句号结尾、是否有加粗或特殊符号有些导出的txt保留了**标题**这类标记。结构感知的意义在于如果能把章节边界标记出来后续转Markdown、分块、注入标题元数据就都有了依据。我的做法是写一个启发式标题识别函数def detect_heading(line: str): line line.strip() if not line: return None if len(line) 50: # 过长的一行通常不是标题 return None if line.endswith((。, , , , , 、)): return None # 以句末标点结尾大概率是正文 # 匹配“1.” “1.1” “第1章” “第一章”等编号模式 if re.match(r^(\d(\.\d)*)[.、\s], line): digits re.match(r^(\d(\.\d)*), line).group(1) return len(digits.split(.)) # 层级深度1 / 1.1 1 / 2 if re.match(r^第[一二三四五六七八九十百千0-9][章节部分], line): return 1 return None看到这里的读者可能会问为什么不直接用某个现成的解析库实际上Python生态里确实有markdownify、pandoc这类工具但它们是用来把已有格式转换成Markdown而不是从“无标记的纯文本”里推测结构。txt恰恰缺少显式标记所以必须自己写规则。这个启发式方法不完美但是可扩展的——如果某个文档有特殊编号风格直接往正则里加分支就行。章节边界的价值在分块阶段立刻体现。一个“第3章 / 3.1节 / 3.1.2小节”的三级标题可以拼出完整的标题路径title_path作为元数据挂到块上。检索时如果命中块可以连同父标题一起送进上下文大模型就能知道这段内容属于哪一章哪一节回答质量会有肉眼可见的提升。我甚至把这种做法称为“给检索结果配目录”比单纯堆文本片段有效得多。3. Markdown结构化给RAG检索装上“目录表”3.1 为什么选Markdown作为中间格式既然最终目标是结构化分块很多人会问为什么非要先把txt转成Markdown而不是直接切块这里我要说一个关键观点Markdown是天然的“结构化中间表示”。它足够轻量普通文本就能写它又保留了完整的语义层级标题、列表、表格、代码块、引用这些核心结构都有显式标记而且它可以直接转成HTML或PDF后续如果要接展示层或做数据清洗都很方便。更实际的好处是大多数现代文档工具和LLM都对Markdown非常友好。很多企业内部知识库实际上就是用Markdown维护的比如GitHub仓库、Notion导出包、Obsidian库大模型的训练数据里也大量混有Markdown格式文本。因此让解析器统一输出Markdown既方便人工检查中间结果也能提高后续embedding阶段对语义结构的利用效率。与纯文本相比Markdown的优势极其明显。纯文本里的“1.1 背景介绍”和正文混在一起解析器无法确定它是标题还是正文首句而Markdown里## 1.1 背景介绍一眼就能识别。纯文本里的表格经过读取变成一堆左对齐右对齐的文字行列关系全部丢失Markdown表格则能保留二维结构切块时可以整表作为一个独立单元。纯文本里的代码片段容易被当成普通句子切成碎片Markdown代码块则可以用围栏标记完整圈住。这些差异在RAG检索场景下会被无限放大。3.2 从txt到Markdown的转换规则设计把txt转换成Markdown本质上是做“结构推断 标记注入”。我在上一节提到的标题识别正好可以作为转换引擎的核心。整体规则如下识别出的标题行按层级深度转成对应数量的#标记。## 1.1这样的二级标题对应## 1.1 xxx。行首以-、*、、1.、1、开头的行按原样保留为Markdown列表。三行以上且用竖线或制表符分隔出的规则行段尝试重建为Markdown表格。代码块线索比如以四个空格缩进、或带def、class等特征的多行转换为围栏代码块。普通连续行合并成一段段落之间用空行分隔。下面是一段简化但可用的转换函数def txt_to_markdown(text: str) - str: lines text.split(\n) md_lines [] i 0 while i len(lines): line lines[i].rstrip() if not line.strip(): md_lines.append() i 1 continue depth detect_heading(line) if depth: md_lines.append(f{# * min(depth, 6)} {line}) i 1 continue if re.match(r^(\s*)([-*]|\d[.、])\s, line): md_lines.append(line) # 列表原样保留 i 1 continue # 普通段落合并 para_lines [line] i 1 while i len(lines): nxt lines[i].rstrip() if not nxt.strip() or detect_heading(nxt) or re.match(r^(\s*)([-*]|\d[.、])\s, nxt): break para_lines.append(nxt) i 1 md_lines.append( .join(para_lines)) md_lines.append() return \n.join(md_lines)这个实现做了几个取舍标题层级最大到6级因为Markdown规范里#最多6个普通段落合并时用空格而非换行连接是为了避免“一句一行”导致的碎片化让整段语义更聚合列表检测放在标题检测之后是因为有些标题也可能以数字开头需要优先命中标题规则。值得注意的是转换结果的验证比转换本身更重要。我每次转完都会随机打开几段原始txt和Markdown对照重点检查标题有没有被误判成正文、段落有没有被错误合并、列表有没有丢失缩进。尤其是伪标题——比如正文里引用了一句话“这是第一点”长度短、不带句号很容易被误判成标题。这类误判不用追求零容忍但要控制在可接受比例内因为少量伪标题最多产生几条无伤大雅的#标记不会导致整个文档结构崩塌。3.3 从Markdown到RAG分块的数据流Markdown转完后真正面向RAG的分块流程才有发挥空间。这里我介绍一个自己常用的策略以标题树为骨架把内容挂到标题下组成带父子关系的块。from dataclasses import dataclass, field from typing import List dataclass class Chunk: content: str metadata: dict field(default_factorydict) def markdown_to_chunks(md_text: str, doc_name: str ) - List[Chunk]: lines md_text.split(\n) chunks [] title_stack [] # 维护当前标题路径 buffer [] def flush(): if buffer: title_path / .join(t for _, t in title_stack) chunk Chunk( content\n.join(buffer).strip(), metadata{ doc_name: doc_name, title_path: title_path, heading: title_stack[-1][1] if title_stack else } ) chunks.append(chunk) buffer.clear() for line in lines: if line.startswith(#): flush() level len(line) - len(line.lstrip(#)) title_text line.lstrip(#).strip() # 弹出比当前层级更深或相等的标题 while title_stack and title_stack[-1][0] level: title_stack.pop() title_stack.append((level, title_text)) else: if line.strip(): buffer.append(line) flush() return chunks这个实现的核心逻辑是遇到新标题先清空缓冲区把已有内容作为块输出然后维护一个标题栈新标题进入时弹出所有层级不小于它的旧标题保证标题路径正确。比如文档顺序是“一、”、“1.1”、“1.1.1”标题栈依次压入当后面出现新的“二、”时会把前面的1.1和1.1.1全部弹出路径重置为“二、”。分块参数这里也顺带提一下虽然没有绝对标准但我实测下来比较稳妥的起点是每块300-500个汉字或500-800个token重叠50-100个token。块太长检索噪声会增大太短语义上下文不够。更重要的是如果某段落本身很长不要硬切可以在段落内部按句号做软边界切分同时保留标题路径。这个策略叫“结构优先、长度兜底”比单纯的固定长度滑动窗口要可靠得多。4. 实操搭建txt到Markdown的通用解析流水线4.1 环境准备与工具选型在动手写完整流水线前先说一下我的推荐组合。解析平台首选Python原因是生态成熟RAG项目几乎默认在用Python。必要的第三方库只有几个charset-normalizer处理编码检测、markdownify某些格式转Markdown的补充工具本方案中可选、pandas如果要做表格数据验证。不需要引入重型NLP库这个阶段用标准库加少量工具库就够了。项目结构建议这样组织rag_parser/ ├── parser.py # 主解析函数 ├── cleaner.py # 文本清洗 ├── converter.py # txt - markdown ├── chunker.py # markdown - chunks └── sample_docs/ # 测试文档 ├── sample_utf8.txt ├── sample_gbk.txt └── sample_structured.txt为什么这样拆分因为解析流水线每个环节的失败模式不同清洗的失败和转结构的失败排查思路完全不一样。拆成独立模块出问题时可以单独调试也可以为后续PDF、Word等格式扩展不同入口复用清洗和分块部分。4.2 核心代码实现完整核心代码其实已经分散在上一节的示例里了。我把它们组装成一个parse_document主函数统一入口def parse_document(path: str) - List[Chunk]: text read_text_with_fallback(path) text normalize_text(text) md_text txt_to_markdown(text) chunks markdown_to_chunks(md_text, doc_namepath.name) return chunks if __name__ __main__: chunks parse_document(Path(sample_docs/sample_structured.txt)) for c in chunks: print(c.metadata) print(c.content[:80]) print(---)这个入口函数看起来很短但已经串联了四个关键模块。如果你想逐块调试也可以把中间层的md_text单独保存到文件中def parse_document_with_debug(path: str) - List[Chunk]: text read_text_with_fallback(path) text normalize_text(text) md_text txt_to_markdown(text) Path(debug_output.md).write_text(md_text, encodingutf-8) chunks markdown_to_chunks(md_text, doc_namePath(path).name) return chunks保存中间结果的好处是能直观看到哪些标题被识别出来、哪些段落被合并、表格有没有被拍平。一旦发现分块结果不理想第一件事不是调分块参数而是检查这个debug_output.md。4.3 跑通全流程与输出验证我用一个模拟的测试文档来演示。假设源文件内容如下项目简介 1. 背景 本项目旨在构建一个企业知识库问答系统。 系统需要支持文档的批量导入、解析和检索。 1.1 目标用户 - 内部员工 - 客服团队 - 技术支持 2. 技术架构 2.1 数据层 这里描述数据存储方案。经过解析流水线后输出的块应该大致是这样metadata: {doc_name: sample.txt, title_path: 项目简介, heading: 项目简介} content: 项目简介 metadata: {doc_name: sample.txt, title_path: 项目简介 / 1. 背景, heading: 1. 背景} content: 本项目旨在构建一个企业知识库问答系统。系统需要支持文档的批量导入、解析和检索。 metadata: {doc_name: sample.txt, title_path: 项目简介 / 1. 背景 / 1.1 目标用户, heading: 1.1 目标用户} content: - 内部员工 - 客服团队 - 技术支持 metadata: {doc_name: sample.txt, title_path: 项目简介 / 2. 技术架构, heading: 2. 技术架构} content: 2.1 数据层 这里描述数据存储方案。这个例子看起来简单但已经覆盖了关键验证点顶层标题“项目简介”作为一级标题被识别二级标题“1. 背景”正确挂到顶层标题下“1.1 目标用户”的三级路径是项目简介 / 1. 背景 / 1.1 目标用户最后一段没有子标题的内容被合并到“2. 技术架构”下。注意最后一块里包含了“2.1 数据层”说明标题“2.1”被当成了正文而不是标题——这是因为“2.1 数据层”较短且不以句号结尾按道理应该识别成标题但我的detect_heading函数里没有专门处理2.1这种目录编号的规则吗其实有\d(\.\d)*是能匹配到2.1的。因此这里应该识别为标题。我再回头修正逻辑detect_heading中2.1 数据层满足\d(\.\d)*[.、\s]所以会返回深度2转成## 2.1 数据层。那么输出块应是title_path: 项目简介 / 2. 技术架构 / 2.1 数据层。这样的结构才是对的。这个例子提醒我验证环节一定要用结构化明显的文档能覆盖标题多级嵌套、列表、段落合并三类场景。还有一类测试文档要故意包含乱码和特殊字符用来验证编码回退和控制字符清理。我经验里最值得做的事是准备一份“坏样本清单”每次代码改动后都跑一遍保证修复一个问题不破坏原有功能。这套回归测试的习惯在RAG解析这种多环节链路里特别重要。5. 真实踩坑记录从乱码到脏块的排查手册5.1 乱码与编码误判最经典的情况是文件明明显示为GBK编码检测库却给出Windows-1252之类的西欧编码解码后大量文本变成建这类丑陋字符。原因是短文本样本下检测算法容易被部分字节的统计特征误导。排查思路是先看文档来源如果来自中国大陆企业内部系统优先考虑GB18030如果来自网页导出大概率是UTF-8。如果实在不确定我可以提供一个快速人工判断法把解码结果打印前100个字符如果看到大量Ã、â€、Â这样的字符组合基本可以断定是“UTF-8编码的字节被错误地用Latin-1/Windows-1252解码了”。此时强制改用utf-8或gb18030通常能瞬间恢复。5.2 表格被拉平成文本很多txt里的表格其实是“用空格或制表符对齐的文本”一旦转成普通段落行列关系全部丢失。比如每行有姓名、部门、工号三列用多个空格隔开。在RAG检索时如果用户问“张三在哪个部门”单纯靠文本匹配可能能撞上但如果你想精确知道“这一行的第三列是工号”就必须先做列对齐重建。一个实用技巧是按行按分隔符拆开统计列数一致性如果多行都有相同列数就尝试用|重建Markdown表格。不过这个方法对排版要求高如果原文件列宽不齐可以先用pandas.read_fwf做定宽读取再导出为Markdown表格成功率更高。5.3 标题切分后的“孤儿块”分块时最常见的脏块是“孤儿块”——一段内容挂在很深的标题路径下但它的真正标题因为层级判断错误被吞掉了或者标题在段落末尾才出现比如“上述内容总结如下”。这种块检索时很难被语义相关的问题命中。我的排查方式是统计每个块的平均长度和标题路径深度如果大量块都挂在顶层标题下且长度差异极大说明标题识别规则对该文档失效需要去查debug_output.md里的标题列表。另一个方法是直接在分块时记录“本块包含几个段落”如果某个块既有标题路径又有超过10个段落大概率是标题切分点丢失需要调整切分逻辑。5.4 特殊符号污染我从一个真实的政府报告txt里解析时遇到过\u3000全角空格大量混在行首导致每一行的缩进不一致影响列表识别。还有从网页复制的文本里会带零宽空格\u200b肉眼看不见但会让“关键词匹配”完全失效用户搜“RAG”匹配不到“RAG”中间插了零宽字符的文本。处理方案就是我前面写的ZERO_WIDTH_RE把这些不可见字符在清洗阶段一次性剔除。但要注意零宽字符也分很多种有些用于文字排版方向控制无脑剔除可能影响阿拉伯语等特殊语言中文文档场景下基本可以全清。5.5 大文件与内存暴涨一个几百MB的txt如果全部读进内存再清洗转换Python进程的内存占用会轻松超过2GB。这个问题在导入企业历史日志时尤其明显。我的做法是流式分块读取按固定字节数读取保留最后一行不完整部分拼到下一块再处理。不过流式读取会让标题树的维护变得复杂因为一个章节可能跨多个读取块。如果条件允许我更推荐用mmap按行迭代内存占用小代码也更简洁。如果用的是服务器还可以直接限制单文件大小超过100MB的先压缩或者让用户拆分避免解析服务被单个大文件拖垮。5.6 问题排查速查表症状可能原因排查思路中文变成建UTF-8被Latin-1解码强制用utf-8/gb18030解码全文开头有\ufeff未处理BOM清洗阶段移除BOM标题全部缺失检测规则未匹配编号风格查看debug输出增加正则分支表格变一长串文本未做列对齐重建用pandas.read_fwf或竖线重建分块全是碎片切块位置过于激进增加重叠量合并短段落大文件内存溢出一次性加载全文改用mmap或流式读取检索命中但答案乱脏文本进入embedding检查清洗后的抽样文本这个表是我在项目里长期维护的真实速查表。每次遇到新问题我都会往表里加一行半年下来能覆盖80%以上的解析故障。6. 关于RAG解析几点自己的体会做完整套txt到Markdown的解析流程后我最深的感触是解析不是一个纯技术问题而是一个“文档理解”问题。同样一份文档人类一眼就能看出哪里是标题、哪里是正文、哪些行组成了表格但机器需要你把规则一条条写清楚。这个过程没有捷径只能靠多观察真实文档、多留中间结果、多建回归样本去逼近。具体到工具链选择我建议团队里至少要有一个成员对纯文本处理非常敏感能够随手写正则、处理编码、做流式读取。这些能力看起来不性感远不如“调优RAG算法”有吸引力但恰恰是它们决定了数据管道能不能稳定运行。很多时候一个知识库项目难产不是模型不行而是数据管道一天崩三次。另外解析规则的演进永远跟着业务走。比如你的知识库以产品说明书为主那么标题规则要优先匹配“型号参数”这类模式如果以制度文件为主就要优先匹配“第X条”这类条目标记。所以不要指望一套通用规则打天下把规则设计成可配置、可扩展的模块才是长期最优解。后续我会在系列第二篇里专门讲Word和PDF的结构化解析会把今天这套标题树和分块策略延伸到更复杂的格式中。最后分享一个实用的小技巧解析后的块在写入向量库之前先跑一轮“块自检”——检查空块比例、标题路径重复率、平均长度分布、特殊字符残留数。这四个指标可以快速暴露90%的解析问题。用自动化脚本把这些指标打印出来比肉眼翻看几万条文本可靠得多。数据导入与解析这件事做得越笨、越细RAG系统后期的表现就越稳。