1. RAG 数据导入与解析全攻略开篇为什么文本解析是 RAG 的第一道生死关做 RAG 的人都有一个共识检索效果差八成不是模型不行而是数据没处理好。我见过太多团队花大价钱调 embedding 模型、换向量数据库、折腾重排序策略结果回头一看原始文档里全是乱码、断行、页眉页脚、表格错位。你喂给系统的是一堆垃圾它当然只能还你一堆垃圾。这个系列我打算把 RAG 数据导入与解析这条链路从头到尾拆一遍。第一篇先聚焦最基础也最容易被低估的环节从纯文本 txt 到结构化 Markdown 的通用文本解析。别看 txt 简单它恰恰是所有文档格式的“最大公约数”——PDF 抽出来的、Word 转出来的、网页爬下来的、OCR 识别出来的最终往往都落到 txt 或类 txt 的纯文本形态。能不能把这一层吃透直接决定了后面分块、向量化、检索的上限。这篇文章适合谁看如果你正在搭 RAG 知识库、做文档问答、搞企业级智能体或者单纯想搞清楚“为什么我的知识库答非所问”那这篇就是给你写的。我会从设计思路讲到实操细节从编码识别讲到 Markdown 结构化把踩过的坑和能直接抄的代码都摆出来。核心关键词就几个RAG、数据导入、解析、txt、Markdown围绕它们把这条链路讲透。先说一个反直觉的结论txt 解析的难点从来不在“读文件”而在“读懂文件的意图”。一个open().read()谁都会写但你要处理 GBK 和 UTF-8 混用、要识别段落边界、要还原被硬换行切断的句子、要把“第一章”这种标题层级抽出来——这些才是真正决定 RAG 质量的地方。下面我按实际项目里的处理顺序一层层往下拆。2. 整体设计思路为什么我坚持“先归一化到 Markdown”2.1 从“格式地狱”到“统一中间层”的核心逻辑做过数据导入的人都懂那种痛苦PDF 有 PDF 的解析库Word 有 Word 的HTML 有 HTML 的每种格式抽出来的文本结构都不一样。如果针对每种格式单独写一套分块和清洗逻辑维护成本会爆炸。我的做法是引入一个统一中间层——Markdown所有格式先转成 Markdown后续的分块、清洗、向量化全部基于 Markdown 来做。为什么选 Markdown 而不是纯文本或者 HTML三个理由。第一Markdown 保留了结构语义#是一级标题、##是二级标题、-是列表、|是表格这些符号在纯文本里是没有的而结构信息对 RAG 至关重要——分块时你可以按标题切检索时你可以带上标题路径做上下文增强。第二Markdown 足够轻量不像 HTML 那样带一堆标签噪音也不像 JSON 那样需要严格 schema。第三生态成熟几乎所有编程语言都有 Markdown 解析库转成 AST 后想怎么处理都行。提示不要一上来就追求“完美结构化”。很多团队卡在“我要把 PDF 里的表格 100% 还原”这种执念上结果项目迟迟上不了线。先做到 80% 的结构可用剩下的边角料用人工兜底这才是工程思维。2.2 解析链路的四个阶段划分我把整个 txt 到 Markdown 的解析拆成四个阶段每个阶段职责单一方便排查问题阶段核心任务关键产出常见坑编码识别与读取正确读出字符不乱码干净的 Unicode 字符串GBK/UTF-8 误判、BOM 头残留文本清洗与归一化去噪、统一换行、去控制符规整的纯文本全角半角混用、多余空行结构识别与还原识别标题、段落、列表、表格带层级语义的中间结构硬换行误判、标题漏识别Markdown 序列化输出标准 Markdown.md 文件或字符串转义字符处理、表格对齐这个划分的好处是每一层都可以单独测试和替换。比如你发现乱码问题一定在第一层发现段落被切碎问题在第三层。定位效率比一锅炖高得多。2.3 为什么不用现成的“一键转换”工具市面上有不少 txt 转 Markdown 的工具但我基本不用原因有两个。一是通用工具为了兼容各种情况做了大量妥协比如它不知道你的文档里“第X章”是标题还是正文只能一刀切。二是RAG 场景有特殊需求比如你需要保留原文的字符偏移量offset方便后续做引用溯源通用工具不会给你这个。自己写解析逻辑虽然前期麻烦但可控性和可调试性强太多。当然也不是所有东西都要自己造。像编码检测这种成熟问题直接用chardet或charset-normalizer就行没必要重复造轮子。判断标准很简单这个环节是否和你的业务语义强相关强相关就自己写弱相关就用库。3. 核心细节解析编码、清洗、结构识别的实操要点3.1 编码识别乱码问题的根源与解法txt 解析第一个拦路虎就是编码。中文场景下最常见的三种编码是UTF-8、GBK、GB18030。UTF-8 是事实标准但大量老系统、老文档导出的还是 GBK。如果你用 UTF-8 去读 GBK 文件得到的就是一堆“锟斤拷”反过来用 GBK 读 UTF-8就是“测试”这种鬼东西。我的处理策略是先检测、再尝试、最后兜底。具体流程先检查文件头有没有 BOM。UTF-8 BOM 是EF BB BFUTF-16 是FF FE或FE FF。有 BOM 直接按对应编码读最稳。没有 BOM 就用charset-normalizer检测它比老牌的chardet准确率更高尤其对短文本。检测结果如果是 UTF-8 就直接读如果是 GB 系列用gb18030读它是 GBK 的超集兼容性更好。如果检测置信度低就按候选编码列表逐个尝试解码哪个不抛异常且乱码率低就用哪个。from charset_normalizer import from_path def detect_and_read(file_path): # 优先用 charset-normalizer 检测 results from_path(file_path) best results.best() if best is None: # 兜底按常见编码逐个尝试 for enc in [utf-8, gb18030, utf-16, latin-1]: try: with open(file_path, r, encodingenc) as f: return f.read(), enc except UnicodeDecodeError: continue raise ValueError(f无法识别文件编码: {file_path}) return str(best), best.encoding注意latin-1是“永不失败”的编码任何字节序列都能解码但解出来大概率是乱码。它只能作为最后兜底不能作为首选否则你会得到一堆看似正常实则错误的字符。还有一个细节读取时统一用newline参数避免 Python 自动把\r\n转成\n这样你能拿到原始换行符后续归一化时自己控制。这个参数很多人不知道但它能帮你保留原始文档的换行信息对判断段落边界很有用。3.2 文本清洗哪些该删哪些必须留清洗是最容易“用力过猛”的环节。新手常犯的错是把所有“看起来没用”的字符都删掉结果把有意义的空格、缩进也删了导致段落结构丢失。我的原则是只删确定无意义的噪音保留一切可能承载结构的字符。必须删的控制字符除了\n、\t其他 ASCII 控制符0x00-0x1F基本都是噪音尤其是\x00空字节会让很多解析库直接崩溃。零宽字符\u200b、\ufeff这类零宽空格和 BOM 残留肉眼看不见但会干扰字符串匹配。连续空行三个以上连续换行统一压成两个避免分块时产生大量空块。必须留的单个换行它可能是段落内的软换行也可能是段落边界不能无脑删。行首缩进中文文档里两个全角空格往往表示段落开头是重要的结构信号。特殊符号像•、·、※这些可能是列表标记删了就丢了结构。import re def clean_text(text): # 去掉零宽字符和 BOM 残留 text re.sub(r[\u200b\u200c\u200d\ufeff], , text) # 去掉除 \n \t 外的控制字符 text re.sub(r[\x00-\x08\x0b\x0c\x0e-\x1f], , text) # 统一换行符 text text.replace(\r\n, \n).replace(\r, \n) # 连续空行压缩为两个换行 text re.sub(r\n{3,}, \n\n, text) # 去掉行尾多余空格 text re.sub(r[ \t]\n, \n, text) return text这里有个经验清洗规则要可配置。不同来源的文档噪音不一样网页爬下来的可能有一堆导航文字OCR 出来的可能有识别错误。把规则做成列表按文档来源选择启用哪些比写死一套规则灵活得多。3.3 结构识别从“一堆文字”到“有层级的文档”这是整个解析里最有技术含量的部分。纯文本没有显式的结构标记你得靠模式识别来推断。我总结了中文文档里最常见的几类结构信号标题识别。中文标题有几个典型模式第X章、第X节、一、二、三、、1. 2. 3.、一二。这些模式可以用正则匹配。但要注意区分“标题”和“正文里提到章节号”。我的判断依据是标题通常独占一行且长度较短一般不超过 50 字后面不跟标点或只跟少量标点。import re # 中文标题模式 TITLE_PATTERNS [ (r^第[一二三四五六七八九十百千\d]章\s*.*$, 1), # 第X章 - 一级 (r^第[一二三四五六七八九十百千\d]节\s*.*$, 2), # 第X节 - 二级 (r^[一二三四五六七八九十]、\s*.*$, 2), # 一、 - 二级 (r^[一二三四五六七八九十]\s*.*$, 3), # 一 - 三级 (r^\d\.\s.*$, 3), # 1. - 三级 ] def detect_title(line): line line.strip() if len(line) 50 or not line: return None for pattern, level in TITLE_PATTERNS: if re.match(pattern, line): return level return None段落识别。段落的核心特征是“语义完整”。在中文里段落通常以两个全角空格开头或者以换行分隔。但很多 txt 是从 PDF 抽出来的每行都被硬换行切断这时候你需要把被切断的句子重新拼起来。判断依据是如果一行结尾不是句号、问号、感叹号、冒号等终止标点且下一行开头不是标题模式那这两行大概率属于同一段。列表识别。列表的标志是行首的-、*、•、1.、1等。识别出来后连续的同级列表项要归到同一个列表块里。表格识别。纯文本表格是最难的因为对齐全靠空格。我的做法是检测连续多行是否包含多个由空格或制表符分隔的“列”如果列数一致且行数大于 2就尝试解析成表格。但说实话纯文本表格还原准确率有限遇到复杂表格我建议直接标记为“疑似表格”交给人工处理不要硬转。3.4 硬换行还原一个容易被忽略的关键细节这个细节我要单独拎出来讲因为它太重要了。从 PDF 或某些系统导出的 txt经常是每行只有十几个字就换行这是排版导致的硬换行不是真正的段落边界。如果你不处理分块时会把一个完整段落切成好几块检索时语义就断了。我的还原逻辑是这样的def merge_hard_wraps(lines): merged [] buffer for line in lines: stripped line.strip() if not stripped: # 空行表示段落结束 if buffer: merged.append(buffer) buffer merged.append() continue # 如果是标题或列表不合并 if detect_title(stripped) or re.match(r^[-*•]\s, stripped): if buffer: merged.append(buffer) buffer merged.append(stripped) continue # 判断是否与上一行合并 if buffer and not re.search(r[。】]$, buffer): buffer stripped else: if buffer: merged.append(buffer) buffer stripped if buffer: merged.append(buffer) return merged核心判断就是上一行结尾没有终止标点就认为下一行是它的延续。这个规则简单但有效实测能解决 80% 以上的硬换行问题。剩下的 20% 是特殊情况比如诗歌、代码块这些需要单独处理。实操心得合并硬换行时中英文要区别对待。中文合并时直接拼接即可英文单词之间需要补一个空格否则会出现helloworld这种粘连。判断依据是看上一行末尾和下一行开头是否都是 ASCII 字母。4. 完整实操流程从原始 txt 到标准 Markdown4.1 环境准备与依赖选型先把环境搭起来。我用 Python 做这套流程依赖不多都是成熟库pip install charset-normalizer markdownifycharset-normalizer负责编码检测markdownify在需要把 HTML 片段转 Markdown 时用得上。如果你要处理更复杂的结构可以加上lxml做 HTML 解析。但核心的 txt 解析逻辑我建议手写不依赖重型框架。目录结构我习惯这样组织rag_parser/ ├── parsers/ │ ├── txt_parser.py # txt 解析主逻辑 │ ├── cleaner.py # 清洗规则 │ └── structurer.py # 结构识别 ├── output/ # 输出的 markdown 文件 └── main.py # 入口4.2 第一步编码检测与安全读取这一步的目标是拿到一个干净的 Unicode 字符串。前面讲过检测逻辑这里补充一个分块读取的优化如果文件很大比如几百 MB 的日志一次性读进内存会爆需要分块读。但分块读有个问题——编码检测需要看全文件才准。我的做法是先读前 64KB 做编码检测然后用检测出的编码流式读取全文。def safe_read(file_path, sample_size65536): # 先采样检测编码 with open(file_path, rb) as f: raw_sample f.read(sample_size) from charset_normalizer import from_bytes best from_bytes(raw_sample).best() encoding best.encoding if best else utf-8 # 用检测出的编码读取全文 with open(file_path, r, encodingencoding, errorsreplace, newline) as f: return f.read(), encoding注意errorsreplace这个参数。它保证即使有个别字节解不出来也不会抛异常中断整个流程而是用替代。对于 RAG 场景宁可有个别乱码字符也不要因为一个字节读不了就丢掉整个文档。4.3 第二步清洗与归一化拿到原始文本后按 3.2 节的规则清洗。这里我要强调一个顺序问题先统一换行再去控制字符最后压缩空行。顺序错了会有问题。比如你先压缩空行但此时\r\n还没统一\r\n\r\n\r\n和\n\n\n的匹配规则不一样就会漏处理。清洗完的文本我建议先存一份中间产物比如xxx.cleaned.txt。这样如果后面结构识别出问题你可以直接拿中间产物调试不用每次从头跑。这个习惯在调试阶段能省大量时间。4.4 第三步结构识别与层级构建这是核心步骤。我的做法是逐行扫描维护一个“当前上下文”状态机。状态包括当前是否在列表里、当前标题层级是多少、当前是否在表格里。每读一行根据识别结果更新状态并决定这行是标题、段落、列表项还是表格行。def parse_structure(lines): blocks [] current_para [] for line in lines: stripped line.strip() if not stripped: if current_para: blocks.append({type: paragraph, content: .join(current_para)}) current_para [] continue title_level detect_title(stripped) if title_level: if current_para: blocks.append({type: paragraph, content: .join(current_para)}) current_para [] blocks.append({type: heading, level: title_level, content: stripped}) continue if re.match(r^[-*•]\s, stripped): if current_para: blocks.append({type: paragraph, content: .join(current_para)}) current_para [] blocks.append({type: list_item, content: re.sub(r^[-*•]\s, , stripped)}) continue current_para.append(stripped) if current_para: blocks.append({type: paragraph, content: .join(current_para)}) return blocks这个状态机虽然简单但覆盖了大部分场景。实际项目里我会再加一个列表聚合逻辑把连续的list_item合并成一个list块这样输出 Markdown 时能正确渲染成有序或无序列表。4.5 第四步Markdown 序列化与输出最后把 blocks 转成 Markdown 字符串。这一步要注意转义如果原文里有#、*、_这些 Markdown 特殊字符要转义否则会破坏结构。但转义也不能过度比如正文里的#如果转义了读者看到的是\#很别扭。我的原则是只在行首的特殊字符才转义行内的保持原样。def to_markdown(blocks): lines [] for block in blocks: if block[type] heading: lines.append(# * block[level] block[content]) lines.append() elif block[type] paragraph: lines.append(block[content]) lines.append() elif block[type] list_item: lines.append(- block[content]) elif block[type] list: for item in block[items]: lines.append(- item) lines.append() return \n.join(lines)输出的 Markdown 文件我建议保留原始文件的目录结构比如input/docs/a.txt对应output/docs/a.md。这样后续做增量更新时能快速定位哪些文件变了。4.6 参数选择与效果验证解析效果怎么验证我一般看三个指标指标含义合格线标题召回率正确识别的标题数 / 实际标题数 90%段落完整率未被错误切断的段落数 / 总段落数 85%乱码率乱码字符数 / 总字符数 0.1%验证方法很简单随机抽 20 个文档人工标注标题和段落然后跑脚本对比。这个工作量不大但能帮你快速发现规则的问题。我第一版规则跑下来标题召回率只有 70%后来发现是漏了“第X部分”这种模式补上就上到 92% 了。5. 常见问题与排查技巧实录5.1 乱码问题速查表乱码是最高频的问题我整理了一张速查表按现象反推原因现象可能原因排查方法解决锟斤拷UTF-8 读 GBK看文件头有无 BOM改用 gb18030 读测试GBK 读 UTF-8检测编码置信度改用 utf-8 读问号方块字体缺失或编码丢失检查原始字节用 errorsreplace 兜底部分乱码混合编码分段检测按段落分别检测编码开头有BOM 残留检查前 3 字节读取后 strip BOM实操心得遇到乱码第一步永远是用十六进制编辑器看原始字节。比如\xe4\xb8\xad是 UTF-8 的“中”\xd6\xd0是 GBK 的“中”。看一眼字节就能确定编码比瞎猜快得多。5.2 段落被切碎的三种典型场景场景一PDF 硬换行。前面讲过用“上一行结尾无终止标点则合并”的规则处理。但要注意如果原文是诗歌或代码这个规则会误合并需要加白名单。场景二OCR 识别错误。OCR 经常把标点识别错比如把句号识别成逗号导致合并规则失效。我的做法是放宽终止标点集合把逗号、分号也纳入“可能终止”的候选但降低优先级。场景三多栏排版。PDF 双栏排版抽出来的文本往往是左栏一行右栏一行交替读起来是乱的。这种情况纯文本层面很难还原我的建议是回到 PDF 解析阶段处理用能识别栏位的解析器而不是在 txt 层面硬修。5.3 标题漏识别与误识别漏识别通常是模式不全。除了前面列的中文文档还有这些标题模式一.点号、1、顿号、【标题】方括号、◆ 标题符号开头。建议建一个模式库持续补充。误识别更麻烦典型的是把正文里的“第一章讲了什么”误判成标题。我的过滤规则是标题行不能以逗号、句号结尾且不能包含“讲了”“说了”“提到”这类动词。加了这个规则后误识别率从 15% 降到 3% 左右。5.4 大文件处理的内存与性能几百 MB 的 txt一次性读进内存再处理内存占用会很高。我的优化方案是流式处理逐行读逐行判断维护一个固定大小的缓冲区。只有需要合并硬换行时才把多行拼起来。这样内存占用基本恒定跟文件大小无关。def stream_parse(file_path, encoding): buffer [] with open(file_path, r, encodingencoding, errorsreplace) as f: for line in f: # 逐行处理维护 buffer ... if len(buffer) 1000: yield process_buffer(buffer) buffer []性能上纯 Python 处理 100MB 文本大概需要 10-20 秒可以接受。如果追求更快可以把正则预编译或者用re2库替代标准re。5.5 表格与特殊结构的处理建议纯文本表格我前面说了准确率有限。我的实际做法是能识别就转识别不了就保留原文并加标记。比如检测到疑似表格就在 Markdown 里用代码块包起来至少保证内容不丢、格式不乱。对于公式如果原文是 LaTeX 源码直接保留如果是图片公式那 txt 层面无能为力需要在更早的解析阶段处理。注意不要为了“结构完美”而丢失内容。RAG 的第一原则是内容完整结构是锦上添花。我见过有人为了把表格转漂亮结果把表格里的文字弄丢了这是本末倒置。6. 从解析到分块的衔接几个必须提前考虑的点6.1 字符偏移量的保留做 RAG 引用溯源时你需要知道“这段回答来自原文的哪个位置”。所以解析时要记录每个 block 在原文中的起止偏移量。这个信息在分块和检索时非常有用能让你的系统回答“根据原文第 3 章第 2 段”。实现上在parse_structure里维护一个全局字符计数器即可。6.2 标题路径的构建分块时如果每个块都能带上“它属于哪个章节”的路径信息检索质量会明显提升。比如一个块的内容是“具体参数如下……”单独看没头没尾但带上路径“第三章 3.2 配置说明 具体参数”语义就完整了。所以解析阶段要构建标题树并给每个块打上路径标签。6.3 元数据的附加除了内容每个块还应该带上元数据来源文件名、解析时间、编码、块序号等。这些在排查问题和做数据治理时都用得上。我习惯把元数据存成 JSON和 Markdown 内容分开存检索时按需加载。7. 我在实际项目里踩过的坑与经验总结说几个只有真正做过才会知道的细节。第一个坑是空文件和非文本文件。有些.txt其实是二进制文件改了后缀或者干脆是空的。如果不做检查解析到一半抛异常整个批处理就断了。我的做法是先做文件类型嗅探读前 512 字节判断是不是文本不是就跳过并记录日志。第二个坑是编码检测的“自信错误”。charset-normalizer偶尔会给出高置信度的错误结果尤其是短文本。所以我在检测后加了一步合理性校验用检测出的编码解码后统计乱码字符比例如果超过 5%就换下一个候选编码重试。这一步能把误判率再降一半。第三个坑是正则的性能陷阱。我一开始写的标题正则用了大量回溯处理大文件时慢得离谱。后来改成先做快速前缀判断比如先看行首是不是“第”或数字只有可能匹配的行才跑完整正则速度提升了十几倍。这个优化思路值得记住正则很贵能前置过滤就前置过滤。第四个坑是过度清洗。我曾经写了个规则把连续空格都压成一个结果把代码块里的缩进全毁了。后来学乖了清洗规则要分区域正文区域可以激进清洗代码块、表格区域要保守。判断区域靠上下文状态机。最后一个经验解析结果一定要人工抽检。自动化指标再好看也可能有系统性偏差。我每个项目都会随机抽 30-50 个文档人工看一遍解析结果往往能发现规则覆盖不到的长尾情况。这些长尾情况才是决定你 RAG 系统“能不能用”的关键。这套 txt 到 Markdown 的解析流程我在多个项目里跑下来处理几十万份文档整体准确率能稳定在 90% 以上。剩下的 10% 靠人工兜底和持续迭代规则。记住RAG 的数据处理没有银弹只有不断打磨的工程细节。下一篇我会讲 PDF 和 Word 这类复杂格式的解析那才是真正的硬骨头。