1. 为什么 RAG 项目最容易卡在数据导入这一步做 RAGRetrieval-Augmented Generation检索增强生成项目的人都有一个共同的感受模型选型、向量库搭建、Prompt 调优这些环节虽然也折腾但最让人头疼的往往是第一步——数据导入。我接过不少团队的项目对方一上来就问用什么向量库Embedding 模型选哪个结果看了他们的数据之后才发现问题根本不在检索和生成而在最前端的解析环节。数据导入这件事听起来简单得不像话把文件读进来、切成块、扔进向量库完事。但实际做过的朋友都知道切块之前的那一大段路——编码识别、文本清洗、格式转化、结构重建——才是真正的分水岭。同一个 txt 文件不同来源、不同编码、不同排版风格解析出来的质量天差地别。而 RAG 的检索上限其实在解析完成的那一刻就已经注定了。你后面 Prompt 写得再漂亮、向量模型选得再好都救不回一个被切得稀碎、语义断裂的语料库。我自己最早犯过的错误就是轻视这一步。当时图省事直接拿现成的文档加载器把几百个 txt 文件读进来不区分章节、不分层级按固定字符数一刀切结果检索出来的片段经常是半个表格接一句话、一句话被拦腰截断问答效果惨不忍睹。后来我把这套流程推翻重做才真正意识到RAG 的数据导入绝不是一个读取动作而是一个结构化重构的过程。从 txt 到 Markdown不只是在改后缀名而是在为后续的切块和检索打地基。这篇文章是RAG 数据导入与解析全攻略系列的第一篇我会把通用文本尤其是 txt 类非结构化文档转成 Markdown 结构化表示的全过程拆开讲清楚。适合这几类读者正在搭 RAG 知识库、但对文档解析环节一头雾水的开发者手里有一堆历史遗留的 txt 文档不知道怎么处理才能喂给向量库的运维同学以及那些已经有 RAG 系统、但检索效果差、想回头排查数据链路问题的工程师。我会从为什么非得结构化讲起然后给出从 txt 到 Markdown 的完整解析思路、关键步骤、工具选型和实测中常见的坑。这一篇的内容不依赖任何收费 API 或特殊硬件只要有一台普通电脑和基本的 Python 环境就能跟着做。2. Markdown 为什么适合做 RAG 的中间表示2.1 原始 txt 的三大先天缺陷txt 文件是计算机世界最朴素的存在但也正因为朴素它在 RAG 场景下暴露出的问题特别明显。第一个问题是无结构。一个 txt 文件里只有一行行文本标题、正文、列表、表格在语义上完全等价机器看不到任何层级关系。这种平坦的文本喂给切块器之后切出来的块往往是随机的语义碎片。第二个问题是编码混乱。国内历史文档的编码情况相当复杂UTF-8、GBK、GB2312、BIG5 混着来甚至同一个文件里前半段是 UTF-8 后半段夹杂 GBK 乱码的情况我都遇到过。如果导入流程不做编码识别和转换读进来就是一堆锟斤拷。第三个问题是噪音多。老式 txt 文档里经常混着页眉页脚、重复的章节标题、文档水印、网址信息、电话号码等与核心内容无关的东西。这些噪音如果不清理会被向量模型一并编码进去检索时产生大量干扰命中。这三大缺陷叠加在一起导致一个结果直接用原始 txt 做切块和向量化系统召回质量的上限就是被这些脏数据给锁死的。相反如果先把原始文本转成结构清晰的 Markdown那么切块就有了依据可以沿着标题层级、列表边界、表格边界去切切出来的块在语义上是相对完整的。2.2 Markdown 提供了轻量但够用的结构化能力很多做 RAG 的人一提到结构化第一反应是 JSON 或数据库表结构。但对海量文档型知识库来说用 JSON 去承载全部内容既不现实也没必要。Markdown 的优势在于它是给人类阅读的轻量标记语言同时机器也能轻松解析。Markdown 的几个核心标记恰好对应了文本结构化的几个基本要素多级标题#、##、###表达章节层级列表-、1.表达并列或顺序关系表格|表达二维关系代码块保护需要原样保留的内容引用表达引用语境加粗、斜体、链接补充行内语义。对 RAG 而言最有价值的其实是标题层级和表格。有了标题层级切块器就可以做到按标题切块、保留章节上下文有了表格向量化时可以把二维关系完整保存避免表格内容被横向切碎。而这两个特性恰恰是 txt 完全不具备的。2.3 双格式共存人读 Markdown机器读向量还有一个实用层面的考量。把一个 txt 转成 Markdown不只是为了喂给向量库也为了人工审核和二次编辑。我自己在实际项目中验证过这样的流程先做一批自动解析生成 Markdown 文件然后抽检一部分在 Markdown 编辑器里人工校正修正完再进入切块和向量化流程。这个人可读的中间格式让数据质量检查变得非常直观。要知道RAG 系统的语料质量几乎不可能靠全自动流程一步到位总有一些文档需要人工介入。而 Markdown 恰好是既能让人看懂、又能让程序处理的中间载体。这也是我把本篇标题定为从 txt 到 Markdown 的通用文本与结构化解的原因——Markdown 是我在这个环节里的核心中间表示层。在后面的章节里我会基于这个思路给出完整的解析流水线设计。所有代码示例都以 Python 为主因为生态最全pandoc、BeautifulSoup、正则表达式这些工具都能无缝组合。3. 通用解析流水线的完整设计与关键代码3.1 整体流程读入、识别、清洗、重建一条通用的 txt 到 Markdown 解析流水线我习惯拆成四个阶段字节读入与编码识别把文件以二进制方式读入识别编码默认 UTF-8失败则尝试 GBK 等并消除 BOM 头预处理清洗去掉页眉页脚、空行压缩、全角半角归一化、去除不可见字符结构感知解析识别标题行、列表、表格、代码块等结构这一步是核心Markdown 序列化按规范输出 Markdown 文本同时可附加 YAML front matter 元数据。下面是我在项目中反复用的一套核心代码骨架你完全可以拿去做基础再针对自己的文档类型做调整。# -*- coding: utf-8 -*- 通用 txt - Markdown 解析流水线骨架 依赖pip install chardet import re import chardet from pathlib import Path # 1. 字节读入与编码识别 def read_txt_bytes(path): raw Path(path).read_bytes() if raw.startswith(b\xef\xbb\xbf): # 去掉 UTF-8 BOM raw raw[3:] encoding utf-8 else: guess chardet.detect(raw) encoding guess.get(encoding, utf-8) return raw.decode(encoding, errorsreplace), encoding # 2. 预处理清洗 def clean_text(text): text text.replace(\r\n, \n).replace(\r, \n) # 去除不可见控制字符保留换行和制表符 text .join(ch for ch in text if ch.isprintable() or ch in \n\t) # 全角转半角简化版仅处理常见字符 text re.sub(r[-], lambda m: chr(ord(m.group()) - 0xfee0), text) # 将连续三个以上空行压缩为两个 text re.sub(r\n{4,}, \n\n\n, text) return text # 3. 结构感知解析识别标题行 HEADING_RE re.compile(r^(第[一二三四五六七八九十百0-9][章节卷部篇]| r[0-9](\.[0-9])*\.?[ ]| r[一二三四五六七八九十][、.][ ])) def is_heading(line): line line.strip() if not line or len(line) 30: return False if HEADING_RE.match(line): depth 1 len(line.split(.)[0].split( )[0].count(.)) if . in line else 1 return depth # 也可以根据行长度和是否独占一行来判断 if len(line) 15 and not line.endswith((。, , , )) and len(line.strip()) 0: # 短行且无句读大概率是小标题 return 2 return False # 4. 表格识别连续行中包含竖线 def is_table_row(line): return line.strip().startswith(|) or line.strip().count(|) 2 # 5. 列表识别 LIST_RE re.compile(r^([-*]|[0-9][.、)]|[·•])[ ]) def parse_txt_to_markdown(text): lines text.split(\n) result [] i 0 table_buffer [] code_block_open False while i len(lines): line lines[i].rstrip() # 保护代码块 if line.strip().startswith(): code_block_open not code_block_open result.append(line) i 1 continue if code_block_open: result.append(line) i 1 continue # 表格收集 if is_table_row(line): table_buffer.append(line.strip()) i 1 while i len(lines) and is_table_row(lines[i]): table_buffer.append(lines[i].strip()) i 1 result.extend(normalize_table(table_buffer)) table_buffer [] continue # 标题识别 depth is_heading(line) if depth: title re.sub(r^(第[一二三四五六七八九十百0-9][章节卷部篇]|[0-9](\.[0-9])*\.?|[一二三四五六七八九十][、.]), , line.strip()) result.append(f{# * min(depth, 6)} {title.strip()}) i 1 continue # 列表识别 if LIST_RE.match(line.strip()): m LIST_RE.match(line.strip()) symbol m.group(1) content line.strip()[m.end():] if symbol in (-, *, , ·, •): result.append(f- {content}) else: result.append(f1. {content}) i 1 continue # 普通段落 result.append(line) i 1 return \n.join(result)3.2 表格归一化的小细节上面代码里我调用了一个normalize_table函数这里展开说说为什么需要它。原始 txt 里的表格千奇百怪有的是用竖线分隔的类 Markdown 表有的是用空格对齐的伪表格还有的是用------画的线框表格。最常见的错误处理方式是把这些表格行当普通文本处理结果表格内容被切得支离破碎。我的做法是分三层处理线框表格---开头用正则提取|之间的内容重建为 Markdown 表格竖线分隔表格直接校验列数是否一致不一致时用空格切分补列空格对齐的伪表格这种最难建议用tabulate之类工具的启发式方法识别或者干脆人工处理。def normalize_table(rows): 把各种形态的 txt 表格统一转成 Markdown 表格 parsed [] for r in rows: # 去除线框表格的 ---- 分隔线 if re.match(r^[\\-\s]$, r): continue # 去除首尾竖线 r r.strip() if r.startswith(|): r r[1:] if r.endswith(|): r r[:-1] cells [c.strip() for c in r.split(|)] parsed.append(cells) if not parsed: return [] max_cols max(len(row) for row in parsed) # 补齐列数 for row in parsed: while len(row) max_cols: row.append() header parsed[0] body parsed[1:] lines [| | .join(header) |, | |.join([ --- ] * max_cols) |] for row in body: lines.append(| | .join(row) |) return lines3.3 为什么需要把段落切块延后到解析之后很多 RAG 框架自带的 loader 都是读取即切块把解析和切块搅在一起。这个设计在你处理干净、已经结构化的数据时没问题但处理脏数据时就会放大问题。我建议的做法是先解析成 Markdown再基于解析结果切块原因有两个。第一只有先确定了标题层级和块边界切块才能做到语义完整。比如一个二级标题下的内容有 3000 字你如果按 500 字固定长度切会切成 6 块其中 5 块都没有起始标题检索时丢失上下文。但如果你先知道哪些行是##标题就可以把 3000 字作为一个大块或者先按###切子块、再把父级标题作为 context 拼进去。第二解析阶段发现的表格、列表、代码块可以单独设置切块策略。我的经验是表格一般不与其他段落混切单独提取出来作为一个块代码块要整体保留列表可以整体作为一个块而不是打断成单个条目。这些策略模式化之后检索效果提升非常明显。4. 工具选型对比三种路径的适用边界4.1 自研正则脚本、pandoc、LLM 解析怎么选我在不同项目里尝试过三条技术路径纯正则/规则脚本、调 pandoc 转换、用 LLM 做智能化解析。三条路各有适用场景我把它们的对比整理成了一张表方便你按需选择。路径优点缺点适用场景自研正则/规则脚本零依赖、速度快、可控性强、可批量处理海量文件对格式各异的新文档需要不断补规则历史文档格式相对统一、规模庞大的批处理pandoc 转换支持格式极多、社区成熟、表格处理能力强txt 输入时 pandoc 只能当纯文本处理不识别结构已有结构化 Markdown/HTML/PDF 需统一转换的环节LLM 辅助解析对格式变化适应性强、可识别语义标题速度慢、成本高、输出不稳定、需要做校验文档量少、格式极其复杂或语义难判断的小批量场景纯脚本和 pandoc 不是互斥关系。我经常把它们串联用先把批量 txt 用脚本清洗和结构识别再用 pandoc 做标准格式之间的互转。下面是实际项目里用到的兜底方案——把所有清洗后的文本转成统一的 Unicode 规范形式再交给下游处理import unicodedata def normalize_unicode(text): # 统一为 NFC 规范形式避免组合字符造成的匹配问题 return unicodedata.normalize(NFC, text)4.2 为什么我默认不首选 LLM 解析现在一提文本解析很多人第一反应就是用大模型来搞。我承认 LLM 在识别语义标题、理解上下文方面确实比正则强得多但在 RAG 数据导入这个环节默认首选 LLM 存在三个现实问题。第一是成本问题。企业级知识库往往是几千上万篇文档起步逐篇调用大模型解析按 token 计费的数字会非常可观。第二是稳定性和一致性。LLM 输出是概率性的同一篇文档解析两次输出的标题层级可能不完全一致这会给下游切块带来不必要的变量。第三是可审计性。规则脚本跑完每一条转化逻辑都可追溯LLM 的输出却需要额外投入校验成本。我的建议是阶梯策略先跑规则脚本把能处理的结构都处理掉通常能覆盖 80% 以上的需求剩下的疑难杂症再交给 LLM 或者人工兜底。这样既控制了成本又保证了质量。4.3 批处理流水线的工程化落地单文件解析容易真正的工程难点在批处理。我在生产环境里一般建议做成这样一个 pipeline输入目录扫描按扩展名和文件大小过滤排除隐藏文件和超大文件分文件执行解析单个文件失败不影响整体批次输出目录保持与输入目录相同的相对路径结构便于人工回溯生成一份解析报告 JSON记录每个文件的状态成功/失败/警告原因。# 简化的批处理调度示例 from concurrent.futures import ThreadPoolExecutor, as_completed def process_file(src_path, dst_root): try: raw, enc read_txt_bytes(src_path) cleaned clean_text(raw) md parse_txt_to_markdown(cleaned) dst Path(dst_root) / Path(src_path).with_suffix(.md).name dst.write_text(md, encodingutf-8) return {file: str(src_path), status: ok, encoding: enc} except Exception as e: return {file: str(src_path), status: error, detail: str(e)} def batch_process(src_dir, dst_root, max_workers8): files list(Path(src_dir).rglob(*.txt)) results [] with ThreadPoolExecutor(max_workersmax_workers) as ex: futures [ex.submit(process_file, f, dst_root) for f in files] for fut in as_completed(futures): results.append(fut.result()) return results这里用线程池就够了因为清洗和解析是 CPU 轻量任务瓶颈主要是磁盘 IO。要更顺手的话可以在顶层包一个tqdm进度条几百个文件跑下来也就几分钟。5. 实测中反复踩过的坑与对应解法5.1 编码识别不准原因往往是短文本误判chardet这个库在识别长文本时准确性尚可但遇到只有几十个字的短文件几乎必然出错。我踩过最典型的一次是一个只有 20 行的上传文件明明内容是 GBKchardet 判断成 ISO-8859-1解密后全变乱码。后来我加了一道保险——在解码之后做可读性校验检测乱码字符比例超过阈值就回退尝试其他编码。def decode_with_fallback(raw, candidates(utf-8, gbk, gb2312, big5, latin-1)): for enc in candidates: try: text raw.decode(enc) # 简单可读性检查统计替换符和文化冲突字符 if in text: continue # 检查是否出现大量常见乱码占位 bad_chars text.count(\ufffd) text.count(\u00a0 * 3) if bad_chars 0: continue return text, enc except (UnicodeDecodeError, LookupError): continue # 最后兜底 return raw.decode(utf-8, errorsreplace), utf-85.2 标题识别中的误杀与漏网正则识别标题看起来简单实际调试时你会发现两类问题一是误杀把第一章 绪论这类正常内容识别成标题没问题但第三章 材料与方法下面紧接着的3.1 实验设计也可能被误判关键是怎么处理多级标题的嵌套关系二是漏网有些文档的标题不带编号只有一行居中短文字跟正文之间空一行这种标题用正则根本抓不到。我后来采用的策略是多维信号加权不再只依赖正则而是同时考虑行长度、是否首行缩进、前后空行数量、是否以关键词开头如简介结论参考文献、以及该行在全文中的重复模式。每个信号给一个分数超过阈值才判为标题。这个方法误判率比单纯正则低不少代价是需要一些调参时间但对固定来源的文档可以一次调好长期复用。5.3 表格修复中的列错位问题txt 表格转 Markdown 最常见的坑是列错位。原因是原始表格里的某些单元格包含分隔符比如文本里的竖线或中文逗号一按竖线切分就把一列拆成了两列。特别是当你处理 CSV 类型的 txt 文件时带引号的字段里如果还有逗号切分结果完全不可用。我在生产中的处理方式是引入一个小的状态机当单元格以引号开头时一直读到匹配的引号为止中间的分隔符全部忽略。这个思路和标准 CSV 解析器的逻辑一致实现上也不复杂但能把绝大多数列错位问题挡在门外。def parse_csv_line(line): 极简 CSV 行解析正确处理引号包裹的逗号 cells [] cur in_quotes False for ch in line: if ch and not in_quotes: in_quotes True elif ch and in_quotes: in_quotes False elif ch , and not in_quotes: cells.append(cur.strip()) cur else: cur ch cells.append(cur.strip()) return cells5.4 Markdown 层级过深的处理当原始文档的编号到五级、六级标题时比如3.2.1.4.2这种五级编号直接映射成#####、######在 Markdown 里虽然合法但对后续切块和上下文注入很不友好。级别太深会导致一个父块被切成无数个碎片反而增加检索难度。我的处理方式是做层级压缩超过四层的标题统一合并到四级标题父级信息通过元数据记录而不是无限增加标题深度。这样既能保留层级关系又不至于把树结构拉得太高。def compress_depth(heading_line): m re.match(r^(#{1,6})\s(.*)$, heading_line) if not m: return heading_line level len(m.group(1)) title m.group(2) if level 4: level 4 return f{# * level} {title}5.5 不要忽略空行压缩对切块的影响最后一个看起来很不起眼但影响很大的细节空行数量。很多切块器会依据空行做段落边界判断原始 txt 里如果每隔一行就有空行、甚至有连续四五个空行的情况切出来的块在分布上就会很不均匀。我在清洗阶段统一把多空行压缩成标准格式段落间一个空行结构块前一个空行这样下游切块器的行为才能稳定可预期。6. 进阶从转格式到建索引元数据6.1 在 Markdown 之外补充一个元数据层解析完 Markdown 不等于数据导入完成。我在实际项目中还会同步生成一份元数据 JSON记录每个 Markdown 文件的来源路径、原始编码、解析耗时、标题树结构、表格数量等。这份元数据有两大用处一是切块时可以把来源文件章节路径注入到每个块的前缀里让检索结果自带出处二是做质量监控比如发现某个文件的表格数量异常多或标题树结构异常浅说明解析可能有问题可以及时人工复核。6.2 标题路径注入让每个检索块知道自己在哪切片之后如果每个块的前缀都带着类似[[来源文档] 第三章 | 3.2 方法 | 3.2.1 实验设计]这样的路径检索时匹配到的块会自带层级上下文生成阶段的信息完整度会高很多。这个思路在不同 RAG 框架里都能落地本质上就是把结构化解析的成果下沉到切块策略里。6.3 和工具链的组合建议整个流程跑通之后我一般会把它做成一个可配置的配置文件把不同来源文档的处理规则编码候选、标题正则、是否启用表格修复、层级压缩开关分开管理。这样当新的文本来源加入时不需要改代码只需要新增一段配置规则。熟练之后一整套从 txt 到 Markdown 再到切块的流水线在单项文档格式下只需要调整少数参数就能稳定跑完。7. 我最近一次接手的历史知识库项目复盘分享一个真实的复盘案例。某团队找我的时候已经用开源的 RAG 框架搭了一版知识库但他们反馈检索出来的内容经常答非所问。我去看了他们的原始文档三千多个 txt 文件来源包括扫描版 OCR 输出、不同版本的系统导出、还有早年人工录入的纯文本。文件编码混杂标题风格各异有很多文档甚至没有标题。我先跑了基础解析流水线做了三件事编码统一为 UTF-8、全角转半角、空行规范化。这一步解决了一半文件的可读性问题。然后针对无标题文档做了特殊处理——用文件名作为一级标题再通过段落首句相似度聚类自动推断二级标题。处理后约 85% 的文档形成了可用的标题树。剩下的 15% 实在太乱我直接用人工标注处理掉了。效果对比很直接同样一批测试问题改造前的 Top-5 命中准确率大约是 38%改造后提升到了 72%。这个提升完全来自解析环节模型和向量库都没有变。这个案例让我更确信一件事RAG 项目的收益往往不在模型侧而在数据侧而数据侧的重心就在导入与解析。最后再分享一个小技巧解析流水线跑通后的第一件事不要急着全量处理而是取 20 篇不同来源的代表性文档跑完解析后逐个人工检查 Markdown 输出。这个抽检步骤花不了多少时间但能帮你提前发现一半以上的格式问题比全量跑完再回头返工划算得多。