做 RAG 项目这么久我越来越觉得一个朴素的道理被很多人低估了知识库检索效果的天花板往往不是在模型层而是在数据导入与解析这一层。你选再好的 embedding、再贵的向量库如果进来的文档是乱码、标题层级被拍平、表格被切得稀碎后面的一切都是白搭。所以打算写一个系列把 RAG 数据导入与解析这件事拆开揉碎讲清楚第一篇就先从最基础也最容易被轻视的两种格式说起txt 和 Markdown以及它们背后的通用文本与结构化处理思路。这个系列适合谁我觉得至少三类人会有收获刚搭完 demo 但检索效果不理想的 RAG 新手准备把企业知识库从“能跑”做到“好用”的工程同学以及在做文档解析工具选型时被各种方案弄得眼花缭乱的产品和开发。这篇先解决“把文本干净地送进知识库”这件事不涉及向量化、不涉及重排序模型专注上游。1. 为什么解析环节决定了 RAG 的天花板1.1 RAG 系统里“格式”往往是第一个瓶颈很多人第一次搭 RAG 知识库流程是这样的装好向量数据库接上 embedding 模型然后把一堆文档一股脑丢进去切块、入库、检索。跑通当然没问题但一旦问几个稍微具体的问题比如“这份合同里违约金的计算方式是什么”“第三季度的营收明细在哪个章节”结果往往答非所问。问题基本出在解析上。文本如果被错误地截断、标题层级丢失、表格结构被拍平检索阶段拿到的上下文就是一团浆糊。你可以把 RAG 想象成一个图书馆管理员他只能根据你给的索书卡去找书。如果索书卡上写的是错的楼层和书架编号那无论管理员多聪明都不可能找到正确的书。解析就是把**文档拆成“索书卡”**的过程这个过程出错后面的检索和生成都会跟着错。具体到格式层面txt 和 Markdown 是两个极端。txt 是最简单、最原始、但坑也最隐蔽的格式;Markdown 则是最接近“结构化”的轻量标记语言处理好它就等于给文档加上了语义骨架。这两个会了再去碰 PDF、Word、HTML 就会顺很多因为核心思路是通用的感知格式、保留结构、控制信息密度。1.2 从 txt 到 Markdown两条路线同一目标标题说“从 txt 到 Markdown 的通用文本与结构化解”其实涵盖了两条技术路线通用文本处理把任何输入包括 PDF、Word 转出来的文本先“洗”成干净的纯文本再进行编码纠正、段落合并、规范切分。这条路线的关键词是“通用”核心价值在于兼容性和稳定性。结构化处理在解析时就理解文档的骨架——标题层级、列表、表格、代码块、引用、加粗斜体——把这些结构信息保留下来并在切块时利用这些结构作为天然边界。这条路线的关键词是“结构化”核心价值在于语义保真和检索精准。两条路线的目标是一致的让进入向量库的每一块文本都携带尽可能多的上下文信息同时尽量保持内容的语义完整。区别在于通用路线做“减法”把杂质去掉把重心放在清洗和规整上结构化路线做“加法”在保留结构信息的同时把语义边界切得更准。我把整篇文章的实操路径整理成一张思维导图式的清单你可以先对照着看后面每节都会详细展开阶段核心任务常见工具/方法文本清洗编码识别与转换、BOM 处理、乱码修复chardet、charset-normalizer、iconv段落规整空行归一化、全角半角校正、去控制字符正则、Unicode 规范化NFC/NFKCMarkdown 解析标题树重建、代码块保护、表格结构化markdown-it、remark、mistune结构化切块按标题层级定界、父子块关联、控制 token 预算递归切分器、自研 AST 切块器元数据注入标题路径、文档 ID、块序号、关键词、时间戳Python 字典、JSON 序列化2. txt 导入看似简单却最容易翻车的格式2.1 别被“纯文本”骗了——编码问题是第一道坎我见过太多人栽在最基础的地方。一个 .txt 文件用记事本打开正常但用 Python 一读全是乱码。你第一反应可能是“这个文件坏了”实际上多半是编码问题。txt 文件本身没有内嵌元数据它不告诉你自己是 UTF-8 还是 GBK 编码也不会主动声明有没有 BOMByte Order Mark字节序标记。这就导致所有读取 txt 的程序都面临一个“猜编码”的问题。Windows 上很多国产软件导出的文本默认是 GBK/GB18030 编码Mac 和 Linux 上基本都是 UTF-8。如果你固定用open(file, encodingutf-8)去读遇到 GBK 文件直接报UnicodeDecodeError。但更麻烦的是有些文件没有报错但读出来是“锟斤拷”这种经典乱码。这其实是 UTF-8 解码 GBK 内容后替换字符又被错误转码的结果。这种乱码不会直接让程序崩溃但会悄无声息地污染你的向量库。我的建议是在解析管线入口就做一次编码检测与归一化。核心步骤很简单先读取文件的二进制内容rb模式检测 BOM。有 UTF-8 BOM 就按 UTF-8-SIG 解有 UTF-16 BOM 就按 UTF-16 解。没有 BOM 的情况下用charset-normalizer库做统计检测比老牌的 chardet 更准也更积极。检测出编码后统一转成 UTF-8 存为内部标准格式后续所有处理都基于这种干净文本。一段极简的检测代码长这样from charset_normalizer import from_bytes raw open(sample.txt, rb).read() match from_bytes(raw).best() if match: text str(match) # 已经转成标准的 Unicode 字符串 else: # 实在检测不出来退回去用 errorsreplace但要在日志里标记风险 text raw.decode(utf-8, errorsreplace)提示检测不出来的情况少但一旦存在优先用errorsreplace而不是errorsignore。ignore 会直接吞掉无法解码的字节可能导致相邻内容粘连replace 至少保留一个占位符后续清洗时能发现异常。2.2 段落切分与清洗乱码、全角半角、空行处理编码解决了不代表文本就是干净的。真实世界的 txt 文件里充斥着各种噪声全角空格、不间断空格、硬回车打断的段落、连续十几个换行符、Windows 的\r\n和 Linux 的\n混用、甚至文件中夹杂的 ANSI 转义序列比如从某些终端工具导出的日志。这些噪声不清理切块时就会出现“一个正常段落被切成两半”或者“一个块里全是空白字符”的尴尬情况。我的清洗管线一般按这个顺序操作统一换行符把\r\n、\r全部替换成\n避免后续按行处理时出现空行误判。归一化 Unicode用unicodedata.normalize(NFKC, text)把全角字符如全角逗号、括号、数字转成半角同时把兼容字符如某些特殊空格统一。这一步对中文文本尤其重要因为很多老旧文本会用全角标点而后续的关键词匹配和查询改写可能默认用半角标点。清理控制字符去掉\x00-\x08、\x0b、\x0c、\x0e-\x1f等不可见控制字符但保留\t制表符因为后面可能有 TSV 格式文件。空行规整将连续的多个空行压缩为一个空行同时确保段落之间有且仅有一个空行作为分隔。段落合并策略如果文件里存在大量“硬换行”即每行都换行、但语义上是同一段落的文本常见于从 PDF 直接复制出来的内容可以用启发式规则合并——当前行以句号、问号、感叹号结尾或者下一个非空行首字符是中文句号级别的标点就不合并否则认为是被硬换行打断的段落合并起来。这里特别想提醒一点不要在图省事的情况下直接按固定长度切 txt。固定长度切块比如每 500 字一刀虽然实现简单但切出来的块经常在句子中间断开。你可以用“递归字符切分器”的思路——先按段落切段落超过上限再按句子切句子还超过上限才按字符切。虽然这一步看起来不如“AI 智能切块”高大上但实际检索效果往往不差因为它的粒度边界跟自然语言的语义边界基本对齐。2.3 一个实用的通用文本导入管线结合上面的思路我贴一个可以直接落地的通用文本导入函数。它不依赖任何重型框架只需要charset-normalizer这个库属于任何一个 RAG 项目都能轻松复制的骨架。import re import unicodedata from charset_normalizer import from_bytes def clean_text(raw: bytes) - str: # 1. 编码检测与转换 match from_bytes(raw).best() text str(match) if match else raw.decode(utf-8, errorsreplace) # 2. 统一换行与空白 text text.replace(\r\n, \n).replace(\r, \n) text text.replace(\u00a0, ) # 不间断空格 text text.replace(\u3000, ) # 全角空格 text unicodedata.normalize(NFKC, text) # 3. 去掉控制字符但保留 \n \t text re.sub(r[\x00-\x08\x0b\x0c\x0e-\x1f\x7f], , text) # 4. 压缩空行最多保留一个空行作为段落分隔 text re.sub(r\n{3,}, \n\n, text) # 5. 返回段落列表后续供切块器使用 return text.strip() def load_txt_paragraphs(path: str) - list[str]: with open(path, rb) as f: raw f.read() text clean_text(raw) paragraphs [p.strip() for p in text.split(\n\n)] return [p for p in paragraphs if p]这里的第 5 步就是“段落化”——把清洗后的文本按空行切成段落列表。这个列表是后续结构化切块的输入你可以把每个段落当作一个基础原子块再根据块大小策略做合并或再切分。实操心得我在处理大量来自不同系统的 txt 时发现一个规律——编码检测的准确率远比你想象的低尤其是 GB18030 与 UTF-8 之间的误判。所以清洗之后一定要做一次快速自检比如统计替换字符\ufffd的出现次数如果超过阈值比如 0.1%就把该文档标记为“低可信度”人工抽检或走备用解析路径。3. Markdown 的结构化解让知识库“长眼睛”3.1 Markdown 的标题层级本身就是最好的语义骨架如果说 txt 是一张白纸那 Markdown 就是一张自带网格的纸。#到######六个级别的标题、列表、表格、代码块、引用块、加粗斜体这些语法元素本质上都在告诉你“这段内容的语义层级是什么、归属关系如何、边界在哪里”。很多 RAG 项目处理 Markdown 的方式相当粗暴——用正则去掉 Markdown 符号然后当成纯文本丢进切块器。这样做等于把自带的网格扔掉再自己去猜哪里是边界非常可惜。正确的思路应该是把 Markdown 解析成语法树AST然后基于树结构做切片。比如标题## 3. Markdown 的结构化解下面的所有内容一直到下一个##标题之前都属于同一个语义章节。这个章节的边界是天然的切块关键词范围——不按章节切反而按字数组件切就会把属于同一章节的内容拆到不同的向量块里检索时上下文丢失。具体的解析方案我不建议自己写正则硬啃成熟直接用现成的解析器。Python 生态里可以用markdown-it-py或者mistuneJavaScript/TypeScript 生态里可以用remark系列remark-parsemdast-util-to-string。这些库能把 Markdown 转成结构化 AST你再从 AST 里提取标题树和内容节点。3.2 用 AST 解析替代正则切割保留完整语义咱们直接看一个基于markdown-it-py的标题树构建示例效果是把 Markdown 文档的层级结构提取出来方便后续按章节切块。from markdown_it import MarkdownIt from markdown_it.token import Token def build_heading_tree(text: str): md MarkdownIt(commonmark, {html: False}) tokens md.parse(text) # 标题树每个节点包含 level、title、start_index、end_index heading_stack [] heading_tree [] for i, token in enumerate(tokens): if token.type heading_open: level int(token.tag[1]) # h1 - 1 # 下一个兄弟 token 就是标题文本 content_token tokens[i 1] title content_token.content.strip() node { level: level, title: title, start: token.map[0], end: None, children: [], } # 用栈维护父子关系只保留比当前 level 小的栈顶 while heading_stack and heading_stack[-1][level] level: heading_stack.pop() if heading_stack: heading_stack[-1][children].append(node) else: heading_tree.append(node) heading_stack.append(node) elif token.type heading_close and heading_stack: heading_stack[-1][end] token.map[1] 1 return heading_tree这段代码的意图很直白遍历 AST 里的 token遇到heading_open就读取标题级别和内容用一个栈结构来维护“当前标题属于谁”。这样一来文档的语义层级就被完整还原了。start和end记录的是这个章节在原始 Markdown 文本中的行号区间后续切块时可以直接按照这个行号区间来提取内容块。这里有个细节值得注意解析 Markdown 时最好用 CommonMark 规范模式而不是默认的零配置模式。因为有些解析器默认会开启一些“智能排版”功能比如把--转成破折号把直引号转成弯引号。对于 RAG 的知识库内容来说这种转换经常导致原始文本和检索 query 之间的字符不一致后面的相似度计算会有微小但影响稳定的偏差。3.3 代码表格、代码块、列表、链接的处理策略Markdown 里不仅有标题还有各种块级元素。每种元素在 RAG 场景下都应该有不同的处理策略不能一刀切成纯文本。代码块代码块包裹的内容通常不应该被普通的分块逻辑切开尤其是 Python、SQL 这类有完整语法的内容切在中间会导致代码片段完全失去意义。我的做法是把代码块当作一个“不可分割的原子块”单独存单独建立索引。如果是 SQL 或者配置文件这类跟业务强相关的内容甚至可以走单独的 embedding 通道。表格Markdown 表格在切块时是最容易翻车的。表格的行之间通常依赖上下文才能理解比如“第一列是年份第二列是营收”如果按普通文本切块很容易把表头和某几行切散或者把一行数据从中间斩断。我的策略是先把整个表格用排比转义的方式保留下来——即把表格转成更稳定的纯文本段落形式类似“| 年份 | 营收 |”这样然后保证表格整体作为一个块除非表格超过块大小限制才按行切分且必须保留表头。列表列表项之间有逻辑上的并列关系适合整体保留或者以每个列表项作为独立块。如果是嵌套列表尽量用缩进层级信息来组织块不要让一个三级子项脱离它的上级项单独成块。链接与图片链接的 URL 不一定需要保留但链接的锚文本方括号内的文字一定是正文的一部分。图片的alt文本也一样。块提取时建议把[text](url)处理成text把处理成alt既保留语义又去掉噪声。下面是我常用的一个md_token_to_markdown_text辅助函数处理单个 token 的文本化def token_text(token: Token) - str: # 处理不同类型 token 的文本提取 if token.type inline: # 去掉链接语法 [text](url) - text图片 ![]() - alt content token.content content re.sub(r!\[([^\]]*)\]\([^)]*\), r\1, content) content re.sub(r\[([^\]]*)\]\([^)]*\), r\1, content) return content if token.type code_block: return token.content # 代码块原样保留 if token.type fence: return token.content # 围栏代码原样保留 return token.content if token.content else token.markup or 注意上面这个写法是简化示意真实场景中你可能需要遍历token.children来保留内联元素中的格式语义比如加粗、斜体而不是直接用token.content。但整体思路一致不同 AST 节点类型走不同的文本化分支。4. 从“文本块”到“知识块”切块策略与元数据设计4.1 固定长度切块为什么总切到半句话很多 RAG 教程喜欢教“按 512 或者 1024 个 token 切块”理由是 embedding 模型有长度限制。这个思路本身没错但直接按 token 数硬切就有问题了。语言是一个有边界的序列——句子之间有句号分隔段落之间有缩进和空行章节之间有标题。如果无视这些边界纯粹按长度切就会产生大量“截断块”一句话被切掉后半段一个列表项被拆成两个块一个代码函数的def和函数体分开。这种截断对检索的影响是灾难性的。向量化模型会把一个被截断的句子编码成一个“不完整语义”的向量当用户用完整的问题去检索时相似度匹配几乎不可能命中这个残缺向量。这也是为什么我在前面的 txt 部分反复强调“递归切分”——它的本质就是优先沿着语义边界切实在没办法了才走硬切。4.2 基于标题层级的分块算法实践既然拿到了 Markdown 的标题树分块就该优先按标题层级走。一个成熟的实践是“段落-小节-章节三层递进”策略先把整个文档按h1/h2标题切成大的章节容器在每个章节容器内部再按h3/h4标题切成二级小节二级小节内部的内容如果超过块大小上限比如 1500 token再退回按段落、按句子做递归切分。这样做的最大好处是每块文本都天然携带了它的章节归属信息检索命中某一个块时你可以明确告诉生成模型“这个内容来自某章的某节”上下文完整度大幅提升。切块器的核心逻辑我写了一个简化版本你可以把它作为模板from typing import Generator def chunk_by_heading_tree(text: str, max_tokens: int 1000) - Generator[dict, None, None]: tree build_heading_tree(text) md MarkdownIt(commonmark, {html: False}) tokens md.parse(text) def extract_range(start_line: int, end_line: int) - str: lines text.split(\n)[start_line:end_line] return \n.join(lines).strip() for node in tree: # 当前标题及其内容 node_text extract_range(node[start], node[end]) # 递归处理子节点确保子节点内容不重复出现在父块中 for child in node[children]: child_text extract_range(child[start], child[end]) node_text node_text.replace(child_text, ) # 如果父块还有剩余内容就作为一个单独的块 if node_text: yield { title: node[title], level: node[level], text: node_text, metadata: {heading_path: node[title]}, } # 递归 yield 子节点块 yield from chunk_by_heading_tree(node_text, max_tokens)上面这个写法是概念演示真正生产化的时候你会把extract_range替换成基于 AST token 行号区间的忠实提取并且处理父子节点内容不重复的问题。但核心思路是清晰的父章节除了子章节之外可能有自己的“段落级前言”这个前言应该单独成块不要和子章节混在一起。举个例子一个文档的## 3. 参数配置下面有一段引言“本章介绍所有可配置参数”然后紧接着是### 3.1 数据库配置。如果切块时把引言跟3.1的内容合在一起这个概念块的信息密度就被稀释了检索“参数配置的整体说明”时精度也会下降。4.3 Markdown 元数据注入让向量检索更精准切块完成不等于工作结束。要让每个块在检索阶段能“自我说明”就得往块里注入元数据。元数据有两个去向一是存进向量数据库的 payload/filter 字段用于结构化过滤二是直接拼进要向量化/生成的文本里增强语义表达。我通常会给每个块附加这些元数据字段字段示例用途doc_idguide-2024-v3.md关联到原始文档chunk_idchapter-03-sec-01-chunk-00定位到具体块heading_pathRAG导入 / Markdown结构化解 / 元数据注入携带完整层级上下文chunk_seq12支持后续按文档内部顺序拼接content_typeparagraph/table/code/list为不同类型块设置差异化检索权重token_count857便于生成阶段的上下文预算控制元数据注入的实操技巧是把heading_path拼到向量化前的文本里而不是只作为向量库的 filter 字段。举个例子一个只写了“按上述步骤配置即可”的块脱离章节标题后含义非常模糊。但如果你在向量化前把文本重写成# RAG导入 / Markdown结构化解 / 元数据注入 按上述步骤配置即可。这样 embedding 之后的向量就能同时编码“操作步骤的语义”和“它所属的主题”检索时上下文一致性的匹配效果好得多。5. 常见问题与排查技巧实录5.1 txt 乱码到底是谁的锅如果你发现某个 txt 文档入库后检索时完全匹配不上先把纯文本提取出来打印前 50 个字符看看。乱码有三种常见情况编码误判检测器把 GBK 文档判成了 UTF-8导致替换字符出现。解决方法是把charset-normalizer的best()改成from_bytes(raw, cp_isolation[utf-8, gb18030])强制它在两个常见候选里做优先选择。BOM 干扰带 UTF-8 BOM 的文件如果按无 BOM 方式解码首行会出现\ufeff字符。清洗时最好用utf-8-sig解码或者解码后统一用text.lstrip(\ufeff)去掉。扩展字符集生僻字、古汉语、特殊符号可能超出 GBK 范围但如果原文件是 GB18030 编码检测器可能误判为别的。这类问题排查优先级不高但要预留日志标记。5.2 Markdown 表格被切得稀碎怎么办这是 Markdown 结构化处理里最头疼的问题之一。如果表格较大无论是按标题切还是按 token 切都容易把表格切到一半。我的解决方案分为两级优先整表保留检测 Markdown 中的表格区块计算它的 token 数。如果小于块大小上限的 70%就让表格独立成块不跟前后段落混合。超长表按行组切分如果表格超过上限按“表头 若干行”作为一个子块保证每个子块都带回表头。具体做法是解析表格的 AST把表头行和后续行分组比如每 10 行一组每组前面接上表头文本。检索时你会发现带表头的子块和带完整表格的整块在回答“某行某列是什么”这类问题时效果远好于被随机切开的半截表格。5.3 检索效果差的排查清单如果你的知识库搭好了但检索效果始终不理想先别急着换模型你可以按照这个清单逐项排查先看原始解析结果把文档解析后的纯文本打印出来看看有没有乱码、截断、标题层级丢失。这一步能帮你排除 60% 的问题。检查切块比例统计所有块的 token 分布如果大量块都接近“硬切上限”说明你的切块器没有利用好文档的语义边界。验证元数据注入是否生效随机抽取几个块确认heading_path是否正确、是否有块裸奔没有任何章节上下文。用问题反查拿一个典型的业务问题去向量库检索 top 5肉眼看这些块的内容是否和问题相关。如果 top 1 完全无关多半是解析层的语义丢失如果 top 5 相关但生成结果不好才是生成策略或者候选数量的问题。5.4 来自一线的几个小技巧最后分享几个我自己踩坑换来的经验不要过度清洗有些看似“脏”的内容比如 Markdown 里的加粗标记**文本**在知识库场景下其实保留了强调语义。如果你把加粗符号去掉向量化后的文本反而丢失了重点信息。我的处理策略是加粗文本解析文本时保留星号或者把强调内容用特殊标记包起来让模型知道这是重点。给解析管线写“体检报告”每次批量导入文档时输出一份统计报告包含总文档数、成功解析数、平均块数、乱码文档数、超长表格数。这份数据会让你对知识库的“健康状况”一目了然排查问题时能快速缩小范围。结构化是手段检索才是目的不要为了追求“完全解析正确”而把管线做得过于复杂。如果一个文档的格式很规整简单的段落切分就够用只有复杂文档才需要走 AST 解析。我一般会按文档类型分流比如纯文本走通用管线Markdown 和 HTML 走结构化管线PDF 再单独走 OCR 版面分析管线。写在最后这一篇解决的是“把 txt 和 Markdown 干净地送进知识库”的问题重点讲了通用文本清洗和 Markdown 的 AST 结构化解析。说实话这部分工作不像调模型那样有“刷榜快感”但它实打实地决定着一个 RAG 系统在生产环境里能不能顶住真实业务问题的检索压力。后续这个系列我打算继续往下写PDF/Word 这类非结构化文档的解析与 OCR 策略、表格和图片的混合形态处理、以及不同切块策略在具体检索场景中的效果对比。如果你在实际导入解析中遇到过什么诡异的文档格式也可以在评论区贴出来我看看能不能帮你定位问题。